[DEPRECATED] JavaScript bindings for Objective-C and C.zip

**Please note:** This project is deprecated at Zynga and is no longer maintained. --- # JavaScript Bindings for C and Objective-C ## Introduction JavaScript Bindings for C / Objective-C (JSB) is the "glue" code (or wrapper code) that sits between native code (C or Objective-C) and JavaScript (JS) code. JSB allows calling native code from JS and vice-versa. That means that you can interact with your favorite native library from JS. As an example, you could create a [cocos2d](http://www.cocos2d-iphone.org) particle system in JS, while its logic and rendering will be executed natively. Or you could create a [Chipmunk Physics](http://www.chipmunk-physics.net) world in JS, while the whole physics simulation, including the collisions detections, would run natively.  The JS code is interpreted by [SpiderMonkey](https://developer.mozilla.org/en-US/docs/SpiderMonkey), Mozilla's JS virtual machine (VM). It uses the latest stable version of SpiderMonkey (as of this writing it is v19.0). The JS VM is extended by JSB to support custom types, custom structures and Objective-C objects. JSB has a flexible set of rules that could be used to select the classes, methods, functions and structs to parse or ignore; which methods are callbacks; and renaming rules among some of its features. To ease the creation of these rules, it supports regular expressions. ## Major features Highlights of JSB: - Supports any Objective-C / C library - Automatically generates the JS bindings ("glue" code) - No need to modify the source code of your libraries, or the autogenerated code - Powerful set of rules and plugins to customize the generated JS API - Automatically converts JS objects/types into Objective-C objects/structs/ types and vice-versa - Supports "subclassing" native objects in JS - Supports callbacks - Automatically generates object oriented JS API from C libraries (provided that the C API is OO, like Chipmunk) ## Creating your own bindings ### Quick steps: Bindings Generation 1. Download [JSB](http://github.com/zynga/jsbindings) $ git clone git://github.com/zynga/jsbindings.git 2. Generate the BridgeSupport files for your project. Let's assume that your project is CocosDenshion $ cd ~/src/CocosDenshion/CocosDenshion $ gen_bridge_metadata -F complete --no-64-bit -c '-DNDEBUG -I.' *.h -o ~/some/path/CocosDenshion.bridgesupport 3. Generate complement files for your project $ cd ~/src/CocosDenshion/CocosDenshion $ ~/jsb/generate_complement.py -o ~/some/path/CocosDenshion-complement.txt *.h 4. Create a JSB config file for your project $ vim ~/some/path/CocosDenshion_jsb.ini 5. Run the JSB generator script $ ~/jsb/generate_jsb.py -c ~/som/path/CocosDenshion_jsb.ini 6. Include the recently autogenerated files and JSB source files in your Xcode project 7. Include [SpiderMonkey](https://github.com/zynga/Spidermonkey/) and [JRSwizzle](https://github.com/rentzsch/jrswizzle/) in your Xcode project _The CocosDenshion config files could be found here: [configs/CocosDenshion](https://github.com/zynga/jsbindings/tree/master/configs/CocosDenshion)_ ### Quick steps: Adding the bindings to your project 1. Include all the autogenerated files to your Xcode project. eg: `src/auto/js_bidnings_PROJECTNAME_classes.*`, `src/auto/jsb_PROJECTNAME_functions.*`, `src/auto/jsb_PROJECTNAME_auto_classes.*`, 2. Include the following `manual` files to your Xcode project. `src/manual/jsb_config.h`, `src/manual/jsb_core.*`, `src/manual/basic_conversions.*`. 5. For objective-c projects (not required for C-only projects like Chipmunk), you should include the following files: `src/manual/js_bindigns_NS_manual.*` 6. Add a registration file. Name it: `src/manual/jsb_PROJECTNAME_registration.mm`. See `src/manual/jsb_chipmunk_registration.mm` as an example. 7. Edit `src/manual/jsb_core.mm` and add a call your registration code. eg: // JSBCore class -(id) init { // ... JSB_register_PROJECTNAME(_cx, _object); // ... } 8. If you need to create manual JS bindings for your project, put those files int the `src/manual` directory. Name them: `/src/manual/js_bidnings_PROJECTNAME_manual.*` 9. If you need to further extend your code from JS, create a JavaScript file (eg: see `src/js/jsb_constants_chipmunk.js`), and place it in the `src/js` directory. 10. Add a `#define` to include your new bindings in `src/manual/jsb_config.h`. eg: ```c #ifndef JSB_INCLUDE_PROJECTNAME #define JSB_INCLUDE_PROJECTNAME 1 #endif // JSB_INCLUDE_PROJECTNAME ``` ### Steps in detail JSB comes with a python script called `generate_jsb.py` that generates the glue code. It needs a configuration file that contains the parsing rules and the [BridgeSupport](http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man5/BridgeSupport.5.html) files. BridgeSupport files are generated by a script called [`gen_bridge_metadata`](http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/gen_bridge_metadata.1.html#//apple_ref/doc/man/1/gen_bridge_metadata) that is part of OS X, and generates xml files with information like class names, method names, arguments, return values, internals of the structs, constants, etc. `gen_bridge_metadata`, internally, uses [`clang`](http://clang.llvm.org/) to parse the native code. The output is very reliable, but unfortunately, it is not complete: class hierarchy, protocols and properties data are missing. That's why JSB comes with another python script, called `generate_js_complement.py`, that generates the missing information. Once we have the configuration file setup, we can run the `generate_jsb.py` script to generate the glue code. To summarize, the structure of a JSB configuration file is: - Parsing rules (optional): renaming rules, classes to ignore / parse, etc... - BridgeSupport files (required): Class, methods, functions, structs information - Complement files (required for Objective-C projects): Hierarchy, protocol and properties information  ### The configuration file The configuration has a set of powerful rules that could transform the native API into a customized JS API. Let's take a look at some of them. #### Renaming rule The renaming rule allows us to rename a method names or class names or function names or struct names. As an example, the default JS API for: ```objc // CCAnimation (from cocos2d-iphone v2.0) +(id) animationWithAnimationFrames:(NSArray*)arrayOfAnimationFrames delayPerUnit:(float)delayPerUnit loops:(NSUInteger)loops; ``` would be: ```js // ugly cc.CCAnimation.animationWithAnimationFrames_delayPerUnit_loops_( frames, delay, loops ); ``` So, with a simple set of rules, we can rename that JS API into this one: ```js // more JS friendly cc.Animation.create( frames, delay, loops ); ``` In order to do that, we need to remove the `CC` prefix from the class name, since it is already using the `cc` JS namespace: `obj_class_prefix_to_remove = CC` And finally we add a rename rule for that method: `method_properties = CCAnimation # animationWithAnimationFrames:delayPerUnit:loops: = name:"create",` #### Merge rule But what happens with the other constructors of `CCAnimation` ? ```objc // CCAnimation supports 4 different constructors +(id) animation; // +(id) animationWithSpriteFrames:(NSArray*)arrayOfSpriteFrameNames; +(id) animationWithSpriteFrames:(NSArray*)arrayOfSpriteFrameNames delay:(float)delay; +(id) animationWithAnimationFrames:(NSArray*)arrayOfAnimationFrames delayPerUnit:(float)delayPerUnit loops:(NSUInteger)loops; ``` What we should do, is to create a rule that merges the 4 constructors into one. JSB will call the correct one depending on the number of arguments. This is how the rule should look: method_properties = CCAnimation # animationWithAnimationFram