Codegen

Introduction

Codegen implements a proxy based pattern to wrap underlying iOS and Android libraries to provide a C++ interface for them. It implements all the basic converters and JNI details under the hood, so you don't need to worry about them.

Setup

After cloning this repository, be sure to udpate and initialize all submodules with

$ git submodule update --init --recursive

Note, we depend on our parser https://github.com/proxy-gen/clocxml to parse ObjC header files properly. The gen_bridge_metadata script that came with MacOSX wasn't providing us with all the parse tokens we needed.

Using this tool

The main tool that you interface with is a python script that you can find under 'generator/generator.py'. On Android, we provide an additional convenience wrapper call 'codegen.sh' that you can find under samples for Android project.

Platform specific details are as follows

Android

Please follow along with the samples provided under codegen/samples

For Android we recommend that you interact with the wrapper codegen.sh script instead of directly invoking the generator/generator.py

Overall there are 3 steps to this process. a) You create a full blown config file from a minimal config file you seed the tool with b) You make an necessary changes to the generated config as required, and then you generate the C++ files that implements the proxy patterns. This also builds a static library c) Finally, you package them

samples/platforms/android/android: Contains the configuration setup to generate proxies for the entire Android SDK

First, setup the following environment variables

ANDROID_HOME=/path/to/android/sdk
NDK_HOME=/path/to/android/ndk
CODEGEN_HOME=/path/to/codegen

You would need to ensure that the Android SDK has the following installed

Build Tools for android-18 System Image for Android 2.2 (API 8).

Next, run the following in order under cxx

./codegen.sh --configure /path/to/minimum/config/file # Generates the full blown config
./codegen.sh --generate  # Generates the C++ proxy classes
./codegen.sh --package   # Packages the project as a pre-built binary

samples/platforms/android/facebook: Contains the configuration setup to generate proxies for the entire Facebook SDK.

Configuring this sample is similar to the steps above to generate the Android SDK but has the additional steps of requiring to build the facebook sdk and to add the _callback tags in the config.

For example, the com.facebook.Session#open function accepts an implementation of the callback com.facebook.Session$StatusCallback. At some point in the future, the native Facebook SDK will callback into com.facebook.Session$StatusCallback#call. We need to make sure that this call goes all the way through into the C++ layer and is handled by the C++ implementation of the callback.

By tagging the com.facebook.Session#open as a callback, we make sure that the code generator will propagate the callback invocation all the way into the C++ layer.

Before getting started, navigate to java\facebook-android-sdk-3.0.1\facebook and then run ant debug to build the facebook sdk

Then, as usual,

First, setup the following environment variables

ANDROID_HOME=/path/to/android/sdk
NDK_HOME=/path/to/android/ndk
CODEGEN_HOME=/path/to/codegen

You would need to ensure that the Android SDK has the following installed

Build Tools for android-18 System Image for Android 2.2 (API 8).

Next, run the following under cxx

./codegen.sh --configure /path/to/minimal/config/file # Generates the full blown config

Open up the full blown config file and add the _callback tag to the following classes and functions

'com.facebook.Request$Callback' 'com.facebook.Request$Callback#onCompleted' 'com.facebook.Request$GraphPlaceListCallback' 'com.facebook.Request$GraphPlaceListCallback#onCompleted' 'com.facebook.Request$GraphUserCallback' 'com.facebook.Request$GraphUserCallback#onCompleted' 'com.facebook.Request$GraphUserListCallback' 'com.facebook.Request$GraphUserListCallback#onCompleted' 'com.facebook.Session$StatusCallback' 'com.facebook.Session$StatusCallback#call'

Sample snippet of the changes are below

    {
        'name' : 'com.facebook.Request$Callback',
        'tags' : ['_interface', '_proxy', '_callback'],
        'fields' : [
        ],  
        'functions' : [
            {
                'name' : 'onCompleted',
                'tags' : ['_instance', '_proxy', '_callback'],
                'params' : [
        …
    }

Once the above is done, continue as before

Run the following in order under cxx

./codegen.sh --generate  # Generates the C++ proxy classes
./codegen.sh --package    # Packages the project as a pre-built binary

The samples/platforms/android/facebook\cxx\samples\SessionLoginSampleCXX is a sample C++ application that uses the Facebook SDK to perform basic tasks (Login/Logout/Get Friends)

iOS

The samples/platforms/ios/facebook directory contains an example of how to use this tool to generate proxies for nearly all of FacebookSDK.framework. The latest FacebookSDK framework is located in the objc subdirectory. An example of using the generated Facebook API to perform basic tasks is located under the TestFacebookCXX subdirectory. Two shell scripts wrap the --generate-config and --generate-code invocations of this tool under the cxx subdirectory. The input config file and generated code are also located under the cxx subdirectory.

First, run the generate_config.sh script from the cxx directory via

./generate_config.sh

It may take half a minute to create the AST of the FacebookSDK.framework headers and parse the metadata.

To build a static library for the armv7 and i386 architectures, change to the generated/project subdirectory and run make. The fat library will be located under the lib/fat subdirectory after completion.

Open the TestFacebookCXX Xcode project and notice that the target's Header Search Path settings contain the generated includes directory. Also notice that the project links with the fat library that we created with make. This project uses Objective-C for the UI, but all button callbacks are written in C++. You can build an run this project on the iOS Simulator.

Authors and Contributors

This project is open sourced as part of the work the Mobile ZDK team did for Zynga.com. Android work was lead by Ron Vergis (@rvergis), iOS work was lead by Wesley Souza (@wesjarrettsouza) and Andrew Ushnakov. The project and team was managed by Shiva Bhattacharjee (@bhattas)