Firstly, if you think that you only work with yourself and you can handle yourself, have a quick look at the I Am A Moron section of this post or this recent tweet by Kevin Hoctor.

Now a few years ago, I started work on a helpdesk ticketing system called tina. In the early days of tina development, I’d didn’t use any version control. I was frequently confused by my own code. I’d look at a piece of code and wonder, “What was I trying to do here?” or “When did I change this? Wait, did I change this?”. Occasionally, I’d tar-up my code for a historical record and I’m not sure now if I ever referred to those tarballs. When I eventually put the tina code into a Subversion repository I was much happier because of it.

With another project, that I wanted to put under version control, I found I had no less that 3 different versions of the code lying around on my hard drive. It look some investigation with diff in order to find out which one was the most current. Fortunately I didn’t have some files more recent in one copy and others more recent in another copy, but that could have easily happened.

With version control, it’s easy to find out what changed in my code, especially if I write useful commit messages. The most unexpected (and incredibly positive) side effect was that once I started using version control, the quality of my code went up dramatically. By tracking exactly what was changing between revisions, unwanted changes and debug code did not slip into the shipping code.

It’s worth noting that this approach goes hand-in-hand with unit testing. Version control lets you know what is changing and unit testing lets you know that your changes don’t result in regressions. As solo developers without QA teams or even a QA person, using these best practices seriously improves our ability to complete with larger organizations.

So, I recommend version control for any coding project bigger than a few lines of code. I used Subversion for a while and have now moved onto git.

My tips for version control success:

• Make small commits – don’t commit a whole day’s work if you wrote 2 features and fixed 8 bugs. That should be at least 10 commits. For sure, commit every-time you complete something – a bugfix, a feature, fixing a typo, a formatting change. It’s makes it much easier to find regressions and other issues later. Oh, and try not to work on many things at once especially if the changes overlap in the code.
• Compile before commit – each commit represents a known state of your code, so make sure the code compiles correctly without warnings or errors before committing.
• Diff before commit – before each commit, look over the diff of your current code compared with the last commit. Then you’ll know for sure what you are committing. If you don’t like part of the proposed commit, change it, diff it again, repeat until you like it and then commit.
• Write useful messages – When you commit a message is required is usually. Make sure it makes sense to you and to others looking at your repository.

I use git for version control and also the services of github. Now in another post on this site Marcus covered how to put git commit checksums in your Info.plist’s CFBundleVersion. I have opted to use Apple Generic Versioning (or agv for short) instead as it has an easy to read incrementing build number and is super easy to script. It’s also great for use with Sparkle since Sparkle uses the CFBundleVersion to see if the appcast has a newer version. Chris Hanson wrote a great piece a few years back about getting agv setup in your XCode project. I followed his instructions for that. I also set the CFBundleShortVersionString in Info.plist to __VERSION__. You’ll see why I do that later.

When it comes time to build my app for shipping, either privately or publicly, I run tag.sh. This bash script increments the agv version and creates a git tag. The script takes one parameter which is the marketing version of your build (1.0, 2.0.4fc1, 2.5b6 etc).

Before running tag.sh, the state of the git repo should be clean- there should be no other staged files or uncommitted edits. It’s also a good idea to close the XCode project since agvtool will modify the XCode project file.

tag.sh also takes care of committing the changed CFBundleVersion for you. Here is it’s code:

1
2
3
4
5
6
7
8
9
10
11

#!/bin/sh
tag=$1
if [ "$tag" == "" ]; then
	echo "No tag specified"
	exit
fi
agvtool next-version -all
git commit -a -m "Increment CFBundleVersion for $tag"
git tag -m "Tag for $tag" -a $tag
git push origin master
git push --tags

So having run tag.sh I have created a git tag for my build so I can always go back and see that version of the code either in github or using git checkout <tag name> at the command line.

After this I use a jumbo script that checks out the tag I just created, builds it, zips it up, uploads it to my web server, outputs an <item> for your Sparkle Appcast (including signing the update) and maybe tweets about it. Phew. It’s a heavily modified version of Gus Mueller’s build script. Here’s the usage:

build.sh -p ProjectName -t tag [-u [-w tweet]]

The two required parameters are a project name and a tag. Optionally you can upload and then tweet about the newly available build. I do all of my public builds in a separate clone of my git repo that never gets edited or otherwise messed with (~/Development/building/). There’s a whole lot going on in this script that could be explained, but for now I’ll just leave you with the code to walk through, and if something needs clarified, post a comment and I’ll do my best.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

