Tutorial: Introducing the Xcode 3.0 Organizer

Author: David Gohara
Web Site: gohara.wustl.edu

In my introduction to Xcode and IB 3 article I mentioned a new tool that is used for creating project snapshots call Organizer. In fact Organizer is useful for things other than creating snapshots of projects and files. Organizer can also be used for maintaining and running a variety of coding projects absent a full Xcode project. The primary target of this type of functionality is for Makefile based projects. What this means is that support for other languages can be brought into Xcode without having to develop (reverse engineer) a plugin that understands how to compile your code.

The addition of Organizer is important too for MacResearchers using languages such as Fortran, since as I mentioned before, our Xcode plugin for gfortran no longer works in Xcode 3. However, it's not the end of the world. In this tutorial I'll introduce you to the Organizer and show you how to use it to build your Makefile based projects (it can be used for non-make based projects and a slew of other things as well). I'd also mention that since Organizer is new, there are a few things about it that could use some improvement. I'll offer my feedback as it comes up throughout the tutorial. But in general I think you'll be happy with Organizer.

Let's get started...

For this tutorial we'll use a program called APBS as our canonical Makefile based application. Since APBS is written in C and Fortran you'll also need a gfortran installed. You can download it from MacResearch.org or http://hpc.sourceforge.net. The plugin won't work but the compiler will. I recommend using one of the pre-August builds of gfortran on Leopard.

Once you've installed gfortran obtain the source for APBS from SVN:

1) Open Terminal
2) cd Desktop
3) svn co https://apbs.svn.sourceforge.net/svnroot/apbs/trunk apbs

After a few minutes the download should be complete and you'll have a folder called apbs on your desktop. We're ready to go.

In Xcode

Launch Xcode and select Window -> Organizer. A window will appear that has a few greyed out controls and a source list. Drag the entire APBS folder to the source list.

Open the disclosure triangle next to the top level apbs folder, select any file beneath it and then click on the little rectangular icon on the bottom toolbar (third from the left in the lower left corner). That should open the Organizer editor. You'll notice that you have access to all of the editing features you do with Xcode, including syntax coloring code folding, focus follows selection, line numbers and method shortcuts.

Select the top level apbs folder. The toolbar icons should now be active.

Important: Toolbar actions are based on the level you are working at. If you select a subfolder, for example config, and create an action, that action will only affect that folder and the items beneath it. Actions aren't necessarily global. Keep this in mind. It can be confusing.

With the top level APBS folder selected click the little triangle next to the Build button. A pop menu will appear, choose Edit Actions...

A sheet will drop down that will look similar to the one in the figure below.

Note that there is a listing of the build "actions" and there is a hierarchy of folders. In this case, I had selected apbs -> bin when I opened the Edit Actions sheet. Whatever folder you on when you activate the Edit Actions dialog, will show you that folder and every folder through the path to it from the top level item. What we want to do is edit the top level action for APBS, so instead I highlight the apbs folder at the top.

Again, this is one of the confusing things about how the Organizer works, so you need to be careful what is selected in the source list when you edit actions.

The full window should now look something like this:

On the left is the list of actions associated with the Build toolbar item. On the right are two elements. A drop down menu (see below) and the script editor. The script editor allows you to create a simple script that is used to issue a command to the build process. In this case, we are going to run configure.

The drop down menu labeled Directory dictates where the script or command will be executed from. Again, this is why it's important the correct folder is selected. The options are:

Selection - The script will be executed as if it were being run in the selected folder. In this case the APBS folder is highlighted, so that is where the command will run from. It's as if you opened terminal and typed the command within that folder.

Top Level Organizer Item - Regardless of what is selected on the left hand side, the command will be run from the top level folder. In this case the folder is called "apbs".

Defining Organizer Item - This is the item selected that the Action was created in.

Home Directory - The script will run from your Home Directory (~/).

File System Root - The script will run as if it were at the base of your file system.

Edit the configure Script

Select configure on the left hand side, choose Top Level Organizer Item on the right, and change the script to the following:


export PATH=${PATH}:/usr/local/bin

./configure --prefix=/tmp/apbs

