There are a couple of resources out there describing how to set up basically Unity3D with Subversion. In this posting I describe the special situation when developing for iPhone i.e. which XCode specific files should be under version control, how to have different versions in parallel and how to get off cheaply on major Unity3D version updates.

Prerequisites And Goal

My environment:

Unity3D Pro 3.4 (updated for 3.5)

XCode 4.02

Subversion repository (or Git or whatever is your favourite or is your boss‘ favourite) hosted at service provider

Note that until version 3.4 Unity3D Pro is required in order to use Subversion conveniently i.e. not checking in zipped directories. I read from some people reporting that they use it with Standard edition but it appeared to me somewhat tricky. Starting with version 3.5 generic version control is now supported for the free version as well according to the release notes.

While the pure Unity3D part is pretty straightforward, getting the right stuff of your XCode project is far more trickier. Having a directory with more than 500 MB putting all files under version control is not an option, especially if you are connecting via https even if you are working alone. I guess trouble is just one step away if other team members are involved .

There are situations when you need to put some generated code, for example:

Whenever you need to integrate more complex code that could not be handled with Assets/Plugins/iOS

If you need to hook into UIApplicationDelegate callback methods like applicationWillResignActive

When you are profiling and want to change profiling output or frequency

But even if you are happy with Build And Run without any modifications, it might be a good idea to use version control for having a backup of some relevant files just to be on the safe side.

Preparing Unity3D Asset Files

Follow the instructions from Unity3D documentation Using External Version Control Systems with Unity and the links from Unity Answers posting Unity 3.4 and svn ignores

In Unity3D there are some more .asset files in the library folder not mentioned in Unity’s documentation. I found it a good idea to take them all and had no problems with that approach. I expect the list to grow with each Unity3D version, currently there are 5 files not mentioned in the Unity doc:

BuildSettings.asset

EditorSettings.asset

EditorUserBuildSettings.asset

InspectorExpandedItems.asset

MonoManager.asset

XCode Specific Files

Let’s assume your project name is MyGame and you build your stable versions to directory Release and development takes place under directory Develop. After hitting the build button I am the lucky owner of another 356 MB in my Release directory. Opening XCode and performing a build will increase the size above 500 MB – worth to take a closer look what is actually needed.

Release Directory

Checking file sizes and analysing export results afer small changes reveals that there is one file Release/Libraries/libiPhone-lib.a to blame for the huge size (322 of 356 MB) while all others contain data and seem to be subject to changes. It’s a matter of taste whether generated files should be put under version control or not. I prefer to add them for the release version but to ignore them for development. libiPhone-lib.a appears to remain constant for one Unity3D version but changes (grows) on Unity3D updates. Thus it is not worth to waste repository space.

After doing an XCode build, a new root folder DerivedData shows up which should be ignored because it contains temporary files only. Further on the build folder and Unity-iPhone.xcodeproj have grown. Again it is a matter of taste if you want to save your MyGame.app in repository, I refrain from it because of the size and the fact, that it is saved at other places as well. So let’s ignore everything new under build. The XCode project package Unity-iPhone.xcodeproj, which is a directory structure with several XML files, is the heart of your iPhone build and we add it to Subversion.

The last thing to consider are the DefaultSettings.bundle and possibly own files like libraries. DefaultSettings.bundle is needed when you are working with user preferences like Unity3D’s PlayerPrefs. C, Obj-C, Obj-C++ Header files and libraries located under Assets/Plugins/iOS folder are transferred automatically to the XCode project during the build process (s. Unity – Building Plugins for iOS). This works only as long as they rely on a flat directory structure but it fails when your code contains something like #import „types/CoreTypes.h“. In this case you have to edit your build settings and put the files manually into XCode’s directory structure. See my previous article iPhone & Unity3D: Integrating 3rd Party Static Libraries in Unity3D Generated XCode Projects for more information how to handle this.

Step by step:

Export to your clean Release directory

Add all files except Release/Libraries/libiPhone-lib.a and Unity-iPhone.xcodeproj



Open XCode and build

Ignore DerivedData new directories under build

If needed, copy your DefaultSettings.bundle and add it

Optionally add code, resource, 3rd party libs, etc. of your own

Add Unity-iPhone.xcodeproj