#!/bin/bash
 
upload=0
tweet=""
 
while getopts ":t:up:w:" Option
do
  case $Option in
    w ) tweet=$OPTARG;;
    u ) upload=1;;
    p ) project=$OPTARG;;
    t ) tag=$OPTARG;;
  esac
done
shift $(($OPTIND - 1))
 
if [ "$project" == "" ]; then
	echo "No project specified"
	exit
fi
 
if [ "$tag" == "" ]; then
	echo "No tag specified"
	exit
fi
 
# Configuration
final_builds=~/Development/release_builds
code_folder=~/Development/building/$project
build_folder=$code_folder/build
keys_folder=~/Development/keys
upload_destination=user@yourcompany.com:/usr/local/apache2/htdocs/downloads/
release_notes_webfolder=http://yourcompany.com/releasenotes
downloads_webfolder=http://yourcompany.com/downloads
twitter_uname=someone@somewhere.com
twitter_pword=password
 
if [ ! -d  $final_builds ]; then
	mkdir $final_builds
fi
 
# clean up
if [ -d $build_folder ]; then
	rm -rf $build_folder
fi
 
cd $code_folder
 
git pull origin master
git pull --tags
git checkout $tag
 
sed -i "" 's/__VERSION__/'$tag'/g' Info.plist
 
echo building project
xcodebuild -target $project -configuration Release OBJROOT=$build_folder SYMROOT=$build_folder OTHER_CFLAGS=""
 
if [ $? != 0 ]; then
	echo "Bad build for $project"
	say "bad build!"
else
 
	#ok, let's index the documentation if we've got it.
	#/Developer/Applications/Utilities/Help\ Indexer.app/Contents/MacOS/Help\ Indexer "/tmp/buildapp/build/Release/BuildApp.app/Contents/Resources/English.lproj/BuildAppHelp"
 
	mv $build_folder/Release/$project.app $final_builds
 
	# make the zip file
	cd $final_builds
	zip -r $project-$tag.zip $project.app
 
	rm -rf $project.app
 
	if [ $upload == 1 ]; then
 
		echo uploading to server...
		# upload
		scp $project-$tag.zip $upload_destination
 
		# get values for appcast
		dsasignature=`$keys_folder/sign_update.rb $final_builds/$project-$tag.zip $keys_folder/$project\_dsa_priv.pem`
		filesize=`stat -f %z $final_builds/$project-$tag.zip`
		pubdate=`date "+%a, %d %h %Y %T %z"`
 
		cd $code_folder
 
		cfbundleversion=`agvtool what-version -terse`
 
		#output appcast item
		echo
		echo Put the following text in your appcast
		echo "<item>"
		echo "<title>Version $tag</title>"
		echo "<sparkle:releaseNotesLink>"
		echo "$release_notes_webfolder/$project.html"
		echo "</sparkle:releaseNotesLink>"
		echo "<pubDate>$pubdate</pubDate>"
		echo "<enclosure url=\"$downloads_webfolder/$project-$tag.zip\""
		echo "sparkle:version=\"$cfbundleversion\""
		echo "sparkle:shortVersionString=\"$tag\""
		echo "sparkle:dsaSignature=\"$dsasignature\""
		echo "length=\"$filesize\""
		echo "type=\"application/octet-stream\" />"
		echo "</item>"
		if [ "$tweet" != "" ]; then
			echo "Calling twitter: $tweet"
			curl -u $twitter_uname:$twitter_pword -d status="$project $tag is up. $tweet" http://twitter.com/statuses/update.xml
		fi
	fi
 
	open $final_builds
	say "done building"
 
fi
 
cd $code_folder
git checkout Info.plist
rm -rf $build_folder

Other References

Push tags to github Sparkle Basic Setup

Yes, indeed. Last Wednesday morning, Qwest “upgraded” our DSL to 7Mbps. From then until Saturday lunchtime, I had 13 hours of solid connectivity, most of which I was asleep for. It did indeed get resolved and I am enjoying the new speed but it certainly wasn’t worth stress of trying to find connectivity while trying to ship. I went to Barnes and Noble, Krispy Kreme and the seminary library in search of the uplink. I also wasted a trip to Best Buy to get a new DSL modem which didn’t solve the issue, despite the Qwest tech’s assurances that it would. (That reminds me, I need to return it and get my $75 back.)