The first line simply says what shell to use (by default it's sh. In this case I don't have gfortran in my default path, so I need to tell the environment where to look. Then it's the standard configure command, and we'll install apbs into /tmp since that's easy and gets cleaned out automagically.

Let's also modify our make command as shown below:

Shortcut Keys

I also assigned some shortcut keys. You can assign shortcut keys for every action and even have the same key for multiple actions. This is because an action is called that is specified at the level you have selected in the Organizer source list. Again, this is very confusing and can be a source of frustration. So be careful where you select.

Ok... With the top level APBS folder selected, click and hold on Build and select configure. Now open the Build Results Window (command-shift-B). You should see a bunch of configure based text fly by. This text is the same as if you were running from the command line. Note you may need to open the "build transcript" pane which is the little icon two over from the checkbox.

Once "configure" is done, run "make install".

Once that is completed you should have an installed application in /tmp/apbs.

Testing it out...

Ok. Building applications is fine, but we also want to run, debug and test them (you know...develop). So let's do that.

In the source list on the left, open the disclosure triangle next to "exmaples" and select the "born" folder. We're going to run the "Born Ion" example. No this isn't some knock-off of a Matt Damon movie... this is real science, 1920's style.

With the "born" folder selected. Click and hold on the "Run" toolbar item and choose "Edit Actions"

Click and hold on the little plus at the bottom of the left side of the sheet and choose "New Shell Script". Configure as shown below:

Notice this script is a bit different. Effectively what will happen is the following when you click "Run -> run born":

1) The spawned task will start in the born directory (Defining Organizer Item)
2) It will issue the command: /tmp/apbs/bin/apbs . This effectively is the executable path.
3) It'll set on the command line arguments to use the input file (for apbs) apbs-mol-auto.in

I've also set the debugger to GDB. We'll get to that in a second. In essence, we're just running a shell command that says change into the born ion example directory, launch APBS from the following path (our install path) and tell apbs to use the following input parameter file.

Click OK and then run it. You should see something like this in the Console window (command-R):

Ok... great so we can edit out programs source, build it using the standard Makefile (which means we can use whatever compiler technology we want), but how do we debug it.


Okay, this part isn't as easy as it is in Xcode where can graphically set a breakpoint and run the app. In this case we have to do it a bit differently. In this case, we want to break on a call to the function solveMG. Open the debugger window (command-shift-Y), then click on the breakpoints icon. This will give you the breakpoints editor as seen below:

Double-click on the text that says: Double-Click for Symbol. And type in solveMG. What we are doing here is setting a symbolic breakpoint. You can do this in a number of ways. For example:

Cocoa Method -> - [NSFoo bar]
C function -> myFunction
Generic Source -> main.c:15 (where :15 is the line number)

If the "Location" field doesn't automatically update, fill it in with the text apbs. Basically we are telling it that apbs is the project this breakpoint belongs to. This is important though, if the field is wrong or empty your breakpoints won't work.

Sweet... So now click on Go. And when solveMG is called: Booom!

You can then step into, over, out-of, set additional breakpoints etc...

SCM and Organizer

A fellow MacResearcher asked the other day if Organizer can be tied into the SCM system as part of Xcode. And the answer is an affirmative 'Sort of...'

Creating SCM repositories in Xcode is now a breeze, but it does imply that the source is being used as part of an Xcode project. You can easily drag and drop any folder or set of files into the Organizer, however. So setting up your repository base and then dragging over the relevant subfolder should work.

The issue that arrises is when you want to commit or revert files. In Xcode, this is trivial as the IDE supports the ability to commit and revert changes. In Organizer you have to take a slight different approach. Recognizing that Organizer is essentially running scripts in the background, you can create a new "Action" item. The Action item can be something to the effect of calling a shell script that in turn calls 'svn commit'. The crux here is that editing the comments can be tricky. So you may have to modify your commit Action to include the commit message. The image below has an example of what I'm referring to.

I tried setting the editor to various types including vi, TextEdit and even to 'open'. But all failed for one reason or another.

In fairness, I believe the idea behind Organizer is that it's a lightweight more universal way to access Xcode/Dev Tools features. And this type of integration might be outside the design plans. But, it would be nice if there was a way to tie this into the Xcode management system somehow. But for now you can try a hybrid type of repository integration or continue to proceed via terminal.

Wrapping up

