In this article we will discuss the latest iteration of my Prefix.pch file. As with anything I post, it is available for you to use as you see fit.

The File

For those who don’t want to read the entire post, here is the file:

1
2
3
4
5
6
7
8
9
10
11
12

#ifdef DEBUG
  #define DLog(...) NSLog(@"%s %@", __PRETTY_FUNCTION__, [NSString stringWithFormat:__VA_ARGS__])
  #define ALog(...) [[NSAssertionHandler currentHandler] handleFailureInFunction:[NSString stringWithCString:__PRETTY_FUNCTION__ encoding:NSUTF8StringEncoding] file:[NSString stringWithCString:__FILE__ encoding:NSUTF8StringEncoding] lineNumber:__LINE__ description:__VA_ARGS__]
#else
  #define DLog(...) do { } while (0)
  #ifndef NS_BLOCK_ASSERTIONS
    #define NS_BLOCK_ASSERTIONS
  #endif
  #define ALog(...) NSLog(@"%s %@", __PRETTY_FUNCTION__, [NSString stringWithFormat:__VA_ARGS__])
#endif
 
#define ZAssert(condition, ...) do { if (!(condition)) { ALog(__VA_ARGS__); }} while(0)

This does not replace the Prefix.pch that comes with your project but it does go at the top of every project that I work on. The rest of this post we will review what this does.

#ifdef DEBUG

I normally run my code in one of two modes. Either I am writing and testing the code or I am compiling it to hand over to QA, a user or Apple (btw I consider all three of those to be synonymous when it comes to builds). Therefore the first line is a switch to see if we are in debug mode. I set this value in the build settings of my project. If you look under the “Preprocessor Macros” section you can set the DEBUG definition there.

#define DLog(...)

This is the most used macro I have in my Prefix.pch file. This is simply NSLog as we know it and love it. However I automatically prepend the included macro __PRETTY_FUNCTION__ so that any log statement that comes out will declare where it is being called from. Personally I hate having to track down which “Fix Me” just spit out to the Console.

The nice thing about DLog over NSLog is that in the other branch this is a no-op that will be removed by the compiler. Therefore when I do a client build they won’t see the debug statements nor will their build be slowed down by any potential conditional logic around the debug statements.

#define ALog(...)

While I do not use this one very often I do like this one an awful lot. When I am in DEBUG mode it will throw an NSAssertion when it gets hit. This is similar to a common line of code that I see:

1

NSAssert(NO, @"It failed");

or if you want to see the variables:

1

NSAssert2(NO, @"It failed. Value1: %i Value2: %i", value1, value2);

My version does not have the condition before hand and can take any number of parameters.

1

ALog(@"It failed. Value1: %i Value2: %i", value1, value2);

In addition, when the DEBUG flag is not set, this assertion turns into a NSLog which remains visible. This allows me to have “This will never happen” calls in my code that will explode when I hit them but will be more polite if a user hits them but not so polite that I am left wondering what happened. They won’t intentionally crash the application but they will leave a fingerprint in the output from the application so that I can discover what happened.

NS_BLOCK_ASSERTIONS

I am of the school of thought that believes you should never throw an assertion in production code. If your code cannot handle that part of your app being hit and survive in some form or another then it is not production ready. Simple as that. Therefore I turn them off in production builds.

However, some other people who write libraries that I depend upon also feel this way. Therefore I need to check to see if it is already defined so that I can avoid a warning about resetting it. Since I have warnings set as errors in my code this is needed.

#define ZAssert(condition, ...)

The final gem in this collection is ZAssert. This is my personal favorite and it lets me clean up my code very nicely. First, ZAssert is a condition check. If you pass the check nothing happens. If you fail the check, bad things happen. This is just like NSAssert except for one big difference. When you turn off assertions, NSAssert goes away completely. This is not what I want to happen in my code. Instead, when assertions are turned off, I want a failure of this check to turn into an NSLog. That is what ZAssert does for us. In this way, we can clean up our code very nicely. Picture this very common block of code:

1
2
3
4
5
6

NSError *error = nil;
 
if (![managedObjectContext save:&error]) {
  NSLog(@"My save failed: %@\n%@", [error localizedDescription], [error userInfo]);
  abort();
}

That is a LOT of code just to perform a save! Blocks of code like this are very common in Objective-C. Unfortunately we can’t roll this up into a NSAssert because the entire line of code will disappear when we turn them off.

With ZAssert it gets a lot cleaner:

1
2

NSError *error = nil;
ZAssert(![managedObjectContext save:&error], @"My save failed: %@\n%@", [error localizedDescription], [error userInfo]);

Because ZAssert survives when NS_BLOCK_ASSERTIONS is set and simply mutates, we can inline the save directly and make the code a lot easier to read.

Wrap Up

I am sure this code will evolve. When it has changed significantly I will do an updated post. If anyone else has some nice tips for the Prefix.pch then please share them as we all benefit.

Acknowledgements

First I would like to recognize Fraser Hess who did the original post and showed me what we can do with macros.

Second I would like to point out that the NSAssert line of code above is borrowed heavily from BareBones software. They figured out how to generate an assertion without actually using the NSAssert macros.

The issue, however, is that the dSYM file must match the binary exactly^[1]. I have not even had luck with pulling the code out of version control and compiling a second time to get the files to match up. Therefore, we need to store these dSYM files for every build that gets handed off to someone else. For Cocoa Touch development this means every ad hoc build and every release build. This can be a pain.

To solve this problem I wrote a script that is added as the last build phase of all my iPhone projects. The script will move the dSYM bundle into the project directory in a directory cleverly called “dSYM”. In addition the script will check the bundle into git (after confirming the project is maintained in a git repository) and commit just that bundle. Also, since the file is always named the same thing, it renames the file using the current date and time so that no two bundles have the same file name.

Failure checks

The first thing the script does is determine if it should run.

if [ "$BUILD_STYLE" == "Debug" ]; then
  echo "Skipping debug"
  exit 0;
fi

The first part of the script checks to see if the build style is Debug. Since all debug builds run just on the developer’s device and still contain the debug symbols, they can be safely ignored.

if [ "$EFFECTIVE_PLATFORM_NAME" == "-iphonesimulator" ]; then
  echo "Skipping simulator build"
  exit 0;
fi

The second step is to check to see if the build is against the simulator. Again, we have no interest in storing the symbol files for these builds.

Move the file

Since the location of the file is determined at build time and can vary from developer to developer (as well as machine to machine) I use the environmental variables that are part of the build.

SRC_PATH=${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}
RELATIVE_DEST_PATH=dSYM/${EXECUTABLE_NAME}.$(date +%Y%m%d%H%M%S).app.dSYM
DEST_PATH=${PROJECT_DIR}/${RELATIVE_DEST_PATH}
echo "moving ${SRC_PATH} to ${DEST_PATH}"


mv "${SRC_PATH}" "${DEST_PATH}"

The next step is to build up the paths of where the file is currently and where we are going to move it to. I like to store these in variables so that I can print them out to the console in case something goes wrong.

Commit it to version control

Every project is part of version control right? (RIGHT?)

if [ -f ".git/config" ]; then
  git add "${RELATIVE_DEST_PATH}"
  git commit -m "Added dSYM file for ${BUILD_STYLE} build" \
      "${RELATIVE_DEST_PATH}"
fi

The final part only occurs if the project is part of a git repository. If it is then the bundle is added to git and then just that bundle is committed with a simple message.

Conclusion

Although I have recently been having issues getting symbolicatecrash to work properly, eventually either I or someone else will get it working again and at that time these files will be invaluable in tracking down crashes.

The final script is attached. I normally add the file to the project and then have a script phase that just calls this script file.

Move_dSYM_To_Storage.sh.zip