Thinking about it, my rule should be generalized as:

Don’t replace/upgrade/otherwise mess with any of your critical infrastructure within two weeks of your ship date unless it’s broke.

After being burned by the DSL outage, I left well alone newly released updates to XCode, PHP, Safari and Java. I’ll get to those at a less critical moment.

Well, lesson learned. I won’t be doing that again. Now if you’ll excuse me, I’m gonna download a movie from Netflix.

Our customers give us money for something we have already written.

This is an important point to grasp. We write software once and sell it many times over with no production costs other than initial development. Unlike almost every other industry in the world we only have to write the software once! We do not have to produce something new every time a customer wants to purchase something from us.

Yes we need to maintain the code and provide updates to our customers. However we do not need to create something new out of whole cloth every time a customer wants to buy it. It is about as close to printing money as you are going to get — legally.

I am not saying this is easy! I would argue that software development is one of the most mentally challenging career choices out there.

Do not steal from your customers

Your customer has already given you money for your software that you wrote. Do not try and go back to that customer again unless you have written something significantly new. If your software has gone from v1.0 to v2.0 then absolutely charge them an upgrade fee. However, do not force your customers to purchase another license just because you do not like the way that they are using your software.

I own several Macintosh computers. Those who know me claim I buy Macs like other people buy lattés. That might be an exaggeration but I do tend to buy the new shiny. I normally have two machines running at once, sometimes I am using even more at the same time while I do software development and testing.

However, when I purchase a piece of software I expect to buy ONE license for my personal use. If my wife likes it she gets her own license. If my son likes it he also gets a license. I do not expect to, nor will I, purchase one license per machine that I am currently using. That is gouging your customers.

Do not pretend to be a lawyer

As you can guess, this blog post was prompted by a piece of software putting in a stealth change which blocked me from using it on two of my machines. I immediately contacted the author of the software and expressed my displeasure with this change. The author wrote me back and told me that I had been using their software illegally.

Guess what, you are not a lawyer. Neither am I. We also are not a government body. What that means is that we have no authority or ability to make something illegal. Violating a software license, whether it is a valid license or not, does not illegal make. Stabbing someone is illegal; there is a law against that. Purchasing software and using it outside of the scope of the EULA is not illegal; at most it is a civil disagreement. When talking to your customers do not claim that something is illegal. It makes you sound like a moron.

If you want to sound like a lawyer, either hire one to handle customer support or go to law school. Don’t use legalese to sound impressive or try and scare your customers. Scared customers do not give you more money.

Customers want to like you

You solved a problem for them. They like you. They want to be your friend and shower you with affection. However that can quickly be turned into hate. When you treat your customers poorly they will become your worst nightmare. They will tell their friends not to buy your software and perhaps even start writing nasty blog posts about your software.

Word of mouth is a powerful thing. Most people when they are happy tend to keep quiet about it. However when they are upset they want to share their frustration. Guess which kind of customer is going to be vociferous; the one you made happy or the one you screwed over?

Piracy

I learned long ago, never to wrestle with a pig. You get dirty, and besides, the pig likes it. –George Bernard Shaw

I learned long ago to never fight pirates. They enjoy it more than you do. From their point of view it is a challenge just to see if they can outsmart you. They enjoy it so much that they will do it for free! You, however, like to get paid for your work. No one is going to pay you for adding code to your software that is targeted at pirates. However you have a good chance of losing money if your customers get caught in your anti-piracy code and can’t use their software that they purchased.

Assume your customers are doing the right thing. Put in a serial number to keep your customers honest and then stop. Do not put in authorization checks to your server. Do not put in network checks on the license. Do not waste your time with junk that can cause problems for your customer if you made a programming mistake. Just like the lock on your front door is not going to stop a determined thief, your serial number is not going to stop a pirate. However both of them are going to stop an honest person from being tempted. That is your goal.

Spend that time making your software better and you will gain far more than you might lose to pirates. Your paying customers will be happier for it.

Conclusion

As with everything on this blog, this is the opinion of the author. But it is an opinion born out of experience and I practice what I preach. There are no network checks in my software. There is no authorization check to my server to stop a license from being used more than once.

Guess what happened with the software that prompted this article. I removed their software from my second machine, rolled back to the previous version on the remaining machine and I will be replacing it with their competitor’s software as soon as possible. They will not be seeing any more money from me. When someone asks my advice for a piece of software that solves that particular problem; guess who I am going to recommend.

