Building

Foundation can currently build output packages for Desktop devices (Windows, Linux, OS X). More build targets (mobile) will be added soon. The first time you run a build command, additional dependencies will be downloaded.

To build your project, open a terminal / console in your project folder and run the tools/build script with a comma-separated list of targets to build. Do not include spaces in the list of build targets. The following example will build desktop applications for 64 bit Windows systems, 64 bit Linux systems, and 64 bit OS X systems:

node tools/build win64,linux64,osx64

Available Build Targets

Build Target Builds for: Output Output Location Available
win32 Desktop, Windows (32 bit) NW.js App output/[PROJECTNAME]/win32 0.7.0+
win64 Desktop, Windows (64 bit) NW.js App output/[PROJECTNAME]/win64 0.7.0+
linux32 Desktop, Linux (32 bit) NW.js App output/[PROJECTNAME]/linux32 0.7.0+
linux64 Desktop, Linux (64 bit) NW.js App output/[PROJECTNAME]/linux64 0.7.0+
osx64 Desktop, OS X (64 bit) NW.js App output/[PROJECTNAME]/osx64 0.7.0+
desktop All desktop targets NW.js Apps output/[PROJECTNAME]/[target] 0.7.0+
nwjs NW.js Package (no runtime) NW.js package output/nwjs 0.7.0+
android Mobile, Android Cordova Project See 'Cordova Output', below 0.8.0+
ios Mobile, iOS Cordova Project See 'Cordova Output', below 0.8.0+
windows Windows Universal App Platform Cordova Project See 'Cordova Output', below 0.8.0+
blackberry10 Mobile, Blackberry 10 Cordova Project See 'Cordova Output', below 0.8.0+
ubuntu Ubuntu Runtime Cordova Project See 'Cordova Output', below 0.8.0+

NW.js Output

Due to restrictions in an underlying dependency, Foundation builds projects against an older version of NW.js (0.12.3). As soon as the underlying dependency has been updated, Foundation's build process will be updated to allow for newer versions.

You can configure NW.js in your project's project.json file (look for the nwjs object). Please note that you do not need to add fields for project name or version as these will be inferred from your project settings. Additionally, your main file should be specified in the project configuration section, instead on in the NW.js section. If you do not specify a main file in the project section, the main file will default to game.html.

NW.js apps can seem large at first (approx. 100mb per target for a minimal template). However, once you zip them up for distribution they should be closer to half of that size (as little as 40mb for some targets). That's pretty decent for a self-contained distributable.

Please note that for Windows builds, the 32 bit target will work on both 32 bit and 64 bit systems. For Linux builds, the 32 bit target will generally only work on 32 bit systems (this depends on the user's system configuration).


Cordova Project

Foundation will not actually build Cordova outputs. Intstead, building for any Cordova target will:

  • Create a Cordova project if it does not exit. The project will be created in [project]/output/cordova.
  • Add any plugins listed in your project configuration file.
  • Add missing platforms to the Cordova project.
  • Update your Cordova configuration file (cordova/config.xml).
  • Copy your compiled project files to the cordova/www directory.

To run or build your cordova projects, cd into the created Cordova project and use the Cordova command line tools as normal. For example, to create and run an android app (in debug mode), open a terminal in you project folder and run the following sequence of commands:

node tools/build android
cd output/cordova
cordova run android

To build Cordova outputs, cordova must be a global command on your system (i.e. foundation does not bundle Cordova as a dependency). You can install Cordova globally with:

npm install -g cordova

Building for specific platforms will also require any relevant SDKs or runtimes. You can find out more about Cordova's platform support and requirements at:

You can configure your Cordova projects by adding a cordova entry to your project's configuration file ([project]/project.json). The following is an example entry which includes some useful plugins:

"cordova": {
  "widget": {
    "id": "com.my.app"
  },
  "plugins": [
    "cordova-plugin-crosswalk-webview",
    "cordova-plugin-fullscreen",
    "https://github.com/EddyVerbruggen/Insomnia-PhoneGap-Plugin.git",
    "cordova-plugin-screen-orientation"
  ]
}

Currently, the widget.id and plugins keys are the only values recognized by foundation. Additionally, the Cordova project's version, name, description, author info, and main file will all be set from the corresponding values in your project configuration file.

The cordova-plugin-crosswalk-webview plugin is recommended when building for Android. This plugin bundles a chromium-based web view with your application. The result is a more consistent experience across Android devices, but this does come at the cost of a higher memory footprint and a larger APK size. If you use this plug in (in default configuration), it will create separate APK files for x86 and armv7 architectures. These will be available in output/cordova/platforms/android/build/outputs/apk.

One final note: Currently, Foundation isn't overly performant on mobile devices. Performance improvements for mobile are on the road map.