Getting Started Developing For Mac OS X

This is a response to a message posted to the cocoa-dev mailing list. It contains a bunch of URLs that I need to remember across new environments and, as such, I thought I’d blast it into Radio so it goes on my “permanent record”

On Saturday, April 27, 2002, at 07:54 AM, Mark Weinstein <markfoo; wrote:

I am a software developer in the Seattle area and have recently moved from the Windoze platform over to the Mac and have several observations that I would like to make. Please understand that I am not flaming Apple (or anybody else for that matter), but it makes it much easier to understand why software developers don’t flock to develop for the platform.

Heh… I would imagine that whole ‘other 95%’ thing might has something to do with it, as well. Having been a long time NeXT developer, the Macintosh software market seems positively huge in comparison. Kind of like the difference between potential Windows customers and potential Macintosh customers.

(I stuck with NeXT and, now, OS X because– frankly– sitting in front of a Windows box makes me nauseous in fairly short order. I would have to replace far too many keyboards to even ship a single app.)

1) I have been a software developer for a little over 20 years, and never in my life have I seen such poor documentation. I have attempted to work with Cocoa, Carbon and even WebObjects and have found that any documentation that I have found that was even worth reading was not from Apple. In addition to the quality of the documentation, it is nearly impossible to even find anything more than quick samples here and there. If people are being actively recruited as developers, why aren’t they getting any support or training out of the recruiter?

Microsoft’s documentation and their developer program is certainly impressive in both the sheer volume of materials they ship you and the quality of a lot of the documentation. My experience over the last 20 years of development work has been a bit different. Microsoft provides excellent documentation, Apple provided excellent docs up until the introduction of Carbon, Rhapsody and the precursors to OS X.

In the early days, NeXT provided excellent documentation, as well. Not only did you have reams of straight reference materials, but NeXT provided excellent concept and architecture documentation.

As OS X has evolved, the documentation has improved immensely. These days, finding the appropriate documentation is more of a challenge than anything else. There is actually a fairly good reason why the docs have been lagging for some time and are just now starting to catch up (not that I’m attempting to make excuses for the state of the docs, simply that I can understand and even sympathize with the state they are in).

Namely, the Cocoa, Carbon, and WebObjects SDKs had been moving sideways until relatively recently. Cocoa is fairly solid these days, but Carbon and WebObjects is changing and evolving in fairly significant ways. Because of this, any documentation written against these APIs often must be massively revised with any major release.

Given the nature of the documentation– highly technical documentation that requires heavy engineering involvement to produce– it consumes a tremendous amount of engineering effort to keep everything up to date. Unfortunately, engineering resources are not cheap and time is not plentiful. I can understand (but don’t necessarily like) that Apple would make the decision to let the documentation slip a bit until it stops moving sideways.

This is exactly what appears to be happening. The Cocoa APIs are solid– there have been additions, but no major architectural revisions recently. As of the April development tools seed, executing the command….

find /System/Library/Frameworks -name '*.html' -exec grep -l 'forthcoming' {} \;

…reveals that there is not a single ‘description forthcoming’ left in the documentation for any of the Cocoa related frameworks. Likewise, as of WebObjects 5.1 [update whatever], the WO documentation has been moved forward to a similar state.

Core and Carbon– less so Carbon than Core– still has a number of ‘description forthcoming’ bits throughout the docs, but both of those APIs are still evolving.

On the non-reference front, there is quit a lot of examples and taks/concepts guides available. Again, the challenge is largely one of finding them.

For Cocoa:




Excellent starting points for figuring out where all the useful Cocoa documentation lives. The second document is particularly useful to those new to the Cocoa development platform. Scan through the last document to gain an understanding of some of the vocabulary used throughout the rest of the documentation.


Contains a tremendous wealth of examples that exercise particular chunks of API or implement particular concepts



This is the book to read to gain a relatively deep understanding of Objective-C. However, it is also of value to programmers of other OO languages as it provides an awesome overview of OO architecture and implementation methodologies. This is a very mature document; I believe one of the first version shipped with, at least, NeXTSTEP 1.0– maybe earlier– in 1990. However, it is not obsolete/out of date!

