Project Builder is an application that manages software development projects. It’s Apple’s integrated development environment (IDE) for Mac OS X, which provides a project browser, a full-featured code editor, language-savvy symbol recognition, advanced project-searching capabilities, documentation access, build and debugging support, and other features that can streamline the development process. With it, you can create such Mac OS X software projects as:
An application, which is a bundle that contains all the resources necessary to launch the application, including the application’s executable files. A bundle is a folder packaged to look like a single file.
Frameworks, which are bundles that contain a dynamic shared library and all the resources that go with that library, such as header files, images, and documentation.
Kernel extensions, which are bundles the operating system loads into the kernel environment.
Libraries, which are code and resources that can’t execute on their own, but that export functions and global variables for others to use; usually linked to an application when the application runs instead of when it’s compiled.
Plug-ins, which are bundles that contain executable code and associated resources that must be loaded into a running application.
This chapter shows you how to create one type of software project—a Carbon application. You’ll use the Carbon programming interfaces and the C language from within Project Builder’s development environment to:
Look at the components of a Carbon application project
Examine the code you get “for free” with the Carbon application template
See how Project Builder organizes a project
Find out what’s in an application bundle
Take a look at the tools for building, debugging, and running
Find out how to access documentation from within Project Builder
Create, build, and run a new Carbon application
Before you start building your own application, let’s take a tour of Project Builder. When Project Builder opens a new project for a Carbon application, you’ll see a window similar to what’s shown in Figure 3.1. The area near the top of the window contains buttons for building, cleaning (that is, deleting the current build products and intermediate products), running, and debugging. The Run and Debug buttons remain dimmed until you build a project.
The left side of Figure 3.1—Groups & Files—shows a list of file references. The right side of the figure shows the contents of the most recent Project Builder release notes. The vertical tabs let you switch between views of the project’s files, bookmarks you save, and targets (should your project have more than one target). Let’s look a bit more closely at file references and targets.
File references refer to the source files, resource files, libraries, and frameworks in your project. The important thing to remember is that, although the Groups & Files list shown in Figure 3.2 may look like a directory listing, the items in the list are references to files or folders on your hard disk; they are not the files or folders themselves.
Project Builder organizes the project’s file references into four groups: Sources, Resources, External Frameworks and Libraries, and Products. You can move a file reference into any group you want. You can also add your own groups. Groups are there solely for your convenience and do not affect Project Builder’s ability to find or compile the files. It’s easier to manage large projects if you keep related files together. Let’s take a closer look at what each group normally contains.
These are files that contain the application’s source code and are compiled to produce object code. In Project Builder, it’s recommended that you list header files in the project window and include them in the Sources group. The project in Figure 3.2 contains only one source file: main.c. We’ll take a close look at the main.c source file Project Builder provides in Section 3.1.3.
These are files that contain resources or that can be compiled to produce resources. The project shown in Figure 3.2 contains two: InfoPlist.strings, which contains a list of properties associated with the application, and main.nib, which contains the application’s interface-based resources. Both the main.nib and InfoPlist.strings files can be localized. You’ll read more about localization in Chapter 8.
Note
Resources refer to a wide variety of bits and pieces that are needed to run the program, including strings, menus, dialogs, icons and other images, sounds, and much more. Resources are separated out from the program code, so that you can change the resources without having to change the code. For one thing, this makes it easier to design an application with various languages and cultures in mind.
In Mac OS X, a framework is a shared library that’s bundled with its header files and resources. This project shown in Figure 3.2 contains three frameworks and a library. A Carbon project always contains the Carbon framework. If you click the disclosure triangle next to a framework, you can see a list of its header files.
The Products group includes anything produced when you build your project. The Sample Application shown in Figure 3.2 has one product—SampleApplication.app.
It’s an application that runs on Mac OS X. Notice SampleApplication.app appears dimmed in the figure. That’s because either the project has been
“cleaned” (that is, built products have been removed by clicking the Clean button shown in Figure 3.1) or the project hasn’t been built yet.
The SampleApplication.app product is an application bundle. We’ll take a look at a typical bundle in Section 3.1.5.
Targets provide a way for you to organize project files so you can build a variety of products. Think of the files, resources, libraries, and frameworks in your project as a list of ingredients and the project targets as courses in a meal. Some targets use some ingredients, and some may use all the ingredients. All targets share some ingredients with other targets.
For example, a project for a client-server software package can contain targets for:
A client application
A server application
A private framework that both applications use
Command-line tools that you can use instead of the application’s menu commands
Although the command-line tools might use most of the same source files the client application uses, the tools might not use the resources needed to build the interface. The client application would use the same framework used by the server, but the client application would use different source files and resources to create the client interface.
When you create a project, you add all the files you need for all your targets. When you set up a new target, you identify which files in the project should be used to build that target.
The complete list of an application’s targets is in the Targets pane. You can view the Targets list by clicking the vertical Targets tab shown in Figure 3.3. (The sample application shown in the figure has only one target.) When you view a target, the right side of the project window displays four tabs: Files & Build Phases, Build Settings, Application Settings, and Executables. These tabs provide access to panes in which you can customize settings for a target. For example, in the Files & Build Phases pane, you can specify whether a header file should be private or public; in the Application Settings pane, you can enter the name of the file that contains the target’s icons; and so forth.
Project Builder provides most of the defaults you need, such as the location of the Carbon framework and the name of your source files. But there are some settings, such as Application Settings, that you will need to modify for your application. We’ll show you how to do that in Chapter 10.
When Project Builder creates a new Carbon project, it provides a main.c file and a main.nib file.
The main.c file contains C code that will actually compile and run. The main.nib file is an Interface Builder file that contains a default menu bar and window. (You’ll read more about nib files in Chapter 4.)
The code in the main.c file will read the main.nib file and create a simple interface for the skeletal application. Let’s take a closer look at the main.c file shown in Figure 3.4.
Example 3.1 shows the lines of code from the main function, but without the embedded comments shown in Figure 3.4. Below the listing you’ll find an explanation of each numbered line of code. Where appropriate, we’ll identify the name of the Carbon manager or service to which each function belongs.
Example 3-1. The Key Lines of Code from the Main Function
err = CreateNibReference (CFSTR ("main"), &nibRef); //1 require_noerr (err, CantGetNibRef); //2 err = SetMenuBarFromNib (nibRef, CFSTR("MainMenu")); //3 require_noerr (err, CantSetMenuBar);
err = CreateWindowFromNib (nibRef, CFSTR ("MainWindow"), &window);
require_noerr (err, CantCreateWindow);
DisposeNibReference (nibRef); //4 ShowWindow (window); //5 RunApplicationEventLoop (); //6Here’s what the statements do:
The Interface Builder Services function
CreateNibReferencecreates a reference to a nib file. You must supply two parameters. The first is aCFStringthat represents the name of the nib file, but without the nib extension. A nib file is an Interface Builder file that contains information on how the operating system should construct the interface. You’ll read more about these in Chapter 4. The string"main"is used here becausemain.nibis the name of the nib file. It must be converted to aCFStringusing the Core Foundation functionCFSTR. You’ll use this function throughout the book to convert a string to aCFString.The second parameter is a pointer to an
IBNibRefdata type-a nib reference returned by theCreateNibReferencefunction. This sample application will later pass the nib reference to other functions that use information from the nib file to construct the menu bar and windows used in the application.Note
A Core Foundation string (
CFString) represents an array of Unicode characters (UniChar) along with a count of the number of characters. Unicode-based strings in Core Foundation provide a solid basis for internationalizing the software you develop. Unicode makes it possible to develop and localize a single version of an application for users who speak most of the world’s written languages, including Russian (Cyrillic), Hebrew, Arabic, Chinese, and Japanese. Although conceptuallyCFStringobjects store strings as arrays of Unicode characters, in practice they often store them more efficiently. The memory aCFStringobject requires is typically about the same as or even less than that required by a simpleUniChararray.The macro
require_noerrchecks for an error condition. It takes two parameters—one of typeOSStatus, used to return result codes from a function, and a label. If an error is returned, the program jumps to the label. Note that all labels used in the main function are located near the end of the function. So jumping to a label causes the application to quit before it fully launches. You should use this macro to check for “show stopping” errors. If you can’t create all or part of the interface, you shouldn’t continue to launch the application.The Interface Builder Services functions
SetMenuBarFromNibandCreateWindowFromNibset up the menu bar and main window based on the information in the nib file. Each takes a nib reference as the first parameter—it’s the nib reference returned byCreateNibReference. You must pass aCFStringas the second parameter to denote which interface object from the nib file you want to create.CreateWindowFromNibtakes a window reference as the third parameter. On return, the function provides a reference to the window it created from the nib file. You’ll need the window reference to show, hide, read, and write to the window.The Interface Builder Services function
DisposeNibReferencedisposes of the reference to the nib file. It doesn’t affect the object already created from the reference.The Window Manager function
ShowWindowdisplays the main window. You need to call this function because the functionCreateWindowFromNibby default creates a window as hidden.The Carbon Event Manager function
RunApplicationEventLoopruns the main event loop. If anything happens in the application, the Carbon Event Manager hands it to your application to take care of or takes care of the event itself, if the event is a standard event like quit. The functionRunApplicationEventLoopdoesn’t return until the application quits. You’ll learn more about events and the Carbon Event Manager in Chapter 6.
Recall that Project Builder shows file references, not the files themselves. This means that the groups and files you see in the Project Builder window may not reflect the actual location and grouping of the files on your hard disk. From the Finder, a project’s files and how they are grouped look a bit different from the view you see in Project Builder. Compare the Finder view in Figure 3.5 with the Files & Groups list in Figure 3.2. Here are some additional explanations about the items you see in the Finder view:
-
SampleApplication.pbproj This is a bundle that Project Builder uses to keeps track of the project’s files and targets along with project and user-specific settings.
-
English.lproj This folder contains resources that are localized into English. You can have
lprojfolders for other languages, in which case the folder is named with the English name for the language, such asFrench.lprojorJapanese.lproj.-
build Project Builder uses this folder to store build products, including intermediate projects, project headers, and executable files. You won’t see this folder until you build the application.
Notice that Carbon.framework isn’t in the project directory. It’s in /System/Library/Frameworks.
However, as you saw in Figure 3.2 the project contains a reference to it.
Note
The critical point here is that you can regroup files in the Project Builder window, but if you move the files on disk, you’ll break the file references. (A broken file reference appears red in Project Builder.) To fix a broken reference, do the following:
Choose Show Info from the Project menu.
Choose Set Path from the Change Path pop-up menu. A navigation dialog appears.
Navigate to the new location of the file or folder whose location you changed.
Click Open, then click Change.
An application bundle is the file package you distribute to users. Now that you know a little about a Carbon application project, it’s time to “look under the hood” of a built application to see how Project Builder packages it. Packaging assures that everything your application needs—the executable file, resources, help files, libraries, and plug-ins—is in one location. It also assures that users cannot accidentally break an application by renaming its components, moving them, or otherwise manipulating them in the Finder.
An application bundle can contain any of the following:
Images, sounds, or other files used by the application
Localized character strings
Localized versions of nib files
Multiple executable versions of an application
An application bundle appears to the user as if it were a file. To see the contents of an application bundle, you can Control-click the application’s icon and choose Show Package Contents (as shown in Figure 3.6) from the menu that appears.
These are the items Project Builder puts in the application bundle when you build the application (see Figure 3.7):
Info.plist. The information property list contains information about the bundle. You’ll read more about this in Chapter 10.MacOS. Contains the application’s executable files. It’s possible to have multiple executable files if you are providing versions for multiple platforms (such as for Mac OS 9 and Mac OS X).
pbdevelopment.plist. Contains information Project Builder uses when it builds your project. This file is created only for development builds. A deployment build does not have this file.PkgInfo. Contains the bundle type and creator codes for your application.Resources. All the resources an application needs are in this folder.
The Build and Run buttons at the top of the project window let you build a project and then run the resulting application. When you click the Build button, a pane slides down from the top of your project window. Figure 3.8 shows an example of a build window. The top part displays error messages and warnings (if any), and the bottom part displays the build log. When the build finishes, a message appears at the bottom of the project window. Hopefully, the message is “Build succeeded.”
Compiling and linking messages are displayed in the area shown in Figure 3.8. These messages provide a record of the input to, and output from, the tools that Project Builder calls upon to build the targets you set up in your project.
It’s pretty optimistic to think you’ll create an application that runs successfully every time. Fortunately Project Builder has an easy-to-use debugger for those occasions when the program functions incorrectly. We’ll show you how to use the debugger in the next section.
Project Builder’s debugger is easy to activate—just click the Debug button (the bug spray can called out in Figure 3.1). Before you start the debugger, you may want to set some breakpoints so you can examine the state of the running code at points you suspect to be a problem.
To set a breakpoint, scroll to the part of the code in which you want a breakpoint, then click in the margin beside the statement. A marker appears next to the statement, as shown in Figure 3.9. To get rid of a breakpoint, you simply drag the marker out of the margin.
When the debugger runs, the Debug pane slides down (see Figure 3.9). Project Builder runs the application until the first breakpoint, or until the program crashes or is interrupted. When the application stops at the breakpoint, you’ll see the currently executed statement highlighted with a red arrow pointing at it. Above the code, you can examine the application’s variables and current values.
You can control the debugger with the buttons located at the far right of the toolbar, as shown in Figure 3.9:
Pause temporarily stops the application and displays the currently executing statement.
Continue starts a paused application.
Step Over executes the next statement within the same function.
Step Into executes the next statement, but jumps to the first line in the next function if its source code is available.
Step Out executes until you exit the current function.
The threads pop-up menu in the debugger pane lets you choose among threads in your application. A thread is an independent execution path within your application. (Threads are discussed in more detail in Chapter 14.) The list below the pop-up menu displays the thread’s call chain in the Frames list. If your application has only one thread, other threads you see are system threads that handle interapplication communication and the debugger.
The Variable list shown in Figure 3.9 displays the values of the local and global variables associated with the selected frame.
When you use Project Builder, you have access to a wealth of documentation. You can access a variety of help from the Help menu in Project Builder, shown in Figure 3.10. Choosing an item from the Help menu opens Help Viewer to the appropriate set of help or to Project Builder release notes. Searching for specific details in help is as simple as typing words or phrases in the field at the top of the Help Viewer application and clicking the Ask button. The search engine returns a list of “hits” (links), ranked by relevance, that you can browse through.
A search always focuses on the set of documentation you have open. Thus a search when you are perusing Carbon Help confines the results to Carbon documentation. If the results yield nothing of interest, you can easily expand the search to Apple’s complete set of Mac OS X developer documents.
Let’s look at Apple’s Carbon documentation. To open the Carbon Developer Documentation page, click Carbon Help in the Project Builder Help menu. At the upper-left corner of this page you’ll find a list of Developer Guides installed on your system. Some of these guides are in HTML format, some are in PDF format, and some are in both. A book in HTML format opens in Help Viewer; a book inPDF format opens in the Preview application or Acrobat Reader (if you’ve downloaded it from Adobe).
In addition to the Developer Guides, the Carbon Developer Documentation page supplies links to detailed documentation for the programming interfaces described in Chapter 1.
The Carbon documentation includes a clipboard feature that allows you to copy declarations and sample code from a Help Viewer page to your project. Figure 3.11 shows the reference documentation for the ShowWindow function, with a Clipboard button to the right of the function declaration.
Click the Clipboard button to copy a declaration or code example from a Help Viewer page to the system’s Clipboard. Then, in Project Builder, move the insertion point to the desired place in your code and choose Paste from the Edit menu.
