iOS Project Builder for Unity

Thank you for using this project builder which enables you to build and deploy Unity-powered iOS apps in Windows. I hope you enjoy using it as much as I enjoyed creating it.

I know it's boring, but still, please take five minutes of your time to read this document!

CAVEAT EMPTOR: This iOS Project Builder for Unity is a subset, centered around and tailored for Unity, of a larger toolchain called the iOS Build Environment available from this page. Even if both share the same core, they are not identical and should not be confused. The one you have here is specific to Unity and must be updated solely through the Unity Asset Store.

Summary of this document

  1. First steps
  2. How to transfer your app to your device
  3. How to catch application logs, system logs and stack traces
  4. How to upload an app to iTunes Connect (and submit it to Apple's official App Store)
  5. How to submit an app to the Cydia Store
  6. About digital signing identities
  7. About provisioning profiles
  8. What's this "add framework" button and how do I use it?
  9. How do I add extra entitlements (a.k.a Application Services) to my app?
  10. What's a "pre-packaging script" and why would I need one?
  11. Can I build or upload my iOS projects from the command line?
  12. Can I add embedded binaries (dylibs or frameworks) into my app?
  13. Limitations (and workarounds)
  14. Troubleshooting
  15. Change log

Legal foreword

In the license that comes with the iOS SDK, Apple Inc. states that the iOS SDK shall only be deployed on Apple-branded computers. So, for the rest of this document, I will assume that your Windows computer is an Apple-branded computer running Windows through Boot Camp. I do not condone the use of this program outside this scope, and cannot be held responsible for any misuse you make of it.

1. First steps

First-time setup

In order to use this builder, you need to copy some files from the Mac side to the Windows side of your computer. Just follow these directions step by step.

Installing the SDK

click to enlarge

Login onto Windows and plug a FAT-formatted USB key (not NTFS! macOS can't write to NTFS keys) with at least 50 Mbytes free into your computer.

Open the SDK migration assistant shortcut from your Start menu (it's in All Programs > iOS Project Builder for Unity)

Drag both these files to your USB key and reboot into macOS.

click to enlarge

Login onto macOS. NOTE: if you can't use your Mac for this, you may ask a friend with a working Mac to help.

Make sure that Xcode is installed (you can download and install it for free from the Mac App Store).

Open your USB key and double-click the item called Migration assistant (step 1, Mac).command.

click to enlarge

Let it do its job, and when it tells you so, reboot into Windows.

(You will notice that a, and possibly a file too, will have been created on your USB key. They contain the files we need.)

click to enlarge

Login onto Windows.

Open your USB key and double-click the item called Migration assistant (step 2, PC).

click to enlarge

The SDK unpacks. Wait for it to finish... and that's all.

Setting up your signing identity

click to enlarge

On Windows, open the Keychain Tool shortcut from your Start menu (it's in All Programs > iOS Project Builder for Unity).

If your Mac was previously used to build iOS apps, the migration assistant will have found your existing signing identity and you should see that appear in the Keychain Tool. That is to say, you should see things called certificates named iPhone Developer: <Your Name> and/or iPhone Distribution: <Your Name>, along with at least one private key and probably some provisioning profiles.

click to enlarge

On the other hand, if you see nothing in the listbox like on this image, then it means no existing signing identity was imported from your Mac, and you need to create one from scratch.

In which case please see 6: About digital signing identities case c) "You don't have any signing identity yet".

click to enlarge

A signing identity, in a nutshell, is the combination of 3 things: a certificate that attests of your identity, the private key (and its protecting passphrase) out of which this certificate was created, and a provisioning profile that tells which iOS device(s) are allowed to install the app that carries it.

Select the provisioning profile to use by default. This will auto-select the certificate it contains (if your profile contains multiple certificates, pick one of them), and the private key that was used to create it. Enter that private key's passphrase. When everything matches, the lock turns green. This will be your default signing identity.

Note that for a generic identity, you should select a generic, development provisioning profile, i.e. one that's not specific to a particular app. Later, when you build your apps for release, you will select for each of them a distribution certificate and a specific provisioning profile.

Voil´┐Ż. Your build environment is ready!

Building and deploying your iOS project

click to enlarge

Create your iOS project within Unity on Windows (select File - Build Settings... or Ctrl+Shift+B, then select iOS, and hit Build.)

Unity will prepare a directory containing a project to be compiled with Xcode.

click to enlarge

Start the "Project Builder for Unity" from your Start menu (it's located in the "iOS Project Builder for Unity" programs group in the Start menu, under "All programs").

Pickup the location of the Xcode project created by Unity using the Browse button.

Check that your signing identity is correct (see 6.) and that the provisioning profile is suitable for your app (see 7.), review the build options, then hit Build.

click to enlarge

Grab a cookie while your project is being built.

click to enlarge

After a successful compilation, your apps can be found in the 'Packages' subdirectory of your project.

These packages are ready to be deployed on your iOS device (iPhone, iPod or iPad).

click to enlarge

If you opted so, your app should also be available for OTA (over the air) installation to your device. Simply follow the on-screen instructions.

OTA deployment users, please note that:

  • The app must be signed with a DEVELOPMENT certificate, or an enterprise one. OTA deployment with other types of certificates is blocked by Apple (that would be a convenient method of app piracy :-)).
  • Your iDevice must have a working Internet connection to download the install manifest. This is a tiny resource that is generated online during the process and downloaded to your device to allow installation.

IMPORTANT: As long as you haven't set up a signing identity, only a pseudo-signature can be performed. Pseudo-signed apps can only be deployed on jailbroken devices, while fully signed apps can be deployed on any device, jailbroken or not. To import and use your digital signing identity to sign the app, use the Keychain tool.See 6 - About digital signing identities for a brief howto on how to use a digital signing identity from the iOS Developer Program.


Problem encountered during the build phase? Head up there: 13 - Troubleshooting.

[ Back to top ]

2. How to transfer your app to your device (manually)

If you haven't opted for the recommended way to deploy your app over the air, you can still deploy it manually. There are two cases.

2.a) You specified a digital signing identity for building your app (certificate + private key)

If it's the case, your device doesn't need to be jailbroken. To install your app on your device, you must ensure:

If the above conditions are met, we can proceed: open iTunes. Locate your device in the left-hand panel (connect it via USB if necessary). Click the little arrow next to it so as to develop its contents. Now drag-and-drop the created app package (.ipa file) onto any of these categories in iTunes. Sync, and your app icon appears.

This is called side-loading. Please note that these instructions are known to work for iTunes 12.7 (see this thread on StackOverflow). You might need to experiment a bit if you use another version (please don't ask me: truly, I don't know how other iTunes versions are meant to work.)

2.b) You built your app without a digital signing identity

If you don't have any digital signing identity from the iOS developer program, you can only deploy your app if your device is jailbroken.

Jailbreaking your device is the process of lifting some security barriers that Apple put on it, that prevent it to run unsigned code (which is literally code for which we can't know the author. You understand why it's an important security restriction). Although Apple would prefer you to abstain, lifting this restriction by "jailbreaking" is authorized, safe, and reversible.

To jailbreak your device, first check its model and iOS version in Preferences > General > Informations. Once you know these, head up to and let the website select the right jailbreak program for you. Make sure you have a good ad blocker enabled so as not to download anything else than the jailbreak program (I am not affiliated with this website nor with the ad campaigns it runs - you have been warned). Get the jailbreak program that's right for your device (they're free), run it and follow the instructions.

