Tutorial: Building Configure/Make Projects in Xcode
I use the Xcode IDE for all of my programming tasks either as full-fledged Xcode projects or simply using it for text editing. I find Xcode, aside from being free, to be very powerful as a project manager. I especially like the way it wraps gdb (the GNU debugger) in a nice GUI that simplifies stepping through applications.
Recently I decided that one of the programs I work on (APBS) would benefit from being converted into an Xcode project. APBS is entirely an configure/make style application, run from terminal. It’s cross platform, so any changes to the application need to be mirrored first in the configure/make portion of the application. What I eventually decided was that the Xcode project would simply serve as an overlay to the main subversion project, but in such a way that I could use most (if not all) of the Xcode facilities for managing the daily programming/maintenance tasks of the APBS development cycle. Arranging the project this way maintains cross platform development/building of the application, while providing a nice, unobtrusive front end.
This tutorial will outline the steps I took for this application to create the Xcode overlay. Some of the steps are specific for APBS, but I think overall it will cover the general considerations that others might need to take to create Xcode overlays for their cross platform configure/make style projects. Rather than create a contrived project, I think it will prove more useful to see some of the considerations in a real-world application. I could be wrong... You can either just read the contents or follow along (all of the steps for following along are included...I think).
Xcode 2.3 or higher
gfortran and Xcode IDE plugin for gfortran
Mac OS 10.4
Setup (gfortran and Xcode IDE):
You can obtain a working copy of gfortran plus the Xcode IDE plugin as installer packages from the MacResearch site at the following address:
gfortran PPC: http://www.macresearch.org/files/gfortran/gfortran-ppc-bin.tar.gz
gfortran Intel: http://www.macresearch.org/files/gfortran/gfortran-intel-bin.tar.gz
gfortran plugin: http://www.macresearch.org/files/gfortran/gFortran_Installer.mpkg.zip
APBS is an open source project hosted on SourceForge and uses Subversion for version control. As of Mac OS 10.4.8 subversion isn’t included as part of the OS (or developer tools), although it is supported by Xcode. So the first thing you need to do is build/download a copy. You can get a precompiled subversion binary from Martin Ott’s website:
This is the version I used for this project. It will be installed to /usr/local/bin.
Once you run the installer, make certain that subversion (svn) is accessible in your path.
1) Open terminal and verify that subversion is installed by typing 'which svn' (no quotes)
Note: If it doesn't find it make sure that /usr/local/bin is in your path or use the full path to svn in the following steps.
While still in terminal create a new directory:
Then type the following command:
svn co https://svn.sourceforge.net/svnroot/apbs/trunk apbs
This will download the trunk of apbs into ~/Make_Xcode
Note: If you get an error midway through the download process, re-run the command above, this sometimes occurs if the SourceForge server times out the connection during the download. To confirm that you have the full distribution the last line of the download should state what revision you currently have.
At this point you have the following directory hierarchy:
Now we will want to create the Xcode project overlay. All of the Xcode project files will be installed in the ~/Make_Xcode folder above the apbs directory.
A few of the files needed to compile APBS are generated during the ‘configure’ stage. Rather than having configure run as part of the Build stage (it can take a while to run, even if it caches the results), we will create a separate configure stage that we can run once, then use the generated files for all subsequent builds (which will be much faster).
Note: A quick note about dependencies. APBS has few internal dependencies when building the actual application. That is, most generated object files can be compiled in any order with a single link step. This may not be the case with your project. However, Xcode has facilities for creating multiple build stages that can be used for ordering dependencies.
1) Start Xcode and create a new project in the top level directory (~/Make_Xcode)
2) Create a new target and name it 'configure'
3) Open the configure disclosure triangle in the Targets > configure section of the "Groups & Files" pane (a build step called "Run Script" should appear).
Double click the “Run Script” icon (or click once on it and press the Info button in the Xcode toolbar).
4) Edit the Shell from /bin/sh to /bin/csh (or /bin/bash) and make sure gfortran is in your default path
You can verify that gfortran is in your path by opening terminal and typing:
prompt> which gfortran
5) Edit the script with the following code:
# shell script goes here
./configure > log
6) Switch the target from 'apbs' to 'configure'
7) Open a separate terminal window and cd into the following directory:
8) Press the "Build" button to run the configure script (this could take several minutes to run).
9) In the terminal window type:
tail -f log
Doing this will allow you to follow the configure scripts progress. If the build stops somewhere searching for a Fortran binary, double check that you changed the default shell (Step 4 above) and that gfortran is in your path.
Once configure finishes you should see something like the following in the file ‘log’ at the end:
APBS to be linked with following libraries: -L/Users/gohara/Projects/apbs/apbs/contrib/lib \ -lmaloc -Wl,-framework -Wl,Accelerate -lm -lSystemStubs APBS to be compiled with following includes: -I. -I/Users/gohara/Projects/apbs/apbs/contrib/include Please type "make; make install"
Now we want to get the APBS binary build portion of the project in place. There are a lot of ways to accomplish this. For this tutorial, I’ve taken a minimalist approach to getting the project together, adding in only the files and directories necessary to build the main portion of the project (that is the final APBS executable, and not the additional tools).
1) Switch the active target from 'configure' back to 'apbs'
2) Open the “Source” disclosure triangle in the “Groups & Files” pane and delete main.c
3) Add the apbs source (src) files (make sure "Copy items..." is unchecked and "Recursively
create..." is selected). For "Add to Targets", make sure only apbs is selected.
4) Right clicking on "Source" and add the "bin" directory as you did for "src" in Step 3 above.
5) Open the Targets > apbs > Compile Sources disclosure triangle and delete all of the references to the file 'Makefile'
Note: Deleting the files from here doesn’t actually delete the files on disk. It only removes them from consideration for deletion by the Xcode build system. If you don’t remove them from here, Xcode will halt when it encounters those files.
6) Right click on Link Binary with Library and choose Add > Existing Files,
7) In the dialog that appears navigate to ~/Make_Xcode/apbs/contrib/lib and select libmaloc.a adding it to the apbs target only.
At this point your project will look something like this:
8) Click on the top level item in the “Groups & Files” pane (apbs project icon) and click the Info button.
9) Click the Build tab and for “Header Search Paths” add:
./apbs/contrib/include ./apbs/src/generic ./apbs/src/aaa_inc ./apbs/src/mg ./apbs/src/fem
10) Finally add the Accelerate framework to the project by Right-clicking on the apbs project and selecting "Add > Existing Frameworks". Navigate to /System/Library/Frameworks and choose Accelerate.framework
Note: Accelerate provides the necessary BLAS routines that APBS uses at runtime.
At this point the project should be setup. Now we can try and build that binary. You will almost certainly see warnings come up during the compilation process. Most of these are harmless and have to do with unused variables. Do the following to build APBS:
1) Click the Build button in the main Xcode toolbar.
2) In terminal cd to ~/Make_Xcode/build/Debug (or navigate there in the finder) and make sure the apbs binary exists.
Xcode (Build and Go):
Ok so now we have a binary, big deal. What we really want to be able to do is run the binary and do various coding/debugging tasks. So we need to create a stage for actually running the binary in the appropriate environment.
Since APBS is a terminal application we need to use the Xcode facilities for running terminal based programs. What? You didn’t know Xcode could do this? Of course it can.
1) Right click on "Source" and choose Add > Existing Files... Add the examples directory to the Source group.
2) Expand the Executables disclosure triangle, click on 'apbs' and then click on the Info button.
3) Select the "General" tab.
4) In the Info panel choose "Custom Directory" for the working directory and set it to the full path where the apbs binary is located.
5) Select the "Arguments" tab and add a new argument as below
6) Click "Build and Go"
At this point in the Run Console you should see a bunch of text scroll past in the window like:
---------------------------------------------------------------------- APBS -- Adaptive Poisson-Boltzmann Solver Version 0.4.0 ... ... ... ---------------------------------------- PRINT STATEMENTS Warning: The 'energy' print keyword is deprecated. Use elecEnergy. print energy 1 (solvated) - 2 (reference) end Local net energy (PE 0) = -2.295849319626E+02 kJ/mol Global net energy = -2.295849319626E+02 kJ/mol ---------------------------------------- CLEANING UP AND SHUTTING DOWN... Destroying force arrays. No energy arrays to destroy. Destroying multigrid structures. Destroying 1 molecules Final memory usage: 0.000 MB total, 58.786 MB high water Thanks for using APBS! apbs has exited with status 0.
Sweet.... Now we have a project that builds and a test script that can be used to run a particular problem. In the case of APBS, there are a lot of examples that are available, and depending on what I’m actually debugging the input script and arguments can be changed for that particular purpose.
You can now run the Xcode debugger by setting breakpoints anywhere in the code. As a quick example of using the Xcode debugger (which is a wrapper to gdb). Do the following:
1) Open the file nosh.c in Source > src > generic
2) Set a breakpoint on the function NOsh_parseAPOL (~line: 410) by clicking once in the "gutter" (where the line numbers are). A blue arrow should appear.
3) Instead of clicking "Build and Go" click and hold on the "Build and Go" Button and select "Build and Debug"
The application should halt at the first variable to the function entry.
At this point you can step into, out of, and do all of the things you’d do with gdb. You can view the values of variables, navigate the call stack etc... It’s extremely powerful, and at the same time very user friendly. How much butt does Xcode kick? A lot.
Xcode (Managing Debug Symbols):
One very cool thing about Xcode that you can have debug symbols all over the place in your project but you can navigate and manage them from a single place. In the main Xcode menu click on Debug > Breakpoints. A new window will appear:
Clicking on a particular line will jump to that point in the project. You can set and unset the current breakpoints from that window as well. For someone who steps through code a lot, I find the debugging tools to be very useful. Xcode Rocks!
Xcode works with Subversion and since this is a subversion project, it’s tempting to use subversion within Xcode (and indeed I have). However, I’ve noticed to some extent that there is a bit of a disconnect between the terminal subversion control and Xcodes. So what I do when I want to commit changes or update the project is run those commands from the command line.
Files that Xcode is already aware of will automagically update. If a new file was added to the project you’ll need to manually add that in Xcode. However if you want to try and use Subversion (or some other SCM) to control the project you can use the following steps:
1) Select the highest level 'apbs' object in the "Groups & Files" pane and click on the Info button
2) On the General tab you can set the SCM Type and then check "Enable SCM"
3) Xcode will then (for authorized users/projects) manage the check-in/check-out process for the project.
There are a lot more things that you can do with Xcode and configure/make style projects. This is just one example. In future tutorials we’ll discuss in more detail the power of Xcode for managing and developing projects.