Developing SAMRAI apps in Xcode

I do like my graphical front ends; but I am also quite partial the the unix back end of OS X. The AI of SAMRAI stands for Application Infrastructure, which means that it is essentially a lot of code that helps someone wishing to develop a parallel adaptive mesh refinement application do exactly that. Applications are built using the Makefile system; SAMRAI has a configure file, so that it can be incorporated into the developer's own Makefile.

To use Xcode with SAMRAI, it just requires modifiying some build settings, and adding some libraries. Here's what you do...

1. Create a project
   Select a C++ command line tool.
   
   On the next screen you'll be asked for a project name and location. I called this demo "samraitool".
2. Ammend the header and library search path.
   Open the Project Info window, by clicking the Information button, or keyshortcut Apple+I. Xcode has a setting hierarchy system, which for most users will boil down to Project settings (which we're going to edit) and then Target settings which override the Project settings. You might well be looking at something like this:
   
   On the build tab, for all configuration settings, look at the search paths, and enter the paths to where you've installed mpich, hdf5, samrai and any other libraries your tool might be dependend on, such as X11. For example I've added the following to my project Header Search Paths:

   $(HEADER_SEARCH_PATHS) /usr/local/samrai/include /usr/local/hdf5/include 
   /usr/local/mpich/include /usr/local/lsmlib/include /usr/X11R6/include

   To the Library Search Paths, it's very similar, I've also got the paths to the xlf libraries:

   $(LIBRARY_SEARCH_PATHS) /usr/local/samrai/lib /usr/local/hdf5/lib 
   /usr/local/mpich/lib /usr/local/lsmlib/lib /opt/ibmcmp/lib 
   /opt/ibmcmp/xlf/8.1/lib /opt/ibmcmp/xlsmp/1.3/lib  /usr/X11R6/lib
   

   
3. Add external libraries.
   

   Executables in Xcode are dependent on targets, which in turn have different buid phases. These build phases might be copying resources (such as icons) or linking with external libraries. When one creates a Cocoa application, then this linking, to the Cocoa framework is done automatically for you by Xcode. For our project we need to specify the external libraries manually.

   Firstly, if you use Finder's sidebar, then it's a good idea to navigate to the /usr or /usr/local folder on your machine and add it to the sidebar (press Apple+T).

   Select your target in Xcode and Add Existing Files to it.
   
   Select the SAMRAI library files, use your sidebar shortcut to navigate to your samrai library file, most probably /usr/local/samrai/lib. You can also bring up the Go dialog with Shift+Apple+G. Select all the *.a library archives, which should be all the files in there. Click Add on the next pane, so that you are only creating references to the libraries, and associating them with the only target. You'll probably want to move all those libraries to a new group (the yellow folders).

   Other than the SAMRAI libraries, you'll also need to add:
   

   /usr/local/hdf5/lib/libhdf5.a
   /usr/local/mpich/lib/libmpich.a
   /usr/local/mpich/lib/libpmpich.a
   /usr/X11R6/lib/libX11.a
   /opt/ibmcmp/xlf/8.1/lib/libxl.a
   /opt/ibmcmp/xlf/8.1/lib/libxlfmath.a

   Those last two are xlf fortran math libraries. Essentially any libraries that are linked to on the command line need to be added here in this fashion. If you expand the arrow next to the target in Xcode, then you can see the build stages, one of which should be 'Link with external libraries' and in brackets it will have all the libraries it's linking against. If you've added a library to the project, but it doesn't show up in the target's build stage, then select the library and check the info, make sure it's ticked against the correct target.

4. One last thing
   I've also added "-bind_at_load" to Other Linker Flags in the build settings. You might get a warning about it otherwise

Hopefully, that should be everything, and provided your code is correct, Xcode should be able to build your samrai project.

I've also created an Xcode project template, that should have all the above steps already completed. Download the archive, Unzip it, and place it in /Library/Application Support/Apple/Developer Tools/Project Templates/Command Line Utility. Then in Xcode when you create a new project, you should be able to select SAMRAI C++ tool that links against your SAMRAI installation. This will probably only work if you've installed the libs into /usr/local/{samrai|hdf5|mpich}/libs.