Now on to installing your unsigned app by hand on a jailbroken device:


Problem encountered during the deployment phase? Head up there: 13 - Troubleshooting.

[ Back to top ]

3. How to catch application logs, system logs and stack traces

Open the remote debug console by clicking on the link in the builder window, or from your Windows start menu: All Programs > iOS Project Builder for Unity > Remote debug console.

click to enlarge

This cute piece of witchcraft allows any iOS app to send all that it would normally write to the standard output and the standard error streams stdout and stderr, to a window on your PC. That is to say, everything that is logged in your app using NSLog() macros, with printf(), fprintf(stderr, ...) or with cout << ... and cerr << ... will be caught, even stack dumps when it crashes, sent over the network to display before your eyes, on your computer, while your app is running on your device. And this works even for release builds.

It catches the iOS system logs. If your device is plugged to your computer with a USB cable and if you have iTunes installed, you can catch the syslogs in glorious ANSI colors. This is invaluable to find out what happens when your app refuses to launch (for example, because of an invalid entitlement). To opt for it, tick the "System logs" checkbox in the console bottom status bar. Beware: iOS is a very chatty system.

Data filtering. Say you've enabled all checkboxes and are now receiving encyclopediae of data flooding the console window so fast that you can't read anything. Halp. You may filter all this garbage to either exclude, or allow, or highlight a character string. No less valuable.

