Tuesday, February 25, 2014

Creating an Apple XCode Project Using the GNU Build System (a.k.a. Autotools)

Some posts ago I wrote about two of the best portable C/C++ IDEs, NetBeans and Eclipse CDT, and their support for projects configured and built with the GNU Build System (a.k.a. Autotools). The only shortcoming of these IDEs is the lack of support for Apple frameworks and in another post I showed one possible workaround and provided the ZSH script I use, hosted on GitHub, to automatically create the soft links to include in the C/C++ include paths of your project.

Sometimes, however, it may be desirable to use Apple XCode instead of the aforementioned IDEs. Since there's no native support for the GNU Build System in XCode, some manual configuration must be performed to have XCode use the Makefile (and the other artefacts) generated by autoconf and automake for your project.

In this use case I prefer to maintain the sources completely separated from the XCode project. XCode lets you add references to the source files in a project, so that the physical location of either thing is irrelevant. Moreover, you won't risk polluting the sources with XCode-specific files and adding them by mistake to your source code repository.

Creating the project

First of all, an External Build System project must be created:

Create External Build System project

In the project options window, type the name of the project and your name: since the build is made using your autotools configuration files, these fields are irrelevant and are only used to label the XCode project:

Choose options for the project

Unless you want to use another make binary, you can leave the Build Tool path as is.

After setting up your project options, XCode will ask you the location where your new project must be created.

Configuring the Build Directory

As you know, the sources must be configured with the configure script (created by the GNU Build System) in order for them to be built on a specific platform. Since XCode has no knowledge of this mechanism, you must configure as a build directory a directory where the sources have been configured.

Once again, I prefer configuring the build on a separate directory, instead of doing it directly in the sources folder. This way, I do not pollute the source trees with object files and any other artefact created during configuration and build.

To configure your sources you must perform the following operations:
  • Go to the designated build directory of your XCode project (I usually create the build directory in the project root).
  • Run the configure script from your source root directory:
$ [sources]/configure [opts]

Now, the build directory path must be set into your project configuration:
  • Select the project root node in the Project Navigator pane.
  • Set the build directory in the Directory field, as shown in the following screenshot.

Project build directory

The configuration of the build directory is a one-time task for each target, no matter how many times you reconfigure the build in that folder. If you plan to have more than one kind of build, such as debug build and release builds (each one with different configuration options), just create multiple targets in different build directories (such as build/debug and build/release), each one configured separately. To create a new target in an XCode project, use the File/New/Target menu item.

Adding Sources to the Project

Your new XCode project will be empty and source files must be added to it. To add existing sources to your project you can use the Add files to [project-name] menu item in the File menu or in the contextual menu that appears when you right click over your project root in the Project Navigator pane. Alternatively, you can use the ⌥⌘A shortcut.

In the add files window, choose the files and/or the directories to be added. If you want to, you now have the opportunity to create groups or folder references for any added folders.


Now you are ready to build your sources from XCode using the GNU Build System. And if you wonder where your build output is, in XCode the Log Navigator pane must be used.

1 comment:

Maury said...

I came across this page looking for detailed instructions about using the external build system, but it seems there have been some minor changes since this was posted. To get it to work under Xcode 7.x, I had to skip the step about the "build" folder and set the Directory in the project settings to the source folder. Then it worked fine, although it ignores the build folder, of course. This isn't as bad as it sound though, because it puts all of the output in a "DerivedData" folder, which has the same ultimate result.