You are ready to commit and svn stat Release should print somithing similar to my Release directory file listing. We stripped down the directory size by factor 13 from ~500 MB to 39 MB. Let’s repeat this to reach < 3 MB for our develop directory.

Develop Directory

Our goal ist put the absolute minimum of files under version control so that Unity3D allows building in Append mode. I found out following files and directories:

Unity-iPhone.xcodeproj

Info.plist

Data

Just an empty directory is needed, otherwise Unity3D fails to create iPhone project (bug ?)

Just an empty directory is needed, otherwise Unity3D fails to create iPhone project (bug ?) Libraries

Only files RegisterMonoModules.cpp and RegisterMonoModules.h are needed; These are the files used by Unity3D for detecting if the existing code was generated based on an older version.

Only files RegisterMonoModules.cpp and RegisterMonoModules.h are needed; These are the files used by Unity3D for detecting if the existing code was generated based on an older version. Classes

DefaultSettings.bundle

build

Current Unity3D version works fine without but I remember some trouble a while ago

Againg my my directory file listing for Develop to compare with. 2.8 MB in total for the freshly exported develop directory. That’s enough shrinking even if you use an hosted repostory via https.

Develop And Release Version

In order to get the app installed twice on the iPhone, once as release version MyGame and another one for development let’s call this dev-Game, we need to tell Unity3D what to do in each case. In player settings (menu Edit/Project Settings/Player) we need to adjust the Product Name and the Bundle Identifier. If you change product name only it’s just a renaming of your existing app. It is the bundle identifier which is responsible for creating a 2nd app package.

Let’s assume our release version has the product name MyGame has a bundle identifier de.scio.mygame. For building a develop version we have to change that:

In XCode you will find the result under Unity-iPhone/Targets/Unity-iPhone/Summary in field Identifier just in case that something went wrong:

Stay Prepared for The Next Unity3D Update

If you use Unity3D’s generated XCode project as is without any modifications and if you can live with a replaced XCode project, you can skip this paragraph. In my case there are several adjustments to AppController.mm and iPhone_Profiler.*. At the very first build after a major Unity3D update there is no option to append to the existing project. Thus all changes made are lost.

Depending on the number of changes especially in class UIApplicationDelegate i.e. AppController.mm it might be a good idea to have a copy of all Unity3D original files. I put a copy of the original file as AppController.mm.org under version control.

Now the bad news: That’s it so far. If you have made some changes in your build settings, there is no chance to rescue them on major version updates. The main file containg most things is Unity-iPhone.xcodeproj/project.pbxproj and is in JSON format but it won’t help you so much. So I try to keep my changes in build settings as small as possible and apply them manually after a major Unity3D update.

It’s a good idea to make a backup of the MonoDevelop data files before starting to update. Their location can be found under User Profiles – MonDevelop (section Data).

Fine Tuning

Preparing The Subversion Client for $Id$ Tag

I prefer to set the Subversion Id tag within the header of all C#, Objective-C, and other text files. To get this done for all new files you have to prepare the Subversion client configuration. On Mac OS X go to your home directory, press Shift+CMD+G for Go To Folder and enter .subversion (if necessary at all i.e. you don’t have show hidden files enabled). Then scroll down to section called [auto-props] and insert for *.cs file type

*.cs = svn:eol-style=native;svn:keywords=Id

Do this for all types you like to have the Id tag expanded. It hardly needs mentioning that you must not activate this for binary file types, they will likely be useless after keyword expansion.

Now every newly created file of the affected types will automatically update every $Id $. If you want to enable this for all older files already checked in, open a terminal, go to the project source code folder (e.g. Assets/Scripts) and enter:

find . -type f -name „*.cs“ -exec svn propset svn:keywords „Id“ {} ;

After the next commit Id tag will be treated properly.

Then you can modfiy the file standard header used when doing Edit / Insert Standard Header. In MonoDevelop go to Project / Assembly-CSharp Options and look for Source Code / Standard Header and insert $Id $

Summary

Spending some initial effort when setting up your Unity3D iPhone project can save a lot file system space at your repository server. With the right setup your development build process will be smarter and in the end faster.

I hope you find the information helpful. Feel free to add some comments or press the Like, Twitter, +1 buttons.

Kay