When you need a break, Stop and resume logging by clicking the "Stop / Record" button (top right of the console window).

To enable debug cuteness, tick the "Enable remote debug console" checkbox in the builder window, and make sure the IP address that displays next to is is the IP of your computer. The app will send its data over TCP ports 5001 and 5002, so you should also make sure that the remote debug console window is open on your PC and that no firewall or other "Internet Security" stupidware gets in the way (at least for these protocol/port pairs).

NOTE: each time you toggle this checkbox, the project must be rebuilt from source in order to embed or disembed some additional code. If you get linker errors such as: duplicate symbol _main or ld: entry point (_main) undefined, then it means you toggled the remote debug console on/off without rebuilding. Simply tick the "Rebuild all files (once)" checkbox to fix it.

[ Back to top ]

4. How to upload an app to iTunes Connect (and submit it to Apple's official App Store)

In order to submit an app to the App Store, you need to send it using your iTunes account to the iTunes Connect website. This can be done from the iTunes Connect upload tool.

You need a few things to upload your app to iTunes Connect. Checklist:

First, you need a build of your app signed (or re-signed) with a signing identity that's fit for App Store submissions. iTunes Connect will only accept apps that are signed using a distribution certificate, so make sure your app is signed with such a certificate. In case it's not, see the signing identities section of this document to learn how to get one. Luckily for you, the iTunes Connect upload tool that comes with this toolchain allows you to re-sign already packaged apps before submission.

You also need your app to embed a provisioning profile that has an explicit app ID in it. See the provisioning profiles section of this document to learn about the difference between explicit and wildcard app IDs: basically, a provisioning profile with an explicit app ID is made for one and only one app, whereas a provisioning profile with a wildcard app ID can be reused across multiple apps. Apple doesn't allow the latter for App Store submissions. So, if your current provisioning profile is a wildcard one, you will need to create an explicit app ID for your app first, then an explicit provisioning profile out of it.

You also need your provisioning profile to be fit for App Store submissions. Choose App Store (under the Distribution category) when creating such a provisioning profile.

Now, if you haven't already done so, you need to prepare a record for your app on the iTunes connect website. Log in to the iTunes Connect website, go to My Apps and click the plus sign to create a new record. Fill the form that describes your app: the platform on which it'll run (obviously you want iOS), the app's name, its main language, its bundle identifier (which must match the one you specified in your Info.plist or in the Unity editor), and a unique string for you to identify it easily. Once this is done, you can enter this new app record to view its details, and there you will see it has a number named Apple identifier associated to it. This is a unique number that Apple attributed to your app so as to identify it uniquely. All build submissions to iTunes connect will need to use this Apple identifier, so copy/paste it in a safe place.

When you're set, fire up the iTunes Connect upload tool. Browse to the .ipa file you want to upload, specify a signing identity suitable for the App Store, fill in the fields as appropriate (your login, password, and the Apple ID of your app), and hit the Upload button. A window will pop up with a progress bar during which your app will be delivered to iTunes Connect.

After the upload is done, Apple will send you an e-mail at your iTunes account's address to tell you whether it accepted your app for delivery (w00t!) or whether there are still some problems to fix in it. Pay attention to these messages if you want to correct them quickly and efficiently. A Google search on a particular phrase usually helps in understanding what's wrong.

Once your build has been accepted by Apple, it's up to you to choose what to do with it: for example, distribute it to your beta testers through the TestFlight program, or send it to the App Store. All the rest of this process now takes place on the iTunes Connect website, which you will soon be accustomed to use. :-)

NOTE: if during the upload step, you receive a message such as "all transfers failed diagnostics", it simply means the Apple upload servers are overloaded at the moment. In this case, just try again later.


Problem encountered during the publication phase? Head up there: 13 - Troubleshooting.

[ Back to top ]

5. How to submit an app to the Cydia Store

To send your app to Cydia, it only depends on which source (repository) you want to host it.

[ Back to top ]

6. About signing identities

iOS apps require to be signed with a signing identity in order to be deployed on non-jailbroken (stock) devices, and/or submitted to iTunes Connect and the App Store.

A "signing identity" is the association of a certificate approven by Apple and a private key, that is used to seal that certificate into the app, AND a provisioning profile that tell which devices (typically yours and your testers') are allowed to install your apps.

3 cases:

case a) You already have these files on Windows.

In order to sign your app with a signing identity, put these certificate(s) (.cer files), private key (.key file) and provisioning profile(s) (.mobileprovision files) in the Keychain directory where the iOS Project Builder for Unity is installed. The build tools will then be able to pick them up and let you select which identity to use.

case b) You don't have them on Windows but you have a signing identity on Mac.

