Linked Source Files Across PhoneGap Projects on OSX

If you are manually building PhoneGap projects across multiple platforms, managing source files can sometimes become a little bit tricky. If you are building for Android, you need a project within Eclipse. If you are building for iOS, you need a project within Xcode. If you are building for both, you need to make sure that the code in the Eclipse project is in synch with the code in the Xcode project so that the platform-specific apps are in parity with each other.

Keeping the project source code in synch can be achieved using manual copy/paste between projects, but this is messy and error prone. The synchronization can also be scripted using ANT or other scripting language, but this requires an additional script and/or step in your build process. Although scripting is a reliable process, sometimes you just don’t need the script.

If you don’t want to manually synch things, and you don’t want a script, you can use a symlink to link directory paths. Basically, create a “src” folder outside of each project, and create a symlink reference to the src folder inside of the “www” folder for each project.   Symlinks allow a logical directory mapping, which actually points to another location on the hard disk.

From the command line, you just use the following command:

ln -s source target

To setup your project, first create your directory structure.  I created a parent folder for the project. Inside of that folder, I created a “project-ios” folder, “project-android” folder, and “src” folder.   The “src” folder will contain the shared HTML/JavaScript for the application.   The “project-ios” folder will contain the Xcode project, and the “project-android” folder will contain the Eclipse project.

Project Structure

Next, create the actual iOS and Android projects inside of these folders, following the normal setup instructions:

Once you have set up both projects, you’ll need to configure the symlinks.   Put a copy of the “index.html” file into your “src” directory.  Next, go to the “www” directory for each project and delete the “index.html” file to remove any ambiguity or chance for error.


The phonegap.1.4.1.js files are platform specific.  The Android version will not work with iOS, and the iOS version will not work with Android.

Next, navigate to your root folder that contains the “src”, “project-iOS”, and “project-Android” folders. Here you will create the actual symlink references.   When doing so, be sure to use the full path to the source and target destinations.  You will need to create a symlink reference from the “src” directory to “project-ios/www/src”, and a symlink reference from the “src” directory to “project-android/assets/www/src”.

If you try to use a relative path from your current location, it will give you errors and a massive headache.     You can use “pwd” to get a reference to the full path of your current directory.

Here are the commands that I used on my system, where the root directory is “/Users/triceam/Documents/dev/phonegap-sharedsource”:

[bash]ln -s /Users/triceam/Documents/dev/phonegap-sharedsource/src/ /Users/triceam/Documents/dev/phonegap-sharedsource/project-ios/www/src
ln -s /Users/triceam/Documents/dev/phonegap-sharedsource/src/ /Users/triceam/Documents/dev/phonegap-sharedsource/project-android/assets/www/src[/bash]

You can see this in my console in the image below:

Create Symlinks

This will create logical links to the root “src” folder, which can be treated like any other directory structure.

Symlink References

In both Eclipse and Xcode, this will show up as a normal folder.  Any edits in one IDE will show up in the other IDE since they are pointing to the same physical directory on the hard disk.

Content in Eclipse & Xcode

Next, you’ll need to update the PhoneGap projects to point to the shared index.html file.

In the Eclipse project, open your main Android activity and change the call to super.loadUrl to refer to the index.html file inside of the linked “src” directory in the onCreate method.

[java]public void onCreate(Bundle savedInstanceState) {

In the iOS project, open AppDelegate.m. You’ll also need to update it to reference the index.html file inside of “src”. You’ll just need to edit the start page to “src/index.html” inside of the function: (BOOL) application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions

[objc]self.viewController.wwwFolderName = @"www";
self.viewController.startPage = @"src/index.html";[/objc]

Also, be sure to update the link inside of “src/index.html” to point to the project-specific PhoneGap JavaScript files in the parent directory “../phonegap-1.4.1.js”
(they are not inside of the linked folder):

[html]<script charset="utf-8" type="text/javascript" src="../phonegap-1.4.1.js"></script>[/html]

21 replies on “Linked Source Files Across PhoneGap Projects on OSX”