As memory serves the only time I’ve used version control in a meaningful way the system I was using was Visual SourceSafe from Microsoft. I know. Blech! It’s awful! I’ve pulled code from many a CVS or Subversion repository, but I’ve never really used them in the way they are intended to be used. Now, thanks to Marcus, I realize that version control isn’t just about versioning any more. It’s a whole methodology/ideology that makes better programmers. Here is what I mean.

Branching Inspires Wild Experimentation

Have you ever been so far down a path in your code that you just think, though you probably should, there is no way you would take a chance to re-factor due to looming deadlines or even just a simple fear that you might mess up so badly you couldn’t recover? Well, fear no more! Git provides such a simple way to create a branch of your code in which you can experiment, you won’t even give it a second thought. I won’t go into the whole setup and how to get going with Git as this is done very well elsewhere including a previous post from Marcus. I just want to point out how easy it is to branch with a single command. In Terminal.app, cd to the directory of a project you have under Git source control and enter the following command.

bash$ git branch experimental

bash$ git checkout experimental

bash$ git checkout master

bash$ git checkout master
bash$ git merge experimental

If you found, conversely, that your ideas were purely delusional–a characteristic of your over-achieving sense of hubris–you can blow them away by simply typing:

bash$ git branch -d experimental

Now the idea is just a bad memory and not something you ever need worry about (or mention to your programming peers) again. Your code on the master branch is still as it was when you first started the branch. Hallelujah!

Note: The word ‘experimental’ I’ve used in these command line examples is simply a tag. You can call your branch whatever you like. Call it ‘hubris’ if you like. Depending on your personality, this may be more appropriate.

The chance to experiment so easily and without fear will make you a better programmer. You will venture into areas that you would have never tried before and will likely become more bold in what you’re willing to attempt. This can only be a good thing in the long run.

Collaboration

The Tutorial introduction to git provides a good example of how to collaborate when multiple people are working on the same computer, but where Git’s real power comes in is in its ability to enable collaboration. If you’re familiar with extreme programming or pair programming then you are already aware of how collaboration will make you a better programmer. The learning curve for developing applications for the Macintosh for me has been significantly leveled as Marcus has shown me how to do things in the context of real code. You can learn things in many different ways, but sharing code has got to be one of the strongest means of gaining deeper understanding. This can only make you a better programmer.

While not a direct feature of Git itself, you can share your repository over the many file sharing web applications out there. Marcus and I use Dropbox for our projects that we collaborate on. Here are the steps you take to collaborate remotely using Git and Dropbox.

1. Sign up and install Dropbox from http://www.getdropbox.com.
   
   This will create a folder in your home directory under ~/Dropbox.
2. Have the person you want to collaborate with do the same and then create a shared folder that both of you can access through the Dropbox web interface.
   
   
3. From the project directory of the project you want to share, type:

   bash$ git clone --bare . ~/Dropbox/Shared/MySharedProject.git
   

   Note: Keep in mind that I’m assuming you already have this project under Git version control. If not you first need to run init like so in the root of your project directory.

   bash$ git init
   

   The –bare keyword we used in the clone command means that we simply want to create a directory that contains the contents of the .git directory in your project directory and not the actual workspace. The .git directory contains all of your code and changes to everything you need is there–it’s just not the actual workspace where xcode works from.
4. Create a remote (alias) for the newly cloned project by typing:

   bash$ git remote add sharedproject ~/Dropbox/Shared/MySharedProject.git
   



5. Now you can push any code changes from your working directory to the cloned directory, which, since it is in your Dropbox will automatically be uploaded to the drop box and downloaded by any other computers you have that can access Dropbox. First you need to commit any changes in your working directory with the following command.

   bash$ git commit -a -m "Commit message"
   

   Then you need to push the changes to the remote with the following.

   bash$ git push sharedproject master
   

   This pushes your changes to the cloned repository which is in your Dropbox directory. As soon as you do this, you should see the Dropbox icon in your menu bar change to the ‘synchronizing’ icon. If your change is small, it will only change for a split second so you’ll have to watch it closely to see that happen.

