.___ ____ ___________ __| _/_______ _______ _/ ___\/ _ \_ __ \/ __ |/ _ \ \/ /\__ \ \ \__( <_> ) | \/ /_/ ( <_> ) / / __ \_ \___ >____/|__| \____ |\____/ \_/ (____ / \/ PhoneGap\/Project Toolchain\/
A PhoneGap project toolchain that automates common tasks for building cross platform mobile projects with OS X.
Automate common development workflow tasks such as: compiling, debugging, testing, releasing and other things in between. As an added benefit projects generated with Cordova create a consistent, predictable, easy to understand and therefor extend software project. A number of conventions are introduced removing the need for mobile developers to relearn their tools or, worse, rebuild them for every project.
Currently Supported Platforms
Mobile development requires proprietary SDKs. The SDKs supported by this tool currently work well with OS X. If you are doing PhoneGap development on a Windows based machine for BlackBerry, Bada or Windows Phone 7 then a different tool chain is required (or, perhaps with contribution, this one will grow to accommodate other operating systems).
ios sdk .......... http://developer.apple.com android sdk ...... http://developer.android.com palm sdk ......... http://developer.palm.com ios-sim .......... https://github.com/Fingertips/ios-sim blackberry sdk ... http://us.blackberry.com/developers/browserdev/widgetsdk.jsp (for Windows) phonegap/ios ..... http://phonegap.com/download <-----------( run phonegap/ios/PhoneGapLibInstaller.pkg
- Make sure you have an Android AVD named
- Clone the repository.
- From the root of the Cordova folder, run: python setup.py install
- Add the following line to
~/.bash_profile: export PATH="$PATH:/path/to/cordova"
- Install the Blackberry WebWorks SDK on the Windows (virtual) machine on which you intend to run the simulator.
- Create a shared folder accessible by the Windows (virtual) machine pointing to /path/to/cordova
Generate a new PhoneGap project by running:
phonegap create PROJECTNAME --www [www recipe] --test [test recipe] ex., phonegap create MyProject --www vanilla
For further usage info try:
Generated Project Structure
Your generated project will look like this:
/AppName ...... Project name; not programatically meaningful. |-bin/ ........ Cordova scripts (DO NOT MODIFY). |-doc/ ........ Project documentation. |-lib/ ........ Place for *your* scripts/utils. |-test/ ....... Place for *your* app tests. |-tmp/ ........ Native app src. (GENERATED! Leave out of src control.) |-www/ ........ Place for *your* app files. `-Makefile ... Useful examples of commands. Yours to modify too.
From here try running
make to see what sort of useful commands you have available to you. Each of these
Makefile commands are packaged for each platform in the
./bin folder so, when needed, you can call scripts directly such as
Other important notes about the generated project:
./libfolder is your place for custom automations. Protip: make everything relative to the root of your project.
- The generated
Makefileis intended as an example only. Use it to extend in your own common automations. This is what computers are for, eh.
- There is further documentation in the
./docsfolder. You should put your project documentation there too.
- Place unit tests in
./testand copy in applicable js from
./www. This is the point of build automation!
- Put your app code, logic and assets in
./tmpdirectory is full of toxic proprietary build sludge. Interaction with it should limited as possible.
- Do read
./binscripts but only modify at risk of not getting future updates! Instead add your own to
- Blackberry only supports create, build, and debug make commands. Emulating or deploying the build requires either
ant load-devicerespectively to be performed on your Windows (virtual) machine.
A future release of Cordova will allow easy upgrading by simply overwriting
./bin and leave an example
Makefile if none is present. Happily modify
./test to develop your app.
Recipes are little packages of web code that initialize from an
index.html file. By default
phonegap will create a project with a bare bones (vanilla)
www/index.html and qunit starter project in the
test/index.html directory. In the future recipes will be added for all the major mobile dom frameworks like XUI, Sencha Touch and jQuery Mobile. If you'd like to see them sooner, have a look at
ROADMAP.md and consider contributing!
Generated MakeFile Commands
create .... writes out native code to ./tmp directory based on config.xml debug ..... copies www, compiles native src, installs and launches web ....... serve www at http://localhost:8000 weinre .... launch weinre at http://localhost:8080 test ...... compiles ./test into native log ....... launches logger release ... this is for you to implement! emulate ... launch platform emulators
You will need to install a modern Python, PIP and pyvows. On OSX this is pretty easy:
easy_install pip pip install pyvows
You may run into an error installing lxml dependency. Set your arch by:
export ARCHFLAGS='-arch i386 -arch x86_64'
And then continue pip installing away... from there you should be able to run:
And see the unit tests execute!