All iOS signing identities found on your Mac are automatically migrated along with the iOS SDK by the Migration Assistant when you run it. If you want to grab a signing identity from your Mac that was created after the iOS SDK was migrated, simply run the Migration Assistant again.

case c) You don't have any signing identity yet.

First, you need to enroll in the iOS Developer Program: (if you wonder whether you can use a free Xcode certificate, read about it a few paragraphs below).

Now, you need to generate a new signing identity. Use the iOS Project Builder for Unity's Keychain tool to generate a new private key, and a certificate signing request (CSR). Your private key will be automatically installed in the Keychain directory, and you get a .certSigningRequest file that you can save somewhere on your disk.

Now visit the iOS Developer Portal at, login with your Apple iOS developer ID, click on Certificates, Identifiers & Profiles in the menu and create the certificates you need using your .certSigningRequest file ('+' button). Once the Apple website created your certificate, download it and save it in the Keychain directory, alongside with your private key.

Finally, you need a provisioning profile, to tell iOS which devices are allowed to install your apps. Read on the next section to find out how to create that.

all cases

Once you have your private key and certificate installed in the Keychain directory, they become usable by the builder. Please note that only valid, non-expired certificates will appear in the certificates list.

You may then deploy your signed apps to all the devices that are listed in the app's provisioning profile (see 7) with the generated .ipa, automatically after each build (OTA), or manually (see 2.)

Frequently asked: Is enrolling into the iOS Developer Program (and paying $99 to Apple) really mandatory? Can I use that "free" signing identity that Apple offer to Xcode users?

It is not strictly necessary to enroll in the iOS Developer Program, but in my opinion the benefits exceed the expense. Simply put, if you don't, you will need to use those "free" code signing certificates generated by Xcode, and since these certificates have a very limited lifetime (10 days) by Apple's design, be prepared to migrate them each and every week from your Mac and rebuild the apps that use them to make them installable again. Not only that, but by Apple's design, over-the-air deployment can't be used with those free certificates, which means you'll need to deploy your apps by hand on your devices (using iTunes sync for example), and when you do this 20 times a day or more, that's a consequent waste of time. A lot of advanced features related to signing identities, application entitlements, device provisioning, are not available to free users (or seriously hindered), which mean you won't be able to test many things that you code. That's why my advice is to bite the bullet and go the official way, unless you're really budget-constrained - and be prepared for a lot of hassle if you choose to go the narrow way.

[ Back to top ]

7. About provisioning profiles

Provisioning profiles are authorization files that, when installed on an iOS device, tells iOS which apps it is allowed to let you install. When you install a custom app on your iOS device, iOS complies to the provisioning profiles it has to decide whether it lets the app in or throws it away. App Store apps are not concerned, because they are all re-signed by Apple as part of the app submission process (this is why App Store apps are always accepted by iOS.)

If you want to deploy your own signed apps on an iOS device, you need a provisioning profile for it.

I already have a provisioning profile from Xcode. Can I reuse it?

