Elegant Chaos

I posted last week about running Doxygen from XCode using a custom build step.

I originally found a nice article on the Apple website here which describes how to do this, but it needed a little bit of tweaking, and wasn't great, so I've improved the process a little bit.

First of all, I moved the bulk of the work into a script file, so that I can reuse it in multiple projects. This seems more sensible than cutting & pasting into every project. DRY principle!

I also decided to use a standard layout, relative to the project file, which meant that I could cut down on the number of variables that needed defining per-project.

My custom build step now just has to define a couple of variables and call on to the script.

You can find my version of the script here:

http://github.com/samdeane/code-snippets/blob/master/scripts/build-doxyg...

It could be cleaned up a lot more - it's basically copied from Apple's script then hacked a bit - I didn't write it with public review in mind! One thing I fixed in the script was support for projects that have a space in their name or the name of a containing folder. Bloody unix programmers!

Second, I was annoyed by the output of the script, so I piped it into a file.

Finally, I was also annoyed at having to wait for the script to complete. Rebuilding the documentation each time is useful, but it's not like you actually want to go and use it immediately.

So, I tweaked the build step to run it in the background.

Now my build step looks like this:

${WORKROOT}/scripts/xcode/build-doxygen.sh > "$TEMP_DIR/doxygen.output.log" 2> "$TEMP_DIR/doxygen.log" &

$WORKROOT is a variable that points to the root of my development folder - you can just replace it with the path to the build-doxygen.sh script file.

The script file itself relies on one extra variable - $DOXYGEN_ID - which I define in the project settings. It uses this to name the documentation bundle - so you should set it to something appropriate for the product - like com.yourcompany.yourproduct.

If you want to see the output of the script, you can add a second line:

open "$TEMP_DIR/doxygen.output.log"

This will launch Console and open the log file. Console is smart enough to update as the log file gets filled in, so it works even though the script may not have finished running by the time you open the log.

Update: one more thing...

By default XCode runs the build step every time. You can tell it to be a bit smarter by telling it what the input files and output files are for the step; it will then dependency check them.

I set the inputs to:

• $(SRCROOT)/Code
• $(WORKROOT)/scripts/xcode/build-doxygen.sh

And the output to:

• /Users/$(USER)/Library/Developer/Shared/Documentation/DocSets/$(DOXYGEN_ID).docset/Contents/Info.plist

Now, if you do something that doesn't change the source code, the documentation shouldn't rebuild.

I was wondering whether to use HeaderDoc or Doxygen for Objective-C project, and after a bit of googling I get the impression that HeaderDoc is on its way out.

I found a nice article on the Apple website here which describes how to get XCode to run Doxygen for you as part of your build, and turn the results into a DocSet which XCode knows about.

It works rather well, and the documentation for my test iPhone project now shows up in XCode along with the standard Apple sets.

One slight issue - I had to edit the script a bit to cope with having a space in the path to your project. It also has rather verbose output - adding --silent to the make command helps a bit, as does altering the doxygen.config to run quietly. Unfortunately the commands in the make file that Doxygen generates still seem to spit out a fair amount of crap even if everything is working.

One other problem - XCode can't seem to find the documentation for a type when I option-click on it, in the way that it would do for an Apple type. This may just be a question of needing to rebuild my indexes though...

In recent years Apple has started doing something that I regard as pretty dumb - tying versions of XCode to a particular system, and/or not supporting older XCode versions on newer systems. XCode 3.0 required Leopard, and I suspect that the next big XCode update will go the same way.

What's even more annoying is that the distributed build system is tied to your system, architecture and xcode version. I can see why the version of the tool chain used by each node in a distributed build needs to match, but Apple should really spend some time making this stuff work a lot better.

The IDE should really be far more de-coupled from the tool chain, and I really ought to be able to participate in a shared build system running on a number of system versions (for that matter the IDE is a horrible monolithic lump which should really be broken down into smaller components and updated in a far more agile way, but that's another topic).

The main reason why the Xcode thing is such an issue for me, is that it's a really big barrier stopping me doing early testing of system updates. One way or another I've been getting pre-release systems from Apple for the last 20 years or so. Until fairly recently, I was very happy (keen, even) to live on the edge. Maybe not for alphas, but certainly by the time the system got to beta I'd typically install it and live on it for my main development machine. Crashes and glitches notwithstanding, I wanted to know what was coming, try it out, and give feedback on it whilst there was still time to change stuff.

Now, however, access to pre-release builds is next to useless for me. I simply can't live on pre-release systems, since I immediately lose access to the other 5-10 macs that are normally happy to help out with my builds (and believe me, I need them to help compile Football Manager, which contains a lot of code!). For the amount of time & effort it takes to install a new system, it's barely worth it just to click around for half an hour to see what's changed, before switching back to my "real" system.

I can't believe I'm the only person who has this problem, and it seems to me that the quality of the feedback that Apple receives must suffer as a consequence.