Setting up the Xcode IDE for developing Qt applications for Mac OS X is relatively simple. There are three options, GNU Make, Carbon, and Xcode makespec. Using the Xcode makespec is the simplest way to get started, but it seems to have problems with certain setups.

Using the Xcode makespec

If you don't mind using the console to set up your project, creating a new Xcode project can be done automatically by qmake.

Create the project bundle

1. Create a folder for your project. (You can switch the order of this step with the next.)
2. Open a console such as Terminal.app or an xterm using X11.app.
3. Change directories to the project folder using the cd command.
4. Create a .pro file. Calling qmake -project in an empty folder will not produce a suitable pro file, but touch myproject.pro will.
5. Execute the command qmake -spec macx-xcode.

From here you can close the console and open the .xcode bundle created by qmake or you can use the open command to launch it from the command line.

Known Issues

These issues are as of Qt/Mac 4.1.3, all experienced using OS X 10.3.9 and Xcode 1.5.

• Adding files to the Xcode project does not automatically add them to the .pro file. The .pro file can be edited within the project.
• Sometimes, adding a header file to the project will cause the build process to fail in dependency checking. There should be a workaround but I have not found it yet.
• Xcode will sometimes emit spurious internal errors about the build settings. I'm not sure if this is due a bug in qmake, a bug in Xcode, or misconfiguration of my build environment. It is also possible that qmake generates valid Xcode 2.x project files that aren't completely backwards-compatible with Xcode 1.x.

As a GNU Make project

The solution most similar to the traditional build process is to use GNU Make. This uses the traditional build tools and is quicker to set up, but ultimately is less convenient than the other methods.

Create a new GNU Make project

1. From File | New Project, select "GNU Make".

Add a qmake target

1. From Project | New Target, select "External Target".
2. Name the new target "qmake".
3. Under the new target's settings, under Custom Build Command, specify the full path to the qmake binary in "Build Tool".
4. Erase the contents of the "Arguments" field.

Manage your .pro file

If you want to maintain your own .pro file:

1. From File | New File, select "Empty File in Project".
2. Name the file with a .pro extension.

If you want to use qmake -project to maintain your .pro file:

1. Duplicate the "qmake" target. Name the new target "qmake -project".
2. Under the new target's settings, under Custom Build Command, set the "Arguments" field to "-project".

Building your project

1. If using the qmake -project method, select "qmake -project" as your active project and click Build to update your .pro file.
2. Select "qmake" as your active project and click Build to run qmake to generate your Makefile.
3. Select your main target and click Build to run make to compile your application.

As a Carbon project

Setting up a Qt application as a Carbon project requires more work but gives you better control over the build process and integrates qmake more comfortably into the Xcode toolchain when compared to the GNU Make method. This method produces a project similar to the one created by using the Xcode makespec, but has been deprecated in favor of the more automatic approach.

Create a new Carbon project

1. From File | New Project, select "Carbon application".
2. Delete the main.c and .pch file automatically generated by the template. (Feel free to replace them with a main.cpp file.)

• Deleting the prefix header is optional; you can use it if you want but it's not portable. If you choose to use it, take out the Carbon include provided by default.

Add Qt frameworks

1. Control+click or right-click on "External Frameworks and Libraries" in your project's file tree. Select Add | Existing Frameworks.
2. Find and add QtCore.framework.
3. Repeat to add QtGui.framework and any other frameworks or libraries needed by your application.

Add a Shell Script build phase

1. From Project | New Build Phase, select "New Shell Script Build Phase".
2. Set the script to:

   /path/to/qt4/bin/qmake 

1. If you intend to use Qt Designer, add make compiler_uic_make_all after make mocables.
2. If you wish to allow qmake to automatically maintain your .pro file, add /path/to/qt4/bin/qmake -project as the first line.
3. Expand the active target in your project's file tree and drag the Shell Script Files step up to be the first step of the build sequence.

Configure the compiler and linker

1. From the Project menu, select "Edit Active Target".
2. In the Build tab, find "Other Linker Flags" and set it to "-filelist MocLinkList".
3. Find "Prefix Header" and clear it.
4. Find "Precompile Prefix Header" and uncheck it.

• Of course, if you chose to use the prefix header, don't clear it. You may or may not wish to precompile it; consult Xcode's documentation.

Building your project

At this point you can use all of the Xcode build tools directly with no special steps.

Using Qt Designer

Unfortunately, while Xcode allows you to choose external editors for various file types, it seems to lack a way to specify new file types. If you could specify a new file type (i.e. "sourcecode.ui"), it would be a simple matter to associate it with Designer.

This doesn't mean you're out of luck, though. You can add .ui files to your project just like any other file, and if you control+click or right-click the file, selecting "Open with Finder" will launch Designer with the selected file.