<commit_before>A unified JavaScript layer for [Apache Cordova](http://incubator.apache.org/projects/callback.html) projects.

# Project Structure

    cordova-js
      |
      |-build/
      | Will contain any build modules (currently nothing here as it is all hacked
      | into the JakeFile)
      |
      |-lib
      |  |-bootstrap.js
      |  | Code to bootstrap the Cordova platform, inject APIs and fire events
      |  |
      |  |-builder.js
      |  | Injects in our classes onto window and navigator (or wherever else is needed)
      |  |
      |  |-channel.js
      |  | A pub/sub implementation to handle custom framework events 
      |  |
      |  |-cordova.js
      |  | Common Cordova stuff such as callback handling and
      |  | window/document add/removeEventListener hijacking 
      |  | 
      |  |-utils.js
      |  | General purpose JS utility stuff: closures, uuids, object
      |  | cloning, extending prototypes
      |  |
      |  |-exec/
      |  | Contains the platform specific definitions of the exec method
      |  |
      |  |-platform/
      |  | Definitions of each platform that help us describe where
      |  | and what to put on the window object, and what to run to
      |  | initialize the platform. A common set of globals are also
      |  | defined (common.js)
      |  |
      |  |-plugin/
      |  |  | All API definitions as plugins, ones common to all
      |  |  | platforms reside at the top level...
      |  |  `-<platform>
      |  |    ... and platform-specific ones reside in their respective
      |  |    folders

# Building

Make sure you have [node.js](http://nodejs.org) installed. It
should come pre-installed with [npm](http://npmjs.org) - but if you
install node and can't run `npm` then head over to the website and
install it yourself. Make sure you have all of the node dependencies
installed by running the following command from the repository root:

    npm install

Then all of the build tasks can be run via the `jake` node module.
Install it globally first by running:

    npm install -g jake

Then from the repository root run:

    jake

This will run the "build" and "test" tasks by default. All of the available tasks
are:

- build: creates platform versions of cordova-js and builds them into
  the `pkg` directory.
- test: runs all of the unit tests inside node.
- btest: creates a server so you can run the tests inside a browser.
- clean: cleans out the `pkg` directory

# How It Works

The `build/packager.js` tool is a node.js script that concatenates and
wraps various .js files with a RequireJS-compatible module syntax in this
project together to generate cordova.js files that are compatible
to the various supported platforms. Check that script out to figure out
how and in what order the various files are concatenated together.

We end up with a script file that has a ton of `define` calls, wrapping
each Cordova API or object into its own module. Next, the Cordova bridge is initialized with the
help of `lib/bootstrap.js`. This file attaches the `_self.boot` function
once the `channel.onNativeReady` event is fired - which should be fired
from the native side (native should call `require('cordova/channel).onNativeReady.fire()`).
Finally, the `boot` method is where the magic happens.  First, it grabs
the common platform definition (as defined under
`lib/platform/common.js`) and injects all the objects defined in there
onto `window` and other global namespaces. Next, it grabs all of the platform-specific object
definitions (as defined under `lib/platform/<platform>.js`) and
overrides those onto `window`. Finally, it calls the platform-specific
`initialize` function (located in the platform definition). At this
point, Cordova is fully initialized and ready to roll, however, before<commit_msg>added warning about mac os x lion + node v0.6.10 and dependencies<commit_after>A unified JavaScript layer for [Apache Cordova](http://incubator.apache.org/projects/callback.html) projects.

# Project Structure

    cordova-js
      |
      |-build/
      | Will contain any build modules (currently nothing here as it is all hacked
      | into the JakeFile)
      |
      |-lib
      |  |-bootstrap.js
      |  | Code to bootstrap the Cordova platform, inject APIs and fire events
      |  |
      |  |-builder.js
      |  | Injects in our classes onto window and navigator (or wherever else is needed)
      |  |
      |  |-channel.js
      |  | A pub/sub implementation to handle custom framework events 
      |  |
      |  |-cordova.js
      |  | Common Cordova stuff such as callback handling and
      |  | window/document add/removeEventListener hijacking 
      |  | 
      |  |-utils.js
      |  | General purpose JS utility stuff: closures, uuids, object
      |  | cloning, extending prototypes
      |  |
      |  |-exec/
      |  | Contains the platform specific definitions of the exec method
      |  |
      |  |-platform/
      |  | Definitions of each platform that help us describe where
      |  | and what to put on the window object, and what to run to
      |  | initialize the platform. A common set of globals are also
      |  | defined (common.js)
      |  |
      |  |-plugin/
      |  |  | All API definitions as plugins, ones common to all
      |  |  | platforms reside at the top level...
      |  |  `-<platform>
      |  |    ... and platform-specific ones reside in their respective
      |  |    folders

# Building

Make sure you have [node.js](http://nodejs.org) installed. It
should come pre-installed with [npm](http://npmjs.org) - but if you
install node and can't run `npm` then head over to the website and
install it yourself. Make sure you have all of the node dependencies
installed by running the following command from the repository root:

    npm install

Then all of the build tasks can be run via the `jake` node module.
Install it globally first by running:

    npm install -g jake

Then from the repository root run:

    jake

This will run the "build" and "test" tasks by default. All of the available tasks
are:

- build: creates platform versions of cordova-js and builds them into
  the `pkg` directory.
- test: runs all of the unit tests inside node.
- btest: creates a server so you can run the tests inside a browser.
- clean: cleans out the `pkg` directory

## Known Issues

- On Mac OS 10.7.3, there were issues with the contextify module not
	being able to build properly when using node v0.6.10 and running `npm
	install`. Using node v0.6.6 works, though.

# How It Works

The `build/packager.js` tool is a node.js script that concatenates and
wraps various .js files with a RequireJS-compatible module syntax in this
project together to generate cordova.js files that are compatible
to the various supported platforms. Check that script out to figure out
how and in what order the various files are concatenated together.

We end up with a script file that has a ton of `define` calls, wrapping
each Cordova API or object into its own module. Next, the Cordova bridge is initialized with the
help of `lib/bootstrap.js`. This file attaches the `_self.boot` function
once the `channel.onNativeReady` event is fired - which should be fired
from the native side (native should call `require('cordova/channel).onNativeReady.fire()`).
Finally, the `boot` method is where the magic happens.  First, it grabs
the common platform definition (as defined under
`lib/platform/common.js`) and injects all the objects defined in there
onto `window` and other global namespaces. Next, it grabs all of the platform-specific object
definitions (as defined under `lib/platform/<platform>.js`) and
overrides those onto `window`. Finally, it calls the platform-specific
`initialize` function (located in the platform definition). At this
point, Cordova is fully initialized and ready to roll, however, before
{'fraction_non_alphanumeric': 0.07150127226463104, 'fraction_numerical': 0.0019083969465648854, 'mean_word_length': 2.9641956631366617, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4165622', 'n_tokens_mistral': 2178, 'n_tokens_neox': 2078, 'n_words': 1023}