Skip to content
Permalink
Browse files
feat: export build-tools JS API & add CLI (#229)
* feat(build-tools): infer config from platform's package.json

* feat: export build tools for use in platforms

* feat: add CLI to build cordova.js

* docs: remove sections about grunt-based build

* docs: document new cordova-js build
  • Loading branch information
raphinesse committed Dec 16, 2020
1 parent 2278ac5 commit 07379820d277c54009d0d776e7d6957ef7f94dfc
Showing 5 changed files with 125 additions and 52 deletions.
@@ -55,42 +55,6 @@ A unified JavaScript layer for [Apache Cordova](http://cordova.apache.org/) proj
'-tests/ ............... unit tests
```

## Setup for Building

* Make sure you have [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed.

`npm` should come pre-installed with `Node.js`. If `Node.js` installed but can not run `npm`, please follow the npm doc: [Downloading and installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).

* Install all the node dependencies by running the following command from the repository root:

```bash
npm install
```

## Building

The build script assumes that users have the cordova-platforms checked out as siblings to this `cordova-js` directory. When generating `cordova.js`, `npm run build` will grab platform specific files from these directories if they exist.

Then from the repository root run:

```bash
npm run build
```

To compile the js for just one platform, run:

```bash
npx grunt compile:android --platformVersion=4.0.0
```

To compile the js for all platforms but pass in a custom path for your cordova-android and cordova-ios platforms, run:

```bash
npm run build -- --android='../custompath/cordova-android' --ios='../custompath/cordova-ios'
```

For integration, see the 'Integration' section below.

## How It Works

The `build-tools/build.js` process is a Node.js script that concatenates all of the core Cordova plugins in this repository into a `cordova.<platform>.js` file under the `pkg/` folder. It also wraps the plugins with a RequireJS-compatible module syntax that works in both browser and node environments. We end up with a `cordova.js` file that wraps each **Cordova** *plugin* into its own module.
@@ -117,19 +81,9 @@ Tests run in a bundled headless Chromium instance. They can be run with:

Final testing should always be done with the [Mobile Spec test application](https://github.com/apache/cordova-mobile-spec).

## Integration

### Cordova

Build the js files by running **grunt** as described above. Update each platform independently. For a given platform:

Replace the `cordova.js` file in the cordova <platform>platform_www/cordova.js directory with the newly generated `cordova.js` file. If necessary, change the name of the new file to match that of the overwritten one.
## Creating a New Platform

Once the new js file has been added, any new projects created will use the updated js. To update an already existing project, directly replace the cordova.js file within the project's `www/` folder with the generated `cordova.PLATFORM.js`. Make sure to change the file name to match the original.

## Adding a New Platform

### In Your Platform Repository
In your platform repository:

1. Create the `cordova-js-src` directory.

@@ -168,6 +122,13 @@ Once the new js file has been added, any new projects created will use the updat
};
```

### In `cordova-js` Repository

1. Add a `<platform>: {}` entry to the `Gruntfile.js` `compile` arrays.
4. Bundle the modules from `cordova-js/src` and `<platform-repo>/cordova-js-src` into a file that ends up in `<platform-project>/platform_www/cordova.js`. This can be done in various ways. The following is recommended:
- Add `cordova-js` as a `devDependency`: `npm i -D cordova-js`
- Build `cordova.js` when preparing your platform's npm package. You can do that by adding the NPM `prepare` hook script to your `package.json`:
```json
"scripts": {
"prepare": "cordova-js build > project-template/platform_www/cordova.js",
// ...
}
```
- During project creation, make sure that the `cordova.js` file created by the `prepare` script ends up where your platform expects it
@@ -17,13 +17,41 @@
* under the License.
*/

const path = require('path');
const bundle = require('./bundle');
const scripts = require('./scripts');
const modules = require('./modules');
const getBuildId = require('./build-id');
const { collectModules } = require('./common');

module.exports = function build (userConfig) {
const config = Object.assign({ preprocess: x => x }, userConfig);
const defaults = { preprocess: x => x };

// Infer some defaults from platform package root if present
const { platformRoot } = userConfig;
if (platformRoot) {
const pkg = require(path.join(platformRoot, 'package'));
Object.assign(defaults, {
platformName: pkg.name,
platformVersion: pkg.version,
modulePath: path.join(platformRoot, 'cordova-js-src')
});
}

const config = { ...defaults, ...userConfig };

// Populate extraModules property if missing
const { extraModules, modulePath } = config;
config.extraModules = extraModules || collectModules(modulePath);

// Throw error on misconfigured modulePath
if (modulePath && Object.keys(config.extraModules).length === 0) {
throw new Error(`Could not find any modules in ${modulePath}`);
}

// Delete convenience config keys that are not used after this point
delete config.platformRoot;
delete config.modulePath;

return Promise.all([
scripts(config),
@@ -0,0 +1,63 @@
#!/usr/bin/env node

/*!
* 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.
*/

const { resolve } = require('path');
const { promisify } = require('util');
const { pipeline, Readable } = require('stream');
const { build } = require('.');

const USAGE = `
Usage:
cordova-js [help]
cordova-js build [<platform-root>]
`.trim();

async function main ([cmd = 'help', ...args]) {
if (!Object.prototype.hasOwnProperty.call(commands, cmd)) {
console.error(`Unknown command "${cmd}"`);
process.exitCode = 1;
return commands.help();
}
return commands[cmd](args);
}

const commands = {
help () {
console.log(USAGE);
},

async build (args) {
const platformRoot = resolve(args[0] || process.cwd());
const bundleCode = await build({ platformRoot });
return promisify(pipeline)(
Readable.from([bundleCode]),
process.stdout
);
}
};

if (require.main === module) {
main(process.argv.slice(2))
.catch(err => {
console.error('cordova-js failed:', err);
process.exitCode = 1;
});
}
@@ -0,0 +1,20 @@
/*!
* 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.
*/

module.exports = require('./build-tools');
@@ -8,6 +8,7 @@
"version": "6.0.1-dev",
"repository": "github:apache/cordova-js",
"bugs": "https://github.com/apache/cordova-js/issues",
"bin": "build-tools/cli.js",
"scripts": {
"lint": "eslint --ignore-path .gitignore .",
"pretest": "npm run build:test",

0 comments on commit 0737982

Please sign in to comment.