Sure. Just make sure that the App ID you specify in Unity matches the App ID in the provisioning profile.

If it's a "wildcard" provisioning profile, you're good. Else, if it's an "explicit" one, the IDs must match exactly. To find out the difference between a "wildcard" app ID and an "explicit" app ID, see this page.

In all cases, if you have the slightest doubt, the safest way is certainly to obtain a new provisioning profile from the iOS Provisioning Portal.

How to obtain a provisioning profile?

Provisioning profiles instruct iOS to let you install apps signed by yourself. Here is how to create one.

First, create an app ID:

Now, let's instruct which device(s) this provisioning profile will concern:

Finally, create a provisioning profile for this app ID and the device(s) you just registered:

Your provisioning profile is ready. You may download and save it in the Keychain directory, alongside with your private key.

And now that you have a private key, a signing certificate and a provisioning profile with your app and device IDs in it, your signing identity is usable and you're good to go.

[ Back to top ]

8. What's this "add framework" button and how do I use it?

In Apple's terminology, frameworks are a set of APIs (i.e. entrypoints to bits of native code) regrouped together in a bundle, that developers can use to extend their apps' functionality.

More specifically, frameworks are directories ending with .framework that contain either the framework library (the framework's compiled dynamic library, or a file describing it) plus its associated header files, or the full source code for that library (such a file layout is OS-agnostic, yet when they are viewed on a Mac, those directories look like a regular file and you need to "show package contents" to browse inside them).

The "add framework" button lets you use a framework that isn't already included in your Unity-generated Xcode project, just as you would include it in your project with Xcode. If it's not one of the stock iOS frameworks, you need to have this framework somewhere on your PC. Each third-party framework supplier provides instructions on how to use them and a download link (sometimes labelled "SDK").

Click on the button, browse to the .framework directory that you want to include, and validate with OK. The builder will set up for you the extra compiler and linker flags to use at build time to include the framework you selected.

Hint for advanced users: if you know the clang compiler and ld64 linker syntax, you can also specify any extra flags of your choice here.

Example: how to add the Google Mobile Ads framework

This is an excellent example because the GoogleMobileAds framework is known to require a bunch of dependencies that are not explicitly specified. Quite expectedly, Google doesn't simplify the task of people wanting to use their technologies on concurrent platforms (they'd rather have them all throw their iPhones and buy Androids). So, you click on the "Add framework" button and you locate the GoogleMobileAds.framework directory that's in the Google Mobile Ads SDK that you downloaded from Google. But when you attempt to build your project after that, you get unresolved symbols errors, telling you that the Google framework wants to call functions that are present in other frameworks that you also need to include in your project. The procedure to solve this problem is simply to resolve them one after the other. Taking the first one of the list, a Google search tells us that the missing symbol called "SecTrustCopyPublicKey" about which the linker complains is found in the iOS framework called Security: see.

So, you should add -framework Security into the "extra linker flags" field, rebuild, and see what comes next. Repeat the process until no more errors.

For the Google Mobile Ads framework, you end up with the following extra flags (currently): -framework GoogleMobileAds -framework Security -framework MessageUI -framework MobileCoreServices -framework GLKit -framework StoreKit -framework CoreTelephony -framework AdSupport

[ Back to top ]

9. How do I add extra entitlements (a.k.a Application Services) to my app?

If you want to enable your app to access special iOS services (such as Apple Pay, iCloud, etc) it must fullfill two conditions:

Enabling these services is done when you register your app ID on the iOS Developer portal here:

When you create an app ID, either generic (wildcard ID) or specific (explicit ID), you are allowed to choose which extra Application Services will be accessible to an app wearing this ID. Technically speaking, these services are called an app's entitlements.

Configuring these services now is done through an external .plist file, a text-editable ASCII property list that will contain the app-specific entitlements data, that will be hard-stamped in the app binary at signing time. In a nutshell, this is a text file you create with the .plist extension, and in which you put a dictionary of key/values like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

In this example, the Associated Domains app service is set to trust the and hosts. The key to use for this service is

Then, simply tick the checkbox called Entitlements from .plist file in the builder window and browse to your .plist file to tell the builder to stamp these entitlements in your app at code signing time.

