(Apologies for the somewhat wired post title - it'll all make sense later and I wanted to get it listed by Google in case you're experiencing the issues discussed here.)

November 14th update: I've just published even more details about mobile provisioning here.

I've started this post quite a while ago but never really finished it. Last night one of my colleagues ran into a mysterious PreflightingApplication error when trying to deploy an application from Xcode to the iPhone.

We finally solved the problem by setting him up completely new and while so doing I again noticed that some of the instructions Apple is providing are confusing if not imprecise. Therefore I finally decided to finish the post up and highlight some of the subtleties of the process. Hope it helps!

Prerequisites

Here is a brief overview of the environment we are working in:

• We are approved and paying members of the iPhone Developer Program.
• We are using iMacs with Mac OS X 10.5.4, Xcode 3.1 and the final version of iPhone SDK 2.0 (build 9M2199a).
• Our iPhones are running the pwned Apple firmware 2.0.1 with Jailbreak and Unlock applied. We've used Pwnage tool 2.0.2 to do the magic.
• We are not using any methods to circumvent Apple's code signing practices and generally do not endorse those.

The Developer Program Portal

Your entry point into iPhone developer heaven is the Developer Program Portal. Navigate to the iPhone Dev Center and log in with your Apple ID.

The iPhone SDK download is available for free. However, in order to set up iPhone developers for code signing and provisioning, you need to be an approved iPhone developer and should see the login for the Developer Program Portal in the upper right corner.

Apple's Guide to setting everything up and some additional remarks

Apple has published a pretty comprehensive guide how to do the basic set up. You need to be an approved iPhone developer to access this download. Here are some tips which helped us getting things right:

• Make sure you've downloaded all certificates and stored them in a secure place on your hard disk. This includes the WWDR Intermediate Certificate and your personal certificate issued by Apple which you can download from the Developer Program Portal.
  
  
  
• Install the certificates by double-clicking them. This will launch the Keychain Access application. Make sure you install to the login chain which should be selected by default. Validate that your keys have been correctly installed and validated by opening Applications > Utilities > Keychain Access and expanding the iPhone Developer: Your Name section in the login Keychain.
  
  
  
• Make sure your App IDs are set up correctly.
  
  App IDs are an important piece of the overall iPhone developer infrastructure and one, where I found many people struggling with subtle details. Unfortunately neither the Developer Program Portal's How to section nor Apple's guide are extremely clear on what needs to be done to get things going.
  
  An App ID is a unique digital fingerprint that OS X iPhone uses to grant your application access to a portion of the Keychain and is one part of your development provisioning profile. In the App IDs section of the Developer Program Portal create an App ID if you have not yet done so. You can give your App ID an arbitrary Name. The name is used for reference purposes only.
  
  The ID itself must be unique. Therefore most developers use a reversed version of their domain name (or their companies domain name) as it is pretty common for namespaces. In case you would like to use a single App ID for all of your applications, you have to add a trailing asterisk. With that said I'm using the following ID:
  
  net.24100.*
  
  Important: Apple generates a Bundle Seed ID for every App ID you create and appends it to your App ID as a prefix, however, the Bundle Seed ID must not be considered as a part of your App ID. So whenever you're prompted for your App ID anywhere in Xcode or elsewhere, you must only use your App ID without the Bundle Seed ID. To make this very clear: In my case in the ID column of the Portal it says C5LRL9WHCV.net.24100.*. The "C5LRL9WHCV" part is the Apple generated Bundle Seed ID and only the net.24100.* part is my App ID!
  
  
• Use the Developer Program Portal's Devices section to set up your development device. Make sure to use the correct Device ID by copying it from Xcodes Window > Organizer.
  
  
• In the Provisioning section of the Developer Program Portal make sure you've set up at least a single Provisioning Profile. Provisioning profiles combine a developer certificate, an App ID and a device and link them together. Once you've double-checked everything, download the provisioning profile to your hard disk. If you have not yet done so, you need to install the provisioning profile to your iPhone. I'd suggest not to use the method outlined by Apple (dragging the downloaded provisioning profile file to the Xcode icon) but instead open Window > Organizer in Xcode with your device connected, selecting the device and hitting the [+] in the Provisioning section.
  
  You can double-check whether the profile has been installed correctly by going to Settings > General > Profile on your device.

Fixing settings in Xcode

You've got to go through the previously outlined one-time process in order to start deploying and debugging applications to your iPhone. There are also some additional important details which - if you're not doing it right - can cause wired errors once you deploy.

You might see error messages like the one we've encountered:

"Your mobile device has encountered an unexpected error (0xE8000001) during the install phase: PreflightingApplication"

Chances are you also occasionally see application verification failed errors with the same or similar hexadecimal error codes. In almost all cases related to this error the problem has been a wrongly configured Bundle Identifier in Xcode's project settings.

Even though Apple explicitly states somewhere on their web site that you don't need to set the Bundle Identifier manually anymore, we never got deployment working without having it set correctly manually. So before you move on check your project settings:

• In Xcodes project organizer expand the Resources section.
  
  
• Find the Info.plist file and double-click to open it.
  
  
• Enter your App ID into the Bundle identifier field. In my case I've entered net.24100.*.
  
  Note: I've seen others recommending to put something like net.24100.${PRODUCT_NAME:identifier} in here. While this might be perfectly correct, it simply did not work for us in most cases. The reason might be (and this is a purely personal assumption as Apple unfortunately does not reveal specific details about the inner workings of the deployment process) that with the ${PRODUCT_NAME:identifier} set as the Bundle identifier the deployment can not uninstall a previous version of the application. If you manually uninstall the application on your iPhone and redeploy, this version seems to work, too. Again, this is pure speculation and in case you've got further information, I'd love to see your comments. Anyway, we simply put net.24100.* in the field and it works like a charm.
  
  
• The last thing I found many people struggling with are the correct project settings. You might want to verify those, too. To access your project settings select the first entry in the Group & Files pane in Xcode project window. Double-click it or select Get Info from the context menu. Here are my current settings. I've highlighted the area which is important for deploying:
  
  In the Code Signing Identity field enter iPhone Developer: Your Name. The name must match the one used for the certificate. You might find it awkward but you really do have to manually type in iPhone Developer a colon a blank and then your name.
  
  In the Code Signing Identity > Any iPhone OS Device filed make sure it says iPhone Developer.
  
  In Code Signing Provisioning Profile > Any iPhone OS Device you should be able to select a provisioning profile. In case no provisioning profiles show up here, you most likely have a typo in the Code Signing Identity field.

That's it for today. I hope this helps. In case you've got additional tips and findings, please do use the comment feature as others very likely will find your information valuable, too.