Okay so this was a quick introduction to Organizer using it for Makefile based projects. Organizer is a nice addition to Xcode and enables support for a number of programming languages that Apple simply cannot (will not?) support natively within Xcode via plugins. And as a first pass, it's usable. I've used it to debug memory leaks in APBS and some other development tasks for a program called TINKER. There are a few things I'd like to see worked into it.

1) The way actions are stored and set hierarchically is a bit confusing. I'm not certain how to make it less confusing, but it was a stumbling block for a brief while.

2) The debugger support needs some work. My understanding is that a lot of the ease of use that we've become accustomed to in full Xcode projects is due to the back-end support a full Xcode project provides. This is simply lacking in an organizer based project. But still, it'd be nice if I could simply set a breakpoint in the gutter of the Organizer Editor window and have the break point "just work".

3) I didn't go over this here, but the way the Find in Project window works in Organizer requires that you constantly select folders you want to search. For example.

Open Organizer, select the examples folder (as if you were working on a file in that folder) and then press command-shift-F (which is normally the Find All in Project search tool). The search by default is limited to the examples folder and everything below it. If I really wanted to search my entire APBS project I have to go back and select the top level APBS folder.

Instead I should have three options:

1) Search in selected Organizer item
2) Search in top-level Organizer item
3) Search in all Organizer projects (items... whatever)

I really like the Organizer and think a number of you cross-platform developers will as well. It's lightweight and solves a number of problems. And for a first pass is very good. If they could find some way to simplify the search and debugging options, I'll be really happy.


Comment viewing options

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

SVN Integration

Great overview Dave!

I was the one wondering about repository integration. As you outline, it's possible to create scripts to call SVN commands, but it's very frustrating that two of the big features in Xcode 3 don't work with each other.

Re: SVN Integration

Agreed... After looking at how well the repositories were implemented in Xcode, it's a shame you can't access them as easily from within Organizer. I also feel similarly about the debugging. I wish it was a little easier. But this is a first pass, so perhaps if file enough feature requests, they might consider extending the functionality.


86 errors

I need help :( I install this and was following the directions and it was working, but I don't know what I did and I lost the proper installation of my Python because I try to redo everything and now I get this error and 86 more like:

File: /SourceCache/DevToolsBase/DevToolsBase-1148/pbxcore/Target.subproj/PBXTarget.m
Line: 4061
Method: targetBuildContext

Assertion failed: (nil != [self project]) && ![[self project] isClosed]

Very helpful! Thanks.

Hi, this Xcode/Organizer guide is really very helpful. I agree with you that there are things to be improved, but I didn't even imagine that one could do what you describe. A couple of brief comments and questions.

- where does Xcode/Organizer keep all the actions that are defined? Can they be kept somewhere for use outside of Organizer (eg from the terminal?).

- I couldn't get breakpoints to work at all, either using the line number in the code or a symbolic name. Is there any special compilation option to take care of (I used "-g", but I didn't think this was required for breakpoints in general).

- A bit unrelated, but still. With age comes failing eyesight. Is there any way to increase the fontsize in the differend build log, debug etc. windows (Editor text can be easily changed from the preferences, but for these other 'special' windows this does not seem to be the case..)

Thanks anyway!
Marc (MDDriver project)

How breakpoints work

Answering part of my own question about breakpoints not working:

1) Try to uncheck the "Load symbols lazily" in Xcode preferences - debugging pane. It worked for me. (copied from another post)

2) if the "Location" is not found automatically you have to indicate the name of the executable

3) To set the breakpoint you have to use the Organizer/Breakpoints window (from the Organizer/Editor code window it does not work). I have checked either symbolic using the function name, or by indicating the line in the source code, for example like this: "DsspCMBI.c:2583"

4) Don't forget to "Activate" the breakpoints in the Organizer/Breakpoints windo

This seems to do it.

How to debug X11 applications?

Hi again,

I was trying to debug an application that is supposed to open a graphics window (X11) from within Xcode/Organizer.
The gdb debugger however just complains:

[Switching to process 29814 local thread 0x2d03]
Error: Can't open display: localhost

Debugger stopped.
Program exited with status value:1.(gdb)

Even if I try to run it without the debugger I get the error message.

Any ideas how to solve this?
From the command line outside of xcode this works fine, of course.
Thanks in advance,