To keep the Xcode 3 material I wrote from going to waste, I am making eight chapters I wrote for an Xcode 3 version of the book available for download. There are six chapters on Xcode as well as a chapter on the OpenGL tools and a chapter on command-line debugging tools.?

You can download the chapters at the Xcode Tools Sensei site. There is a zip archive with all eight chapters available as well as the individual chapters if you don’t want all eight of them.

Switching to the Source View

At the bottom of the trace document window is a collection of six buttons.

If you see only four buttons, you’re most likely running Leopard and Instruments 1. Instruments 2 requires Snow Leopard. The buttons from left to right are:

• Table view
• Outline view
• Diagram view
• Console
• Source view
• Extended detail view

The source view looks similar to an Xcode editor window. Click the source view button to switch to the source view.

I’ll briefly explain the other views for those of you new to Instruments. The table, outline, and diagram views provide different views of the trace data. The table view shows the data in a flat list. The outline view shows the data in a hierarchical list, and the diagram view shows the data as a list of individual samples. Most instruments do not use the diagram view.

The console is similar to Xcode’s debugger console. If your application uses NSLog or printf to log debugging information, the logged output appears in the console when you trace the application in Instruments.

For most instruments the extended detail view shows the call stack. The extended detail view is initially invisible. To take full advantage of the source view, open the extended detail view. The extended detail view resides on the right side of the trace document window.

Viewing Source Code

When you first open the source view, it displays the following message:

Drop Source File to Analyze

Drag one of your source code files to the source view to examine it in the source view.

There is a second way to view source code. Make sure the extended detail view is open. Switch to the table, outline, or diagram view. Select a trace sample and examine the call stack in the extended detail view. Find a function you wrote on the call stack and double-click it. If there is no function you wrote on the call stack, select another trace sample.

When you double-click a function you wrote, something cool happens. Instruments switches to the source view and displays the function you double-clicked. It also highlights the code with a message bubble that looks similar to the message bubbles Xcode shows when you have a compiler error or warning. The exact contents depend on the instrument, but the following is an example from the ObjectAlloc instrument:

Each line of code that allocates memory is highlighted. The amount of memory allocated by that line of code appears on the right.

The Leaks instrument highlights every line of code that leaks memory and tells you the total amount of leaked memory. The Time Profile and Sampler instruments tell you the number of samples recorded for a line of code.

If you look at the screenshot, you’ll notice an information button next to the amount of allocated memory. Clicking the information button shows you the five heaviest backtraces. For the ObjectAlloc instrument, the heaviest backtraces are the largest memory allocations. For the Leaks instrument, the heaviest backtraces are the largest memory leaks.

$source.AttributeName

I wanted to see what kinds of values you could give a value expression. I did a Google search and found some questions from people on mailing lists and message boards from people who wanted the same information as I did. But I found no answers. After doing some more searching, I learned an important piece of information.

A value expression is an object of the NSExpression class. With this information I could look at Apple’s documentation. The place to start is the NSExpression class reference. In the class reference is a link to Apple’s Predicate Programming Guide. After looking at both documents, I learned value expressions are a large topic with many possible values, too many for me to answer here. But I now know where to look when I need information on value expressions. Now you know where to look too.

Cause 1: PNG Files Not Found

The most common cause of trouble of PNG file loading is the operating system being unable to find the file. Suppose you have the following SDL_image function call in your code to load an image:

SDL_Surface* image;
image = IMG_Load_RW("background.png", 1);

That code works only if the file background.png is in the current working directory. If the file isn’t in the current working directory, SDL_image won’t load it, and you have problems.

On Linux and Windows, the current working directory is the directory where the executable file is. Make sure your image files are in the same directory as the executable file.

On Mac OS X, SDL sets the working directory to the directory containing the application bundle. But your image files are in the Resources folder inside the application bundle. This means the code example to load background.png will not work on Mac OS X. The best solution is to change the working directory. My SDL Tips for Mac OS X post has instructions on changing the working directory.