I could have set up a rule to block their network check and continued to use their software. It would have been trivial and taken a lot less of my time than this article or writing the software author. However I have no interest in working with a developer who treats his customers like thieves.

Don’t treat me like a thief and I will give you money for your software. It is that simple.

• Create your own file format with your own file extension


• Register your file format with the operating system


• Provide application loading of your file that’s been double clicked in the Finder


• Write data and preferences back out to your application file


• Add resources such as media files to your application file

You can download the demo application here: PDF Keeper Demo Application

A Brief Discussion On Files and Folders

If you’ve ever come across a file in your file system that when control-clicked gives you an option in the pop-up menu to Show Package Contents then you are familiar with the type of file we are looking to create. What you may not know, however, is that this file is actually a directory. The choice to show the package contents is the OS allowing you to treat the file as a folder, which it actually is behind the scenes. When you create a custom file format in this manner, you are simply storing your project data and files under a sub directory.

You can verify that a special bit is set on these types of files by opening Terminal.app, navigating to the directory where such a file resides and running ls -al to get a detailed file list. When I do that on my directory where some of my custom files types are stored, I get a listing that looks like this.

Notice the at symbol (@) in the file listing. This is the visual indicator that this directory has extended information–which in our case means that the directory is being treated as a package. If you want to set this bit through the command line, just run the following command:

SetFile -a B <directory_name>

PDF Keeper Demo Application

For this post, I’ve included a demo application I’ve named PDF Keeper. PDF Keeper isn’t terribly practical as an application, but it effectively demonstrates the principles I’m wanting to convey. It simply opens our custom file type and loads in properties and data specified in the Info.plist file that each custom file contains. When you first run the application, you will be prompted to create a new PDF Keeper file. You will then see a list view that displays a list of PDF files stored within our custom file type. When you first create the file, the list veiw will be blank, so you will need to add some PDF files by selecting File | Add PDF File…. It then allows you to double-click any of the files in the list to view them in a PDFView.

If you were to look at one of the PDF Keeper file contents by selecting Show Package Contents from the context menu in the finder, you would see file hierarchy similar to the one below.

Note: Keep in mind that you will have different PDF files in the Resources directory than I have.

The Info.plist file inside the Contents directory is a property list file in XML format that keeps track of the PDF files we are storing. The Resources directory is where all of the PDF files are actually stored when we add one in PDF Keeper. Download, build and run the demo application to see it in action.

The path to your Info.plist file is important. It should be located inside of the Contents directory and be named Info.plist. That way, when we call, -[NSBundle bundleWithPath:], we will receive back an NSBundle whose infoDictionary member variable is an NSDictionary populated with the contents of the Info.plist file.

You can see how we do this in the call to -setupProject.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

- (void)setupProject:(NSString*)projectPath;
{
  currentProjectFilepath = projectPath;
 
  // Load the file bundle to obtain the bundle dictionary
  NSBundle *contextBundle = [NSBundle bundleWithPath:projectPath];
  if (![contextBundle infoDictionary]) return;
 
  // The infoDictionary represents the Info.plist file. We load it
  // and grab the array of files using the key "Files"
  NSArray *files = [[contextBundle infoDictionary] objectForKey:@"Files"];
 
  // If we have a list of files, we initialize our array model with them.
  // Otherwise we initialize the array with a capacity of 10
  if( files != nil )
  {
      pdfFiles = [[NSMutableArray alloc] initWithArray:files];
  }
  else
  {
      pdfFiles = [[NSMutableArray alloc] initWithCapacity:10];
  }
 
  // Reload the table view
  [tableView reloadData];
}

Create Your Own File Format

This is probably the most tedious aspect of the custom file format task as you have to decide what data you want your file to contain. I suggest that you code up a sample property list file in xcode and manually edit it to represent what you want. Then you can tweak it as you go. You won’t think of everything you want to save at first, so you do this loosely, however, you do need to start somewhere. This property list file is what will be stored inside the Contents folder of your custom file. Here is what a Info.plist file looks like in a PDF Keeper custom file.

1
2
3
4
5
6
7
8
9
10
11

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Files</key>
  <array>
    <string>About Stacks.pdf</string>
    <string>8051 Microcontroller.pdf</string>
  </array>
</dict>
</plist>