Once your files are committed and have been pushed to your cloned repository, you can now pull the project from another computer. I’m assuming you have Git and Dropbox set up on the second computer. Here are the steps you take to get the code into Git.

1. In Terminal.app on your other computer, create a new directory where you want your project to be stored with a working directory. Now run the following command.

   bash$ git clone ~/Dropbox/Shared/MySharedProject.git
   

   Notice that we didn’t use the –bare keyword this time. This is because we want our cloned copy to also setup a working directory since we’ll be accessing it from xcode on the second computer as well.
2. Now create a remote (alias) to reference the project like you did on the other computer using the following.

   bash$ git remote add sharedproject ~/Dropbox/Shared/MySharedProject.git
   

   Note: This step is optional as your clone will do this automatically. The difference, however, is that the clone will create a remote called ‘origin’ by default where you can name it whatever you want (sharedproject in the example) if you do run it.

3. Now you can pull the code at any time with the following command.

   bash$ git pull sharedproject master
   

   You won’t need to do that at this point as your code is fresh from the clone, however, should you make any changes on the originating computer that have been pushed, you could now pull those changes from this secondary computer.

If you now make changes to the code on the second computer, you can use the exact same command you used on the first computer to push the changes. First commit the changes with:

bash$ git commit -a -m "Commit message"

bash$ git push sharedproject master

And now you’re up to date. The changes are ready to be downloaded from the first computer.

The Urge To Merge

Nothing like sexual inuendo (urge to merge, hint hint, wink wink) on a site called ‘Cocoa is my Girlfriend’ to get a geek going, but that’s not what I mean. Settle down. Take it easy…

In the end, Git’s greatest feature is its ability to merge code changes.

There are times when you have fairly complex code merges that are necessary and systems such as CVS or SVN (Subversion) will simply choke and give up leaving the messy merging process to your weak manual merging skills. This is a shame and not necessary any more as it is rare for Git to be unable to successfully merge code. Again, this probably its biggest strength. When you don’t have to worry about merging your code, you can do whatever you like in your branch with little fear that merging in your changes are going to conflict with someone else’s. This merging power comes from Git’s unique philosophy of source code management which sees changes as individual code additions and deletions rather than complete file changes.

Conclusion

There will remain naysayers who have “always done it this way” and will remain in the realm of central repositories for version control. However, if you can think outside of tradition and see the power that comes from a good source control system, you will become a better programmer. I will submit that simply starting to use any version control when you haven’t before will make you a better programmer, however, using Git for your version control system, will make it infinitely easier to become so.

There are a few scripts floating around that perform this trick for subversion, but git handles build numbers a bit differently and it appears that no one has bothered to publish one. As is known, subversion uses an incrementing integer for build numbers. This makes it very easy to determine which build number came first and makes it very useful for a non-public version number. Git, however, uses a hash for each build number which is not incrementing and therefore not very useful for determining version numbers. However, it is still very useful for pulling up a specific build when a crash report is received, etc.

Therefore, with the help of Matt Long’s perl-fu, I have updated Daniel Jalkut’s subversion perl script to work with git. Since the build numbers are not sequential, I would not recommend using them for Sparkle. Therefore, in my own build process for iWeb Buddy, I hand select the version number (for example 1.0.4) and then use the short hash from git as the CFBundleVersion number. Normally this number is displayed in parens after the primary build number but, at least in iWeb Buddy, I have removed it from the display entirely. Since it is no longer a sequential number it would only potentially confuse users and it displays in the crash reports anyway.

The updated script is as follows:

# Xcode auto-versioning script for Subversion by Axel Andersson
# Updated for git by Marcus S. Zarra and Matt Long
 
use strict;
 
# Get the current git commit hash and use it to set the CFBundleVersion value
my $REV = `/opt/local/bin/git show --abbrev-commit | grep "^commit"`;
my $INFO = "$ENV{BUILT_PRODUCTS_DIR}/$ENV{WRAPPER_NAME}/Contents/Info.plist";
 