Cause 2: DLLs Not Found

The second common cause of PNG loading problems affects only Windows programmers. For SDL code to run on Windows, Windows must be able to find the SDL DLLs. To find the DLLs, they must reside either in the same directory as the executable file or in the windows\system32 directory.

To use SDL_image on Windows, you must add the SDL_image DLL to the same location as the SDL DLL. Most people remember to add the SDL_image DLL, but they discover PNG files will not load.

The reason the PNG files will not load is that loading PNG files with SDL_image on Windows requires the zlib and libpng DLLs as well as the SDL_image DLL. It’s an easy mistake to make, and the error message SDL_image returns isn’t very clear. The solution is to move the zlib and libpng DLLs to the same location as the SDL and SDL_image DLLs.

When you submit your first comment, you’ll get a message on the blog saying that a verification email was sent. If you don’t get an email within a few minutes check your spam folder. If the email is not there, you most likely won’t be getting an email. You’ll have to wait for me to approve the comment. But the newest version I’ve tested has been working well so you should be getting verification emails.

For Java profiling to work with Shark, you must link Shark with the Java virtual machine. To link Shark with the Java virtual machine, you must add the following flag to the virtual machine:

-agentlib:Shark

Profiling with Shark on Snow Leopard is complicated by the fact that Snow Leopard initially uses the 64-bit version of the Java virtual machine. Shark does not work with 64-bit Java applications. You must use the 32-bit version of the Java virtual machine to profile with Shark. Add the following flag to the virtual machine

-d32

If you’re using Xcode 3.2 to write your Java applications, you must add the flags to the build.xml file Xcode includes when you create a Java project. Search build.xml for the </java> tag and add the flags before that tag.

<jvmarg value="-d32"/>
<jvmarg value="-agentlib:Shark"/>

At this point you’ll be able to use the Java Time Profile and Java Call Trace profiles. You won’t be able to use the Java Alloc Trace profile because Snow Leopard uses JVM 1.6, and the Java Alloc Trace profile doesn’t work with it. You will have to install JVM 1.5 to use Java Alloc Trace.

Once you get a comment approved, any future comments you make will not be subject to moderation. They will appear on the blog when you submit them.

Xcode is set to rename all files in the project that are based on the project name: project file, targets, build products (application name is an example), precompiled headers, and property lists. If you want to keep the old name for some files, deselect the checkbox in the left column.

Xcode has one requirement for third-party documentation sets. The documentation set must be either an RSS or Atom feed. If you want an example of a documentation set, the cocos2D game engine has an Atom feed at the following URL:

http://aptocore.com/downloads/cocos2d/cocos2d-iphone-doc.atom

Opening Xcode’s Documentation Preferences

Open Xcode’s preferences by choosing Xcode > Preferences. Click the Documentation button in the Xcode toolbar window. The Documentation button is on the far right. You’ll have to use the scroll bar to get to it unless you have a very wide monitor. You should see the documentation sets on the left side of the documentation preferences.

Adding a Documentation Feed

Click the Add Documentation Set Publisher button. You will be asked for a feed URL. RSS feeds start with feed:// while Atom feeds start with http://. Click the OK button when you’ve finished entering the feed URL.

Installing the Documentation

After adding your documentation feed, it should appear in the list of available sets. Click the Get button to install the documentation in Xcode.

Reading the Documentation

After installing the documentation, open Xcode’s documentation window by choosing Help > Developer Documentation. Click the Home button in the documentation window toolbar. A menu with a list of installed documentation sets opens. The documentation set you installed should be one of the menu choices. Choose it to read the documentation.

Removing the Documentation

To remove documentation you installed, open Xcode’s documentation preferences. Select the documentation set from the list of available sets. Right-click and choose Reveal In Finder. Drag the documentation set to the Trash.

My workaround was to open the statistics and trace windows and start profiling. When I did this, both windows filled with the appropriate profiling data.