dpogue / seymour

A build helper for Apache Cordova projects.

Seymour

Seymour is a build helper for Apache Cordova projects.

It takes configuration from environment variables, making it ideal for use in continuous integration environments with a matrix of platforms and build types.

Usage

Install Seymour:

npm install --save-dev seymour

Run Seymour on your Cordova project:

npx seymour

How it works

Seymour requires your Cordova platforms and plugins to be listed in your config.xml file. It will effectively run the following:

cordova prepare
cordova build --device

You can control additional behaviour through environment variables.

To update the config.xml file without running a build, you can run Seymour with the --config-only flag.

Future Features

• Collect the resulting build artefacts into a top-level output directory

Configuration

The following environment variables will be used by Seymour to alter the resulting build:

SEY_BUILD_MODE

• Valid options: debug, release
• Default value: debug

SEY_BUILD_PLATFORMS

• Valid options: A comma-separated list of Cordova platforms to build
• Default value: Use the platforms listed in config.xml

You cannot use this to add new platforms that are not listed in config.xml. You can only use this to restrict to a subset of platforms.

SEY_BUILD_CONFIG

The name of a JSON file containing build signing information.

See the following Cordova documentation for JSON options:

• Android
• iOS
• Windows

SEY_BUILD_NUMBER

This will override the build version number (not the application version) defined in config.xml.

This corresponds to the iOS CFBundleVersion and the Android versionCode.

SEY_APP_NAME

This will override the application name defined in config.xml.

SEY_APP_SHORTNAME

This will override the application display name defined in config.xml.

SEY_APP_ID

This will override the application identifier defined in config.xml.

SEY_APP_VERSION

This will override the application version defined in config.xml.

SEY_VERBOSE

This will enable verbose logging from the Cordova build commands.

SEY_PREFERENCE_*

This will allow you to set and override preferences globally in config.xml.

For example, you could specify SEY_PREFERENCE_backgroundColor=FF0000FF to override the backgroundColor preference in config.xml.

SEY_*_PREFERENCE_*

This will allow you to set and override platform specific preferences in config.xml.

For example, you could specify SEY_IOS_PREFERENCE_SasApiKey=123456789 to override the SasApiKey preference nested in the ios platform in config.xml.

Contributing

Contributions of bug reports, feature requests, and pull requests are greatly appreciated!

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Licence

Copyright © 2015-2023 Darryl Pogue & Ayogo Health Inc.
Licensed under the Apache 2.0 Licence.

seymour's Issues

Don't use .npmignore - Use "files" in package.json.

Use the files array from package.json to include files / folders in the package. It's like ".npmignore" but reversed. The use of .npmignore is not recommended and takes a lot of effort to maintain. The result is a package of junk and potentially sensitive files.

Currently there are following files in package:

• .github (*)
• bin/
• src/ (*)
• .editorconfig (*)
• .eslintrc (*)
• etc...

(*) Should not included.
Ok your "src" folder is also your "dist". Concider to rename it to "lib", "dist" or in root as "index.js" if you don't want to compile / deploy.

See NPM docs

Example: package.json (Snippet)

{
  "files": [
    "bin",
    "lib"
  ]
}

The package.json itself is automatically in a package. And the related files like license. But to validate the content of the package you can use the command: npm pack. This will generate the tarball without publishing. You can extract it with e.g. 7zip.

Turn on CodeQL scanning

https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/enabling-code-scanning-for-a-repository

GitHub has a new security scanning tool that's available through GitHub Actions. It looks pretty easy to set up, would be nice to integrate into the existing PR and CI runs.

Drop the seymour.cmd batch script

This shouldn't be needed anymore for Windows, and people should be encouraged to run node module binaries using something like npx

Refactor to ESM

Although seymour is available as an library, I'm pretty sure anyone using it is using it as a binary.

Allow overriding custom values in config.xml

Hi,

As far as I understand it, your project seems to permit to easily customize the config.xml according to some env variables. I'd like to use that to create different config.xml files according to the release context (dev/staging/prod)

But I have preferences that have to vary per env. Is it possible to configure the values based on some env variable?

    <preference name="intercom-app-id" value="f91b67651d379de0exxx1d3452d94ab6"/>
    <preference name="intercom-ios-api-key" value="ios_sdk-d9bab7918bc78823fxxxxxee885965"/>
    <preference name="intercom-android-api-key" value="android_sdk-2a841db307c589becddxxx5bd9065a9a153e"/>

Also, instead of using env variables, wouldn't it be great to have a json with all the things we want to override?

Documentation: SEY_BUILD_TYPE => SEY_BUILD_MODE

The SEY_BUILD_TYPE environment variable does not work - no matter how it is set, you get a debug build.

Looking at the code, I can see that a variable SEY_BUILD_MODE will, if set to 'release', produce a release build. Otherwise you get a debug build.

Please update the documentation with the correct variable name.

Tested on v2.1.0, since I'm trying to add Seymour to a Cordova 7.1.0 project, but it looks like this is also the case in v5.0.0.

Remove "elementtree" and other unused dependencies.

The package "elementtree" is unused, right? See src/seymour.js:

var et = require('elementtree');

et is never read. And there is no more require of elementtree.

Option to generate config.xml without building

Updating config.xml based on envvars is something a lot of people find useful, but sometimes they don't want to immediately invoke the build steps. This is definitely the case when they're using tools like Ionic that need to run their own additional build steps.

There should be a --no-build or --config-only flag that stops Seymour after writing the updated config.xml file.

Drop Node 12 and 14 support (and 16?)

TBD what to do about node 16, which will be EOL in September 2023.
As a general rule, seymour supports whatever versions of node are supported by Cordova.

Dropping Node 16 would allow using the Node Test Runner and removing the tap dependency. I guess one option would be to support running seymour with Node 16, but only run CI tests on Node 18+. I don't love it, but it's an option (and Node 16 will be EOL anyways, so maybe it's fine?)