README.md

Crosswalk-app-tools

Crosswalk-app-tools is our forthcoming packaging tool for creating Crosswalk applications. We are inviting early adopters to build their web applications using crosswalk-app-tools, and provide feedback for future improvements.

Installation

The tools are cross-platform by virtue of being based on Node.js. We are supporting Microsoft Windows, Apple OS X and Linux as host operating systems.

The following components are required

• Node.js and NPM
• Android development (APK packages): Android SDK with 5.0 (target-21) or later installed, plus Java JDK and Apache Ant. Supported host systems are Apple OS X, Linux, and Windows.
• Windows development (MSI packages): WiX Toolset. MSI installers can only be created on Windows systems.

In order to get the tools available from the command-line easily, global npm installation is recommended.

Microsoft Windows: npm install -g crosswalk-app-tools

Apple OS X and Linux: sudo npm install -g crosswalk-app-tools

The best way to check if a machine has all the required dependencies is to create and build a plain empty Android app on the system. If this does not work, then building Crosswalk apps will not succeed either. App-tools provides a command for doing this:

Check Android target setup:

crosswalk-app check android

Check Windows target setup:

crosswalk-app check windows

Two executables are provided, crosswalk-app implements low level helper commands, crosswalk-pkg is the main tool for creating packages.

Usage (crosswalk-pkg --help)

  Crosswalk Project Packaging Tool -- https://crosswalk-project.org
  Usage: crosswalk-pkg <options> <path>

  <options>
    -a --android=<android-conf>      Extra configurations for Android
    -c --crosswalk=<version-spec>    Specify Crosswalk version or path
    -h --help                        Print usage information
    -k --keep                        Keep build tree for debugging
    -m --manifest=<package-id>       Fill manifest.json with default values
    -p --platforms=<target-systems>  Specify target platform
    -r --release                     Build release packages
    -s --skip-check                  Skip host setup check before building
    -t --targets=<target-archs>      Target CPU architectures
    -v --version                     Print tool version
    -w --windows=<windows-conf>      Extra configurations for Windows

  <path>
    Path to directory that contains a web app

  <android-conf>
    Quoted string with extra config, e.g. "shared"
    * "shared" Build APK that depends on crosswalk in the Google Play Store
    * "lite"   Use crosswalk-lite, see Crosswalk Wiki

  <package-id>
    Canonical application name, e.g. com.example.foo, needs to
    * Comprise of 3 or more period-separated parts
    * Begin with lowecase letters

  <target-archs>
    List of CPU architectures for which to create packages.
    Currently supported ABIs are: armeabi-v7a, arm64-v8a, x86, x86_64
    * Prefixes will be matched, so "a","ar", or "arm" yield both ARM APKs
    * Same for "x" and "x8", but "x86" is an exact match, only x86-32 conforms
    * Short-hands "32" and "64" build ARM and x86 for the requested word size
    * Default behavior is equivalent to "32", creation of 32-bit installers
    Example: --targets="arm x86" builds both ARM plus 32-bit x86 packages

  <target-systems>
    List of operating systems for which to create packages.
    Default is android-only, which is supported on Apple OSX, Linux and Windows
    Creating Windows MSIs is supported on Microsoft Windows only.
    Example: --platforms="android windows"

  <version-spec>
    * Channel name, i.e. stable/beta/canary
    * Version number, e.g. 14.43.343.25
    * Path to release, e.g. $HOME/Downloads/crosswalk-14.43.343.25.zip
    * Path to build, e.g. crosswalk/src/out/Release/xwalk_app_template
    When passing a local file or directory, only the contained ABIs can be built.
    See <target-archs> for details.

  <windows-conf>
    Quoted string with extra config, e.g. "google-api-key:<name>"
    where <name> is the keyset in ~/.crosswalk-app-tools-keys.json

  Environment variables
    CROSSWALK_APP_TOOLS_CACHE_DIR=<path>: Keep downloaded files in this dir

Example: Creating and packaging an application

To get started, all you need is a web manifest, and an html file. The web manifest holds name and settings for your application. A minimal manifest.json looks like this:

{
  "name": "My first Crosswalk application",
  "start_url": "index.html",
  "xwalk_package_id": "com.example.foo"
}

Then add an index.html in the same directory:

<html>
  <head>
    <title>My first Crosswalk application</title>
  </head>
  <body>This is my first Crosswalk application</body>
</html>

Finally, time to create the APK package:

crosswalk-pkg <path>

Creation of an MSI package on Windows:

crosswalk-pkg -p windows <path>

This sets up a skeleton project, downloads and imports Crosswalk, and creates a package using the files above.

Next steps and limitations

• Android release packages will have to be signed manually before they are published on Google's Play Store, as that functionality is not yet integrated. See https://developer.android.com/tools/publishing/app-signing.html#signing-manually for details.
• We encourage everyone to use this app-tools and appreciate feedback, as we are looking to improve user friendliness and integration with Crosswalk in the coming releases.

Additional target platforms

There is forthcoming support for additional target platforms. For iOS packaging, see https://github.com/crosswalk-project/crosswalk-app-tools-ios.

Run development versions from git

1. Download: npm install https://github.com/crosswalk-project/crosswalk-app-tools.git
2. The main script is crosswalk-app-tools/src/crosswalk-pkg. Set environment PATH or invoke with directory.

License

The license for this project is the Apache License Version 2.0, please refer to the LICENSE-APACHE-V2 included with the package for details.