Register Your Custom File Format

This part is actually quite simple. You will, however, want to have your own custom icon ready to use for your custom format file. To register your file format, which is what enables you to double click your file in the Finder and have it properly load your application, with your project loaded in xcode, select Project | Edit Active Target “<Project Name>” where <Project Name> is the name of your project. In the ensuing window, select the Properties tab. You will see at the bottom a list view labeled Document Types:. This is where you will specify your document name, extension, and icon file. Below is a screenshot of the Document Type specified in PDF Keeper.

Notice that the Package checkbox is checked. This is what tells Finder that your file, though a directory, should look like a single file to the end user. You should also make note that the file extension field does not have a dot (.) in it. I learned that one the hard way.

Hiding/Showing File Extensions

Some applications that use this technique for custom file formats hide the file extension while others show it. Garageband, the entry level music recording application from Apple, for example, hides its file extension which is .band while our beloved xcode shows its file extension which is .xcodeproj.

Hiding and showing file extensions is handled in the Finder through the Get Info… window. If you select a Garageband file in the finder and press Command-I you will notice under the Name & Extension section the Hide extension checkbox is checked.

Here is a screenshot of a Garageband file’s Get Info… information.

Note: If you don’t have any Garageband files to look at, just run the demo app, PDF Keeper and create a new file. You can then Get Info… by pressing Command-I with that file selected in the finder to see the same thing.

You can do the same with an xcode project and you will notice that its Hide extension checkbox is not checked.

So the question becomes, how do we handle this in the code. When you create a new file of your custom format, you’ll want to control this, so how do we do so? It is a simple attribute you specify in an NSDictionary before calling NSFileManager’s createDirectoryAtPath called NSFileExtensionHidden. The code looks like this in PDF Keeper

1
2
3
4
5
6

NSNumber *num = [NSNumber numberWithBool:YES];
NSDictionary *attribs = [NSDictionary dictionaryWithObjectsAndKeys:num, NSFileExtensionHidden, nil];
if( ![[NSFileManager defaultManager] fileExistsAtPath:filepath] )
{
  [[NSFileManager defaultManager] createDirectoryAtPath:filepath attributes:attribs];
}

Keep in mind that you will also want to control whether or not file extensions can be seen in your NSSavePanel and whether or not the OS should treat file packages as directories. The following code is how we do this in PDF Keeper

1
2

[savePanel setCanSelectHiddenExtension:NO];
[savePanel setTreatsFilePackagesAsDirectories:NO];

If canSelectHiddenExtension is set to YES, the user would have the option to select/deselect a checkbox in the save file panel to show or hide the extension. We simply hide it for PDF Keeper as it reduces confusion and makes it easier to manage everything behind the scenes.

If treatsFilePackagesAsDirectories is set to YES, the file system would allow the user to drill down into the custom file as if it were a regular directory. We don’t want the user to be able to do that as we are treating the custom file as a normal file rather than a directory.

Loading Your Custom File From the Finder

You will likely want to enable your users to double click a file in the Finder that will then automatically load into your application. If you added a document type to your project as specified in the Register Your Custom File Format section above, then you are already part of the way there as on the first run of your application, the file/document type is automatically registered with the OS so that double clicks of your file type will be handed to your application without any further effort on your part.

Now you just need your application to be able to respond when it gets notified that the Finder wants you to load your files type. Fortunately, there is a very simple way to handle this scenario. All you need to do is implement the delegate

