Mac OS X Development Tools Overview

February 25, 2004 Java and all Java-based trademarks are Apple Computer, Inc. trademarks or registered trademarks of Sun © 2003, 2004 Apple Computer, Inc. Microsystems, Inc. in the U.S. and other All rights reserved. countries. OpenGL is a trademark of Silicon Graphics, No part of this publication may be Inc. reproduced, stored in a retrieval system, or transmitted, in any form or by any means, PowerPC and and the PowerPC logo are mechanical, electronic, photocopying, trademarks of International Business recording, or otherwise, without prior Machines Corporation, used under license written permission of Apple Computer, Inc., therefrom. with the following exceptions: Any person X Window System is a trademark of the is hereby authorized to store documentation Massachusetts Institute of Technology. on a single computer for personal use only Simultaneously published in the United and to print copies of documentation for States and Canada. personal use provided that the documentation contains Apple’s copyright Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR notice. REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, The Apple logo is a trademark of Apple ITS QUALITY, ACCURACY, Computer, Inc. MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS Use of the “keyboard” Apple logo MANUAL IS SOLD “AS IS,” AND YOU, THE PURCHASER, ARE ASSUMING THE ENTIRE (Option-Shift-K) for commercial purposes RISK AS TO ITS QUALITY AND ACCURACY. without the prior written consent of Apple IN NO EVENT WILL APPLE BE LIABLE FOR may constitute trademark infringement and DIRECT, INDIRECT, SPECIAL, INCIDENTAL, unfair competition in violation of federal OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR and state laws. INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages. No licenses, express or implied, are granted THE WARRANTY AND REMEDIES SET with respect to any of the technology FORTH ABOVE ARE EXCLUSIVE AND IN described in this document. Apple retains LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, all intellectual property rights associated or employee is authorized to make any with the technology described in this modification, extension, or addition to this document. This document is intended to warranty. assist application developers to develop Some states do not allow the exclusion or limitation of implied warranties or liability for applications only for Apple-labeled or incidental or consequential damages, so the Apple-licensed computers. above limitation or exclusion may not apply to you. This warranty gives you specific legal Every effort has been made to ensure that rights, and you may also have other rights which the information in this document is vary from state to state. accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010

Apple, the Apple logo, AppleScript, AppleScript Studio, Aqua, Carbon, Cocoa, Mac, Mac OS, Macintosh, MPW, QuickTime, Sherlock, and WebObjects are trademarks of Apple Computer, Inc., registered in the United States and other countries. Finder, Quartz, and Xcode are trademarks of Apple Computer, Inc. Objective-C is a trademark of NeXT Software, Inc. Contents

Chapter 1 Introduction 9

Who Should Read This Document 9 Organization of This Document 10 See Also 10

Chapter 2 Getting Started 13

About Xcode 13 The Mac OS X Application Environments 14 Carbon 15 Cocoa 15 BSD and Darwin 16 Java 16 Classic 17 Development Projects and System Architecture 17 What to Read Next 18 Developers New to the Macintosh 18 Experienced Macintosh Developers, Pre–Mac OS X 20 Macintosh Developers With a Non-Apple IDE 21 Tool Developers 21 Plug-in Developers 21 Developers of Drivers and System Software 22 Pure Java Developers 22 Solutions Providers 23 QuickTime Developers 24

Chapter 3 The Apple Integrated Development Environment 25

Features of the Xcode Application 25 Creating a Project 26 Writing an Application 27 Carbon-Based Applications 27 Cocoa-Based Applications 28 Using Interface Builder to Add a UI to a Program 30

Chapter 4 Development Process 33

Designing an Application 34 Designing a User Interface 35 Creating Source Code 36 Localization 36 Documenting Code 37 Help 37 Property Lists 37 Icons 37 Graphics 37 Source-Code Utilities 38 Version Control 38 Debugging and Tuning 38 Memory Use 39 Efficiency of Execution 39 Graphics 40 Packaging 40 Copying and Moving Files 41 Libraries 41

Chapter 5 Notes for Specific Project Types 43

Scripting 43 Creating Frameworks 44 Standard Apple Plug-in Projects 45 Tool Projects 45 Java 46 Java Remote Interface 46 Debugging Java Applications 47 Packaging Java Applications 47 Kernel Extensions 47 Networking Extensions 48 I/O Kit Drivers 48 WebObjects 49

Appendix A Tool Descriptions 51

Creating Source Code 51 Localization Tools 51 Documentation and Help Tools 52 Compilers, Linkers, Build Tools 52 Library Utilities 53 Code Utilities 54 Version Control 56 RCS 56

CVS 56 Comparing Files 57 Debugging and Tuning 57 General 57 Memory 58 Graphics 59 Examining Code 59 Performance 60 KEXTs, Drivers, and Instruction Traces 61 Packaging 62 Scripting 63 Interpreters and Compilers 63 Script Language Converters 64 Perl Tools 64 Parsers and Lexical Analyzers 65 Documentation Tools 65 Java 66 General 66 Java Utilities 66 Java Archive (JAR) Files 67 Kernel Extensions 68 I/O Kit Drivers 68

Document Revision History 71

Index 73

Chapter 2 Getting Started 13

Figure 2-1 Xcode application 14 Figure 2-2 Mac OS X system architecture and development environments 18

Chapter 3 The Apple Integrated Development Environment 25

Figure 3-1 Interface Builder windows for a new Carbon project 30 Figure 3-2 Interface Builder windows for a new Cocoa project 31

Chapter 4 Development Process 33

Figure 4-1 The software development process 34

Introduction

Mac OS X, with its heritage of great user interfaces and its roots in a solid, open-source UNIX implementation, is the most advanced computer operating system available today. Because of the selection of development environments and tools available for it, Mac OS X is also the easiest platform to write software for. Whether you want to take advantage of the rapid development afforded by Apple’s object-oriented frameworks (Cocoa), or the power and flexibility of its procedural API (Carbon), there is a large assortment of tools available for your use. The Xcode application, Interface Builder, and the other tools that constitute Apple’s full-featured integrated development environment (IDE) work equally well with Carbon and Cocoa and can also be used for cross-platform UNIX and Java development. The Xcode software development tool set includes the IDE, other applications and command-line tools written by Apple, and many tools written by other companies and by the UNIX open-source community.