my $version = $REV;
if( $version =~ /^commit\s+([^.]+)\.\.\.$/ )
{ 
	$version = $1;
}
else
{
	$version = undef;
}
die "$0: No Git revision found" unless $version;
 
open(FH, "$INFO") or die "$0: $INFO: $!";
my $info = join("", <FH>);
close(FH);
 
$info =~ s/([\t ]+<key>CFBundleVersion<\/key>\n[\t ]+<string>).*?(<\/string>)/$1$version$2/;
 
open(FH, ">$INFO") or die "$0: $INFO: $!";
print FH $info;
close(FH);

Since git is distributed, there is no need to be online to produce a build. The script will grab the current abbrev-commit hash and will inject it into the current build’s Info.plist file.

As usual, I’ve created a demo application that will allow you to see how things work. You can download it here: Leaky Demo Application. In this post I am simply going to show you how to use Instruments to detect memory leaks. It’s pretty straightforward, but there are few little nuances you may not be familiar with that once you understand will help you feel comfortable using this powerful tool.

Running Instruments From XCode

You can start Instruments directly and then navigate to your project build, however, it’s much quicker and simpler to start Instruments from XCdoe. To do so , open the demo project or a project of your own in XCode and select Run | Start With Performance Tool | Leaks.

While working on this project, Marcus and I discovered a few things that you should keep in mind while you are using Instruments.

• Breakpoints Do Not Break. Instruments utilizes debug information from your debug build, however, it does not stop at break points you set. This is because while you are loading your application into Instruments from the menu in XCode, Instruments simply uses the path of the current executable as its start path and loads it externally from XCode. The menu in XCode is really there as a convenience mechanism. This is not a big deal as you can always run again in Debug mode after your instruments session should you want your application to break. It’s just something to make a note of.


• NSLog Statements Do Not Show In The Debugger Console. If you want to see your NSLog statements, you will need to load the system Console application (/Applications/Utilities/Console).

Leaking Like A Sieve… Or Not

Our expectation was that when we allocated memory for a new NSString* object we would see it leak right away. This was, after all, our intention. Things, however, don’t always work the way you might expect. This code would not leak in our tests no matter what we tried.

1

NSString *string = [[NSString alloc] initWithString:@"Leaker"];

And here’s why. It turns out that since NSString(s) are immutable and since we are allocating the string using the @ operator, the compiler is making things more efficient for us. Strings with the same contents are given the same memory address. Here is a comment from the CocoaDev site that clarifies what I mean.

The nice thing about using the @”" notation for initializing NSString objects is that if you create two of them and their content is the same, the runtime uses the same storage for them. (Note, this is not guaranteed and certainly may not be the case across compilation unit or library boundaries. It is a performance optimization and the fact that it happens sometimes should not lead you to believe that you can safely, for example, use “==” to compare strings if you know they’re both from string constants.) (Ref. CocoaDev NSString)

In the example code, the NSString objects never leak and so they weren’t very useful. This isn’t to say that they never will leak, so you should be in the habit of calling release on your NSString(s), however, for our example project at least, the NSString leaks were never detected. We instead switched over to using NSMutableString at which point the application began to leak as desired.

Detecting Leaks

When instruments loads your application, you will see the ObjectAlloc track start to fill in. To detect the leaks in your project, click on the Leaks track and then watch the Leak Status category which will detect leaks after the current timeout value. Alternatively, you can just click the Check For Leaks Now button under the Check Manually category.

Once the leak detection process has occurred you will see a list of objects that are currently leaking. To get details for any leaks in the list, click the object in the list and then click the Extended Detail button at the bottom of the Instruments screen.

Once you have clicked the Extended Detail button, you will see the stack trace list on the right side of the Instruments window. Look through the stack and locate any code highlighted with the color #CCFFFF which looks like this.

