Ionic Build Tools
A template app using the Ionic Framework and AngularJS to demonstrate a set of Gulp build tools.
Before using, check the TODOs marked in the
A brief tour of the repository:
img/- the application's images
js/- the application's scripts
scss/- the application's scripts
templates/- the AngularJS templates
index.html- the AngularJS application loader
www/- this is the build output directory that Ionic injects into the Cordova applications. You shouldn't be editing anything in this directory. The contents are overwritten by the Gulp build process.
lib/- this is one exception to the above - Bower installs frontend dependencies directly into www/lib
Install the Node packages required:
sudo npm install -g ionic sudo npm install -g cordova # if you want to run the iOS emulator, install the following dependency # NOTE: THIS REQUIRES XCode 5.1.1 WHICH REQUIRES OS X MAVERICKS # if you're not running the iOS simulator, you can skip this dependency sudo npm install -g ios-sim npm install # we also need a couple of local versions, so we have it available for the hooks/after_prepare npm install cordova npm install cordova-lib npm install gulp # we needed to run this to get the node binary installed
Install ImageMagick for icon processing:
brew update brew install imagemagick --build-from-source
(We need to use the build from source option in Mac OS X Mavericks to get PNG support. If that fails, see https://github.com/Homebrew/homebrew/issues/14325#issuecomment-45429003 )
Check to make sure that NPM modules are added to your path. If not, and you installed Node via Homebrew, add this to your .zshrc/.bashrc:
# add node_modules to path export PATH=$PATH:./node_modules/.bin
Install the Android SDK - download from: http://developer.android.com/sdk/index.html
Extract the SDK and move the folder into
Create a symlink to the extracted version:
cd ~/Development ln -s adt-bundle-mac-x86_64-20140321 adt-bundle
Add the SDK to your path - edit
# add android dev tools to path export PATH=$PATH:~/Development/adt-bundle/sdk/platform-tools:~/Development/adt-bundle/sdk/tools
Ensure Java is installed
Install Ant through Homebrew:
brew update brew install ant
Create an emulator image:
android create avd --name kitkat --target android-19
For help, see the Cordova Android Platform Guide: http://cordova.apache.org/docs/en/3.4.0/guide_platforms_android_index.md.html
Building & Testing
For the build commands, you can control the build target using the
BUILD_TARGET environment variable, which switches between the development / staging / production environments.
app/js/config/config.js to see some of the elements switched based on the build target. Environment specific code is switched throughout the app using https://github.com/jas/gulp-preprocess
The primary configuration the build target controls is the API hostname:
Information on setting the BUILD_TARGET environment variable on Windows: https://github.com/shedd/ionic_build_tools/issues/1
Local Browser Testing
Run the default gulp task to build the application code, start the watch task, and load it on the local Ionic testing server with LiveReload enabled:
See more about testing here: http://ionicframework.com/docs/guide/testing.html
Running Development Builds on Emulators
First, do a recompile:
BUILD_TARGET=development gulp compile
This will be combined back into the
build command, but struggling with async/sync gulp tasks
Kick-off the build for the platform you want to test:
BUILD_TARGET=development gulp build --ios BUILD_TARGET=development gulp build --android
If you want to run the build on the platform's emulator, add the
BUILD_TARGET=development gulp build --ios --run BUILD_TARGET=development gulp build --android --run
This section is still in progress.
See more about publishing here: http://ionicframework.com/docs/guide/publishing.html
Compile the code
Compile the code & build for iOS, configured for the environment desired - do this before opening XCode:
gulp patch BUILD_TARGET=staging gulp compile --release BUILD_TARGET=staging gulp build --ios --release
gulp patch BUILD_TARGET=production gulp compile --release BUILD_TARGET=production gulp build --ios --release
Setup iOS Device for Development
- Open the XCode project that Cordova generates
- Plug in your test device
- In the XCode Organizer window, click Use for Development
- XCode will prompt you to add the device to an iOS Developer account
- XCode will prompt you to generate a certificate
Deploy to Device
- Use the USB cable to plug the device into your Mac.
- Select the name of the project in the Xcode window's Scheme drop-down list.
- Select your device from the Device drop-down list. If it is plugged in via USB but still does not appear, press the Organizer button to resolve any errors.
- Press the Run button to build, deploy and run the application on your device.
Follow these instructions to setup your device for testing: http://developer.android.com/tools/device.html
Setup Code Signing
Unless you are changing something, this has already been setup for you.
Generate a new key if needed:
keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -keysize 2048 -validity 10000
With the details from the key you just generated, create an
ant.properties file in
platforms/android with the following content (as discussed here: http://stackoverflow.com/questions/20402818/build-android-release-apk-on-phonegap-3-x-cli/22979830#22979830):
This will mean you'll be prompted for your keystore password during the build process.
Configure the keystore password
secure.properties file in
platforms/android to contain the keystore password.
The content of
secure.properties should be the following (as discussed here http://stackoverflow.com/a/14765511/139934):
key.store.password=<your keystore password> key.alias.password=<your alias password>
(This file is in the
.gitignore and will NOT be checked into version control.)
This file is referenced in
Run the build
The release build has been scripted via Gulp to automate build cleaning.
gulp patch BUILD_TARGET=staging gulp compile --release BUILD_TARGET=staging gulp build --android --release
gulp patch BUILD_TARGET=production gulp compile --release BUILD_TARGET=production gulp build --android --release
By default, the build output file ends up in the 'platforms/android/ant-build' directory already signed and aligned and ready to deploy.
The Gulp script copies the output apk to
./release_builds/ with the timestamp appended.
You can install this to your device using
adb as follows:
adb install -r ./release_builds/release.apk
Summarized Production Release Sequence
gulp patch BUILD_TARGET=production gulp compile --release BUILD_TARGET=production gulp build --ios --release BUILD_TARGET=production gulp compile --release BUILD_TARGET=production gulp build --android --release
Bump app versions
Every time a build is release, the app's versions should be bumped in the relevant files.
gulp commands have been implemented to bump the version.
The app is versioned with semantic versioning - please see http://semver.org
- MAJOR ("major") version when you make incompatible API changes -- major: 1.0.0
- MINOR ("minor") version when you add functionality in a backwards-compatible manner -- minor: 0.1.0
- PATCH ("patch") version when you make backwards-compatible bug fixes. -- patch: 0.0.2
- PRERELEASE ("prerelease") a pre-release version -- prerelease: 0.0.1-2
You can use the commands
gulp patch # makes v0.1.0 → v0.1.1 gulp feature # makes v0.1.1 → v0.2.0 gulp release # makes v0.2.1 → v1.0.0 gulp prerelease # makes v0.2.1-2 → v1.0.0-2
Android ADB Quick Reference
adb devices # see Android devices attached to system adb install <file.apk> # install apk to device adb install -r <file.apk> # replace existing file.apk while preserving data adb shell screenrecord --time-limit 10 /sdcard/demo.mp4 # take a screencast of device for 10 seconds adb pull /sdcard/demo.mp4 # retrieve file from device
Resolving error 'Not an Android project'
If when running a Cordova command, you get an error like the following:
The provided path "/Code/.../platforms/android" is not an Android project.
This is because
AndroidManifest.xml, which is preprocessed for builds, does not currently exist in
gulp process-android-build-config --android which will generate another version for you and you should be set.
Installing New Dependencies
Currently, frontend dependencies (i.e. those loaded by Angular) are managed by Bower via
bower.json. Install new dependencies via Bower as follows:
bower install dependency --save
Build dependencies (i.e. gulp) are managed by NPM via
package.json. Install new development dependencies via NPM as follows:
npm install dependency --save-dev
JS-Hint is integrated into Gulp. Run:
Customizing Ionic with SASS
See this guide on customizing Ionic using SASS: http://ionicframework.com/tutorials/customizing-ionic-with-sass/
To update to a new version of Ionic, open bower.json and change the version listed there.
For example, to update from version
1.0.0-beta.5, open bower.json and change this:
After saving the update to bower.json file, run
Alternatively, install bower globally with
npm install -g bower and run
Using the Nightly Builds of Ionic
If you feel daring and want use the bleeding edge 'Nightly' version of Ionic, change the version of Ionic in your bower.json to this:
Warning: the nightly version is not stable.
XCode: Code Signing Failed: Check that the identity you selected is valid
It seems that XCode has real problems with directory structures in Resources. Check the System Console because it seems that this is where the errors are spit out.
The one time this happened to me, a
node_modules directory ended up getting caught in the
www/lib directory from building a dependency. Deleting this fixed the issue. Don't forget to remove this from the platforms copy of the www directory, too.