Tutorial: Building Configure/Make Projects in Xcode

Author: David Gohara
Website: http://www.sbgrid.org

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).

Requirements:

Xcode 2.3 or higher
gfortran and Xcode IDE plugin for gfortran
Subversion
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

Subversion:

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:

http://www.codingmonkeys.de/mbo/

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:

mkdir ~/Make_Xcode
cd ~/Make_Xcode

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.

Xcode (configure):

At this point you have the following directory hierarchy:

~/Make_Xcode
~/Make_Xcode/apbs

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
cd apbs
./configure > log
exit 0

6) Switch the target from 'apbs' to 'configure'

7) Open a separate terminal window and cd into the following directory:

~/Make_Xcode/apbs

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"

Xcode (APBS):

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.

Xcode (Build):

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.

Xcode (Debugging):

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!

Subversion (Commit/Update/Revert):

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.

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Breakpoints not working in Fortran

I recently tried to debug a Fortran app with Xcode. The program was built with an external build system, and the compiler was xlf.

I could get the debugger to load the program and run it, but it seemed to be ignoring my breakpoints. It turns out I had to change a preference to get it to work, so I am entering instructions here in the hope that it may help someone else. This is what I did:

1) Open preferences from Xcode menu
2) Click the debugging tab
3) Deselect the 'Load symbols lazily' checkbox

If you find your breakpoints are not working, it may be worth giving this a look.

Drew

---------------------------
Drew McCormack
http://www.macanics.net
http://www.macresearch.org

Re: Breakpoints not working in Fortran

I gave this a try but it didn't work for me. I'm using the internal build system in Xcode. However, I did find a solution and it's posted here:

http://www.macresearch.org/xcode_gfortran_contest_winner_damien_bobillot#comment-11300

Adding projects in Single solution

Hi,
Your article is very nice for starting.
Thanks.
I am new in MAC programming. I have 5 different project in XCode. I want to make them in a single solution but don't know how to. As we make a single solution for more project in Visual studio.

Could you please help meout regarding this problem?

Regards,
Shadab