This document introduces the software development tools provided on the Xcode CD (also available on the Apple Developer Connection website at http://developer.apple.com), puts the various tools in the context of the development process, and briefly describes each tool so you can determine when you might want to use it. The tools in the Xcode tool set include many written by Apple, plus a variety of tools available from other sources and provided by Apple for your convenience. Whether you are new to Mac OS X or an old hand, this document will help you find the tools you need.

Who Should Read This Document

This document is intended for all developers of Mac OS X software. If you are new to developing software for Mac OS X, read the remaining sections in this Introduction to determine which development environment to use and to learn which additional sections of this document to read. If you are an experienced Mac OS X software developer, this document can serve as a resource to help you find the right tool for a specific task. You can skim through it to get an idea of what tools are available and come back to it later when you need to locate a tool for a specific purpose.

Organization of This Document

This document outlines the software development process, tells you which tools are useful at each stage of development, and lists and describes all the tools available from Apple. This document contains the following chapters:

■ “Getting Started” (page 13) explains what Xcode and the Xcode application are, describes the different sorts of development projects that can be undertaken using Apple’s tools, describes how each type of development project relates to the system architecture, and tells you—based on your experience and the type of project you intend to undertake—what to read next. ■ “The Apple Integrated Development Environment” (page 25) provides a brief introduction to The Xcode application and Interface Builder, including a summary of their capabilities and how they interact with each other and with other tools. The Xcode application is the core application of Apple’s integrated development environment (IDE) for Mac OS X. Together with Interface Builder and the other tools in the IDE, it provides all of the features you need to build a program for the Mac OS X platform, whether it’s an application, kernel extension, shared library, or tool. ■ “Development Process” (page 33) gives an outline of the software development process for Carbon and Cocoa applications, and describes how the Xcode tools support this process. For each stage in the process, this chapter lists and describes the tools that are useful at that stage. ■ “Notes for Specific Project Types” (page 43) describes the exceptions to the generalizations described in the preceding chapter. Although all software development projects have certain similarities (they all require design, coding, and debugging, for example), some types of software require a different process or a different set of tools than others. For example, the tools used for writing and debugging scripts are different from those used for Carbon or Cocoa applications. This document also contains an appendix that lists the tools in Xcode and a revision history.

What to Read Next

Tools are available for developers of all types who want to develop software for Mac OS X. The application environment you select and the tools you use depend on your background and the type of program you intend to write. This section gives you some advice on the development environment you should use based on your experience and the type of project you are planning, and then points you to the appropriate section in this document to learn more about the tools that will be most useful to you.

Note on Terminology: The term tool is used in different ways in different contexts. In this document, tool refers to any program that can be used by software developers to help complete their software development project. The term “application” is reserved for a tool (or other program) with a graphical user interface (GUI). A tool that has no GUI and that is customarily run from a command line is referred to in this document as a “command-line tool.”

Developers New to the Macintosh

If you are new to Mac OS X and have a GUI application that you would like to port, start with the appropriate section:

■ “With an Existing UNIX Application” (page 19) ■ “With an Existing Windows Application” (page 20) If you have a Java application and you would like to make sure it runs as well as possible on Mac OS X, see “Pure Java Developers” (page 22).

If you are starting from scratch, begin with the following section, “With No Existing Application” (page 19).

With No Existing Application

The fastest way to write a new Mac OS X GUI application from scratch is to use the Cocoa application environment. The Cocoa frameworks do a lot of the work for you, providing much of the user interface plus many lower-level features such as I/O and interapplication communication. Once you have developed an application in Cocoa, it is easy to maintain and the code is easy to reuse, which makes updating your program even faster than the original development. However, if you intend to port your program to another platform, you might want to write all or a portion of it using procedural calls instead of using the Cocoa frameworks. In that case, you should use the Carbon application environment.

The primary tools for developing Cocoa and Carbon applications are the Xcode application and Interface Builder; see Chapter 3, “The Apple Integrated Development Environment”, for an introduction to these tools. There are many other tools useful for such tasks as debugging and tuning your application, source control, and so on. See Chapter 4, “Development Process”, for details.

If you want to write a pure Java application, see “Pure Java Developers” (page 22).

For programs that do not have a graphical user interface, start with one of the following sections:

■ “Tool Developers” (page 21) ■ “Plug-in Developers” (page 21) ■ “Developers of Drivers and System Software” (page 22)

With an Existing UNIX Application

Because of its close alignment with BSD, the back-end (that is, non-GUI portion) of most UNIX applications can run in Mac OS X with little or no modification. For a UNIX tool or utility designed to be run from the command line, you might not have to do any further development. However, such an application is useful only to other UNIX developers and a small group of power users; most Mac OS X users prefer to interact with the Finder and do not know how to use the Terminal application.

If you have already developed an X Window System (X11R6) interface for your application, you will probably need only minor changes to get it to compile in Mac OS X. Apple provides an X Window System implementation (http://www.apple.com/macosx/x11/). This solution is adequate for experienced UNIX users who are used to the X Window System and do not have other expectations for the application.

However, if you intend your application to appeal to the vast majority of Mac OS X users, you must implement a standard Mac OS X user interface. A Mac OS X user should never have to resort to the command line to perform any task in an application with a graphical user interface. Furthermore, Mac OS X users expect their applications to conform to the standards promulgated in Aqua Human Interface Guidelines in the User Experience Documentation area. Well-behaved applications from Apple and third-party developers give Mac OS X its reputation as the most usable interface on the planet, and an application that does not follow these guidelines is perceived as crude and difficult to use.

You can use the Cocoa application environment and the Interface Builder application to quickly implement a standard Mac OS X GUI as a front-end for your application (see “Cocoa” (page 15) for a brief description of Cocoa). Interface Builder and all the other tools you need for Cocoa

development are provided in Xcode and on the ADC website. See Chapter 3, “The Apple Integrated Development Environment”, to get started. See UNIX Porting Guide in the Porting Documentation area for more information about porting UNIX applications to Mac OS X.

You can also use AppleScript Studio to add an Aqua GUI to a UNIX command-line tool. For an example, see Developer/Examples/AppleScript Studio/Archive Maker/Application.applescript. See “Solutions Providers” (page 23) for more information about AppleScript Studio.

With an Existing Windows Application

Although Microsoft Windows and Mac OS X share many fundamental GUI paradigms—such as application windows, dialogs, controls (buttons, progress bars, and the like), and menu bars—there are major differences in the details and manners of implementation of the two user interfaces. Mac OS X users expect a great deal of consistency among their applications and consider an application that does not follow the Mac OS X user interface (Aqua) standards to be of poor quality and hard to use. For an introduction to the user interface differences between Microsoft Windows and Mac OS X, see http://developer.apple.com/ue/switch/windows.html.

The easiest way to create a graphical user interface that conforms to Aqua standards is to use Interface Builder. See Chapter 3, “The Apple Integrated Development Environment”, for an introduction to Interface Builder.

If you have a Microsoft Windows application with certain characteristics, conversion to a Mac OS X application is fairly straightforward. The characteristics are:

■ Written in C, C++, Objective-C, or Objective C++ ■ Clean separation between the GUI code and the back-end ■ Back-end that uses procedural code rather than Microsoft Foundation Class Library or some other object-oriented framework In this case, you can replace the calls to the Windows API with calls to the Carbon API. In addition, if your GUI code is separate from your other code, you can use Cocoa to create a standard Aqua GUI for your application. You can use the Xcode application to write your procedural code and Interface Builder to create your GUI. See Chapter 3, “The Apple Integrated Development Environment”, for an introduction to the Xcode application and Interface Builder. There are many other tools useful for such tasks as debugging and tuning your application, source control, and so on. See Chapter 4, “Development Process”, for details.

For suggestions and advice on converting a procedural Windows application to a Carbon application, see Porting to Mac OS X from Windows Win32 API (http://developer.apple.com/macosx/win32porting). For details about the Mac OS X standard GUI, see Aqua Human Interface Guidelines in the User Experience Documentation area.

Experienced Macintosh Developers, Pre–Mac OS X

If you have a Mac OS 9 or earlier application written with the Mac OS procedural API, you can replace unsupported function calls with Carbon functions as necessary and use Xcode to compile and link your application. If your GUI code is well segregated from your other code, you can use Interface Builder for your user interface.

All the tools you need for Carbon development are provided in Xcode and on the ADC website. For information on converting a Mac OS 8 or Mac OS 9 application to Mac OS X, see Carbon Porting Guide and the other documentation provided in the Porting Documentation area on the ADC web site. See Chapter 3, “The Apple Integrated Development Environment”, for more information on the Xcode application and Interface Builder.

Note that you cannot use the Xcode application to build applications that run in Mac OS 9 or earlier. If you need to compile and debug code to run in Mac OS 9, you can use MPW and MacsBug, found at http://developer.apple.com/macos/macos9.html.

Macintosh Developers With a Non-Apple IDE

If you are developing for Mac OS X but are using Code Warrior or another non-Apple IDE, you should consider switching to Xcode. Xcode is the only set of development tools guaranteed to keep pace with changes in the Mac OS and with the Cocoa and Carbon APIs. The Xcode application user interface provides most of the features available in Code Warrior, and some features that Code Warrior does not have. The Xcode application’s performance is comparable to that of Code Warrior.

For tips on converting a Code Warrior project to Xcode, see the programming topic Moving Projects from CodeWarrior to Xcode.

Tool Developers

The word tool is used to mean many different things, but as used in this document, a tool is any program that can be used by software developers to help complete their project. A tool can be an application (that is, a program with a GUI), in which case it is developed like any other application, or a command-line tool. Other than the fact that a command-line tool has no GUI, it is developed in a manner similar to an application.

Plug-in Developers

Plug-ins are modules of code and data that developers and users can add to an application to extend its capabilities. Because the Mac OS X operating system can dynamically load code when it is needed, it is not necessary to link the plug-in code to the main application during the development process; the user has only to place the plug-ins in the correct directory, and the application can locate the plug-ins and load them when it needs them.

If you want your application to use plug-ins, you must design an external API that plug-in writers can use. If you are using an object-oriented programming language, you can define an abstract base class or a list of methods (called a protocol in Objective-C). In a procedural language, such as C, you can define a set of functions that the plug-in writer must implement, plus a mechanism for registering callback functions for different types of messages. In Carbon applications, you can use the Core Foundation CFPlugIn opaque type to define an object-oriented architecture that works with both C and C++ plug-ins. For more information on designing plug-ins, see the programming topic Dynamically Loading Code in the Cocoa Resource Management Documentation area.

From the point of view of development tools, a Mac OS X plug-in is a type of loadable bundle. For more information about bundles, see System Overview in the Mac OS X Documentation area.

There are several standard Apple applications for which you can write plug-ins. For information about plug-ins for programs written by Apple, see “Standard Apple Plug-in Projects” (page 45).

Developers of Drivers and System Software

Mac OS X provides a mechanism allowing dynamic loading of code into the kernel, without the need to recompile or relink. Because any other method of modifying the kernel would require you to create, distribute, and maintain your own custom version of Mac OS X, you need to use a Mac OS X kernel extension (KEXT) if you want to load code into the kernel.

It’s important to note that adding code to the kernel is very hazardous. Because none of the mechanisms protecting the operating system from faulty code (protected memory, preemptive multitasking, management of virtual memory) apply to code executing in the kernel, you can cause a kernel panic (that is, crash the operating system), cause hardware to malfunction, cause data loss, and damage other applications with faulty kernel code. Most features you need to implement, including many device drivers, can execute at higher levels of the operating system, outside the kernel; see Accessing Hardware From Applications in the Device Drivers & I/O Kit Documentation area. For more information about the architecture of the kernel and the characteristics of kernel code in general and KEXTs in particular, see Kernel Programming in the Darwin & Core OS Documentation area.

If you want to write a device driver, you should use the I/O Kit. The I/O Kit is a collection of system frameworks, libraries, tools, and other resources for creating device drivers in Mac OS X. It is based on an object-oriented programming model implemented in a restricted form of C++. For detailed information about the I/O Kit, see I/O Kit Fundamentals in the Device Drivers & I/O Kit Documentation area.

For general information on the kernel environment and writing code that executes in the kernel, go to the Darwin Developer Documentation area on the ADC web site.

You can use Xcode to develop KEXTs and I/O Kit drivers. Although you can use the Xcode application to write the source code, not all of the tools used for debugging and tuning applications can be used with code that executes in the kernel. See Chapter 3, “The Apple Integrated Development Environment”, for an introduction to the Xcode application. For other tools used with kernel-level code, see “Kernel Extensions” (page 47) and “I/O Kit Drivers” (page 48).

Pure Java Developers

Pure Java refers to programs written to run in the Java platform-independent environment, including applications with a GUI and applets designed to run without a user interface.

Most of the standard Java Development Kit (JDK) command-line tools are included as a standard part of Mac OS X. In addition, a variety of other Java-specific and general-purpose command-line tools are provided in Xcode. As with other Mac OS X program environments, you can use the Xcode application to write your code (see Project Builder for Java in the Java Documentation area). Jar Bundler is a utility for packaging already-compiled Java applications to run as Mac OS X applications.

If you want to develop a web server application, you can use WebObjects to expedite the process. WebObjects 5.2 includes a comprehensive suite of tools and frameworks for quickly developing standards-based web services and Java server applications. Among other tools, WebObjects includes the EOModeler application—which can reverse-engineer existing databases or be used to design schemas for new databases—and assistants to create enterprise-level web service, HTML, and Java applications. You use the Xcode application to build your web application and can use Interface Builder to add an Aqua interface. Other than the Xcode application and Interface Builder, the WebObjects tools and frameworks are a separate product, which you can purchase from Apple. See http://www.apple.com/webobjects and the WebObjects Documentation area on the ADC web site for more information.

See Chapter 3, “The Apple Integrated Development Environment”, for an introduction to the Xcode application and Interface Builder. For other Java tools, see “Java” (page 46). For complete Mac OS X Java documentation, go to the Java Documentation area on the ADC web site.

Solutions Providers

Using AppleScript, Perl, and shell scripts, you can automate workflows involving multiple applications. AppleScript provides direct control of many Mac OS X applications and parts of the Mac OS itself. In order to be scriptable, the writer of an application must include AppleScript support. Fortunately, many developers have done so, including most of the applications commonly used by businesses. For more information about AppleScript, go to http://www.apple.com/applescript and the AppleScript Documentation area on the ADC web site.

You can use Script Editor (located in /Applications/AppleScript) to compile and execute standard scripts, which have limited user interface capabilities. You can use AppleScript Studio to create AppleScript applications with complex user interfaces that support the Aqua human interface guidelines. AppleScript Studio is a combination of technologies, including AppleScript, Cocoa, the Xcode application, and Interface Builder. For more information about AppleScript Studio, go to http://www.apple.com/applescript/studio/. Documentation for AppleScript Studio is in the AppleScript Documentation area on the ADC web site.

Perl is a standard scripting language available on multiple platforms. It is open source and free. It can be used to execute programs or to take the output of one program, process the data, and use it for input to another program. Perl can be used for interprocess communication, for reading information from the World Wide Web, and for writing CGI scripts. Perl programs can execute modules written in C and other languages, treating them like Perl subroutines. Perl is included with the Mac OS X distribution.

In addition to AppleScript and Perl, you can write shell scripts to run in the Terminal application. A shell script is just a sequence of shell commands read from a file instead of typed in by hand. Therefore, you can write scripts to do anything you can do from the Terminal; which is to say, nearly everything that can be done by Mac OS X, including some functions not available in the Finder. You can execute shell scripts from AppleScript and you can execute AppleScript scripts from a shell script. You can execute AppleScript scripts and command-line tools from a Carbon or Cocoa application.

To write an AppleScript Studio application, you create an Xcode project. See Chapter 3, “The Apple Integrated Development Environment”, for an introduction to the Xcode application. There are also a variety of tools used with Perl, AppleScript, and terminal scripts. For an introduction to other tools used with scripts, see “Scripting” (page 43).

QuickTime Developers

QuickTime is a technology for manipulating and storing a variety of media including video, sound, animation, graphics, text, music, and even manipulating, storing, and displaying 360-degree virtual reality. It also allows you to stream digital video from either a live or stored data stream. QuickTime is available for Mac OS and Microsoft Windows.

It is relatively easy to include QuickTime support in an application using Cocoa or Carbon and the standard application development tools (primarily the Xcode application). For more information, see the Apple Developer Connection website for QuickTime at http://developer.apple.com/quicktime/index.html. You can also write QuickTime components to extend the capabilities of QuickTime. Because the QuickTime API is procedural, you should use Carbon to write QuickTime components. See the QuickTime Documentation Topics area on the ADC web site for details about the component API.

If you are interested in creating content for QuickTime, you can avail yourself of many Apple and third-party tools. Because these tools operate on data, not on source code, they are beyond the scope of this document. For more information, see the QuickTime Tools web page at http://developer.apple.com/quicktime/quicktimeintro/tools/index.html.

The Apple Integrated Development Environment

Xcode is the set of software development tools for Mac OS X. Xcode includes the Apple integrated development environment (IDE) for Mac OS X plus a variety of other applications and command-line tools. The IDE consists of the Xcode application, Interface Builder, and a set of integrated compilers, debuggers, and build tools. Together with the IDE, the development tools in Xcode provide all of the facilities you need to build a program for Mac OS X, whether it’s an application, kernel extension, or command-line tool. If you are writing a Carbon or Cocoa application, you can do most of your work using only the Xcode application and Interface Builder. This chapter provides a brief introduction to the Apple IDE and explains how it is used in the development of a Carbon or Cocoa application.

Certain tools in Xcode are especially useful at specific stages in development. See Chapter 4, “Development Process”, for a more general discussion of the development process as it applies to Carbon and Cocoa applications. Some tools in Xcode are included to support specific types of projects, such as scripts, Java programs, or kernel extensions. See Chapter 5, “Notes for Specific Project Types”, for more information on projects other than Carbon and Cocoa applications. Appendix A, “Tool Descriptions”, provides a complete listing of the development tools included with Xcode.

Features of the Xcode Application

The Xcode application contains features to support a wide variety of development projects; these features include:

■ An editor for source code ■ A file browser and organizer for the project files ■ A documentation viewer, offering direct linking to API documentation for symbols in your code and to man pages for tools ■ A class browser ■ Automatic creation of build files for compiling and linking your code ■ Access through the GUI or through a command line to a variety of standard, open-source compilers ■ Source-level debugging through the Xcode application GUI

■ Direct command-line access to GDB, the GNU debugger The Xcode application provides a powerful user interface to many industry-standard and open-source tools, including:

■ The GCC compiler

■ The javac compiler

■ The jikes compiler ■ The GDB debugger ■ Code completion You can create executables using C, C++, Objective-C, Java, or assembly language. The Xcode application contains templates for creating applications, frameworks, libraries, plug-ins, Java applications and applets, and command-line tools.

Creating a Project

Xcode supports development of programs written in C, C++, Objective-C, Objective-C++, and Java. It has many templates for creating new projects, including ones tailored for using the Carbon or Cocoa API suites. A project contains all the files needed to build one or more related products and maintains the relationships between them. A target contains instructions on building a product from specific files. The Xcode application automatically provides most of the default targets you need, but you may need to modify some for your project.

The Xcode application has explicit support for a large number of different types of projects. Depending on the project type you pick, the Xcode application creates files you need, including in each source-code file a few lines of code to include specific header files and to help you organize the contents of the file.

The type of project you create determines what files the Xcode application generates and their content. Here is a list of the application project types supported by the Xcode application at present:

■ Carbon application; a Carbon application that uses Resource Manager (.r or .rsrc) files for resources ■ Carbon application (nib based); a Carbon application that uses nib files for resources (a nib file is a resource file created by Interface Builder) ■ Cocoa application; a Cocoa application written in Objective-C ■ Cocoa document-based application; a Cocoa application, written in Objective-C, that supports documents ■ Cocoa-Java application; a Cocoa application written in Java ■ Cocoa-Java document-based application; a Cocoa application, written in Java, that supports documents

■ AppleScript application; a Cocoa application written in AppleScript (an AppleScript Studio application is a special kind of Cocoa application that can be written in AppleScript and Objective-C) ■ AppleScript document-based application; a Cocoa application, written in AppleScript, that supports documents ■ AppleScript droplet; a Cocoa application, written in AppleScript, that processes files dropped on it In addition to applications, you can create several other types of projects:

■ Bundles, including Carbon, Core Foundation, and Cocoa bundles. A bundle is a file system directory that stores executable code and the software resources related to that code; in the Finder it looks like a file. Although applications and Frameworks are types of bundles, the Bundle projects in the Xcode application are for loadable bundles. Loadable bundles are used for code that can be loaded by an application when it is needed, such as application plug-ins.

■ Frameworks, including Carbon and Cocoa frameworks. In this context, a framework is a type of bundle that packages shared resources, such as a dynamic shared library or reference documentation. ■ Java, including applets, applications, and tools. ■ Kernel extensions, including KEXTs and drivers. ■ Plug-ins for standard Apple applications, including Interface Builder, preference panes, the Screen Effects pane in System Preferences, and Sherlock. ■ Command-line tools—utilities without graphical UIs—including C++ tools, C tools, and tools that link against the Core Foundation, Core Services, and Foundation libraries.

Writing an Application

This section gives brief descriptions of how you use the Xcode application to write Carbon and Cocoa applications. See Chapter 4, “Development Process”, for a more general discussion of the development process for such applications, and see Chapter 5, “Notes for Specific Project Types”, for information about other types of projects.

Carbon-Based Applications

You can create a Carbon application that uses Resource Manager (.r or .rsrc) files for resources or one that uses Interface Builder resource files (called nib files because they have an extension of .nib). (Note that, in Mac OS X, resources are put in the data fork of a separate file rather than in the resource fork of the application file.) If you are working with legacy code that already uses the Resource Manager, you might want to use .r or .rsrc files. However, because Interface Builder provides an easy-to-use graphical method for designing and implementing a GUI, you can save a lot of time by using nib files for your resources.

If you select Carbon Application (Nib Based) from the Xcode application’s New Project Assistant and name the project CarbonSample, then the Xcode application creates these files:

■ CarbonSample_Prefix.h

■ main.c

■ Main.nib

■ InfoPlist.strings

■ CarbonSample.pbproj

■ Several build files

Here is an example of the start of a main.c file:

#include

int main(int argc, char* argv[]) { IBNibRef nibRef; WindowRef window;

OSStatuserr;

// Create a nib reference passing the name of the nib file // (without the .nib extension) // CreateNibReference only searches into the application bundle. err = CreateNibReference(CFSTR("main"), &nibRef); require_noerr( err, CantGetNibRef ); ...

This file uses calls to the Carbon API to interface with the nib file (Main.nib) that contains the resources for the document window and the main menu. The code includes a call to the event loop function RunApplicationEventLoop; you have to add your own event handlers as appropriate for your application.

To fill in the nib file with details about the window controls and menu items, and to link those controls with the appropriate controller code, you use Interface Builder, described in “Using Interface Builder to Add a UI to a Program” (page 30).

Cocoa-Based Applications

If you select Cocoa Document-based Application from the Xcode application’s New Project Assistant and name the project CocoaSample, then the Xcode application creates these files:

■ MyDocument.h

■ MyDocument.m

■ CocoaSample_Prefix.h

■ main.m

■ credits.rtf

■ MainMenu.nib

■ MyDocument.nib

■ InfoPlist.strings

■ CocoaSample.pbproj

■ Several build files

As created, the main.m file contains the following code:

#import int main(int argc, const char *argv[]) { return NSApplicationMain(argc, argv); }

The file MyDocument.m contains the stubs for the application’s main document window. For example, the code might begin like this:

#import "MyDocument.h"

@implementation MyDocument

- (id)init { self = [super init]; if (self) {

// Add your subclass-specific initialization here. // If an error occurs here, send a [self release] message and // return nil.

} return self; }

- (NSString *)windowNibName { // Override returning the nib file name of the document // If you need to use a subclass of NSWindowController or if your // document supports multiple NSWindowControllers, you should remove

//this method and override -makeWindowControllers instead. return @"MyDocument"; } ...

As you can see, this file includes stubs for class definitions that you need and some indication of what code you need to provide. You can use this file to contain the code that handles the window controls, plus code to write to and read from your document. The descriptions of the window and window controls themselves are contained in the window resource file, MyDocument.nib. The resource file for the application’s main menu is MainMenu.nib. the Xcode application creates these files for you as well. To fill them in with details about the window controls and menu items, and to link those controls with the appropriate controller code, you use Interface Builder, described in “Using Interface Builder to Add a UI to a Program” (page 30).

Using Interface Builder to Add a UI to a Program

Interface Builder is the Xcode application for creating graphical user interfaces (GUIs) for Mac OS X applications. Interface Builder provides a graphical interface that lets you lay out interface objects (including windows, controls, menus, and so on), resize them, set their attributes, and make connections to other objects and to source code.

The resulting information is stored in user interface resources, called nibs, which in turn are stored in nib files that become part of your application. (The “ib” in “nib” stands for Interface Builder. The “n” is a legacy from an earlier version of the product.) When the application is opened, it creates an interface containing the windows, buttons, and other user interface objects specified in its nib files.

Although you can use Interface Builder to create a new nib file, it is much easier to use a nib file created for you by the Xcode application, as described in “Carbon-Based Applications” (page 27) and “Cocoa-Based Applications” (page 28). Double-click the nib file in the Xcode application to open Interface Builder and display the contents of the file.

Figure 3-1 shows the Interface Builder windows for a new Carbon project. You can drag controls, text fields of various sorts, and various views from the Palette window to the document window. You can also drag new windows from the Carbon-Windows palette to the desktop. For each window and control you create, you need to write controller and handler code.

Figure 3-1 Interface Builder windows for a new Carbon project

Figure 3-2 shows the Interface Builder windows that open when you double-click the nib file in a new document-based Cocoa application project. The windows are similar to those for a Carbon project, but the window for the main menu is missing, because it is in a separate nib file for a Cocoa application. In addition, the controls and fields in the Cocoa Palette window are somewhat

different from those in the Carbon Palette window, reflecting the difference between the controls and views offered by the Carbon API and those offered by the Cocoa Application Kit framework. The Cocoa Windows palette, for example, provides drawers and palettes in addition to standard windows.

Figure 3-2 Interface Builder windows for a new Cocoa project

As for a Carbon application, you can drag controls and views from the Palette window to the document window and you can drag new windows from the Cocoa-Windows palette to the desktop. For each window and control you create, you need to write controller and handler code. For a Cocoa application, you can use Interface Builder’s graphical interface to connect the control or window to the appropriate controller or handler.

Development Process

This chapter discusses the Xcode development tools in the context of the development process ( Figure 4-1). Although there are similarities among all project types, this chapter concentrates on writing Carbon and Cocoa applications; that is, programs that have a graphical user interface and that are written using the Carbon or Cocoa development environments. See Chapter 5, “Notes for Specific Project Types”, for tools used with other project types.

The primary program used for most Mac OS X software development is the Apple IDE application. For application development, you will probably use Interface Builder as well. These applications are referred to but not described in this chapter. See Chapter 3, “The Apple Integrated Development Environment”, for more detailed descriptions of the Apple IDE application and Interface Builder.

Figure 4-1 The software development process

Decide on program architecture

Design program

Write source code

Version control

Build

Test

Good Debug Reneosuoguhrc?e and Found tune

Package

Distribute

Designing an Application

The earliest planning stages of the creation of an application are conceptual; you decide what the problem is that you are trying to solve and think about the best programmatic approach and the best interface design. In terms of Mac OS X development and development tools, the decisions you make now will determine how you approach the entire project. The first practical decision, and one that will affect the entire software architecture, is whether you will use a procedural or an object-oriented approach. See “What to Read Next” (page 18) for a discussion of the factors that affect whether you want to use Cocoa, Carbon, or another development environment for your application.

If you are porting or updating an existing application, the architecture is already set. If you are planning a new application, you have the opportunity to design it in a way that makes updating it easier and that makes it easier to take advantage of new hardware architectures as they are developed. In this regard it is usually best to separate the code that implements the GUI from the code that performs the actual work of the application as much as possible. One common approach that works well with object-oriented applications, but that can be applied to procedural applications as well, is called the Model-View-Controller (MVC) design pattern. In this architecture, the code is divided into three functional areas (or three types of objects, for object-oriented code): the model code deals with the data storage and manipulation performed by the program, the view code deals with the user interface, and the controller code ties the data model to the user’s view of the data. The MVC architecture is discussed in more detail in the programming topic Application Architecture in the Cocoa Program Design Documentation area.

If you are updating a well-factored application that follows the MVC design pattern or some similar architecture, you can replace the UI without affecting the data model. If you are porting a well-factored UNIX or Windows application, you can consider using Cocoa for the UI and having it talk to your existing data-model code. If your existing code is not well factored, you might find that Carbon provides individual functions that can be substituted one-to-one for functions in the Windows or UNIX API you are currently using.

Regardless of whether you decide to use Carbon, Cocoa, or a combination of the two environments, you can use the Xcode application to write and compile the code and to build the application. When you use the Xcode application to create your project, it creates a set of files that will help you get started with coding, as discussed in “Creating a Project” (page 26).

Designing a User Interface

Once you have decided on the development environment and architecture for your application, you need to begin to design the user interface. If you are designing an application and using Cocoa for the user interface, or if you want to use Carbon nib files rather than Resource Manager resources for your user interface, you can use Interface Builder to create the user interface.

When you use the Xcode application to create a project with a graphical user interface, the Xcode application includes one or more nib files in the project. The nib files contain the resources that describe the various user interface elements, such as text fields, controls, and menus. When you double-click a nib file in the Xcode application, the Interface Builder application opens, displaying the current contents of the nib file, as described in “Using Interface Builder to Add a UI to a Program” (page 30). You can then use Interface Builder to design the user interface for your application.

Interface Builder automatically provides you with elements that conform to the Mac OS X Aqua user interface standards. To make sure that your entire user interface conforms to Apple standards (and therefore meets your users’ expectations), read Aqua Human Interface Guidelines in the User Experience Documentation area.

Creating Source Code

Having designed your program and user interface, you need to implement your design. The Xcode application is the core application of the Xcode development tools. The Xcode application has many features to facilitate your job, including a full-featured code editor, a code completion feature, direct linking to function, class, and method descriptions as well as to man pages for tools, an automated build system, and support for CVS and Perforce version control. You can write code in C, C++, Objective-C, or Java. You can include modules written in different languages in the same project, and you can even use a mixture of C, C++, and Objective-C in the same source file. Note, however, that calls to the Carbon API must be in C, and calls to the Cocoa API must be in Objective-C or Java. The Xcode application works closely with Interface Builder when you are creating an application that has a graphical user interface.

Because the Xcode application and Interface Builder are written and maintained by Apple, you can always be sure that they will support the latest version of the Macintosh operating system and will work with Apple’s latest API libraries and object frameworks. The Xcode application is described in more detail in “Features of the Xcode Application” (page 25). See “Using Interface Builder to Add a UI to a Program” (page 30) for more information about Interface Builder.

If you are currently using Code Warrior and would like to convert your project to use Xcode, see the programming topic Moving Projects from CodeWarrior to Xcode.

Although the Xcode application and Interface Builder are the primary applications for writing source code, there are a variety of other tools you can use for specific tasks during this stage of the development process. Some of the most useful are described in the rest of this section.

Localization

If your application is targeted for audiences in more than one country, you might want to translate the text strings in your GUI into other languages. You can use the AppleGlot application to help in this effort. AppleGlot can extract localizable information from Mac OS X software into a text file for translation. AppleGlot then reinserts these strings into the application. AppleGlot also supports incremental localization; once software has been localized, subsequent use of AppleGlot extracts only the new or changed items in the file that potentially require localization. AppleGlot supports Cocoa and Carbon applications, bundled applications, and shared libraries or frameworks. It works with nib files, Resource Manager .rsrc files, and .string files in XML format or an AppleGlot-defined key-value format. AppleGlot is available from ftp://ftp.apple.com/developer/Tool_Chest/Localization_Tools/AppleGlot/AppleGlot_3.1.dmg.bin.

The genstrings command-line tool takes the strings from C source code (NSLocalizedString..., CFCopyLocalized String... functions) and generates string table files (*.strings). It can also work with Bundle.localizedString... methods in Java.

The DeRez command-line tool decompiles the resource fork of a resource file according to the type declarations in the type declaration files you specify. You can use this utility to find strings for localization purposes, for example. DeRez works with Resource Manager resource files, not with nib files (which do not have a resource fork).

The Rez command-line tool compiles the resource fork of a file according to the textual description contained in the resource description files. You can use Rez to recompile the resource files you decompiled with DeRez after you have localized the strings.

Documenting Code

If you are exporting an API, you can use HeaderDoc tags to structure the comments in your C, C++, and Objective-C header files and then run the headerdoc2HTML script to generate HTML documentation. The HeaderDoc tags and scripts are described in /Developer/Documentation/DeveloperTools/HeaderDoc/.

Help

The Apple Help Viewer displays HTML help files for your application. The Apple Help Viewer uses the Sherlock search engine to provide fast, full-text searching of Apple Help files. Use the Apple Help Indexing Tool to create a search index for a help file. Instructions for creating Apple Help and for using the indexing tool are in Providing User Assistance With Apple Help in User Experience Documentation).

Property Lists

A property list, or .plist file, is a data representation used by Cocoa and Core Foundation as a convenient way to store, organize, and access standard object types. Property lists are useful when you need to store small amounts of persistent data. You can use the Property List Editor application to write, read, and edit the contents of a property list. The plutil command-line tool can check the syntax of a property list or convert a property list from one format to another (XML or binary).

If you do use property lists, the .plist files must be bundled with other application files when you create your installation package. Once your program is built and run, it can access the information in the property list by using special routines that read the property list and convert the data represented in it to the appropriate types.

Icons

Many applications require the design of one or more custom icons. There are a couple of programs that are useful for this purpose. The IconComposer application creates .icns files appropriate for use as application and document icons. You can import files, or drag and drop images to specify the various data and mask components of the icon. The icns Browser application displays the contents of .icns files.

Graphics

OpenGL is an open, cross-platform three-dimensional (3D) graphics standard that supports the abstraction of current and future hardware accelerators. OpenGL Shader Builder is an application that provides real-time entry, syntax checking, debugging, and analysis of vertex/fragment programs. It allows exporting of your creation to a sample GLUT application, which performs all necessary OpenGL setup, giving you a foundation to continue your application development. For more information about OpenGL, see OpenGL for Mac OS in the Graphics & Imaging Documentation area.

Source-Code Utilities

There are many command-line tools you can use while implementing your application. Here are some of them:

■ ifnames scans C source files and writes out a sorted list of all the identifiers that appear in #if, #elif, #ifdef, and #ifndef directives.

■ indent formats C source code.

■ mkstr extracts error messages from C source code, places them in an error message file, and replaces the error message in the source code with a pointer to the error message file.

■ nmedit changes global symbols in object code to static symbols. You can provide an input file that specifies which global symbols should remain global. The resulting object can still be used with the debugger.

■ tops performs universal search and replace operations on text strings in source files.

■ unifdef removes #ifdef, #ifndef, #else, and #endif lines from code as specified in the input options. See Chapter 5, “Notes for Specific Project Types”, for additional tools useful for projects other than Cocoa and Carbon applications.

Version Control

The Xcode application works with two open-source version control systems: Concurrent Versions System (CVS) and Perforce. To use Xcode for source-code control, your project’s files must already be part of a CVS or Perforce repository and checked out for editing. You select which version control system you wish to use, and the Xcode application sets itself up automatically. Documentation on CVS is located at /Developer/Documentation/DeveloperTools/cvs/cvs_toc.html. Documentation on Perforce is located at http://www.perforce.com/perforce/technical.html.

Debugging and Tuning

In most large application projects, debugging and tuning the code proceeds in parallel with implementation. Xcode includes a source-level debugger that provides a graphical user interface to the GNU debugger, GDB. GDB is a command-line debugger for C, Objective-C, C++, and Objective-C++ code. For more information on using GDB, see Debugging With GDB in the Tools Documentation area. (http://www.gnu.org/manual/gdb-4.17/html_mono/gdb.html) and the GDB Quick Reference (/Developer/Documentation/DeveloperTools/gdb/refcard.pdf).

In order to enhance your users’ perception of your application, you should minimize the application’s launch time, execution time, and memory footprint. The tools discussed in this section help you achieve those goals. Performance tuning is discussed in detail in a series of programming topics located in the Performance Documentation area of the ADC website.

The Xcode application lets you step through your code line by line, set and modify breakpoints and watchpoints, view variables, stack frames, and threads, and access GDB directly through a command line. If you wish, you can also use the gdb command from the Terminal.

In addition to the Xcode application and GDB, Xcode includes a number of applications and tools that you might find useful in debugging your program, as discussed in the rest of this section.

Memory Use

A major consideration in debugging code is ensuring that there are no memory leaks. In addition, when tuning your code to improve its efficiency and performance, you need to know how often and where memory is allocated and deallocated and how much memory is used. You can use the MallocDebug application to measure and analyze all allocated memory in an application or to measure the memory allocated since a given time. MallocDebug also detects memory leaks. Another very useful utility is ObjectAlloc. ObjectAlloc is an application that allows you to observe memory allocation and deallocation activity in an application, almost in real time. It also keeps a history of memory allocations, so you can scroll backwards and forwards in time. This process can help identify some types of allocation patterns.

If you want to use a command-line tool to report on memory use, the malloc_history command inspects a given process and lists the malloc allocations performed by it. This tool relies on information provided by the standard malloc library when debugging options have been turned on. If you specify an address, malloc_history lists the allocations and deallocations that have manipulated a buffer at that address. For each allocation, a stack trace describing who called malloc or free is listed.

Efficiency of Execution

To make your application run as efficiently as possible, you need to know which routines are being executed, and in which routines your program is spending most of its time. You can then optimize those routines, or change your program flow so that the routines are not called as often.

Xcode includes a framework and a set of tools built on that framework, called the Computer Hardware Understanding Development tools, or CHUD tools. These tools are designed for monitoring the performance of Mac OS X applications. You can use the CHUD framework to develop your own performance tools; see Computer Hardware Understanding Development Tools 2.0: Reference Guide for Mac OS X. The CHUD toolkit, including all documentation, can be downloaded from ftp://ftp.apple.com/developer /Tool_Chest/Testing_-_Debugging/Performance_tools/.

The Sampler application is a utility you can use to help understand an application’s running behavior. Sampler can identify the routines in which the program spends most time executing. It can also summarize why allocation routines, system calls, or arbitrary functions were called. The sample command-line tool serves a similar purpose. This tool gathers data about the running behavior of a process by stopping the process at user-defined intervals, recording the current function being executed by the process, and checking the stack to find how the current function was called. It then lets the application continue. At the end of a sampling session, sample produces a report showing which functions were executing during the session.

MONster is a CHUD tool for gathering information about program execution. The MONster application collects data from processor and memory-controller performance counters and presents it in tabular form. It can collect data system wide, or from a specific program running on the system. Similarly, the top command-line tool displays an ongoing sample of system use statistics. It can operate in various modes, but by default shows CPU and memory use for each process in the system.

If your application is multi threaded (and all Mac OS X applications should be thread-safe), you can use the Thread Viewer application to graphically display activity across a range of threads. It provides timeline color-coded views of activity on each thread. By clicking a timeline, you can see a sample backtrace of activity at that time.

For information about both general program behavior and thread behavior, you can use the Shark application, one of the CHUD tools. Shark profiles the system to see how time is being spent. It can work at the system, task, or thread level and can correlate performance counter events with source code. Shark’s histogram view can be used to observe scheduling and other time-dependent behavior. It can produce profiles of hardware and software performance events such as cache misses, virtual memory activity, and instruction dependency stalls.

Graphics

There are some development tools that you can use to tune the performance of the graphics in your application.

OpenGL Info is an application that displays extensive information about the OpenGL environment. OpenGL Profiler is an application that creates a runtime profile of an OpenGL-based application. The profile contains OpenGL function-call timing information, a listing of all the OpenGL function calls made by your application, and all the OpenGL-related data needed to replay your profiling session. For more information about OpenGL, see OpenGL for Mac OS in the Graphics & Imaging Documentation area.

Pixie is a magnifying glass utility for Mac OS X. Pixie is useful for doing pixel-perfect layout, checking the correctness of graphics and the user interface, and getting magnified screen shots.

Quartz Debug is a debugging and tuning utility for the Quartz graphics system. By watching the rectangles that Quartz Debug displays, you can determine how often and where your application redraws itself. It can display a text window identifying the owner of each window and the memory the window occupies. This information is useful for understanding the impact of buffered windows on your application’s memory footprint. Quartz Debug is documented in the programming topic Drawing Performance in the Performance Documentation area.

Packaging

The last step in application development is bundling the various object files, frameworks, and data files into a package that can be installed by the user. The Xcode application automatically packages all of the files that it knows are part of the application. Whenever possible, you should package your application for drag-and-drop installation. When necessary, however, as when you want to let the user install a new version of an application over an old one without replacing all the files, you can use the PackageMaker application to create an installation package. Installer, located in /Applications/Utilities, is the native installer for Mac OS X. When the user double-clicks

the package, the Installer launches and installs the files you packaged. You can use PackageMaker to package files or to assemble individual packages into a single package. PackageMaker and Installer are documented in the programming topic Software Distribution.

You can run PackageMaker from the command line or from a shell script. For information, enter this command on the command line:

/Developer/Applications/PackageMaker.app/Contents/MacOS/PackageMaker

Be sure to use full paths in all command-line arguments. There is also a command-line version of Installer, named installer. See the installer man page for details.

To create a multi-architecture (“fat”) executable file, use the lipo command-line tool. In addition to creating fat files, this tool can list the architectures in a fat file, create a single-architecture file from a fat file, or make a new fat file with a subset of the architectures in the original fat file.

There are several command-line tools useful for copying and moving files, creating directories and bundles, and creating libraries.

Copying and Moving Files

The Finder and the commonly used cp and mv command-line tools can copy or move files, but only in the most simple, straightforward fashion. If you need to change a file’s attributes or manipulate the files in a more complex way, you can use the command-line tools listed here:

■ GetFileInfo gets the file attributes of files in an HFS+ directory.

■ SetFile sets the attributes of files in an HFS+ directory.

■ install copies files to a target file or directory. Unlike the cp or mv commands, the install command lets you specify the new copy’s owner, group ID, file flags, and mode.

■ CpMac copies a file or a directory, including subdirectories, preserving metadata and forks.

■ MvMac moves files, preserving metadata and forks.

■ pbxcp copies files. It can skip specific files; strip out debug symbols; preserve metadata, user IDs and other information; and resolve the first level of symbolic link source entries.

■ mkbom creates a bill of materials for a directory.

Libraries

Your application bundle might include one or more static or dynamic libraries, or your application might link dynamically to an external library. You can use the Xcode application to create libraries. In addition to the Xcode application, you can use the following command-line tools when you are creating libraries:

■ libtool takes object files and creates dynamically linked libraries or archive (statically linked) libraries, according to the options selected.

■ ranlib adds to or updates the table of contents of an archive library. The ranlib tool must be run on the system every time a new library is installed.

■ lorder determines interdependencies in a list of object files. The output is normally used to determine the optimum ordering of the object modules when a library is created so that all references can be resolved in a single pass of the loader.

Notes for Specific Project Types

There are many types of programming projects you can undertake in addition to Carbon and Cocoa applications; for example, you might want to write a Java application, kernel extension, or command-line tool. The development process differs somewhat for different project types, and some developer tools are used only, or primarily, for certain types of projects. Whereas Chapter 4, “Development Process”, describes the development process and tools used for Carbon and Cocoa applications, this chapter describes what is different for other types of projects.

Scripting

Scripts can range from background routines executed automatically with no user interface to applications complete with GUIs. You can use Script Editor (located in /Applications/AppleScript) to compile and execute standard scripts, which have limited user interface capabilities. You can use AppleScript Studio to automate one Mac OS X program or link several together in a complete solution, and provide a standard Aqua interface in the bargain. If you are using AppleScript Studio, you can open a project in the Xcode application to write your script. For other scripting languages, such as Perl or Python, you can use any text editor. Shell scripts, as well, are standard text files that are executed by the Terminal application.

Script development follows the same general outline as application development, except that design and implementation of a user interface is optional. Debugging a script does not require the same tools as debugging a Carbon or Cocoa application, as you can assume that the individual programs called by the script have already been debugged. Because the script does not directly allocate memory or create threads, you don’t have to use a low-level debugger such as GDB.

Mac OS X comes with implementations of AppleScript, Perl, and Python, and you can write shell scripts that use any of the command-line tools mentioned in this document (as well as any of the standard shell commands).

You can write an AppleScript application that has a standard Aqua user interface by using Xcode and AppleScript Studio. For information on AppleScript and AppleScript Studio, see AppleScript Language Guide for AppleScript 1.3.7, Building Applications With AppleScript Studio, and AppleScript Studio Terminology Reference, all available on the AppleScript Documentation page on the ADC web site.

The osacompile and osascript commands are tools you can run to compile and execute scripts in a shell. The osacompile command compiles the specified files, or standard input, into a single script. Input files may be plain text or other compiled scripts. The osacompile command works

with AppleScript and with any other scripting language that conforms to the Open Scripting Architecture (OSA). The osascript command executes a script file, which may be plain text or a compiled script. The osascript command works with AppleScript and with any other OSA scripting language.

The perl command executes scripts written in the Practical Extraction and Report Language (Perl). The man page for this command introduces the language and gives a list of other man pages that fully document it. The perlcc command compiles Perl scripts. The splain command forces verbose warning diagnostics by the Perl compiler and interpreter.

The python command interprets programs written in the Python language, an interactive, object-oriented language. Use the pydoc command to read documentation on python modules.

Creating Frameworks

In Mac OS X, a framework is defined as a type of bundle that packages shared resources, such as a dynamic shared library or reference documentation. The code in a dynamic shared library can be shared by multiple, concurrently running programs. You can include more than one version of the code in a single framework—to support different localizations, for example, or for backward compatibility with older data files. Because the code is dynamically linked, it is not loaded until it is needed, giving your program a smaller memory footprint. By putting your executable code in a framework, you can fix bugs, test the fixes, and distribute the new code without the need to rebuild or reinstall the programs that use the libraries. Framework bundle directories do not have the bundle bit set; that is, they do not appear to the user to be a single file. Therefore, you can distribute a library as a framework and developers who want to use that library can browse the header files.

On disk, a framework in Mac OS X is a directory with an extension of .framework. When you open the directory, the first level of its contents looks something like this:

GreatSoftware.framework/GreatSoftwareHeaders/PrivateHeaders/Resources/Versions/

The Versions subdirectory can contain multiple major versions of dynamic shared libraries (along with their resources). The other items in the contents (GreatSoftware, Headers, PrivateHeaders, and Resources) are all symbolic links to subdirectories of the current major version of the framework within the Versions directory. The GreatSoftware item in this example points to the dynamic shared library. Headers and PrivateHeaders point to the directories containing the framework’s public and private header files. The framework’s resources—items such as interface definition files, images, sounds, and localized strings—go in the Resources subdirectory.

A new major version of a framework is typically required when the dynamic shared library is not compatible with programs linked with prior versions of the library. Because older versions of the applications can still run with an older version of the library, the older version is included in the framework bundle. Each version of the framework is contained in a subdirectory of the Versions directory. Different major versions are named, by convention, with letters of the alphabet.

In addition to the major (or incompatible) versions, frameworks can have minor (or compatible) versions. The minor versioning scheme allows for bug fixes and other minor enhancements without requiring a new version of the applications that use the framework. A major version of a framework can incorporate a number of minor versions.

Frameworks provided by Apple, such as the Application Kit or the QuickTime framework, are called system frameworks. The shared library code in system frameworks is intended for use by all applications on a system. System frameworks are installed in /System/Library/Frameworks. Other frameworks can go in a number of different file-system locations:

■ If they are to be used only by a single user, they should be installed in the Library/Frameworks subdirectory of the user’s home directory. ■ If they are to be used by all users of a particular Mac OS X system, they should be installed in /Library/Frameworks. ■ If they are to be used across a local area network, they should be installed in /Network/Library/Frameworks. A framework is similar to any other Mac OS X code, except that it is built in a way that allows it to be embedded in other projects. You can use Xcode to create a framework that links against either Carbon or Cocoa libraries.

Standard Apple Plug-in Projects

A plug-in is a special type of loadable bundle that is used by a plug-in–enabled application to dynamically extend or alter the application. Mac OS X includes several applications that use this mechanism, and you can write plug-ins to extend the capabilities of those applications. These applications include:

■ Interface Builder, for which you can provide a new palette of controls with an IBPalette plug-in. ■ System Preferences, for which you can provide a new preference pane. You can also load a preference pane for use from your own application. See Preference Panes in the User Experience Documentation area for details. ■ The Screen Effects pane in System Preferences, for which you can provide a new screen saver. See the documentation for the ScreenSaverDefaults and ScreenSaverView classes for more information.

■ Sherlock, for which you can provide a new channel. See Sherlock Channels in the Apple Applications Documentation area for details. The Xcode application provides a separate project type for each of these types of plug-ins in the New Project Assistant.

Tool Projects

Tools, in the context of this document, are programs without a GUI. The Xcode application provides project types for the following tool projects:

■ C++ tool ■ Core Foundation tool

■ Core Services tool ■ Foundation tool ■ Standard tool

Each of these projects includes a template for man page documentation using the –mdoc macro package and has #include directives for the header files and frameworks appropriate to that project type. The –mdoc package is a set of macros used to format man pages. For details, see the mdoc man page.

Other than the fact that a tool has no GUI, it is developed in a manner similar to an application. You can use Xcode to write and debug your tool. In general, because a tool consists of a single executable file, creating an application bundle should not be necessary.

Java

If you want to do pure Java development—that is, to write programs that run in the Java virtual machine (VM) environment, then you can create a Java project in the Xcode application and can even use Swing to implement an Aqua user interface for your application. The Xcode application can use either the Javac or the Jikes compiler. See Project Builder for Java in the Java Documentation area for more information on the use of Xcode to write Java tools and applications.

If you want to be able to call your Java routines from a Mac OS X–native application, you can use the javah command to generate C header and source files from your Java classes. The generated header and source files are used by C programs to reference instance variables of a Java object so that you can call Java code from inside your Mac OS X native application. To create documentation of your Java code, you can use the javadoc command, which parses the declarations and documentation comments in a set of Java source files and produces HTML pages describing the public and protected classes, inner classes, interfaces, constructors, methods, and fields.

Because there are Java APIs for the Application Kit and Foundation frameworks, you can use Java as your programming language for Cocoa development. However, not every framework for Mac OS X has Java headers. Objective-C, on the other hand, is the native language for Cocoa and is similar to Java in many ways. It is usually fairly easy for an experienced Java programmer to learn Objective-C.

Java Remote Interface

To create a Java routine that can be invoked from a virtual machine that is not local, you must implement the interface java.rmi.Remote. To do so, you can use the rmic command to generate stub and skeleton class files for remote objects from the names of compiled Java classes that contain remote object implementations. The rmiregistry command creates and starts a remote object registry. A remote object registry is a naming service that makes it possible for clients on the host to look up remote objects and invoke remote methods.

Debugging Java Applications

Xcode provides a full-featured Java debugger that you access through the Xcode application’s user interface. You can use it to set and manipulate breakpoints, step through code, examine the call stack, and switch among multiple threads.

If you need to debug a remote Java application, you can use the jdb command, which provides inspection and debugging of a local or remote Java virtual machine.

Packaging Java Applications

If you are using Java to write applications for the web, you can use the jar command to combine and compress multiple files into a single Java archive (JAR) file so they can be downloaded by a Java agent (such as a browser) in a single HTTP transaction. The jarsigner command lets you sign JAR files and verify the signatures and integrity of signed JAR files, and the extcheck command checks a specified JAR file for title and version conflicts with any extensions installed in the Java Developer Kit software.

Jar Bundler is an application that allows you to package your Java program’s files and resources into a single double-clickable application bundle. Jar Bundler lets you modify certain properties so your Java application behaves as a better Mac OS X citizen and lets you specify arguments sent to the Java virtual machine when the application starts up.

Kernel Extensions

To handle enhancements to the kernel, Mac OS X can dynamically load pieces of code, referred to as kernel extensions (KEXTs), that run in the kernel space. All kernel extensions are implemented as loadable bundles. Kernel extensions have names that end in .kext and contain a property list (plist) describing the KEXT’s contents and requirements. Additionally, a KEXT usually includes a module (KMOD) that contains the binary code that is actually loaded into the kernel and run. A KEXT can also contain additional resources such as icons for the Finder.

It is very hazardous and rarely necessary to add code to the kernel. Faulty kernel code can cause a kernel panic and even damage hardware (for example, by turning off the fan and allowing the circuits to overheat). Most features you need to implement, including many device drivers, can execute at higher levels of the operating system, outside the kernel. For more information about the architecture of the kernel and the characteristics of kernel code in general and KEXTs in particular, see Kernel Programming in the Darwin & Core OS Documentation area.

If you do need to write a KEXT, create a Generic Kernel Extension project in the Xcode application. You can use GDB for debugging the KEXT. Because a faulty KEXT can interfere with all the software on your computer, including the kernel, you have to set up a two-computer debugging environment. You then run GDB from the command line on the development computer while running the target computer in kernel debugging mode.

For tutorials on creating and debugging KEXTs with the Xcode application GDB, see the Darwin HOWTO documents page at http://www.opensource.apple.com/projects/documentation/howto/. For debugging outside of the Xcode application, you can use the Mac OS X built-in debugger, ddb. You must build the

kernel in debug mode in order to use this debugger. See Kernel Programming in the Darwin & Core OS Documentation area for details. For more information on debugging and GDB in general, see “Debugging and Tuning” (page 38). You can use the Property List Editor application to read and edit the contents of a property list.

Command-line tools useful for kernel extension development include the following:

■ kextload loads kernel extensions, validates them to make sure they can be loaded by other mechanisms, and generates symbol files for debugging them.

■ kextstat displays the status of any kernel extensions currently loaded in the kernel.

■ kextunload terminates and unregisters I/O Kit objects associated with a KEXT and unloads the code for the KEXT. For more information on the kernel environment and writing code that executes in the kernel, go to the Darwin & Core OS Documentation and Device Drivers & I/O Kit Documentation categories on the ADC website.

Networking Extensions

Mac OS X provides an extensible networking system. By implementing network kernel extensions (NKEs) you can add support for additional networking protocols as well as enhance the networking already provided. If you need to extend the networking capabilities of Mac OS X, read Network Kernel Extensions in the Device Drivers & I/O Kit Documentation area. In order to debug an NKE, you have to use the ddb debugger. This debugger requires you to build a debug version of the kernel, and to connect to the target computer over a serial line. For more information about ddb, see Kernel Programming in the Darwin & Core OS Documentation area.

I/O Kit Drivers

Device drivers are a special class of KEXTs. To write a device driver, create an I/O Kit Driver project in the Xcode application. The I/O Kit is a collection of system frameworks, libraries, tools, and other resources for creating device drivers in Mac OS X. It is based on an object-oriented programming model implemented in a restricted form of C++. For detailed information about the I/O Kit, see I/O Kit Fundamentals and Writing an I/O Kit Device Driver, both in the Device Drivers & I/O Kit Documentation area.

You can use the I/O Registry Explorer application (filename IORegistryExplorer) to examine the configuration of devices on your computer. I/O Registry Explorer provides a graphical representation of the I/O Registry tree. Documentation for I/O Registry Explorer is in I/O Kit Fundamentals in the Device Drivers & I/O Kit Documentation area. The ioreg tool is a command-line version of I/O Registry Explorer. The ioreg tool displays the tree in a Terminal window, allowing you to cut and paste sections of the tree.

To help find memory leaks in I/O Kit drivers, you can use the ioalloccount tool, which displays a summary of memory allocated by I/O Kit allocators listed by type (instance, container, and IOMalloc), and the ioclasscount tool, which shows the number of instances allocated for each specified class.

WebObjects

WebObjects 5.2 is a separate Apple product, not included in Xcode, used for rapid development of standards-based web services and Java server applications. You can use the Xcode application for WebObjects development; see Project Builder for WebObjects Developers in the WebObjects Documentation area for a WebObjects-specific supplement to the Xcode application documentation. You can also use Interface Builder to add an Aqua interface to your WebObjects application.

Among other tools, WebObjects includes the EOModeler application, which you can use to reverse-engineer existing databases and to design schemas for new databases.

See http://www.apple.com/webobjects for details on the WebObjects product and the WebObjects Documentation page on the ADC website for documentation.

Tool Descriptions

This appendix lists all the tools in Xcode, organized by use. For an alphabetical list of all tools, see the index.

Creating Source Code

Localization Tools

AppleGlot application A localization application for Mac OS X software. AppleGlot can extract localizable information from Mac OS X software into a text file for translation. AppleGlot then reinserts these strings into the application. AppleGlot also supports incremental localization; once software has been localized, subsequent use of AppleGlot extracts only the new or changed items in the file that potentially require localization. AppleGlot supports Cocoa and Carbon applications, bundled applications, and shared libraries or frameworks. It works with nib files, Resource Manager .rsrc files, and .string files in XML format or an AppleGlot-defined key-value format. AppleGlot is available from ftp://ftp.apple.com/developer/Tool_Chest/Localization_Tools/AppleGlot/AppleGlot_3.1.dmg.bin.

DeRez Decompiles the resource fork of a resource file according to the type declarations in the type declaration files you specify. You can use this utility to find strings for localization purposes, for example. DeRez works with Resource Manager resource files, not with nib files.

Rez Compiles the resource fork of a file according to the textual description contained in the resource description files. You can use Rez to recompile the resource files you decompiled with DeRez after you have localized the strings.

genstrings Takes the strings from C source code (NSLocalizedString..., CFCopyLocalizedString... functions) and generates string table files (.strings files). This tool can also work with Bundle.localizedString... methods in Java.

Documentation and Help Tools

Apple Help Indexing Tool application An application to create a search index for a help file. The Apple Help Viewer uses the Sherlock search engine to provide fast, full-text searching of Apple Help files. Instructions for creating Apple Help and for using the indexing tool are in Providing User Assistance With Apple Help (/Developer/Documentation/Carbon/pdf/AppleHelp.pdf/).

compileHelp Merges contextual help RTF snippets into one file. This tool is included to support legacy applications. New contextual help projects do not use this tool.

headerdoc2HTML Generates HTML documentation from structured commentary in C, C++, and Objective-C header files. The HeaderDoc tags and scripts are described in http://developer.apple.com/darwin/projects/headerdoc/.

pbhelpindexer Indexes documentation created with HeaderDoc so that the Xcode application can find the appropriate excerpt for a given symbol. The HeaderDoc tags and scripts are described in http://developer.apple.com/darwin/projects/headerdoc/

install-info Inserts menu entries from an Info file into the top-level dir file in the GNU Texinfo documentation system. It’s most often run as part of software installation or when constructing a dir file for all manuals on a system. See http://www.gnu.org/manual/texinfo/ for more information on the GNU Texinfo system.

Compilers, Linkers, Build Tools

as The Mac OS X Mach-O assembler.

ld Combines several Mach-O (Mach object) files into one by combining like sections in like segments from all the object files, resolving external references, and searching libraries. Mach-O is the native executable format in Mac OS X.

gcc The command-line interface to the GNU C compiler (GCC). Normally you invoke GCC through the Xcode application; however, you can execute it from a command line if you prefer.

make A symbolic link to gnumake, the GNU make program. Note that the Xcode application automatically creates and executes make files for you; however the command-line make tools are available if you wish to use them.

gnumake The GNU make program. bsdmake The BSD make program. jam An open-source build system initially released by Perforce, which provides the back-end for the Xcode application’s build system. It is rarely used directly from the command line. Documented on the Perforce website at http://www.perforce.com/jam/jam.html. mkdep Constructs a set of include file dependencies. You can use this command in a make file if you are constructing make files instead of using Xcode to build and compile your program. pbxbuild Builds a target contained in an Xcode project. This command is useful if you need to build a project on another computer that you can connect to with Telnet. The pbxbuild tool reads your project file and builds it just as if you had used the Build command from within the Xcode application. pbprojectdump Takes an Xcode project (.pbproj) file and outputs a more nested version of the project structure. Note that, due to how conflicts are reflected in the project file, pbprojectdump cannot work with project files that have CVS conflicts. pbutil Checks to make sure all the files on a disk are in a project, or lists all the groups and files in a project.

Library Utilities libtool Takes object files and creates dynamically linked libraries or archive (statically linked) libraries, according to the options selected. The libtool command calls the ld command. ranlib Adds to or updates the table of contents of an archive library. lorder Determines interdependencies in a list of object files. The output is normally used to determine the optimum ordering of the object modules when a library is created so that all references can be resolved in a single pass of the loader. redo_prebinding Updates the prebinding of an executable or dynamic library when one of the dependent dynamic libraries changes.

update_prebinding Updates prebinding information for libraries and executables when new files are added to the system.

Code Utilities

Property List Editor application An application that lets you read and edit the contents of a property list. A property list, or plist, is a data representation used by Cocoa and Core Foundation as a convenient way to store, organize, and access standard object types. Property lists are useful when you need to store small amounts of persistent data. If you do use property lists, the .plist files must be bundled with other application files when you create your installation package.

icns Browser application An application that displays the contents of .icns files. These files contain icon images at various sizes for use by the Finder and other applications.

IconComposer application An application that creates .icns files appropriate for use as application and document icons. You can import files, or drag and drop images to specify the various data and mask components of the icon.

OpenGL Shader Builder application An application that provides real-time entry, syntax checking, debugging, and analysis of vertex/fragment programs. It allows exporting of your creation to a sample GLUT application, which performs all necessary OpenGL setup, giving you a foundation to continue your application development. OpenGL is an open, cross-platform, three-dimensional (3D) graphics standard that supports the abstraction of current and future hardware accelerators. For more information about OpenGL, see OpenGL for Mac OS in the Graphics & Imaging Documentation area.

ResMerger Merges resources into resource files. When the Xcode application compiles Resource Manager resources, it sends them to a collector. After all Resource Manager resources have been compiled, the Xcode application calls ResMerger to put the resources in their final location.

RezWack Takes a compiled resource (.qtr) file and inserts it together with the data fork (.qtx or .exe file) into a Windows application (.exe) file. The resulting file is a Windows application that has the sort of resource fork that QuickTime understands. You can use the Rez tool to compile a resource source (.r) file. The RezWack tool is part of the QuickTime 3 Software Development Kit for Windows.

UnRezWack Reverses the effects of RezWack; that is, converts a single Windows executable file into separate data and resource files.

ifnames Scans C source files and writes out a sorted list of all the identifiers that appear in #if, #elif, #ifdef, and #ifndef directives. indent Formats C source code. mkstr Extracts error messages from C source code, places them in an error message file, and replaces the error message in the source code with a pointer to the error message file. nmedit Changes global symbols in object code to static symbols. You can provide an input file that specifies which global symbols should remain global. The resulting object can still be used with the debugger. pbxhmapdump Dumps to standard output the contents of the .hmap file created by pbxbuild or by the Xcode application. This file gives the full paths of all the header files in the project. plutil Can check the syntax of a property list or convert it from one format to another (XML or binary). printf Formats and prints character strings and C constants. fpr Reformats a Fortran file for printing by the UNIX line printer. fsplit Takes a Fortran multi routine source-code file and splits it into multiple files, one for each routine. tops Performs universal search and replace operations on text strings in source files. unifdef Removes #ifdef, #ifndef, #else, and #endif lines from code as specified in the input options.

Version Control

RCS

rcs Creates new RCS files or changes attributes of existing ones.

rcs2log Generates a change log from RCS files—which can possibly be located in a CVS repository—and sends the change log to standard output.

rcs-checkin Checks a file into a new RCS file and uses the file’s first line for the description.

ci Stores new revisions into RCS files. If the RCS file doesn’t exist, ci creates one.

co Retrieves a revision from an RCS file and stores it in the corresponding working file.

rcsclean Compares the working file to the latest revision (or a specified revision) in the corresponding RCS file and removes the working file if there is no difference.

rcsdiff Compares two revisions of an RCS file or the working file and one revision.

rcsmerge Merges the changes in two revisions of an RCS file into the corresponding working file.

CVS

agvtool Speeds up common versioning operations for Xcode projects that use the Apple-generic versioning system. It automatically embeds version information in the products produced by the Xcode application and performs certain CVS operations such as submitting the project with a new version number. The agvtool program has no man page; for documentation, enter agvtool help in the Terminal.

cvs-wrap Wraps a directory into a GZIP format tar file. This single file can be handled more easily by CVS than the original directory.

cvs-unwrap Extracts directories from a GZIP format tar file created by cvs-wrap.

Comparing Files

FileMerge application An application that compares two ASCII files or two directories. For a more accurate comparison, you can compare two files or directories to a common ancestor. After comparing, you can merge the files or directories.

diff Compares two files or the files in two directories

diff3 Compares three files.

diffpp Annotates the output of diff so that it can be printed with GNU enscript. This enables enscript to highlight the modified portions of the file.

diffstat Reads one or more files output by diff and displays a histogram of the insertions, deletions, and modifications per file.

sdiff Compares two files and displays the differences so you can decide how to resolve them interactively. It then writes the results out to a file. A command-line version of FileMerge.

merge Compares two files modified from the same original file and then combines all the changes into a single file. Merge warns you if both modified files have changes in the same lines.

patch Takes the output of diff and applies it to one or more copies of the original, unchanged file to create patched versions of the file.

Debugging and Tuning

General

gdb The GNU debugger. You can use it through the Xcode application or can invoke it directly from the command line.

defaults Lets you read, write, and delete Mac OS X user defaults. A Mac OS X application uses the defaults system to record user preferences and other information that must be

maintained when the application is not running. Not all these defaults are necessarily accessible through the application’s preferences.

Memory

MallocDebug application A utility application for understanding how an application uses memory. You can use MallocDebug to measure and analyze all allocated memory in an application or to measure the memory allocated since a given time. MallocDebug also detects memory leaks.

ObjectAlloc application An application that allows you to observe memory allocation and deallocation activity in an application, almost in real time. It also keeps a history of memory allocations, so you can scroll backwards and forwards in time. This process can help identify some types of allocation patterns.

CacheBasher application An application that measures memory hierarchy performance under a wide range of conditions.

heap Lists all the objects currently allocated on the heap of the current process. It also describes any Objective-C objects, listed by class.

leaks Examines a specified process for malloc-allocated buffers that are not referenced by the program.

malloc_history Inspects a given process and lists the malloc allocations performed by it. This tool relies on information provided by the standard malloc library when debugging options have been turned on. If you specify an address, malloc_history lists the allocations and deallocations that have manipulated a buffer at that address. For each allocation, a stack trace describing who called malloc or free is listed.

vm_stat Displays Mach virtual memory statistics.

vmmap Displays the virtual memory regions allocated in a specified process, helping you understand how memory is being used and the purpose of memory (text segment, data segment, and so on) at a given address.

Graphics

OpenGL Info application An application that displays extensive information about the OpenGL environment.

OpenGL Profiler application An application that creates a run-time profile of an OpenGL-based application. The profile contains OpenGL function-call timing information, a listing of all the OpenGL function calls your application made, and all the OpenGL-related data needed to replay your profiling session.

Pixie application A magnifying glass utility for Mac OS X. Pixie is useful for doing pixel-perfect layout, checking the correctness of graphics and user interface elements, and getting magnified screen shots.

Quartz Debug application A debugging utility for the Quartz graphics system. Quartz Debug is documented in the programming topic Drawing Performance in the Performance Documentation area.

Examining Code

PEFViewer application An application that lets you examine the contents of an executable that is in PEF format, which is used for Mac OS 9 code. error Analyzes error messages and can open a text editor to display the source of the error. The error tool is run with its input connected via a pipe to the output of the compiler or language processor generating the error messages. Note that the service provided by the error command is built into the Xcode application. c2ph Parses C code and outputs debugger information in the Stabs format, showing offsets of all the members of structures. For information on Stabs, see /Developer/Documentation/DeveloperTools/gdb/stabs/stabs_toc.html pstruct An alias to c2ph. cscope An interactive command-line tool that allows the user to browse through C source files for specified elements of code, such as functions, function calls, macros, variables, and preprocessor symbols.

ctag Makes a tags file for the ex line editor from specified C, Pascal, Fortran, YACC, lex, or lisp source files. A tags file lists the locations of symbols such as subroutines, typedefs, structs, enums, unions, and #defines.

nibtool Lets you print, update, and verify the contents of a nib file from the command line.

nm Displays the symbol tables of one or more object files, including the symbol type and value for each symbol.

otool Displays specified parts of object files or libraries.

pagestuff Displays information about the specified logical pages of a file conforming to the Mach-O executable format. For each specified page of code, pagestuff displays symbols (function and static data structure names).

strings Looks for ASCII strings in an object file or other binary file.

Performance

Sampler application A utility you can use to help understand an application’s running behavior. Sampler can identify the routines in which the program spends most time executing. It can also summarize why allocation routines, system calls, or arbitrary functions were called.

Thread Viewer application A utility for graphically displaying activity across a range of threads. It provides timeline color-coded views of activity on each thread. By clicking on a timeline, you can see a sample backtrace of activity at that time.

MONster application An application that collects data from processor and memory controller performance counters and presents it in tabular form. It can collect data system wide, or from a specific program running on the system.

Shark application An application that profiles the system to see how time is being spent. It can work at the system, task, or thread level and can correlate performance counter events with source code. Shark’s histogram view can be used to observe scheduling and other time-dependent behavior. It can produce profiles of hardware and software performance events such as cache misses, virtual memory activity, instruction dependency stalls, and so forth.

You can download Shark as part of the Computer Hardware Understanding Developer (CHUD) Tools at the Developer FTP site.

Skidmarks GT application A processor performance benchmark that measures integer, floating-point, and vector performance. sample Gathers data about the running behavior of a process. The sample tool stops the process at user-defined intervals, records the current function being executed by the process, and checks the stack to find how the current function was called. It then lets the application continue. At the end of a sampling session, sample produces a report showing which functions were executing during the session. top Displays an ongoing sample of system use statistics. It can operate in various modes, but by default shows CPU and memory use for each process in the system. gprof Produces an execution profile of a C, Pascal, or Fortran77 program. The tool lists the total execution times and call counts for each of the functions in the application, and sorts the functions according to the time they represent including the time of their call graph descendents.

KEXTs, Drivers, and Instruction Traces

USB Prober application An application that displays detailed information about all the USB ports and devices on the system.

Reggie SE application An application that examines and modifies CPU and PCI configuration registers in PowerPC processors. ktrace Enables kernel trace logging for specified processes. The kernel operations that are traced include system calls, namei translations, signal processing, and I/O. kdump Displays the kernel trace files produced by ktrace in human readable format. acid Analyzes TT6E (but not TT6) instruction traces and presents detailed analyses and histogram reports. amber Captures the instruction and data address stream generated by a process running in Mac OS X and saves it to disk in TT6, TT6E, or FULL format. Custom trace filters can

be built using the amber_extfilt.a module in /Developer/Examples/CHUD/Amber/ExternalTraceFilter/. Differences between TT6 and TT6E format as well as the specifics of the FULL trace format are detailed in Amber Trace Format Specification v1.1 (/Developer/Documentation/CHUD/AmberTraceFormats.pdf).

simg4 A cycle-accurate simulator of the Motorola 7400 processor that takes TT6 (not TT6E) traces as input.

Packaging

PackageMaker application An application that you can use to create an installation package. When the user double-clicks the package, the Installer launches and installs the files you packaged. You can use PackageMaker to package files or to assemble individual packages into a single package. You can run PackageMaker from the command line. For details, enter the following command on the command line: /Developer/Applications/PackageMaker.app/Contents/MacOS/PackageMaker. Be sure to use full paths in all command-line arguments.

Installer application The native installer for Mac OS X.

installer The command-line version of Installer. The installer command is used to install Mac OS X installer packages to a specified volume.

GetFileInfo Gets the file attributes of files in an HFS+ directory.

SetFile Sets the attributes of files in an HFS+ directory.

install Copies files to a target file or directory. Unlike the cp or mv commands, the install command lets you specify the new copy’s owner, group ID, file flags, and mode.

lipo Can create a multi-architecture (“fat”) executable file from one or more input files, list the architectures in a fat file, create a single-architecture file from a fat file, or make a new fat file with a subset of the architectures in the original fat file.

SplitForks Removes the resource fork in a file or all the resource forks in the files in a specified directory and saves them alongside the original files as hidden files (a hidden file has

the same name as the original file, except that it has a “dot-underscore” prefix; for example ._MyPhoto.jpg.).

CpMac Copies a file or a directory, including subdirectories, preserving metadata and forks.

MvMac Moves files, preserving metadata and forks.

pbxcp Copies files. This tool can skip specific files, strip out debug symbols, preserve metadata, user IDs and other information, and resolve the first level of symbolic-link source entries.

install_name_tool Changes the dynamic shared library install names recorded in a Mach-O binary.

mkbom Creates a bill of materials for a directory.

MergePef Merges two or more PEF files into a single file. PEF format is used for Mac OS 9 code.

Scripting

Interpreters and Compilers

osascript Executes a script file, which may be plain text or a compiled script. The osascript command works with AppleScript and with any other scripting language that conforms to the Open Scripting Architecture (OSA).

osacompile Compiles the specified files, or standard input, into a single script. Input files may be plain text or other compiled scripts. The osacompile command works with AppleScript and with any other OSA scripting language.

perl Executes scripts written in the Practical Extraction and Report Language (Perl). The man page for this command introduces the language and gives a list of other man pages that fully document it.

perlcc Compiles Perl scripts.

awk A pattern-directed scripting language for scanning and processing files. The scripting language is described on the awk man page.

python The interpreter for the Python language, an interactive, object-oriented language. Use the pydoc command to read documentation on Python modules.

ruby The interpreter for the Ruby language, an interpreted object-oriented scripting language.

sed Reads a set of files and processes them according to a list of commands.

tclsh A shell-like application that interprets Tcl commands. It runs interactively if called without arguments. Tcl is a scripting language, like Perl, Python, or Ruby. However, Tcl is usually embedded and thus called from the Tcl library rather than by an interpreter such as tclsh.

Script Language Converters

a2p Converts an awk script to a Perl script.

s2p Converts a sed script to a Perl script.

sdp Converts a scripting definition (.sdef) file into other formats, including Rez input, Cocoa scripting .scriptSuite file format, or Cocoa scripting .scriptTerminology format. A scripting definition file, also called an AppleScript dictionary file, is a set of definitions for words that are understood by a particular application. Dictionaries tell you which objects are available in a particular application and which commands you can use to control them.

Perl Tools

dprofpp Displays profile data generated for a Perl script by a Perl profiler.

find2perl Converts find command lines to equivalent Perl code.

h2ph Converts C header files to Perl header file format.

h2xs Builds a Perl extension from C header files. The extension includes functions that can be used to retrieve the value of any #define statement that was in the C header files. perlbug An interactive tool that helps you report bugs for the Perl language. perldoc Looks up and displays documentation for Perl library modules and other Perl scripts that include internal documentation. If a man page exists for the module, you can use man instead. pl2pm Aids in the conversion of Perl 4 .pl library files to Perl 5 library modules. This tool is useful if you plan to update your library to use some of the features new in Perl 5. splain Forces verbose warning diagnostics by the Perl compiler and interpreter.

Parsers and Lexical Analyzers flex Generates programs that scan text files and perform pattern matching. When one of these programs matches the pattern, it executes the C routine you provide for that pattern. lex An alias for flex. yacc Generates parsers from grammar specification files. Used in conjunction with flex to created lexical analyzer programs. bison Generates parsers from grammar specification files. A somewhat more flexible replacement for yacc.

Documentation Tools podchecker Checks the syntax of documentation files that are in pod format and outputs errors to standard error. podselect Prints selected sections of pod documentation to standard output.

pod2html Converts files from pod format to HTML format. The pod (Plain Old Documentation) format is defined in the perlpod man page.

pod2latex Converts files from pod format to LaTeX format. LaTeX is a document preparation system built on the TeX text formatter.

pod2man Converts files from pod format to *roff code, which can be displayed using nroff via man, or printed using troff.

pod2text Converts pod data to formatted ASCII text.

pod2usage Similar to pod2text, but can output just the synopsis information or the synopsis plus any options/arguments sections instead of the entire man page.

Java

General

java Starts the Java runtime environment and launches a Java application.

javac The standard Java compiler from Sun Microsystems.

jikes A Java compiler from IBM, which is faster than javac for many applications.

jdb The Java debugger. It provides inspection and debugging of a local or remote Java virtual machine.

Java Utilities

JavaBrowser application An application that lets you browse Java classes, documentation, and source files.

rmic A compiler that generates stub and skeleton class files for remote objects from the names of compiled Java classes that contain remote object implementations. A remote object is one that implements the interface java.rmi.Remote. javadoc Parses the declarations and documentation comments in a set of Java source files and produces HTML pages describing the public and protected classes, inner classes, interfaces, constructors, methods, and fields. javah Generates C header and source files from Java classes. The generated header and source files are used by C programs to reference instance variables of a Java object so that you can call Java code from inside your Mac OS X native application. rmiregistry Creates and starts a remote object registry. A remote object registry is a naming service that makes it possible for clients on the host to look up remote objects and invoke remote methods. native2ascii Converts characters that are not in Latin-1 or Unicode encoding to ASCII for use with javac and other Java tools. It also can do the reverse conversion of Latin-1 or Unicode to native-encoded characters. idlj Reads an Object Management Group (OMG) Interface Definition Language (IDL) file and translates it, or maps it, to a Java interface. The idlj compiler also creates stub, skeleton, helper, holder, and other files as necessary. These Java files are generated from the IDL file according to the mapping specified in the OMG document OMG IDL to Java Language Mapping Specification, formal, 99-07-53 . The idlj compiler is documented at http://java.sun.com/j2se/1.3/docs/guide/rmi-iiop/toJavaPortableUG.html. IDL files are used to allow objects from different languages to interact with a common Object Request Broker (ORB), allowing remote invocation between languages.

Java Archive (JAR) Files

Jar Bundler application An application that allows you to package your Java program’s files and resources into a single double-clickable application bundle. Jar Bundler lets you modify certain properties so your Java application behaves as a better Mac OS X citizen and lets you specify arguments sent to the Java virtual machine (VM) when the application starts up. jar Combines and compresses multiple files into a single Java archive (JAR) file so they can be downloaded by a Java agent (such as a browser) in a single HTTP transaction.

jarsigner Lets you sign JAR files and verify the signatures and integrity of signed JAR files.

extcheck Checks a specified JAR file for title and version conflicts with any extensions installed in the Java Developer Kit software.

Kernel Extensions

Command-line tools useful for kernel extension development include the following:

kextload Loads kernel extensions, validates them to make sure they can be loaded by other mechanisms, and generates symbol files for debugging them.

kextstat Displays the status of any kernel extensions currently loaded in the kernel.

kextunload Terminates and unregisters I/O Kit objects associated with a KEXT and unloads the code for the KEXT.

ddb The Mac OS X built-in debugger. You must build the kernel in debug mode in order to use this debugger. See Kernel Programming in the Darwin & Core OS Documentation area for details.

I/O Kit Drivers

I/O Registry Explorer application An application that you can use to examine the configuration of devices on your computer. I/O Registry Explorer (filename IORegistryExplorer) provides a graphical representation of the I/O Registry tree. Documentation for I/O Registry Explorer is at I/O Kit Fundamentals in the Device Drivers & I/O Kit Documentation area.

ioreg A command-line version of I/O Registry Explorer. The ioreg tool displays the tree in a Terminal window, allowing you to cut and paste sections of the tree.

ioalloccount Displays a summary of memory allocated by I/O Kit allocators listed by type (instance, container, and IOMalloc). This tool is useful for tracking memory leaks.

ioclasscount Shows the number of instances allocated for each specified class. This tool is also useful for tracking memory leaks.

Document Revision History

The table below describes the revisions to this document.

Table RH-1 Document revision history

Date Notes

October 13, 2003 Updated obsolete hyperlinks.

June 11, 2003 Revised names of products.

May 15, 2003 First version of Mac OS X Development Tools Overview.

February 25, 2004 Removed references to Shikari application.

defaults 57 A DeRez 36, 51 diff 57 a2p 64 diff3 57 acid 61 diffpp 57 agvtool 56 diffstat 57 amber 61 dprofpp 64 Apple Help Indexing Tool 37, 52 Apple Help Viewer 37 AppleGlot 36, 51 AppleScript 23 E AppleScript Studio 23, 43 error 59 as 52 extcheck 47, 68 awk 64

B F FileMerge 57 bison 65 find2perl 64 bsdmake 53 flex 65 fpr 55 fsplit 55 C c2ph 59 CacheBasher 58 G ci 56 gcc 52 co 56 gdb 38, 47, 57 compileHelp 52 genstrings 36, 51 CpMac 41, 63 GetFileInfo 41, 62 cscope 59 gnumake 53 ctag 60 gprof 61 CVS 38 cvs-unwrap 56 cvs-wrap 56 H

h2ph 64 D h2xs 65 headerdoc2HTML 37, 52 ddb 47, 48, 68 heap 58

I lorder 42, 53

I/O Registry Explorer 48, 68 icns Browser 37, 54 IconComposer 37, 54 M idlj 67 make 52 ifnames 38, 55 MallocDebug 39, 58 indent 38, 55 malloc_history 39, 58 install 41, 62 merge 57 install-info 52 MergePef 63 Installer 40, 62 mkbom 41, 63 installer 41, 62 mkdep 53 install_name_tool 63 mkstr 38, 55 Interface Builder 30–31, 35, 36 MONster 40, 60 ioalloccount 48, 68 MvMac 41, 63 ioclasscount 48, 69 ioreg 48, 68 IORegistryExplorer 48, 68 N

native2ascii 67 J nibtool 60 nm 60 jam 53 nmedit 38, 55 jar 47, 67 Jar Bundler 47, 67 jarsigner 47, 68 java 66 O JavaBrowser 66 javac 66 ObjectAlloc 39, 58 javadoc 46, 67 OpenGL Info 40, 59 javah 46, 67 OpenGL Profiler 40, 59 jdb 47, 66 OpenGL Shader Builder 37, 54 jikes 66 osacompile 43, 63 osascript 44, 63 otool 60 K kdump 61 P kextload 48, 68 kextstat 48, 68 PackageMaker 40, 62 kextunload 48, 68 pagestuff 60 ktrace 61 patch 57 pbhelpindexer 52 pbprojectdump 53 pbutil 53 L pbxbuild 53 pbxcp 41, 63 ld 52 pbxmapdump 55 leaks 58 PEFViewer 59 lex 65 Perforce 38 libtool 41, 53 Perl 23 lipo 41, 62 perl 44, 63

perlbug 65 SetFile 41, 62 perlcc 44, 63 Shark 40, 60 perldoc 65 shell scripts 23 Pixie 40, 59 simg4 62 pl2pm 65 Skidmarks GT 61 plutil 37, 55 splain 65 pod2html 66 SplitForks 62 pod2latex 66 strings 60 pod2man 66 pod2text 66 pod2usage 66 podchecker 65 T podselect 65 tclsh 64 printf 55 Thread Viewer 40, 60 Property List Editor 37, 54 top 40, 61 pstruct 59 tops 38, 55 pydoc 44 python 44, 64

Q unifdef 38, 55 UnRezWack 54 Quartz Debug 40, 59 update_prebinding 54 USB Prober 61 R ranlib 41, 53 V rcs 56 vmmap 58 rcs-checkin 56 vm_stat 58 rcs2log 56 rcsclean 56 rcsdiff 56 rcsmerge 56 X redo_prebinding 53 Reggie SE 61 Xcode application 13–14, 25–29, 35, 36, 39 ResMerger 54 Rez 36, 51 RezWack 54 rmic 46, 67 Y rmiregistry 46, 67 ruby 64 yacc 65

S s2p 64 sample 39, 61 Sampler 39, 60 sdiff 57 sdp 64 sed 64