The first link leads to the Apple Developer Connection site– likely not news to anyone here– from which you can access any number of very useful resources. If you haven’t done so, register for a free ADC account as that will give you access to various software seed (though not as many as the $500/year select membership) and give you the ability to file bug reports and feature requests via the third URL. (And do file bug reports / feature requests. As long as your report or request is clearly written and contains the appropriate information– version # of the system, build # of the PBX tool suite– Apple really does read the things and really will fix the problems or add the feature (if it makes sense to do so, obviously).

The gateway to all of Apple’s mailing lists. Well, not all, but to a vast majority of the lists that are pertinent to developers. Obviously, you have already subscribed to cocoa-dev, but there may be some other lists that are of interest. If you aren’t sure whether or not a list is useful to you, subscribe in Digest mode. This will limit the # of emails/day you receive from the list– for cocoa-dev, I typically receive somewhere around 3 to 6 digests a day– and will reduce the clutter in your mailbox.

The Omni Group (awesome company — buy their stuff! — they offer the mailing lists completely voluntarily and, beyond the, in each post, I have never seen Omni use the lists for marketing purposes) also has a number of mailing lists of interest to developers. The Omni lists tend to have more traffic and, for whatever reason, tend to have a bit more rampant advocacy then the Apple Lists. Digest mode is definitely the way to go on these lists as macosx-dev alone often has well over 100 messages posted per day (many more, in some case). WebObjects-dev is likewise– I have seen digests with up to 120 messages in it.

The first three links all lead to a boatload of information about Cocoa and OS X development (and OS X development, in general). The last link leads to a page full of links to man0y other sites.

Apple offers a bunch of excellent Cocoa training. Big Nerd Ranch offers excellent Cocoa training, as well, and I hear that their training facilities is quite cool. Aaron– the primary dude behind BNR– has been doing Cocoa and Cocoa related training for a long, long time.

Finally, there are some excellent books out there for Cocoa development. Aaron Hillegas’ “Cocoa Programming for Mac OS X” is available now and does a wonderful job of teaching the developer how to write real world Cocoa apps in an effective manner. On the horizon, Simson Garfinkel and Mike Mahoney have rewritten what was the definitive how to program NeXTSTEP book in the early 90s. The new version is title “Building Cocoa Applications : A Step by Step Guide” is quite excellent.

Of the two, I would actually recommend picking up both. I had the opportunity to act as technical editor on both books and, as such, had a close look at the content. They are really two very different books; the Hillegas book tends to focus on higher level APIs and architectures while the Garfinkel/Mahoney book is oriented more to building a complete application that exercises everything from the unix command line through to high level features. The two books complement each other extremely well.

For WebObjects:


Combining the last software updater update of WO 5.1 with the recent update of the JDK, Apple now ships relatively complete reference documentation with WebObjects. It is hard to find because– unlike Cocoa, Carbon and the Core– there isn’t an index into the documentation available from within PBX (that I have discovered).

I have found three quite workable solutions:

– configure JavaBrowser correctly and it will display javadoc style docs inline as it does the classes. Out of the box, JavaBrowser is nearly useless. I wrote a shell script that will rewrite all of the path preferences for JavaBrowser such that the next time JB is launched it’ll basically have every class and piece of documentation either shipped with the system or installed in the standard extensions directory. The second link leads to a page that describes the script and provides a link for downloads.

– LaunchBar (can be had via the third URL). With LaunchBar installed and correctly configured, I can type (cmd)-(space)WOTF(cr) and LaunchBar will open the WOTextField.html documentation. Very useful.

– If you happen to have a decent Internet connection, searching the documentation is as easy as plugging the class name into the field at the top right of the fourth URL’s page. If someone were motivated, it would be trivial to rip out that form such that you had a minimal version of it on the local hard drive, thus saving the initial round trip to load a page where 95% of the content has nothing to do with the desired search.

Of course, all of this has pertinence to Cocoa development to varying degrees.

The OmniGroup hosts the quintessential development mailing lists related to WebObjects. webobjects-dev and the eof developers mailing list are likely the two most relevant lists. Apple has an announce list, but that’s it. There is also a ‘WebObjects-newbies’ list hosted at yahoo– as its name implies, the questions tend to be more novice in nature.

For Carbon / Core:

Basically, Carbon/Core documentation can be found from the same general locations as the WebObjects and Cocoa documentations and resources. The one big difference with Carbon/Core is that the header files often provide a lot of additional information about the APIs that haven’t made it into the documentation. Unfortunate but, as mentioned earlier, the APIs are still somewhat in flux which greatly impedes the creation of documentation.

The Core differs from Cocoa/WebObjects in that the source for parts of the Core is available within the Darwin CVS repository. Follow the instructions at the first URL to obtain the source.

2) Now, I admit that I am not a strong C programmer, but I can certainly get by. I have started to work with Cocoa and found that in general, it seems really nice and stable. What I find annoying is that there is no documentation on the very few frameworks that currently exist for Cocoa. I have been scraping help off of a few web pages here and there, but I certainly don’t have enough information to build a full application. I have searched Apple’s web site and tried to go through their sample code, but have found few Cocoa samples that did me any good.


(Assuming you did find all the docs mentioned above along with the concepts guides, etc…)

It sounds like you might be looking for something that isn’t there. When learning Cocoa, developers with a lot of deep experience using any of the myriad of APIs available for application construction are actually at a disadvantage until the epiphany happens.

In particular, +the Cocoa Epiphany+ is the moment when the developer realizes that, yes, in fact, the Cocoa frameworks really will do all the work for you.

One key difference with Cocoa development over a lot of other GUI toolkits is that the developer’s code is written in a more passive context.

In Carbon (more old style than new, but the new style stuff is still really hairy to set up), you typically have to write your own event loop and take care of all of the event dispatching within that loop– even for functionality (such as the functionality associated with a Quit or Hide menu item).