Note: This is actually inaccurate. The color may be different on your machine than on mine. Instead of looking for a color, look for your applications name and path and double-click that instead.
Thanks to Jason for pointing out the error.

Once you find the leak in your application, simply double click it and Instruments will return you to the exact line in XCode where the leak is happening.

To fix the leak, you need to make sure that you release the object. For more information and basic guidelines on memory allocation and deallocation, do a Google search. You can start with sites like this one: Very simple rules for memory management in Cocoa.

Conclusion

Finding and fixing issues is not the most glamorous aspect of application development, however, when done, the results are very rewarding. Instruments provides a streamlined way to track everything you would care about in your application. Watch this site for more tutorials on how to use other components available in Instruments. If you want to get an idea of what’s available, click on the Library button in Instruments and scroll through the ensuing list. It’s impressive.

I am also a user of .mac. I like the service and the iDisk is probably my favorite feature. Therefore, I wondered, like chocolate and peanut butter, could I put these two together and come up with something better than the individual parts?

The answer is yes. They work amazingly well together and make it very easy for me to push my code changes off-site even when I am not actually connected to the net. The basic configuration is fairly simple. I created a private directory on .mac, set up a bare repository in that directory and defined that directory as a remote location for my Git workspace. Below are the details on how to accomplish this.

Install Git on OS X

First, you need to have Git. The easiest way that I have found to get it is to use the MacPorts and do a ‘sudo port install git-core +svn’. I add svn because once you get used to Git you will want to put it in front of all your svn repositories that all those stone age developers still use.

Note: After installing MacPorts, you may need to add /opt/local/bin to your PATH in order for the port command to be found from the command line. Edit your .bash_profile file in your home directory (assuming you use bash) in Terminal and add the following line to the bottom of the file: export PATH=/opt/local/bin:$PATH .

Create your working repository

Once you have Git installed, you will want to create a repository. That is accomplished with a single call:

mkdir TempProject
cd TempProject
git init

What that does is create a single directory called .git in the TempProject directory. All of the version information for that workspace is stored in that single .git directory (hello Subversion guys, your .svn directories suck).

Set up the bare clone

Now that your repository is created, you want to create a remote copy of it in case your harddrive eats itself or gets stolen (BTW Wil, sorry to hear about your MBA, that thief should burn). To do that, you want to have iDisk local syncing turned on. When it is, you will have a directory under /Volumes with your .mac username. For instance, mine is at /Volumes/mzarra. In this directory you want to create a new directory (I called mine git). Make sure that directory can only be accessed by you.

Now that it is created, you want to build the bare clone of your workspace. To accomplish this, execute the following:

cd TempProject
git clone --bare . /Volumes/${USERNAME}/git/TempProject.git

After a few moments your new bare clone is ready.

Linking the remote clone

The final step is to tell your local repository where that remote repository is:

cd TempProject
git remote add origin /Volumes/${USERNAME}/git/TempProject.git

Note that I used origin as this is the default repository name for push and pull. If you want your origin to be somewhere else then change this name.

Performing a push

Now that everything is set up all you need to do to sync your repositories is:

git push

And Git will update the bare clone.

Sync multiple working copies

But wait — there is more. If you have more than one Mac, you can use this bare clone to keep your two workspaces in sync! On the other Mac, once Git is installed, you can grab a working copy as follows:

git clone /Volumes/${USERNAME}/git/TempProject.git

And you will now have another working copy! If you need to update your second Mac at a later point just:

git pull

And Git will do all the work for you.

Conclusion

There are a couple things to note.

• The initial sync back to .mac can be slow if your workspace is large. However, as long as you ‘push’ often enough, your subsequent syncs should be very quick. Therefore, get in the habit of pushing often.


• Only one Mac can sync with .mac at a time. Therefore it is possible to get a sync failure if the n Macs try to sync at the same time. Therefore if you are going to do a pull and you just pushed to .mac, make sure that both syncs succeeded.