This documentation is for egoXproject 2.x. For 1.x documentation go here.

Installation

  • Add egoXproject to your project from the Asset Store.
  • It unpacks to Assets/egomotion/egoXproject. In here there is an Editor folder containing the EgoXproject.dll.
  • Its adds a menu at Window > EgoXproject

Basic Concepts

EgoXproject allows you to set up changes that will be applied to the Xcode project file and the Info.plist file when you build your Unity iOS project.

The changes can be set up either using the Xcode Project Editor window or via a PostProcessBuild C# script. The changes are applied to Xcode project file and the Info.plist file during the PostProcessBuild phase.

For more complex projects you can set up multiple changes files and group them into configurations. So for example you could have a configuration you apply during iPhone builds and another during iPad builds, with each configuration applying a different combination of change files.

Xcode Project Editor

Where to find the Xcode Project Editor

The Xcode Project Editor is located under Window > EgoXproject > Xcode Project Editor

Creating a change file

  1. Open the editor
  2. Create a new change file by either pressing the big “+” button if there are no change files or pressing the “+” button to the right of the current change file drop down.

Add Info.plist changes

Changes will either be added to the Info.plist if they don’t exist, or replace an existing entry. Existing dictionaries will have entries added or replaced if they already exist. Arrays will have entries appended unless they match exactly.

  1. Under the Info.plist section press the “+” button to add a new entry.
  2. Enter the key in the Key field
  3. Set the type in the Type field
  4. Enter a valid value in the Value field.
  5. Changes are saved automatically.

Add frameworks and libraries

You can add system frameworks and libraries and your own custom frameworks and libraries. To add a system framework or libraries:

  1. Press the “+ System Framework or Library” button under the Frameworks & Libraries section.
  2. Browse through the list of frameworks and libraries or use the search to narrow the list down
  3. Select the desired framework
  4. Set the item’s link status to either Required to Optional. Unless you have a particular reason, this should be set to Required.

To add a custom library or framework:

  1. Press the “+ Custom Library” or the “+ Custom Framework” button.
  2. Locate the required item on disk using the selection dialog
  3. Set the add method for the item. Either Copy to copy it to the Xcode project directory or Link to link to it at its current location
  4. Set the item’s link status to either Required to Optional. Unless you have a particular reason, this should be set to Required.

Add files and folders

You can add individual files, entire folders of files, special container folders (these are folders that appear as files on Mac OS X). To add a file or folder:

  1. Press the “+ File” or “+ Folder button”
  2. Locate the required item on disk using the selection dialog
  3. Set the add method for the item. Either Copy to copy it to the Xcode project directory or Link to link to it at its current location. For folders you only need to set the folder’s add method. Its contents will be added the same way.
  4. If a file can be compiled (i.e source code), you can additionally add compiler flags if required. A common requirement is to enable or disable ARC using -fobjc-arc or -fno-objc-arc respectively.

Additionally for folders you can:

    • Remove items from its listing by pressing the “-” button next to the item to remove.
    • Refresh the folder’s listing by pressing the refresh button (button with the circular arrow) next to the folder. This will remove any entries that are missing, and add in any files and folders that are not currently in the listing.

Add build settings

You can add and adjust build settings under the Build Settings section.
To add a build setting:

      1. Press the “+” button to add a new entry.
      2. In the popup either select or search for a build setting
      3. If the build setting is not listed enter the name and press the “+” button to add it
      4. Depending on the build setting selected you will be able to set a bool toggle, enter a string value or enter a list of string values
      5. For list entries you have an additional option to either append to existing entries or replace them entirely.

Add post build scripts

Post build shell scripts can be added under the Scripts section. As the name suggests, these are run after the Xcode project has built.
To add a script:

      1. Press the “+” button to add a new entry.
      2. Set the shell if required.
      3. Enter the script

Previewing changes

At the top of the editor window press the “Preview” button to show the preview tab. This tab shows all the changes that will be made combined into a single change set. If you only have one change file it will show just those changes, but if you have more it will show the merged combination of those.

If you are using multiple configurations (see the next section) you can change the active configuration and see the changes that will be applied for that configuration.

Managing Configurations

At the top of the editor window press the “Settings” button to show the settings tab. Here you will find a section labelled Configurations. Configurations allow you to apply different sets of change files to different builds.

There is always a “Default” configuration that has all of the change files. This is what will be applied if no other configurations are set up.

To add a new configuration:

  1. Press the “+” button
  2. Give the configuration a name
  3. Press the “Add” button

To add change files to the configuration:

  1. Press the “+” button in the configuration’s box
  2. Select the change file you want to add
  3. Repeat for any others you want to add

To set a configuration active, either toggle the checkbox by the configuration’s name or select it in the preview tab.

Advanced Settings

Auto Run

You can toggle whether egoXproject should run automatically or not.

Ignored Files and Folders

This section shows which name patterns will be ignored when adding files and folders to a change file. The default ignored files cannot be changed and will always be ignored.

To add additional patterns:

  1. Press the “+” button in the Custom Ignored Files section.
  2. Enter a new pattern. A pattern can either be the exact file name or use the wildcard character, *.

Xcode Location

If Xcode is not in the standard location, you can set its location here. This change is not saved to the egoXproject settings file, but instead to the Editor Prefs. This allows different users to have their own locations configured.