When you need to configure a particular service and you don't know which entitlement key(s) it uses, a good starting point is to read this page in the Apple online documentation to learn which key names are associated with a particular service. Then use Google to find out about its possible values.

[ Back to top ]

10. What's a "pre-packaging script" and why would I need one?

As the builder tries to interpret your Xcode project file so as to embed all the resources your app needs correctly in the final ipa bundle, there are cases, specially when complex third-party plugins are used, where some extra tweaking will be needed.

A "pre-packaging script" is an executable file that you specify (either .bat, .cmd, or even .exe, or any extension for which you have an interpreter: .js for Javascript, .py for Python, etc. as long as the corresponding interpreter is installed), that the builder will run just before your app is signed and packaged. You can use this extra build step to arrange custom resource files in the app's directory, move some from here to there, include some others, exclude other ones, and even generate new ones on the fly.

Your app's file layout, i.e. the directory in which you're interested to make changes, is the directory that is created in your project directory by the builder. This is the directory whose contents will be signed and packaged in the final .ipa file, that will be deployed to your iDevice.

If you want (or need) to use a pre-packaging script for your app, create a script that will make the necessary changes to this directory, and instruct the builder to call it here. To find out which change(s) are needed, you must refer to your plugins' documentation.

Most Unity apps won't ever need this feature, so I recommend using it only if yours require it.

Here's an example of a fictious pre-packaging script, called MyCoolApp-prepkg.bat:

@echo off

