You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by audreyso <gi...@git.apache.org> on 2017/05/11 20:16:52 UTC
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
GitHub user audreyso opened a pull request:
https://github.com/apache/cordova-test-platform/pull/1
Doc requirements for platform api expectations
Not ready for review yet! Thanks! :)
<!--
Please make sure the checklist boxes are all checked before submitting the PR. The checklist
is intended as a quick reference, for complete details please see our Contributor Guidelines:
http://cordova.apache.org/contribute/contribute_guidelines.html
Thanks!
-->
### Platforms affected
### What does this PR do?
Document requirements for platform api expectations
### What testing has been done on this change?
### Checklist
- [ ] [Reported an issue](http://cordova.apache.org/contribute/issues.html) in the JIRA database
- [ ] Commit message follows the format: "CB-3232: (android) Fix bug with resolving file paths", where CB-xxxx is the JIRA ID & "android" is the platform affected.
- [ ] Added automated test coverage as appropriate for this change.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/audreyso/cordova-test-platform DocRequirements
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/cordova-test-platform/pull/1.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #1
----
commit 620be407e792f0c0a9b7aa49689be41137ba2e21
Author: Jesse MacFadyen <pu...@gmail.com>
Date: 2017-05-04T01:20:39Z
document platform api expectations
commit 60c45ec48e4d8b965c26c1ca0e025d64bde12015
Author: Jesse MacFadyen <pu...@gmail.com>
Date: 2017-05-04T03:15:35Z
added more info, and todo:s
commit acc5435520d3f3badb76f9785573357a0ef31959
Author: Audrey So <au...@apache.org>
Date: 2017-05-04T23:49:31Z
DocRequirements : added information about the methods and their params/returns
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r129671498
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,173 @@
+<!--
+# license: Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+-->
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+- invoking this script would create a platform-specific, cordova-compatible project shell
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json must export a 'main'. `"main": "src/cordova/Api.js"`
+ - A 'main' must exist, and it must be an instance of the `PlatformApi` with methods as you define later.
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+
+- The PlatformApi class
+ - The `PlatformApi` class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single `prepare` method to provide a way for cordova-lib to apply a project's setting/www content to the platform. It interpolates metadata, such as application name or description from a `Cordova` project's config.xml into the format expected by the platform. See [config.xml documentation](https://cordova.apache.org/docs/en/latest/config_ref/).
+ - The `PlatformApi` class should be implemented by each platform that wants to use the new API flow.
--- End diff --
I'm not sure we need this point. Do new users looking to implement a platform care that the platform API is "new" or that there used to be a different, legacy approach to implementation? In the "Package Expectations" section we already state that the platform package _must_ expose a `main` module that returns an instance of `PlatformApi` - that tells me that the requirement for using/implementing the `PlatformApi` class is a _must_, not a _should_.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by purplecabbage <gi...@git.apache.org>.
Github user purplecabbage commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r129178197
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
--- End diff --
We use the term 'run' across all platform types. This could mean 'launch | navigateTo | open', but imho we should NOT add language to confuse this. To me this is not an issue currently.
'run' can potentially take additional parameters, and in the case of browser, the parameters 'could' specify different targets, just like the rest of the platforms.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128837232
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
--- End diff --
Sounds like we have more work here in terms of wording and understanding the API... I think we should consolidate on terminology around how to differentiate between Platform and Project-specific API - that would help handle any potential confusion.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by purplecabbage <gi...@git.apache.org>.
Github user purplecabbage commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128834822
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
--- End diff --
this is a MUST
main MUST exist, and it MUST be an instance of the platformAPI with methods as you define later.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128839290
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
+ - runOptions : This is an options object. The structure is the same as for build options.
+ - The `run` method must return a promise either fulfilled if the package was build and ran successfully, or rejected with a CordovaError.
+
+
+- has an `addPlugin` method
+ - PlatformApi.prototype.addPlugin = function (plugin, installOptions) {};
+ - The `addPlugin` method should install a plugin into a platform. It should handle all the non-www files shipped by plugin (sources, libs, assets, js-files) and accept a PluginInfo instance that represents the plugin that will be installed and an options object. It cannot resolve the dependencies of a plugin.
+ - plugin : This is a PluginInfo instance that should represent the plugin that will be installed. It is expected to accept a plugin spec that should be one of the following:
+ - valid plugin id that can be resolved through either cordova plugin registry or npm: 'org.apache.cordova.globalization', 'cordova-plugin-globalization'
+ - valid npm identifier, that resolves to valid plugin : cordova-plugin-globalization@1.0.0
+ - git url, that points to a repo with a valid plugin: http://github.com/apache/cordova-plugin-globalization.git#r.1.0.0
+ - path to local repo of valid plugin: /my/cordova/repositories/cordova-plugin-globalization
+ - installOptions : This is an options object with the following possible options:
+ - installOptions.link : This is a flag that should specify that plugin sources will be symlinked to app's directory instead of copying (if possible).
+ - installOptions.variables : This is an object that should represent variables that will be used to install a plugin.
--- End diff --
Anything we can link to re: variables? Stuff from config.xml?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128838089
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
--- End diff --
I would link to cordova-android and cordova-ios examples of `buildConfig` here.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128834498
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
--- End diff --
I'm unsure about this point, as I've heard the polyfill is on its way out. Can someone else confirm?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by audreyso <gi...@git.apache.org>.
Github user audreyso commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r129104787
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
+ - runOptions : This is an options object. The structure is the same as for build options.
+ - The `run` method must return a promise either fulfilled if the package was build and ran successfully, or rejected with a CordovaError.
+
+
+- has an `addPlugin` method
+ - PlatformApi.prototype.addPlugin = function (plugin, installOptions) {};
+ - The `addPlugin` method should install a plugin into a platform. It should handle all the non-www files shipped by plugin (sources, libs, assets, js-files) and accept a PluginInfo instance that represents the plugin that will be installed and an options object. It cannot resolve the dependencies of a plugin.
--- End diff --
Hi! I'm having some trouble finding links/ documentation for the following:
- PluginInfo
- CordovaError
- Requirement
- CordovaProject
Any suggestions of where I can search for this info?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r129105861
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
+ - runOptions : This is an options object. The structure is the same as for build options.
+ - The `run` method must return a promise either fulfilled if the package was build and ran successfully, or rejected with a CordovaError.
+
+
+- has an `addPlugin` method
+ - PlatformApi.prototype.addPlugin = function (plugin, installOptions) {};
+ - The `addPlugin` method should install a plugin into a platform. It should handle all the non-www files shipped by plugin (sources, libs, assets, js-files) and accept a PluginInfo instance that represents the plugin that will be installed and an options object. It cannot resolve the dependencies of a plugin.
--- End diff --
I think the first two are in cordova-common. `Requirement` is a tricky one - I'm not sure. cordova-lib maybe?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r129181275
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
+ - runOptions : This is an options object. The structure is the same as for build options.
+ - The `run` method must return a promise either fulfilled if the package was build and ran successfully, or rejected with a CordovaError.
+
+
+- has an `addPlugin` method
+ - PlatformApi.prototype.addPlugin = function (plugin, installOptions) {};
+ - The `addPlugin` method should install a plugin into a platform. It should handle all the non-www files shipped by plugin (sources, libs, assets, js-files) and accept a PluginInfo instance that represents the plugin that will be installed and an options object. It cannot resolve the dependencies of a plugin.
--- End diff --
Yeah totally! The Platform API would be consumed by cordova tooling such as cordova-cli and lib, so linking directly to code I think is appropriate. The folks writing up Platform API implementations would reasonably need to know what properties and/or methods exist on these objects being passed in (like `PluginInfo`) to the Platform API methods they are implementing.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128833191
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
--- End diff --
Can we describe what the purpose of the scripts are? i.e. "invoking this script would create a platform-specific cordova-compatible project shell"
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by stevengill <gi...@git.apache.org>.
Github user stevengill commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128869649
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
--- End diff --
maybe just link to the template documentation? https://cordova.apache.org/docs/en/latest/guide/cli/template.html
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128839772
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
+ - runOptions : This is an options object. The structure is the same as for build options.
+ - The `run` method must return a promise either fulfilled if the package was build and ran successfully, or rejected with a CordovaError.
+
+
+- has an `addPlugin` method
+ - PlatformApi.prototype.addPlugin = function (plugin, installOptions) {};
+ - The `addPlugin` method should install a plugin into a platform. It should handle all the non-www files shipped by plugin (sources, libs, assets, js-files) and accept a PluginInfo instance that represents the plugin that will be installed and an options object. It cannot resolve the dependencies of a plugin.
+ - plugin : This is a PluginInfo instance that should represent the plugin that will be installed. It is expected to accept a plugin spec that should be one of the following:
+ - valid plugin id that can be resolved through either cordova plugin registry or npm: 'org.apache.cordova.globalization', 'cordova-plugin-globalization'
+ - valid npm identifier, that resolves to valid plugin : cordova-plugin-globalization@1.0.0
+ - git url, that points to a repo with a valid plugin: http://github.com/apache/cordova-plugin-globalization.git#r.1.0.0
+ - path to local repo of valid plugin: /my/cordova/repositories/cordova-plugin-globalization
+ - installOptions : This is an options object with the following possible options:
+ - installOptions.link : This is a flag that should specify that plugin sources will be symlinked to app's directory instead of copying (if possible).
+ - installOptions.variables : This is an object that should represent variables that will be used to install a plugin.
+ - The `addPlugin` method must return a promise either fulfilled or rejected with a CordovaError instance.
+- has a `removePlugin` method
+ - PlatformApi.prototype.removePlugin = function (plugin) {};
+ - The `removePlugin` method should remove an installed plugin from a platform. It should accept a PluginInfo instance that represents the plugin that will be removed and an options object.
+ - Note: Since this method accepts the PluginInfo instance as an input parameter, instead of a plugin id, the caller should take care of managing and storing the PluginInfo instances for future uninstalls.
+ - plugin : This is a PluginInfo instance that should represent the plugin that will be uninstalled. It is expected to accept a plugin spec that should be one of the following:
+ - valid plugin id that can be resolved through either cordova plugin registry or npm: 'org.apache.cordova.globalization', 'cordova-plugin-globalization'
+ - valid npm identifier, that resolves to valid plugin : cordova-plugin-globalization@1.0.0
+ - girl url, that points to a repo with a valid plugin: http://github.com/apache/cordova-plugin-globalization.git#r.1.0.0
+ - path to local repo of valid plugin: /my/cordova/repositories/cordova-plugin-globalization
+ - The `removePlugin` method must return a promise either fulfilled or rejected with a CordovaError instance.
+
+- CLI work flow integration
--- End diff --
Perhaps it is worth linking to / expanding on the two different kinds of workflows cordova supports? I.e. CLI-based workflow (supporting multiple platforms) or single-platform-based workflow that purely leverages the platform API. e.g. the [top of the Android guide](https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html) describes there are "platform centered shell tools" or "cross-platform Cordova CLI" workflows.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by stevengill <gi...@git.apache.org>.
Github user stevengill commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128869395
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
--- End diff --
yup. polyfill is on the way out
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by purplecabbage <gi...@git.apache.org>.
Github user purplecabbage commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128835035
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
--- End diff --
MUST export a static function createPlatform that returns a new instance of the platformAPI
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by audreyso <gi...@git.apache.org>.
Github user audreyso commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128878157
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
--- End diff --
https://issues.apache.org/jira/browse/CB-13058
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128834741
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
--- End diff --
What is meant by "static" functions? That's not a very javascript-y concept.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128833488
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
--- End diff --
I think we should remove this, as the `update` script seems to be going away, e.g. https://issues.apache.org/jira/browse/CB-12948
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128838640
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
--- End diff --
Worth noting that the concept of 'running' could vary wildly from platform to platform. While most of Cordova targets mobile devices, and thus the concepts of device/emulator apply, a platform such as cordova-browser is a bit different and the same device/emulator concepts apply less.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by audreyso <gi...@git.apache.org>.
Github user audreyso commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128876824
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
--- End diff --
Ohh okay! Just to confirm, all of the info about the updatePlatform function should be totally removed?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128837813
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
--- End diff --
I would provide an example. i.e. the cordova-android platform requires tooling from the Android SDK, and uses this method to make checks that the operating system has access to all necessary tooling.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by purplecabbage <gi...@git.apache.org>.
Github user purplecabbage commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r129108993
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
--- End diff --
Static is the correct term for a method that is called by referencing the Class and not an instance of the class.
Can we merge this, and create new comments/issues for remaining changes? This is impossible to follow now with the number of comments.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128833714
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
--- End diff --
I would tweak the wording and remove "usually" - gives a sense of uncertainty.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by audreyso <gi...@git.apache.org>.
Github user audreyso commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128880058
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
--- End diff --
https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html#using-buildjson
https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html#using-buildjson
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128838263
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
--- End diff --
"will contain only one items" -> "will contain only one item"
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by purplecabbage <gi...@git.apache.org>.
Github user purplecabbage commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128874756
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
--- End diff --
File an issue that we remove the requirement that the file be called Api.js
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by purplecabbage <gi...@git.apache.org>.
Github user purplecabbage commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128835893
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
--- End diff --
This is NOT a requirement. All instances of the platform api are typically created and returned by the createPlatform function.
The newly created platform ( which copies code from the template to the project dir ) MUST export a constructor though.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128836016
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
--- End diff --
Similar to above note on update, not sure it is worth documenting this since it is going away.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128834664
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
--- End diff --
Is this todo still applicable? I am not sure that _will_ change.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by audreyso <gi...@git.apache.org>.
Github user audreyso commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128879376
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
--- End diff --
How about something like this:
Templates allow you to use preexisting code to jumpstart your project. Locate a template you wish to use. Then, create your project using that template, by specifying the --template flag during the create command, followed by your template source.
You can createCordova project with a custom template located locally, in NPM, or GitHub.
```
$ cordova create hello com.example.hello HelloWorld --template <npm-package-name>
$ cordova create hello com.example.hello HelloWorld --template <git-remote-url>
$ cordova create hello com.example.hello HelloWorld --template <path-to-template>
```
https://cordova.apache.org/docs/en/latest/guide/cli/template.html
(and then include a link to the docs?)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by purplecabbage <gi...@git.apache.org>.
Github user purplecabbage commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128879785
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
--- End diff --
Voice should be 2nd person.
Something like ... Templates allow app developers to create apps based on boilerplate application code ...
Not sure how deep you need to go as the audience for this guide is/are platform developers, so it should be more 'How to I respect the template parameter when it is given?' and not 'How do I use templates?'
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by audreyso <gi...@git.apache.org>.
Github user audreyso commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128834249
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
--- End diff --
I think this to-do is a note left from someone else as a reminder for something... Can I just take it out?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform issue #1: Doc requirements for platform api expectatio...
Posted by purplecabbage <gi...@git.apache.org>.
Github user purplecabbage commented on the issue:
https://github.com/apache/cordova-test-platform/pull/1
Another thing to note is that the tests that are in this repo *could* be used to verify the platformAPI for anyone attempting to implement it.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r129180869
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
--- End diff --
My intention with my comment was to try to simplify the language as much as possible, so I think if we can actually _remove_ references to run targets specific to platforms (such as devices and emulators), I think that would be good.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by purplecabbage <gi...@git.apache.org>.
Github user purplecabbage commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128877837
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
--- End diff --
Yes, you can remove the update api. I would also recommend that you test it and verify that it does not get called. ie. try commenting out Api.updatePlatform in ios,android,browser,windows,test platforms and call cordova platform update for each ...
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r129673561
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,173 @@
+<!--
+# license: Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+-->
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+- invoking this script would create a platform-specific, cordova-compatible project shell
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json must export a 'main'. `"main": "src/cordova/Api.js"`
+ - A 'main' must exist, and it must be an instance of the `PlatformApi` with methods as you define later.
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+
+- The PlatformApi class
+ - The `PlatformApi` class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single `prepare` method to provide a way for cordova-lib to apply a project's setting/www content to the platform. It interpolates metadata, such as application name or description from a `Cordova` project's config.xml into the format expected by the platform. See [config.xml documentation](https://cordova.apache.org/docs/en/latest/config_ref/).
+ - The `PlatformApi` class should be implemented by each platform that wants to use the new API flow.
+ - Platforms that implement their own `PlatformApi` instance should implement all prototype methods of this class to be fully compatible with `cordova-lib`.
--- End diff --
This should probably be "must implement all prototype methods", not "should"? Can we be explicit about which of these methods are required? Off the top of my head, a platform _needs_ `create`, `requirements`, `prepare`, `addPlugin` and `removePlugin`... are those the only necessary ones? `build`, `run` and others may not be required. But perhaps it is worth having implementers create, at the minimum, functions that return resolved promises for the method that are considered "no-op" for a platform.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128837876
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
--- End diff --
Can we link to this `Requirement` object definition / code?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by audreyso <gi...@git.apache.org>.
Github user audreyso commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r129092432
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
--- End diff --
Hmm so "static" functions came up in all of the notes, discussions, etc that I read through. I assumed it meant --> https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static
Should I remove all the instances of "static" functions in this guide? Or maybe replace it with something else? Or define static functions at the top somewhere so readers know?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by audreyso <gi...@git.apache.org>.
Github user audreyso commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128834432
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
--- End diff --
Is there a better way to say this?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by audreyso <gi...@git.apache.org>.
Github user audreyso commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r129106466
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
+ - runOptions : This is an options object. The structure is the same as for build options.
+ - The `run` method must return a promise either fulfilled if the package was build and ran successfully, or rejected with a CordovaError.
+
+
+- has an `addPlugin` method
+ - PlatformApi.prototype.addPlugin = function (plugin, installOptions) {};
+ - The `addPlugin` method should install a plugin into a platform. It should handle all the non-www files shipped by plugin (sources, libs, assets, js-files) and accept a PluginInfo instance that represents the plugin that will be installed and an options object. It cannot resolve the dependencies of a plugin.
--- End diff --
Ohh ok so I can include links to code from a cordova repo? They don't just have to be links found in http://cordova.apache.org/ ?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128838987
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
+ - runOptions : This is an options object. The structure is the same as for build options.
+ - The `run` method must return a promise either fulfilled if the package was build and ran successfully, or rejected with a CordovaError.
+
+
+- has an `addPlugin` method
+ - PlatformApi.prototype.addPlugin = function (plugin, installOptions) {};
+ - The `addPlugin` method should install a plugin into a platform. It should handle all the non-www files shipped by plugin (sources, libs, assets, js-files) and accept a PluginInfo instance that represents the plugin that will be installed and an options object. It cannot resolve the dependencies of a plugin.
--- End diff --
I think we need to link to plugin.xml documentation as well as any code or docs we have about the `PluginInfo` object. If I read this, as a person new to Cordova, this is a bit overwhelming and I'm not sure where to start.
Also, is "handle all non-www files" imply that "js-files" objects need to be handled? Let's ensure the list of plugin.xml elements that this method needs to handle is exhaustive and complete.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128836281
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
--- End diff --
Re: the `CordovaProject` object/instance, anything we can link to to provide more details on what this means and how it works?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by audreyso <gi...@git.apache.org>.
Github user audreyso commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128877652
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
+ - runOptions : This is an options object. The structure is the same as for build options.
+ - The `run` method must return a promise either fulfilled if the package was build and ran successfully, or rejected with a CordovaError.
+
+
+- has an `addPlugin` method
+ - PlatformApi.prototype.addPlugin = function (plugin, installOptions) {};
+ - The `addPlugin` method should install a plugin into a platform. It should handle all the non-www files shipped by plugin (sources, libs, assets, js-files) and accept a PluginInfo instance that represents the plugin that will be installed and an options object. It cannot resolve the dependencies of a plugin.
+ - plugin : This is a PluginInfo instance that should represent the plugin that will be installed. It is expected to accept a plugin spec that should be one of the following:
+ - valid plugin id that can be resolved through either cordova plugin registry or npm: 'org.apache.cordova.globalization', 'cordova-plugin-globalization'
+ - valid npm identifier, that resolves to valid plugin : cordova-plugin-globalization@1.0.0
+ - git url, that points to a repo with a valid plugin: http://github.com/apache/cordova-plugin-globalization.git#r.1.0.0
+ - path to local repo of valid plugin: /my/cordova/repositories/cordova-plugin-globalization
+ - installOptions : This is an options object with the following possible options:
+ - installOptions.link : This is a flag that should specify that plugin sources will be symlinked to app's directory instead of copying (if possible).
+ - installOptions.variables : This is an object that should represent variables that will be used to install a plugin.
--- End diff --
Hmm how about this?
https://cordova.apache.org/docs/en/latest/config_ref/#plugin
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by audreyso <gi...@git.apache.org>.
Github user audreyso commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128880654
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
--- End diff --
Thank you for explaining that! So would be enough to just write :
- Templates allow developers to create apps based on boilerplate application code.
- https://cordova.apache.org/docs/en/latest/guide/cli/template.html
(and just exclude the rest of the information since it's already in the docs?)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128902594
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
+- has a `build` method
+ - PlatformApi.prototype.build = function(buildOptions) {};
+ - The `build` method should build an application package for the current platform.
+ - buildOptions : This is an options object. The most common options are:
+ - buildOptions.debug : This indicates that that packages should be built with debug configuration. This is set true by default unless the 'release' option is not specified.
+ - buildOptions.release : This indicates that packages should be built with release configuration. If not set to true, debug configuration should be used.
+ - buildOptions.device : This indicates that the built app is intended to run on device.
+ - buildOptions.emulator : This indicates that the built app is intended to run on an emulator.
+ - buildOptions.target : This indicates the device id that will be used to run the built app.
+ - buildOptions.nobuild : This indicates that this should be a dry-run call. No build artifacts should be produced.
+ - buildOptions.archs : This indicates chip architectures with app packages should be built for. The list of valid architectures is dependent on the platform.
+ - buildOptions.buildConfig : This is the path to the build configuration file. The format of this file is dependent on the platform.
+ - buildOptions.argv : This is a raw array of command-line arguments that should be passed to the `build` command. The purpose of this property is to pass platform-specific arguments, and eventually let the platform define its own arguments processing logic.
+ - The `build` method must return a promise either fulfilled with an array of build artifacts (application packages) if the package was built successfully, or rejected with a CordovaError. The return value in most cases will contain only one items, but in some cases there could be multiple items in an output array, e.g. when multiple architectures are specified. The resultant build artifact objects are not strictly typed and may contain an arbitrary set of fields as in the sample below.
+
+ ```
+ {
+ architecture: 'x86',
+ buildType: 'debug',
+ path: '/path/to/build',
+ type: 'app'
+
+ }
+ ```
+
+- has a `run` method
+ - PlatformApi.prototype.run = function(runOptions) {};
+ - The `run` method should build an application package for the current platform and runs it on the specified/default device. If no 'device'/'emulator'/'target' options are specified, then it should try to run the app on a default device if connected, otherwise it should run on the app on the emulator.
+ - runOptions : This is an options object. The structure is the same as for build options.
+ - The `run` method must return a promise either fulfilled if the package was build and ran successfully, or rejected with a CordovaError.
+
+
+- has an `addPlugin` method
+ - PlatformApi.prototype.addPlugin = function (plugin, installOptions) {};
+ - The `addPlugin` method should install a plugin into a platform. It should handle all the non-www files shipped by plugin (sources, libs, assets, js-files) and accept a PluginInfo instance that represents the plugin that will be installed and an options object. It cannot resolve the dependencies of a plugin.
+ - plugin : This is a PluginInfo instance that should represent the plugin that will be installed. It is expected to accept a plugin spec that should be one of the following:
+ - valid plugin id that can be resolved through either cordova plugin registry or npm: 'org.apache.cordova.globalization', 'cordova-plugin-globalization'
+ - valid npm identifier, that resolves to valid plugin : cordova-plugin-globalization@1.0.0
+ - git url, that points to a repo with a valid plugin: http://github.com/apache/cordova-plugin-globalization.git#r.1.0.0
+ - path to local repo of valid plugin: /my/cordova/repositories/cordova-plugin-globalization
+ - installOptions : This is an options object with the following possible options:
+ - installOptions.link : This is a flag that should specify that plugin sources will be symlinked to app's directory instead of copying (if possible).
+ - installOptions.variables : This is an object that should represent variables that will be used to install a plugin.
--- End diff --
I think linking to this section is a bit more relevant here: https://cordova.apache.org/docs/en/latest/config_ref/#variable
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128837070
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
--- End diff --
I would reword this haha, "tricky" does not infuse confidence. I think the point of this sentence could probably be incorporated into my previous comment about a 'template preamble'. If we can clarify what a platform template is and how it is used (or overridden) at create-time, then I think the particular point being made here becomes less of a challenge to clarify.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128837509
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
--- End diff --
Why is this not typical usage? Worth pointing out?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128902258
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
--- End diff --
To Jesse's point, I would also add that a default template is standard structure for a cordova platform.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128836475
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
--- End diff --
I think we need a pre-amble about what a template is and how it is used in the context of `create`.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128834387
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
--- End diff --
I would expand on this, in particular the "project settings" part. Something like "interpolates metadata from a cordova project's config.xml (link to cordova docs' config.xml section) (such as application name, description, etc.) into the format expected by the platform."
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Posted by filmaj <gi...@git.apache.org>.
Github user filmaj commented on a diff in the pull request:
https://github.com/apache/cordova-test-platform/pull/1#discussion_r128837925
--- Diff: PlatformRequirements.md ---
@@ -0,0 +1,144 @@
+
+# New Platform Checklist
+
+## Stand-alone scripts
+
+bin/create scripts
+- bin/create _(typically a node script)_
+- bin/create.bat for windows
+ - windows .bat file typically just calls bin/create with node
+
+bin/update
+- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
+
+## Package Expectations
+
+- Platforms must have a package.json in their root.
+- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
+ - This allows other modules to simply require() the path to this platform and get access to the Api.
+
+## Api (Platform) Expectations
+- The PlatformApi class
+ - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
+ - It can install & uninstall plugins with all source files, web assets and js files.
+ - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
+ - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
+ - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
+ - The PlatformApi instance should define the following field:
+ - platform : This is a String that defines a platform name.
+
+- Api.js exports static functions
+ - there is currently a requirement that the file be called Api.js (todo:change that)
+
+
+- Api.js exports static function `updatePlatform(destination, options, events);`
+ - PlatformApi.updatePlatform = function (cordovaProject, options) {};
+ - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+- Api.js exports static function `createPlatform(destination, cfg, options, events);`
+ - PlatformApi.createPlatform = function(cordovaProject, options) {};
+ - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
+ - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
+ - options : This is an options object. The most common options are :
+ - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
+ - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
+ - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
+
+The way most platforms work is somewhat tricky. The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js . When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js. The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
+
+A call to the platforms static Api.createPlatform will
+1. Copy template files to destination (according to cfg, options).
+1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
+1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
+ - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
+ - Similarly, they may have their own require() statements, and while typically require would return the same instance, because our modules are loaded from different paths, they get different relative requires also.
+
+
+## Api (Project) Expectations
+
+- Api.js exports a constructor function
+ var Api = require('path/Api.js');
+ var api = new Api(); // This should work, although it's not typical usage.
+
+- These following methods are equal to the platform's executable scripts. The main difference is that they accept a structured options object instead of an array of command line arguments.
+- has a `requirements` method
+ - PlatformApi.prototype.requirements = function() {};
+ - The `requirements` method should perform a requirements check for the current platform. Each platform is expected to define its own set of requirements, which should be resolved before the platform can be built successfully.
+ - The `requirements` method must return a promise, resolved with a set of Requirement objects for the current platform.
+- has a `clean` method
+ - PlatformApi.prototype.clean = function() {};
+ - The `clean` method should clean out the build artifacts from the platform's directory.
+ - The `clean` method must return a promise either fulfilled or rejected with a CordovaError.
--- End diff --
Let's link to `CordovaError` if we can.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org