Version: 2022.3
Language : English
iOS requirements and compatibility
Structure of a Unity Xcode Project

How Unity builds iOS applications

Unity uses Xcode to build iOS applications so it’s useful to understand the build process and how Unity interacts with Xcode. To configure most aspects of the final build, you can use Player SettingsSettings that let you set various player-specific options for the final game built by Unity. More info
See in Glossary
and other Unity windows, however for more control, Unity must build an Xcode project and you must modify Xcode project files directly.

The build process

  1. Unity collects project resources, code libraries, and plug-insA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
    See in Glossary
    from your Unity project and uses them to create a valid Xcode project.
  2. Unity updates the Xcode project based on the Unity project’s Player Settings and Build Settings. Depending on whether you use replace or append mode, Unity replaces or preserves previous changes you made. Append mode preserves changes you previously made and only overwrites certain values. Overwrite mode creates a new project which overwrites any changes you previously made.
  3. Unity generates C++ source files based on your C# scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
    See in Glossary
    and places them in the generated Xcode project. Xcode then invokes the IL2CPPA Unity-developed scripting back-end which you can use as an alternative to Mono when building projects for some platforms. More info
    See in Glossary
    program which compiles the C++ source files into libraries called libGameAssembly.a and il2cpp.a.
  4. Xcode builds the project into a standalone application and deploys and launches it on a connected device or the Xcode simulator.

Replace and append mode

If you build a project in a directory that already contains another Xcode project, Unity displays an alert and gives you a choice on how to proceed. There are two options

  • Replace: Unity removes everything in the target Xcode project directory. It then generates the new Xcode project in the now empty directory.
  • Append: Unity removes all files in the target Xcode project root directory and in the Data and Libraries subdirectories. It then fills these directories with newly generated Xcode project content. Unity then updates the Xcode project file according to the latest Unity project changes. Unity only supports this mode for the existing Xcode projects generated with the same Unity iOS version.

Note: If you use Append mode, you can store custom native code in the Classes subfolder. Unity won’t overwrite them, but it’s best practice to make regular backups.

Incremental build pipeline

Unity uses the incremental build pipeline when it generates the Xcode project for iOS. This means that Unity incrementally builds/generates files such as Information Property List (plist) files and Entitlement files. If you implement callbacks that modify or move any iOS file or asset that the incremental build pipeline uses, see Creating non-incremental builds.

Additional resources

iOS requirements and compatibility
Structure of a Unity Xcode Project