rem // see if we're calling this for the right app
if not exist\ (
	echo Looks like you're not calling this script for the right project... ^(exiting with an error code^)
	exit /b 1

rem // copy the missing .png files that my app expects to find in 'ExtraResources'
copy /b /y C:\Users\Me\DevelopmentPictures\*.png\ExtraResources

rem // remove a big duplicate file that was incorrectly bundled in two places
del /y\BigFatDataBase.sqlite

[ Back to top ]

11. Can I build or upload my iOS projects from the command line?

Yes you can!

The witchcraft to use lies in the build.cmd file that's in the main directory where the iOS Project Builder was installed. Basically, you call it with the path to an Xcode project generated by Unity, your signer identity string, and a couple of options to tell whether you want it to produce an .ipa file, a .deb file, or both, and whether you want to deploy the app to your device directly.

Invoke it with build.cmd /? to see the full list of command-line options, and to learn more about what is a signer identity string in the context of this builder. An example could look like this:

"%IOSUNITYBUILDER_PATH%\build.cmd" "C:\Users\Pierre-Marie Baty\Desktop\AngryBots" -identity "my_certificate.cer:AppleIncRootCertificate.cer:AppleWWDRCA.cer:private_key.key:MySecretPassPhrase" -provision "C:\path\to\provisioning-profile.mobileprovision" -ipa

This command line builds the AngryBots Unity project that's sitting on my desktop and outputs a signed .ipa file. Ain't it cute?

Extra magic: in the Xcode project builder UI, if you hit the Build button while holding the Shift key pressed, the build log will output a lot of debug info. The first line will be the full invokation of build.cmd, that you can copy/paste and use in your own continuous integration tools!

Building from the command line is specially useful if you want to integrate this builder into your own custom build chain. If you are a professional developer, it will make your testers save an insane amount of time!

Uploading (with or without resigning) an .ipa file to iTunes Connect is also possible from the command line. See upload.cmd /? for the gory details. Here's an example:

"%IOSUNITYBUILDER_PATH%\upload.cmd" "C:\Users\Pierre-Marie Baty\Desktop\AngryBots\Packages\AngryBots.ipa" -identity "my_certificate.cer:AppleIncRootCertificate.cer:AppleWWDRCA.cer:private_key.key:MySecretPassPhrase" -provision "C:\path\to\provisioning-profile.mobileprovision" -itclogin "" -itcpassword "SecretITunesPassword" -appid 123456789

This command line re-signs then uploads the AngryBots.ipa file to iTunes Connect.

[ Back to top ]

12. Can I add embedded binaries (dylibs or frameworks) into my app?

Yes (and that's new).

This is normally automatic if those embedded binaries or frameworks are defined as such in your Unity-generated Xcode project file. The builder should simply detect them, and do the job appropriately.

In the case where it wouldn't be the case (you can tell so if you examine the contents of your directory after a successful build, and check whether your embedded binaries are there or not in the Libraries or Frameworks subdirectories), you may try to force-embed them by specifying them explicitly on the command line in a command-line build.

"%IOSUNITYBUILDER_PATH%\build.cmd" "C:\Users\Pierre-Marie Baty\Desktop\AngryBots" [ options...] -embed "relative/path/to/SomeLibrary.dylib relative/path/to/SomeOtherFramework.framework" [...other build options...]

Please note: specifying the embedded binaries on the command-line will add them to the list of embedded binaries that the builder found in the Xcode project. It will not supercede them! So, if there's an error in your Xcode project file, it's wiser to fix it so that your extra binaries are embedded automatically instead of relying on a command-line build to do the job.

This functionality is quite new, so if you have an undoubtedly valid Xcode project file in which the builder fails to identify correctly the embedded binaries, I'd love to have a closer look at it: please do send me your project.pbxproj file for analysis.

[ Back to top ]

13. Limitations (and workarounds)

  • Asset catalogs support is limited. While covering the vast majority of the cases, the current asset compiler this toolchain provides (cartool) is able to compile app icons, splash screens, launch images, AR reference groups, ARKit reference images and store artwork, but not other resources (yet). To have them supported in the next release, please send me the .xcassets directory that doesn't build, so that I can provide you a patch quickly. In the meantime, assuming that your assets don't change across builds, and if you have a working macOS at hand or can borrow one, you can build your project on macOS once, then extract the compiled file from the .ipa archive (.xcassets directories are compiled into an file), then use it as a resource file when building your project on Windows, by inserting this file into the final app using a pre-packaging script (see the section about pre-packaging scripts).
  • The builder doesn't work if your project contains extra .xib files (some assets embed Xcode plugins that do). Assuming that your .xib file doesn't change across builds, the workaround, if you have a Mac at hand or can borrow one, is to build your project on a Mac once, then extract the compiled .nib file from the .ipa archive (.xib files are compiled into .nib files), then use it as a resource file when building your project on Windows, by inserting this .nib file into the final app using a pre-packaging script (see the section about pre-packaging scripts). You will also need to remove all references to the .xib file from the project.pbxproj file to make the builder happy. If the previous tip isn't appliable to you, you will need to rewrite the concerned assets so that they do in plain Objective-C code what they were doing in Interface Builder, or if you can't, simply not use them for now.
  • The builder doesn't work if your project is accessed through a network path (UNC path such as \\SERVER\share\project). To workaround this limitation, just mount your network path as a network drive, and access it using the drive letter instead of the network path.
  • I could not make CocoaPods work consistently on Windows. Despite a heroic struggle, the best I could achieve was partial success. The two reasons are the drastic (and ages old) limitation of path names in the Windows API to 260 characters, and the fact that more characters are forbidden in filenames on Windows than on macOS, which forbids some proeminent CocoaPods packages from being deployed at all. If your project relies on CocoaPods to inject additional libraries, bundles or frameworks in the Xcode project file, inject them manually (see the troubleshooting section). Most of the times a non-CocoaPods distribution of the framework(s) you need exists.
  • Two-factor authentication is not supported by the iTunes Connect upload tool. The workaround is to create and use another account than your primary account, ensuring the "application manager" role is set and this authentication method is disabled.
  • Windows XP/2003 support has been dropped due to this bug in the Microsoft runtime, which would require an unreasonable amount of work to circumvent (and there's no chance Microsoft will ever fix it now).
  • Windows 32-bit support has been dropped to allow crossing the cursed 2 Gb RAM boundary and the successful linking of large files. If it's a problem to you, may I suggest that it's about time to upgrade this archaeologic piece of hardware that you use as a development computer? ;-)

[ Back to top ]

14. Troubleshooting

If none of these directions help to solve your problem, then contact me for support (but only after these verifications are made!)

[ Back to top ]

15. Change log

[ Back to top ]