- (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename

in your app delegate. The filename parameter contains the path to the file that was double-clicked in the Finder. You simply do all of your file loading/initialization when this method gets called. You may also implement

- (void)application:(NSApplication *)sender openFiles:(NSArray *)filenames

if you want to handle multiple files being passed to your application. The following code snippet shows how these two delegate methods are implemented in PDF Keeper

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

- (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename
{
  // This gets called when the user double-clicks a project file in the Finder.
  [self openProject:filename];
  [self setupProject:filename];
  return YES;
}
 
- (void)application:(NSApplication *)sender openFiles:(NSArray *)filenames
{
  // This gets called when the user opens multiple files from the Finder.
 
  // We only take the first file.
  if( [filenames count] > 0 )
  {
      [self application:sender openFile:[filenames objectAtIndex:0]];
  }
}

Importing Resource Files

In the PDF Keeper demo application, we are only concerned with PDF files. When users select File | Add PDF File… they are prompted to select a PDF file that is then imported into the custom file type. This importing procedure is really just a simple file copy. Remember that our custom file is really just a directory that is being treated as a regular file by the OS. The file import just copies the file from the place where it was selected by the user into the Resources directory of our custom file. Here is the code to add a PDF file to our project file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

- (IBAction)addPDFFile:(id)sender;
{
  NSOpenPanel *openPanel;
 
  openPanel = [NSOpenPanel openPanel];
  [openPanel setCanChooseDirectories:NO];
  [openPanel setAllowsMultipleSelection:NO];
  [openPanel setResolvesAliases:YES];
  [openPanel setCanChooseFiles:YES];
 
  NSArray *fileTypes = [NSArray arrayWithObjects: @"pdf", nil];
 
  if ([openPanel runModalForTypes:fileTypes] == NSOKButton)
  {
      // Build our destination filename based upon the current project
      // file path and the Contents/Resources path below it.
      NSString *filename = [openPanel filename];
      NSString *displayName = [[NSFileManager defaultManager] displayNameAtPath:filename];
      NSString *destFile = [currentProjectFilepath stringByAppendingPathComponent:@"Contents"];
      destFile = [destFile stringByAppendingPathComponent:@"Resources"];
      destFile = [destFile stringByAppendingPathComponent:displayName];
 
      // Use the NSFileManager to copy the file
      [[NSFileManager defaultManager] copyPath:filename toPath:destFile handler:nil];
 
      if( pdfFiles != nil )
      {
          // Add the filename to our list of files.
          [pdfFiles addObject:displayName];
          // Save the project.
          [self saveProject:currentProjectFilepath];
          // Reload the table view
          [tableView reloadData];
      }
  }
}

Note: When you import the file you are simply copying it. If the file is large, though, you will want to provide a progress indicator so the user isn’t wondering if the app is hung or has crashed. This is non-trivial and will require you to use Carbon APIs to accomplish. In our demo app, I am simply calling NSFileManager’s copyTo: method which will copy the file, but will block until the copy is completed. If you want to implement a file copy using a progress indicator, see my previous post called Cocoa Tutorial: File Copy With Progress Indicator

Updating Info.plist Property List File

Whenever your user selects File | Save you want to update your Info.plist file with the contents of the pdfFiles NSDictionary that is used as the model for the table view control. To do so, we simply get the full path to the Info.plist file, delete the current file, and then save a new file to the same path. Here is the code we use to do so in PDF Keeper

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

// Set the path for our property list file.
NSString *plistFile = [contentsPath stringByAppendingPathComponent:@"Info.plist"];
 
// If it already exists in the project, delete it.
if( [[NSFileManager defaultManager] fileExistsAtPath:plistFile] )
  [[NSFileManager defaultManager] removeFileAtPath:plistFile handler:nil];
 
// Create a dictionary to use to write out our property list file.
NSDictionary *output;
output = [NSDictionary dictionaryWithObjectsAndKeys:pdfFiles, @"Files", nil];
 
// Write the file.
[output writeToFile:plistFile atomically:YES];

Conclusion

Your custom file format can be as simple or complex as you would like to make it. You simply decide on all of the information you would like to store in your Info.plist file and then create sub-directories under your Contents directory where you will store your data. The concepts are simple. You are storing data and information about the data inside of a directory that the filesystem treats as a single file. It’s a very elegant way to create and manage your own custom file formats. Until next time.

Note: I have to break here for a moment to give credit where it is due. Marcus Zarra, my cohort on this site has an incredible ability to retain information–especially as it relates to developing applications for the Mac and this has really benefited me greatly. He is a tremendous mentor and teacher and so I felt I needed to just break for a moment and mention that the content of this post is really from his wealth of knowledge. I am writing this post as I am now aware of how to do these things, but it is all thanks to Marcus’ own experience and willingness to share. He’s a true asset to the Mac development community. Ok. Enough of that. Marcus’ head may start to swell. ;-)

Here is the demo application for this post. Download About Box App.

Text Formatting

If you, like me, don’t want to mess with fonts, but you would like to have some control over the formatting of the text in your About Box, then this is the tip for you.

When you first create your application, a default about box is already hooked up for you. You can simply Build and Go and select Application Menu | About Application to see what it looks like. I’m not sure about you, but I’ve never seen a commercial application with the default about box look and style. I doubt you want to leave yours as the default either.

Coming from the Windows world of programming where standards are really just whatever you make them, it may seem unnatural to stick to using the standard fonts, but in the Mac world, if you don’t make your app conform to the standards that are there, you run the risk of making your application the red-headed step child. People will notice and make comments about it. They might even taunt you. :-D

There are some passionate opinions on the topic of the HIG (Human Interfaces Guidlines) and I don’t claim to know much about it, but the bottom line is that your best bet it likely to try to conform to the standards even though many people violate them.

My about box, started out looking something like this:

Most about boxes are pretty boring, but you can’t get too much worse than this one. Instead, I created a new window in Interface Builder and hooked it up to the About menu item. When you create your about box window, make sure your window settings are correct.

Note: If you don’t ensure that Release When Closed is unchecked, your about box will crash your application. Also, make sure that Visible At Launch is not checked so that your about box doesn’t show up with your application runs.

Then add your various labels etc. so that it looks something like this:

Yeah, yeah. I know. Still boring, but we’ll add a couple of features that will help make it more interesting.

Making fonts smaller in a label is easy. Simply select a smaller size in the Size attribute drop down.

You can do this for your version and copyright labels. To make the text larger, however, takes a little more effort. In this case you’ll need to bind the font size attribute to a value in your app delegate.

Add a function to your app delegate that returns a float value representing the size of the font you want:

1
2
3
4

- (float)appNameLabelFontSize;
{
    return 24.0;
}

Then, in interface builder, select your application name label and set the Font size binding to use your AppDelegate‘s appNameLabelFontSize field.

Build and run your application in xcode and you should see the new font size in your about box.

The final change we want to make to our about box is to make the font bold for our application name. We could create another field in our app delegate to return YES that we could bind the Font bold binding, however, there’s an easier, cooler way that doesn’t require us to do anything but set the Font bold field to something that is already true. In this case we’ll just use the app delegate’s reference to self and then set the Value Transformer to NSIsNotNil.

Since self is always true, this will suffice to tell our label to display in bold.

That’s it for formatting. Now we need to add some features to keep our version and copyright up to date.

Dynamic Version and Copyright

First let’s look at keeping our copyright data up to date as doing so is very similar to the way we set our font size for the app name in the about box. We simply add another field to the app delegate that we can bind to in Interface Builder. Here is the field.

1
2
3
4

- (NSString*)copyrightString;
{
    return @"Copyright © 2008 My Company, Inc.\nAll Rights Reserved.";
}

Just as before, you hook up your field using bindings in Interface Builder. So go back into Interface Builder and select the copyright label placeholder and set the Value binding to copyrightString as shown in the screenshot below.

Now, if you want to change your copyright information, you can simply specify it in your copyrightString field in xcode and it will be up to date in your about box.

Finally, you can also use a similar technique to update your version number. This, however, is dependent upon adding a user defined setting to your project build and fiddling with your project Info.plist file. To add a user defined setting to your project build, complete these steps:

1. Double click your project in the project tree view and click on the Build tab.


2. At the bottom of the ensuing window, click the drop down and select Add User-Defined Setting as shown.


3. A new setting will be created in the list. Name it APPLICATION_VERSION and give it a value of 1.0. Close the project settings.
   
4. Back in your project tree view, open the Resources sub-directory and select your Info.plist file to edit.
   
5. Look for the key value pair for CFBundleVersion and add a new entry as follows:

   1 2 3 4

   <key>CFBundleVersion</key> <string>Alpha 0.35</string> <key>CFBundleShortVersionString</key> <string>${APPLICATION_VERSION}</string>

   
   
6. As with our copyright version string, we create another field in the AppDelegate as shown.

   1 2 3 4 5 6 7 8 9

   - (NSString*)versionString; { NSBundle *mainBundle = [NSBundle mainBundle]; NSDictionary *infoDict = [mainBundle infoDictionary];   NSString *mainString = [infoDict valueForKey:@"CFBundleShortVersionString"]; NSString *subString = [infoDict valueForKey:@"CFBundleVersion"]; return [NSString stringWithFormat:@"Version %@ (%@)", mainString, subString]; }

   The NSDictionary we grab from the main bundle provides the data in our Info.plist file. We simply plug in the values for the keys we’ve found for CFBundleVersion and CFBundleShortVersionString.
   
7. Finally, back in Interface Builder, connect the value of the version label to the versionString field of the AppDelegate.
   

Now, rebuild and run your project and open your about box. You should now see your version information up to date.

Conclusion

It seems like there is always more to do to get your application finished, but these are the aspects of developing your app that will give it polish. It will look good and will make your life easier. If you start to place build numbers into your version information, it will help you when you get crash reports from your users. This will allow you to know exactly which version of the code caused the problem. And if you are using version control like Git, you can automate this process even further. Take a look at Marcus’s post on Git and XCode: A git build number script for more information. Until next time.

In June of 2007, I was in a position both financially and career wise to buy my MacBook Pro with this long intended, not yet realized pursuit of becoming a Macintosh developer.

Since that time I have been hacking my way through example after example trying to learn Objective-C and the Cocoa framework. I’ve been watching and contributing on the different Apple mailing lists, and I’ve been writing what I’ve been learning here at Cocoa Is My Girlfriend. If everything goes right, I will have my application in the wild within the next few months. The ambition will finally pay off and become realized.

As I am finishing the application, I am faced with the stark reality that the work of building the app is a small fraction of the entire work load. Once the code is finished, the list of what is left to do before being able to release the application seems to be growing rather than shrinking. In this series of posts, I intend to examine these hurdles and provide information not only about my experiences, but how I’ve overcome these hurdles and turned them into success.

(Re) Naming Your Application

I won’t go into any long dissertation on how to choose an application name. Frankly, you can probably name it whatever you want. Just make a quality app and I don’t think that will matter so much. You can use everything from the practical such as Movie Maker (nice little gem from Microsoft) down to the nonsensical Web 2.0 names that lack vowels like flckr or meebo. You can even give the Web 2.0 Name Generator a try if you can’t think of anything cool on your own. You make the call.

Sometimes, maybe even often, the first name you think of isn’t the one you end up using, or, as in my case, you decide you want to put a space in between two words of the app name. If you go into Interface Builder with your MainMenu.nib, you’ll try to change the name of the application that shows up there and then build the app again only to find that the changes didn’t take. That’s because the application name is stored elsewhere. If you need to change your application name in your project, use the following steps.

1. With your application project open in xcode, click on Project | Edit Active Target “App Name” (where App Name is the name of your application).


2. In the ensuing window, select the Build tab.


3. In the search field, type Product Name. This is the name you will see when your application runs. Make changes to the Product Name by double clicking the value. Once you are finished, click ok.


4. Rebuild your application and run it again. You should see the application name as you specified in the Product Name field.

Lickable Application Icons

I’m no graphic artist. This has always been the case and probably always will be. One of the first keys to being successful with any venture is to realize your limitations and weaknesses and be prepared to pay the professionals who can do the work and provide what you need.

While watching the macsb mailing list, the name Jordan Langille came up several times as a graphic artist who could provide the shiny candy coated Macintosh icons and logos that people expecct. I contacted Jordan at One Toad Design and within a couple of weeks he provided me with this icon for my application.

You can see Jordan’s portfolio at his site. I’m quite pleased with the results and highly recommend his work. This is not a paid endorsement. I just like to see good work rewarded, so send him your business. You won’t be disappointed.

As a first time Macintosh application developer, I was thrilled when I received the .icns file from Jordan and the first thing I wanted to do was plug it into my application. How do you do that? Is it obvious in the project settings? This should be easy, but I don’t see where to do it in Interface Builder. What is going on?? Help!!

Oh Google….

After a quick search, I found that adding the icon to my app was as simple as the following steps.

1. Right-click the Resources folder in your project tree and select Add Existing Files….


2. In the ensuing dialog box, navigate to the .icns file that holds your icon and select it. When prompted, select the checkbox labeled Copy items into destination group’s folder (if needed).
   
   This will add the file to your project.


3. Look in your Resource folder in your project tree for the file Info.plist. Open this file


4. Look through the file for the key called CFBundleTypeIconFile. Simply specify the name of the .icns file you just added to the project like this:

   <key>CFBundleTypeIconFile</key>
   <string>MyIcon.icns</string>

Save the Info.plist file. Clean, re-build, and run your application and you should now see your icon display in the Dock. Pretty cool.

Conclusion

As I finish my application, I continue to learn new aspects of becoming a microISV for the Macintosh. It has frustrating and challenging aspects, but I hope that with my experiences I can document those things and help others who also aspire to become Macintosh software developers. Watch this site for more of my experiences.