cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From filmaj <...@git.apache.org>
Subject [GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Date Mon, 24 Jul 2017 23:36:59 GMT
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


Mime
View raw message