With Cocoa, the only event handling code you ever write is for features that deviate from ‘standard application behavior’. Have a look at the TextEdit source for a decent (though there is some cruft that could go away) example of this; fonts, rulers, cut/copy/paste, text selection, text editing, multiple document management, save as/to, revert, printing, hiding, services, spelling, speech, open recent, a basic about panel, handling of graphics in editable text, etc. are all given to you by the AppKit. There is very little custom code in TE and what is there is basically only the code necessary to make the AppKit behave like a text editor.

Another key to success: Don’t pick a fight with the APIs. It is generally unnecessary and you will lose. If something seems like it is a whole heck of a lot harder than it “should” be, it is extremely likely that you are attempting to make the APIs behave in a fashion that is not natural to their architecture. Step back, read some docs, do some googleresearch, and re-approach the problem. A large part of the time, you’ll discover that there is a much better way to solve the problem at hand without writing tons and tons and tons of code.

3) Is Carbon a permanent or temporary technology? I ask because while I want to develop applications for the Mac, I do not want to use Carbon if time is not on my side in the long run. In addition, the majority of the sample code on Apple’s site is still built in CodeWarrior! I have been working with and learning how to use Project Builder and Interface Builder from every bit of documentation I find! Why are code samples still being distributed in CW?

Rephrase the question: How long until all of the software that sells mac systems– Office, PhotShop, Illustrator, etc.etc.etc.– no longer has any dependencies or ties to Carbon?

Until that happens, Carbon is here to stay.

Most of the examples on Apple’s site are still in CodeWarrior because even porting them straight to PBX requires more work than is warranted. Most of the sample code presented as CW projects would need to be rewritten to properly exemplify whatever APIs they are supposed to demonstrate.

This is another case where the samples will improve in quality over time as the APIs stop moving sideways and start moving forward.

In any case, there is a lot of very useful functionality in Carbon and Core. It is easily accessed from Cocoa. Almost all of the recent ‘train hacks’ (I write little apps on the commute to/from the office) have a handful of calls into Carbon/Core to take advantage of APIs that don’t yet have an ObjC wrapper.

Which brings us to the next point….

4) How long will it be before we actually see Cocoa frameworks for the applications like QuickTime? I have a client right now that wants some software developed to process video and due to the lack of documentation and support that I have been able to find, I had to refer back to the PC. Nobody hates doing this any more than me, but I didn’t really feel that i had an out.


QuickTime is a cross platform API/implementation and, as such, it needs to have an API that is easily integrated into many different development platforms. An ANSI-C compliant procedural API is about as cross-platform as you can get.

However, don’t let this stop you from using QuickTime in Cocoa applications. Cocoa provides an NSMovieView and NSMovie class. These classes are simple wrappers around the display of a QT movie and a QT movie itself. The NSMovie object implements the method -QTMovie that returns an opaque pointer to the QuickTime movie encapsulated within the object. With this pointer, you can manipulate the movie’s contents via the standard QuickTime framework’s API.

Again, this is a case of APIs that are still shifting a bit impeding certain other solutions from coming to fruition. As well, wrapping a complex, general purpose, procedural API with a set of ObjC classes that intelligently provide access to that functionality in a general purpose fashion is actually very hard.

Even once done, maintaining the OO wrappers can be costly in that the wrappers have to be modified to track any changes made in the underlying procedural APIs. Certainly, this is also an issue when you have built your own specific purpose wrapper, but to a much lesser degree in that your specific case solution doesn’t exercise the entire underlying API and is not trying to express all functionality possible.

However, it is trivial to hide the procedural calls behind opaque data types and a decent set of classes to wrap the APIs in the fashion you need.

It is likely that Apple will make an ObjC accessible version of the QT APIs available someday. Until that happens, don’t let the lack of it stop you from using Cocoa / OS X!

Again, I do understand that migrating to a new technology like OSX can be frustrating. I would love nothing more than to literally throw my Windoze boxes out the window, but until I can successfully develop a useable application on the Mac, I am stuck with it.

That’s the key; Apple is still migrating to OS X. There are still chunks of API and functionality that need to moved across. Even with the rock solid (I haven’t had a machine crash in months), totally kick butt, 10.1 release we have in our hands now, it is– by no means– a complete migration!

WWDC should be very interesting this year as I believe we are going to see huge strides on the migration front. Overall, the OS “feels” like most of the core issues– stability, performance, etc– have been addressed to the point where Apple is focusing a lot of effort on new development.

Keep in mind, as well, that Apple has “bet the farm” on Cocoa (and WebObjects)! iPhoto is a Cocoa-only application; it doesn’t even run on OS 9. As well, most of the applications that ship with the operating system are written primarily against Cocoa with the few odd calls into Carbon/Core/Hidden APIs. The one notable exception is the Finder. Unfortunate in that the Finder still has some fairly serious usability issues about it.

If anyone has any ideas or suggestions for me, I would love to hear them and
am very excited about being a new member of the Mac community!

Hopefully there’ll be one or two nuggets above that you haven’t stumbled across elsewhere…


Wake up. Breathe….
…. keep breathing.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.