README
<!--
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.
-->
xface-cli
The command line tool to build, deploy and manage xFace-based applications.
xFace allows for building native mobile applications using HTML, CSS and JavaScript. This tool helps with management of multi-platform xFace applications as well as xFace plugin integration.
Check out the Getting Started guides for more details on how to work with xFace sub-projects.
Supported xFace Platforms
- Android
- iOS
- Windows Phone 8
Requirements
- Node.js
- SDKs for each platform you wish to support:
- Android: Android SDK - NOTE This tool
will not work unless you have the absolute latest updates for all
Android SDK components. Also you will need the SDK's
tools
andplatform-tools
directories on your system path otherwise Android support will fail. - Amazon Fire OS SDK - NOTE This tool will not work unless you have Android SDK installed and paths are updated as mentioned above. In addition you need to install AmazonWebView SDK and copy awv_interface.jar to corodva-amazon-fireos/framework/libs folder. If libs folder does not exist then create one.
- Windows Phone SDK - NOTE This tool will not work unless you have
msbuild
on your system path otherwise Windows Phone support will fail (msbuild.exe
is generally located inC:\Windows\Microsoft.NET\Framework\v4.0.30319
). - BlackBerry 10: BlackBerry 10 WebWorks SDK. Make sure you have the
dependencies/tools/bin
folder inside the SDK directory added to your path! - iOS: iOS SDK with the latest
Xcode
andXcode Command Line Tools
- Windows Phone: Windows Phone SDK - NOTE This tool will not work unless you have
msbuild
on your system path otherwise Windows Phone support will fail (msbuild.exe
is generally located inC:\Windows\Microsoft.NET\Framework\v4.0.30319
).
- Android: Android SDK - NOTE This tool
will not work unless you have the absolute latest updates for all
Android SDK components. Also you will need the SDK's
xFace-cli has been tested on Mas OS X, Linux, Windows 7 and Windows 8.
Please note that some platforms have OS restrictions. For example, you cannot build for Windows 8 or Windows Phone 7 & 8 on Mac OS X, nor can you build for iOS on Windows.
Install
Ubuntu packages are available in a PPA for Ubuntu 13.10 (Saucy) (the current release) as well as 14.04 (Trusty) (under development).
npm install -g xface
To build an application for the Ubuntu platform, the following extra packages are required:
sudo apt-get install cmake debhelper libx11-dev libicu-dev pkg-config qtbase5-dev qtchooser qtdeclarative5-dev qtfeedback5-dev qtlocation5-dev qtmultimedia5-dev qtpim5-dev qtsensors5-dev qtsystems5-dev
Installing from master
You'll need to install both CLI and Plugman from git
. Running the npm version of one and (git) master version of the other is likely to end with you suffering.
To avoid using sudo, see Get away from sudo: npm without root.
Run the following commands:
git clone https://git-wip-us.apache.org/repos/asf/cordova-plugman.git
cd cordova-plugman
npm install
sudo npm link
cd ..
git clone https://git-wip-us.apache.org/repos/asf/cordova-cli.git
cd cordova-cli
npm install
sudo npm link
npm link plugman
Now the cordova
and plugman
in your path are the local git versions. Don't forget to keep them up to date!
Getting Started
xface-cli has a single global create
command that creates new cordova projects into a specified directory. Once you create a project, cd
into it and you can execute a variety of project-level commands. Completely inspired by git's interface.
Global Commands
help
display a help page with all available commandscreate <directory> [<id> [<name>]]
create a new xface project with optional name and id (package name, reverse-domain style)
platform [ls | list]
list all platforms for which the project will buildplatform add <platform> [<platform> ...]
add one (or more) platforms as a build target for the projectplatform [rm | remove] <platform> [<platform> ...]
removes one (or more) platform build targets from the projectplatform [up | update] <platform>
- updates the Cordova version used for the given platformplugin [ls | list]
list all plugins included in the projectplugin add <path-to-plugin> [<path-to-plugin> ...]
add one (or more) plugins to the projectplugin [rm | remove] <plugin-name> [<plugin-name> ...]
remove one (or more) plugins from the project.plugin search [<keyword1> <keyword2> ...]
search the plugin registry for plugins matching the list of keywordsprepare [platform...]
copies files into the specified platforms, or all platforms. It is then ready for building byEclipse
,Xcode
, etc.compile [platform...]
compiles the app into a binary for each targetted platform. With no parameters, builds for all platforms, otherwise builds for the specified platforms.build [<platform> [<platform> [...]]]
an alias forxface prepare
followed byxface compile
emulate [<platform> [<platform> [...]]]
launch emulators and deploy app to them. With no parameters emulates for all platforms added to the project, otherwise emulates for the specified platformsserve [port]
launch a local web server allowing you to access each platform's www directory on the given port (default 8000).
Optional Flags
-d
or--verbose
will pipe out more verbose output to your shell. You can also subscribe tolog
andwarn
events if you are consuming xface-cli as a node module by callingxface.on('log', function() {})
orxface.on('warn', function() {})
.-v
or--version
will print out the version of your xface-cli install.
Project Directory Structure
A Cordova application built with cordova-cli will have the following directory structure:
myApp/
|-- config.xml
|-- hooks/
|-- merges/
| | |-- android/
| | |-- blackberry10/
| | `-- ios/
|-- www/
|-- platforms/
| |-- android/
| |-- blackberry10/
| `-- ios/
`-- plugins/
hooks/
This directory may contains scripts used to customize cordova commands. This
directory used to exist at .xface/hooks
, but has now been moved to the
project root. Any scripts you add to these directories will be executed before
and after the commands corresponding to the directory name. Useful for
integrating your own build systems or integrating with version control systems.
Refer to hooks-README.md for more information.
merges/
Platform-specific web assets (HTML, CSS and JavaScript files) are contained within appropriate subfolders in this directory. These are deployed during a prepare
to the appropriate native directory. Files placed under merges/
will override matching files in the www/
folder for the relevant platform. A quick example, assuming a project structure of:
merges/
|-- ios/
| `-- app.js
|-- android/
| `-- android.js
www/
`-- app.js
After building the Android and iOS projects, the Android application will contain both app.js
and android.js
. However, the iOS application will only contain an app.js
, and it will be the one from merges/ios/app.js
, overriding the "common" app.js
located inside www/
.
www/
Contains the project's web artifacts, such as .html, .css and .js files. These are your main application assets. They will be copied on a xface prepare
to each platform's www directory.
Your Blanket: config.xml
This file is what you should be editing to modify your application's metadata. Any time you run any xface-cli commands, the tool will look at the contents of config.xml
and use all relevant info from this file to define native application information. xface-cli supports changing your application's data via the following elements inside the config.xml
file:
- The user-facing name can be modified via the contents of the
<name>
element. - The package name (AKA bundle identifier or application id) can be modified via the
id
attribute from the top-level<widget>
element. - The version can be modified via the
version
attribute from the top-level<widget>
element. - The whitelist can be modified using the
<access>
elements. Make sure theorigin
attribute of your<access>
element points to a valid URL (you can use*
as wildcard). For more information on the whitelisting syntax, see the docs.phonegap.com. You can use either attributeuri
(BlackBerry-proprietary) ororigin
(standards-compliant) to denote the domain. - Platform-specific preferences can be customized via
<preference>
tags. See docs.phonegap.com for a list of preferences you can use. - The entry/start page for your application can be defined via the
<content src>
element + attribute.
platforms/
Platforms added to your application will have the native application project structures laid out within this directory.
plugins/
Any added plugins will be extracted or copied into this directory.
Hooks
Projects created by xface-cli have before
and after
hooks for each project command.
There are two types of hooks: project-specific ones and module-level ones. Both of these types of hooks receive the project root folder as a parameter.
Project-specific Hooks
These are located under the hooks
directory in the root of your xface project. Any scripts you add to these directories will be executed before and after the appropriate commands. Useful for integrating your own build systems or integrating with version control systems. Remember: make your scripts executable.
Examples
before_build
hook for jade template compiling courtesy of dpogue
Module-level Hooks
If you are using xface-cli as a module within a larger node application, you can also use the standard EventEmitter
methods to attach to the events. The events include before_build
, before_compile
, before_docs
, before_emulate
, before_run
, before_platform_add
, before_library_download
, before_platform_ls
, before_platform_rm
, before_plugin_add
, before_plugin_ls
, before_plugin_rm
and before_prepare
. There is also a library_download
progress event. Additionally, there are after_
flavours of all the above events.
Once you require('xface')
in your node project, you will have the usual EventEmitter
methods available (on
, off
or removeListener
, removeAllListeners
, and emit
or trigger
).
Examples
Creating a new xface project
This example shows how to create a project from scratch named KewlApp with iOS and Android platform support, and includes a plugin named Kewlio. The project will live in ~/KewlApp
xface create ~/KewlApp KewlApp
cd ~/KewlApp
xface platform add ios android
xface plugin add http://example.org/Kewlio-1.2.3.tar.gz
xface build
The directory structure of KewlApp now looks like this:
KewlApp/
|-- hooks/
|-- merges/
| |-- android/
| `-- ios/
|-- www/
| `-- index.html
|-- platforms/
| |-- android/
| | `-- …
| `-- ios/
| `-- …
`-- plugins/
`-- Kewlio/
Contributing
Running Tests
npm test
TO-DO + Issues
Please check [xFace issues with the CLI Component]. If you find issues with this tool, please be so kind as to include relevant information needed to debug issues such as:
- Your operating system and version
- The application name, directory location, and identifier used with
create
- Which mobile SDKs you have installed, and their versions. Related to this: which
Xcode
version if you are submitting issues related to iOS - Any error stack traces you received
Contributors
Thanks to everyone for contributing! For a list of people involved, please see the package.json
file.
Known Issues and Troubleshooting
Any OS
Proxy Settings
xface-cli
will use npm
's proxy settings. If you downloaded xface-cli via npm
and are behind a proxy, chances are xface-cli should work for you as it will use those settings in the first place. Make sure that the https-proxy
and proxy
npm config variables are set properly. See npm's configuration documentation for more information.
Windows
Trouble Adding Android as a Platform
When trying to add a platform on a Windows machine if you run into the following error message: xface library for "android" already exists. No need to download. Continuing. Checking if platform "android" passes minimum requirements... Checking Android requirements... Running "android list target" (output to follow)
Error: The command `android` failed. Make sure you have the latest Android SDK installed, and the `android` command (inside the tools/ folder) added t
o your path. Output:
at C:\Users\me\AppData\Roaming\npm\node_modules\xface\src\platform.js:185:42
at C:\Users\me\AppData\Roaming\npm\node_modules\xface\src\metadata\android_parser.js:50:13
at C:\Users\me\AppData\Roaming\npm\node_modules\xface\node_modules\shelljs\shell.js:1707:7
at exithandler (child_process.js:633:7)
at ChildProcess.errorhandler (child_process.js:649:5)
at ChildProcess.EventEmitter.emit (events.js:95:17)
at Process.ChildProcess._handle.onexit (child_process.js:787:12)
run the command android list target
. If you see:
'xcopy' is not recognized as an internal or external command,
operable program or batch file.
at the beginning of the command output, it means you will need to fix your Windows Path variable to include xcopy. This location is typically under C:\Windows\System32.
Windows 8
Windows 8 support does not include the ability to launch/run/emulate, so you will need to open Visual Studio to see your app live. You are still able to use the following commands with windows8:
platform add windows8
platform remove windows8
prepare windows8
compile windows8
build windows8
To run your app, you will need to open the .sln
in the platforms/windows8
folder using Visual Studio 2012.
Visual Studio will tell you to reload the project if you run any of the above commands while the project is loaded.
Amazon Fire OS
Amazon Fire OS does not include the ability to emulate. You are still able to use the following commands with Amazon Fire OS
platform add amazon-fireos
platform remove amazon-fireos
prepare amazon-fireos
compile amazon-fireos
build amazon-fireos
Ubuntu
The initial release of cordova-ubuntu does not support building applications for armhf devices automatically. It is possible to produce applications and click packages in a few steps though.
This bug report documents the issue and solutions for it: https://bugs.launchpad.net/ubuntu/+source/cordova-ubuntu/+bug/1260500 A future release will let developers cross-compile armhf click packages directly from an x86 desktop.
Firefox OS
Firefox OS does not include the ability to emulate, run and serve. After building, you will have to open the firefoxos platform directory of your app in the App Manager that comes with every firefox browser.