Analytics

EgoXproject will check for updates and display an update notice on the editor window. The check will only occur when the Xcode Editor window is open.

EgoXproject will also send anonymous installation info (e.g. Unity version). This allows us to focus development where it is required.

Scripting Interface

If you need to control when egoXproject runs or need to apply dynamic changes (eg changing the bundle version based on the build) you can use a postprocess build script. The following API is available:

namespace: Egomotion.EgoXproject
static class: XcodeEditor


//Get or set whether egoXproject should run automatically. true = enabled.
public static bool AutoRunEnabled

//Get the array of configuration names
public static string[] Configurations

//Get or set the name of the active configuration
public static string ActiveConfiguration

//Apply the changes to the specified project. 
//pathToBuiltProject is the path that gets passed to the PostProcessBuild attributed function.
public static void ApplyChanges(string pathToBuiltProject)

//Set a string value in the Info.plist
public static void SetInfoPlistEntry(string key, string value)

//Set an int value in the Info.plist
public static void SetInfoPlistEntry(string key, int value)

//Set a float value in the Info.plist
public static void SetInfoPlistEntry(string key, float value)

//Set a bool value in the Info.plist
public static void SetInfoPlistEntry(string key, bool value)

//Set a date value in the Info.plist
public static void SetInfoPlistEntry(string key, System.DateTime value)

//Add a system framework or library by name (eg. Accelerate.framework), 
//and set its link type (i.e. whether it is Optional or Required).
public static void AddSystemFrameworkOrLibrary(string name, LinkType linkType)

//Add a system framework or library by name (eg. Accelerate.framework)
//Link type will be set to Required.
public static void AddSystemFrameworkOrLibrary(string name)

//Add a custom framework or library. 
//Path must be absolute or relative to the project folder (e.g. "Assets/Third Party/Foo.framework")
//Set its link type (i.e. whether it is Optional or Required).
//Set its add method (i.e. whether it should be copied to the Xcode project or just linked)
public static void AddCustomFrameworkOrLibrary(string pathToFrameworkOrLibrary, LinkType linkType, AddMethod addMethod)

//Add a custom framework or library. 
//Path must be absolute or relative to the project folder (e.g. "Assets/Third Party/Foo.framework")
//Set its link type (i.e. whether it is Optional or Required).
//Add method will be set to link
public static void AddCustomFrameworkOrLibrary(string pathToFrameworkOrLibrary, LinkType linkType)

//Add a custom framework or library. 
//Path must be absolute or relative to the project folder (e.g. "Assets/Third Party/Foo.framework")
//Link type will be set to Required, and Add method will be set to link
public static void AddCustomFrameworkOrLibrary(string pathToFrameworkOrLibrary)

//Add a file or folder
//Path must be absolute or relative to the project folder (e.g. "Assets/Third Party/Foo.m")
//Add method will be set to link
//No attributes will be set
public static void AddFileOrFolder(string pathToFileOrFolder)

//Add a file or folder
//Path must be absolute or relative to the project folder (e.g. "Assets/Third Party/Foo.m")
//Set its add method (i.e. whether it should be copied to the Xcode project or just linked)
//No attributes will be set
public static void AddFileOrFolder(string pathToFileOrFolder, AddMethod addMethod)

//Add a file or folder
//Path must be absolute or relative to the project folder (e.g. "Assets/Third Party/Foo.m")
//Set its add method (i.e. whether it should be copied to the Xcode project or just linked)
//Set any attributes the file may require. Currently this is just compile flags for source code files (e.g. -fobjc-arc)
public static void AddFileOrFolder(string pathToFileOrFolder, AddMethod addMethod, string attributes)

//Set a build setting to a specified value
public static void SetBuildSetting(string buildSetting, string value)

//Add a script
//Uses the default bash shell
public static void AddScript(string script)

//Add a script with a specified shell
public static void AddScript(string script, string shell)

Upgrading from 1.x

Upgrading from v1.x to 2.x occurs automatically when the Xcode Editor Window is opened.
All change files and settings are upgraded to the new format and the old files are renamed to have a .bak extension. Once you have verified everything is OK, you can delete the old files.

Merging change files

Previously there were change files for the Info.plist and for the Xcode project file. You may now want to merge these into a single change file. To do this:

  1. Select the change files that you want to merge (2 or more).
  2. Go to Window > EgoXproject > Merge Selected Change Files.
  3. Give the merged change file and name, and set a location to save in the dialog window.
  4. Verify that the merged change file is correct using the Xcode Editor.
  5. Remove the unneeded change files.

Miscellaneous

Here are a few extra things that may be useful to know.

  • You can move the EgoXproject.dll to any other Editor folder. It will find its settings file and the change files
  • You can save the change files anywhere in your Assets folder
  • Hovering the cursor over a file/folder/framework/library with show a tooltip with the path to that item.
  • EgoXproject runs its PostProcessBuild function at index 5000. This is so it (hopefully) runs after other plugins, as some will remove sections of the Xcode project that they do not understand.
  • EgoXproject will warn you if it finds errors in the Xcode project file, like missing entries. Currently this is known to happen when using the official Facebook plugin. This plugin will delete sections of your Xcode project. Currently is not deleting anything vital! Remember you can always use EgoXproject to make the changes rather than their project editor.