The Basic Development Environment

Like CodeWarrior, Xcode is focused on the use of projects, targets, and files. But it also takes advantage of some of the popular user interface features found in iTunes and other Apple consumer applications, such as useful grouping of files and other items, fast searching for items, and a clean, relatively simple interface.

The development environments for Xcode and CodeWarrior contain the same major components, including project window, text editor, build system, debugger, symbol navigation, find facilities, and help system. One significant difference is that Xcode includes a number of open source components, including the GCC compiler and GDB debugger, as well as other tools written by the UNIX open-source community.

Behind the user interface, Xcode performs many tasks by launching command-line tools as Mach processes. That allows Xcode to implement features such as distributed and multiprocessor builds, where each GCC compile can be handled by a separate CPU, even on separate machines.

The Project Window

Figure 1-1 shows the Xcode project window for a simple Carbon application.

You can get a complete listing of Xcode features in Xcode 2.2 User Guide, but the following list highlights some of the most frequently used interface features.

• Instead of tabs (as in CodeWarrior and Project Builder), the default project window in Xcode uses a hierarchical list of groups in the Groups & Files list. Xcode includes several different project window layouts, however, including one that provides a tabbed interface to your project's contents.

• The contents of the selected item or items in the Groups & Files list are listed in a detail view.

• Text you type in the Search field is used to filter items in the detail view. The Search field supports simple string matching, regular expressions, and wildcard patterns.

• For source files, the detail view shows build status, SCM status, size, errors, warnings, and so on.

• Some of the items that can appear in the Groups & Files list include:

  • The project group, at the top of the Groups & Files list, shows all of the files, frameworks, and libraries included in the project. The previous figure shows the project group "CarbonTest."

    Source groups, identified by yellow folder icons, can contain other source groups. They help you organize the files in your project into more manageable chunks.

  • The Targets group contains all the targets in the project.

  • The Executables group contains all of the executable environments defined in the project. Executable environments specify the executable file that is launched when you run or debug; typically, this corresponds to a product that the project builds.

  The following items in the Groups & Files list are smart groups:

  • The Errors and Warnings group lists the errors and warnings generated when you build your project.

  • The SCM group lets you view the project files currently under version control, as well as their current state.

  • The Bookmarks group contains all of the locations you have saved as bookmarks for this project.

  • The Find Results group contains the results of any searches you perform in your project. Each search creates a new entry in this group.

  • The Project Symbols group lists all of the symbols defined in your project.

  • The NIB Files group contains any .nib files used to create your product's user interface.

  • The Implementation Files group contains all of the implementation files in your project, such as those ending in .cpp , .c , and .m .

  You can define your own smart groups and the rules for what they contain. User-defined smart groups are indicated with a purple folder icon.

• Inspector windows and Info windows handle much of the interesting work, allowing you to easily display and edit project data. (These windows differ in that inspector windows are floating utility windows that track the current selection, while Info windows are standard windows that continue to display information about the same item.)

  Among other things, you can use these windows to:

  • display per-project settings

  • display per-target settings

    Figure 1-2 shows the target inspector. A useful feature of the build settings interface is a section below the build settings table that provides a description of the currently selected build setting. If this section isn’t visible, you can display it by dragging the separator bar.

    

  • display per-file settings and information, such as location, encoding, tab settings, line endings, and so on

  • select multiple project items—such as files or targets—and change settings on all of them (for settings for which this makes sense)

• The Find string is persistent across dialogs (and even many Mac OS applications).

• Xcode uses shell paths (slash-delimited) exclusively, not colon-delimited paths.

• Xcode supports per-file compiler settings.

• The Xcode editor supports code completion; as you type identifiers and keywords, Xcode suggests likely matches based on the current context.

Limitations

Throughout this document, you will find comparisons between CodeWarrior and Xcode, including differences, issues, and in many cases, alternate approaches. This section lists some Xcode limitations to be aware of, with links to further information where available.

• Compile and build speed are greatly improved, and will get faster, but do not yet equal CodeWarrior.

• GCC provides limited support for CodeWarrior pragmas.

  See Pragma Statements.

• There is no support for wchar_t and wstring prior to Mac OS X version 10.3 (Panther).

  See Support for wchar_t and wstring.

• There is no projectwide graphical tree browser; however, Xcode 2.0 and later include a class modeling tool that you can use to make individual graphical models of your project's classes.

While not strictly a limitation, there are many differences between GCC and the Metrowerks compilers. Information on these differences is provided in many places in this document. For a jumping-off point, see The GCC Compiler.

Companion Applications

CodeWarrior provides the Constructor application for designing user interfaces based on the PowerPlant framework. Xcode provides the Interface Builder application for creating graphical user interfaces for Mac OS X applications. Interface Builder works with both Carbon and Cocoa applications and 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 layout tools in Interface Builder include built-in support for the Aqua interface guidelines. You can, of course, continue to use Constructor even when moving your code to Xcode.

To learn more about using Interface Builder with Carbon applications, see Unarchiving Interface Objects With Interface Builder Services and Interface Builder Services Reference.

CodeWarrior provides the Profiler application for examining the behavior of a running application and fine-tuning performance. Xcode Tools includes the Shark and Sampler profiling tools. For tracking memory usage and bugs, Xcode provides the MallocDebug application, which helps debug memory problems that you would debug on Mac OS 9 with CodeWarrior’s ZoneRanger. To learn more about performance optimization and available tools, see Performance Overview.

Header Files

For a CodeWarrior project, you don’t have to explicitly add header files. Instead, you can add recursive access paths, and as long as the header files are somewhere on a specified path, CodeWarrior will find them. (You may notice that this causes a delay on opening projects and can cause errors if you have different headers with the same name.)

Xcode also supports recursive search paths; however, it is generally recommended that your project include explicit references to its header files. For example, when you add a .c file to your Xcode project, you don’t typically add a search path for the associated header file. Instead, you drag the actual header file into a group in the Groups & Files list in the project to add a reference to the header.

The Build pane in the target and project inspector windows includes build settings for Header, Framework, and Library search paths. By default, these paths are empty; access paths defined in your CodeWarrior project are not brought over by the importer. If you specify a search path in one of these build settings, Xcode uses that path to locate header files during compiling and linking.

To have Xcode search the contents of the entire directory tree located at a given path, select the Recursive option next to that path. This option is not enabled by default when you add a new search path. You should be aware, however, that using recursive search paths can result in longer build times and cause problems if you have multiple files with the same name. For more on using search paths in Xcode, see Build Settings in Xcode 2.2 User Guide.

Framework-Style Headers

One important transition in moving to Mac OS X development is the switch from including individual headers to including framework-style headers in your source code files. A framework is a type of bundle that packages shared resources, such as a dynamic shared library and its associated resource files, header files, and reference documentation. An umbrella framework is a framework that includes a number of related frameworks. The Carbon framework (Carbon.framework) is an umbrella framework that contains just one header, Carbon.h. That header in turn includes headers from many additional frameworks, such as Core Services, HIToolbox, and others.

A framework-style include statement specifies a framework (typically an umbrella framework) and its main header file. For example, a Carbon source file should use the statement #include <Carbon/Carbon.h>, rather than separate include statements for each individual header file it may require. Using framework-style includes will help ensure that your project builds correctly and remains reliable over time.

For related information, see Header Files, Precompiled Headers and Prefix Files, Cross-Development, Use Framework Headers, and Use C99 Standard in Language Settings. For more information on frameworks in Mac OS X, see Framework Programming Guide.

Cross-Development

Cross-development refers to the ability to develop software that can be deployed on, and take advantage of features from, specified versions of Mac OS X, including versions different from the one you are developing on. CodeWarrior provides some support for cross-development for versions of the Mac OS through Universal Interfaces, but those headers have not been updated for recent versions of Mac OS X.

Xcode supports cross-development for various versions of Mac OS X. You can specify which version of Mac OS X headers and libraries to build with, as well as the earliest Mac OS X system version on which the software will run.

To use cross-development for a target in an Xcode project, you make two selections:

• In the General pane of the inspector window for the project group, you use the Cross-Develop Using Target SDK pop-up to select an OS version to develop for, such as Mac OS X 10.4.0. All targets in the project are built as though you were building in that version of the operating system.

• In the Build pane of the inspector window for the target or project, you choose a Mac OS X deployment version, such as 10.2. For this target or project, this specifies the earliest Mac OS X system version on which your software will run.

You can also use the SDK headers and libraries to support cross-development in CodeWarrior projects. For details, see Maintaining Parallel Projects in Xcode and CodeWarrior.

For detailed documentation on cross-development, see SDK Compatibility Guide.

Precompiled Headers and Prefix Files

Precompiled headers are binary files that represent the compiler's intermediate form of the headers required to compile a source file. Generally, all source files in a given target use a large common subset of system and project headers, so by precompiling these headers into intermediate form once and reusing it for many source files, the compiler can build source files more quickly.

CodeWarrior users must manage precompiled headers manually. In CodeWarrior, you can use a precompiled header interchangeably with a normal header file. It can be included in an #include directive or used as a prefix header in a target's Target Settings. You can create a precompiled header file using the Precompile menu item, or by including a .pch file in your project (you use a #pragma directive in that file to define the name of the precompiled header itself, which usually has a .mch suffix). In many larger projects, developers have separate targets (or even whole projects) that just build common precompiled headers that are shared among multiple projects.

In Xcode, precompiled headers are generated automatically and invisibly by the development environment. By setting the Prefix Header build setting of a target to your .pch file (or any other header file that contains #include statements for your framework headers and common target headers), Xcode will generate the precompiled header file and use it when compiling every source file in that target. (The Precompile Prefix Header build setting must also be enabled.)

The precompiled header is regenerated whenever any files it depends on are changed, so you don't need to manually build or maintain the precompiled header.

You can see the Prefix Header and Precompile Prefix Header build settings in the Build pane in Figure 1-3. For more information on using precompiled headers in Xcode, see Optimizing the Edit-Build-Debug Cycle in Xcode 2.2 User Guide.

Pragma Statements

A pragma statement is a directive for providing additional information to the preprocessor or compiler beyond what is conveyed in the language itself. There are a small number of pragma types defined by the C standard; individual compilers may support any number of additional types and values.

The CodeWarrior compiler supports a number of pragmas, including pragma equivalents for most of the compiler settings you can set in the user interface. It also supports some pragmas you can’t set in the user interface. Some examples of pragmas CodeWarrior supports are #pragma unused and #pragma once. In CodeWarrior, pragmas can turn a feature on and off within an individual compilation unit. For example, you can use the pragma statements #pragma export on and #pragma export off in a source file to bracket any symbols you want to export from a shared library.

Xcode supports some CodeWarrior-defined pragmas. However, Xcode supplies build settings for many of the features the CodeWarrior compiler supports through pragmas. These settings should be set automatically when you import a CodeWarrior project, but you can also add, delete, or modify build settings. Figure 1-3 shows some of the Language settings you can set for a target in the Build pane in an inspector window in Xcode.

Although language settings can be set on a file, target, or project basis, you cannot use them for inline control of compiler options. As a result, the smallest unit for which you can set a compiler option is a single source file. To modify build settings on a target-wide basis, select the target in the Groups & Files list and open an Info window (by clicking the Info button or by choosing File > Get Info). Select the Build pane, then make your changes.

Xcode provides a different interface for modifying options for a single file (or several files). You can add additional compiler flags for one or more files with the following steps:

1. Open the target in the Groups & Files list.

2. Open the Compile Sources build phase.

3. Select the file (or files) for which you want to modify the settings.

4. Open an Info window by choosing File > Get Info.

5. Select the Build pane (shown in Figure 1-4 for a multiple selection).

   

6. Add any desired compiler flags. Multiple flags should be separated by spaces.

If your CodeWarrior project follows the common pattern of placing pragmas in a header file that is included by other source files, you won’t have to make changes to individual files—you can just set the corresponding values for an entire target or a subset of files. However, if you have code that uses pragmas to turn settings on and off within a single file, and if you need to maintain that level of control, you may need to break up some files so that code that shares common build settings is in one file.

For additional information on modifying your source files, see Maintaining Parallel Projects in Xcode and CodeWarrior. For information on using pragmas with respect to identifying export symbols, see Exporting Symbols.

For further information on setting per-target and per-file compiler options in Xcode, see Build Settings in Xcode 2.2 User Guide. For a list of pragmas supported by GCC, see the sections "Pragmas" in GNU C 4.0 Preprocessor User Guide and "Pragmas Accepted by GCC" in GNU C/C++/Objective-C 4.0 Compiler User Guide.

For more information on code changes you may need to make as a result of pragma statements in your CodeWarrior code, see Create a Prefix File for PowerPlant.

C and C++ Libraries

When you create Carbon applications in CodeWarrior, you can link against MSL C and C++ libraries (in debug and nodebug variants) to create CFM-style executables that can run in Mac OS 9 or Mac OS X. There is no system-supplied C library in Mac OS 9, so your application relies on the development environment, which for CodeWarrior, means the MSL libraries.

In Mac OS X, there are system-supplied C and C++ libraries. The C library comes in static and dynamic variants. The dynamic version is strongly recommended for most software, though you may need to link the static version in certain situations (such as for KEXTs, which must load when the dynamic loader isn’t available).

Beginning with Mac OS X 10.3.9, the standard C++ library is packaged as a dynamic shared library. In prior versions of Mac OS X, the C++ library is packaged as a static library. Packaging the standard C++ library as a dynamic shared library provides a number of benefits, such as smaller binaries and improved performance. To link against the shared library version, libstdc++.dylib, you must use GCC 4.0. If your application must run on versions of Mac OS X prior to 10.3.9, however, you must link against the static library, libstdc++.a . To learn more about the C++ runtime and using the shared library version of libstdc++ , see C++ Runtime Environment Programming Guide.

CodeWarrior also supplies MSL libraries to create Mach-O style executables that run on Mac OS X only. In some cases, the MSL library calls through to the Mac OS X System framework library, and in some cases it provides missing features (such as wchar_t support, not available in Mac OS X prior to Panther).

If your CodeWarrior project is already building a Mach-O style executable, you should have an easier time in moving it to Xcode. If not, you should consider converting it, as described in Preparing a CodeWarrior Project for Importing. You’ll primarily be changing linker settings, access paths, and precompiled headers. In addition, if you load plug-ins via CFM, you’ll need to rewrite that code to use the CFBundle or CFPlugin APIs.

For related information, see The GCC Compiler.

Support for wchar_t and wstring

The standard C and C++ wide character type wchar_t and the wstring template class that makes use of it are supported in the system libraries for Mac OS X version 10.3 and later. As a result, you can freely use these data types in software created with Xcode that will run only in Panther and later. However, if you need to use these data types in software that will run in versions of Mac OS X prior to Panther, you should obtain a third-party standard C library, such as the one available from Dinkumware, Ltd..

CodeWarrior supports wchar_t and wstring for CFM applications because they are supported in the MSL C and C++ libraries for CFM. However, because MSL libraries for Mach-O in CodeWarrior do not anticipate wchar_t support in the Apple standard C libraries, wchar_t support is turned off in the MSL Mach-O standard library projects. This means that if you use CodeWarrior in Mac OS X v.10.3 or later, you'll get build errors when you rebuild the CodeWarrior MSL libraries because wchar_t support is turned off but the Mac OS X headers now use wchar_t.

To resolve this issue, when rebuilding your MSL libraries on Panther, you should select the “Enable wchar_t Support” checkbox in the C/C++ Language settings for the Mach-O library projects.

The GCC Compiler

CodeWarrior provides a proprietary compiler that supports C and C++ and includes support for Altivec. CodeWarrior and Xcode C and C++ libraries are discussed in C and C++ Libraries.

Xcode uses the open-source GNU C Compiler, or GCC. When you compile C, C++, Objective-C, or Objective-C++ code in Xcode, you’re using GCC. The default version of GCC for Xcode 2.2 is 4.0. For versions of Xcode earlier than Xcode 2.0, the default version of GCC is 3.3. If necessary, you can choose from the the available GCC versions by selecting a target in the project window, opening an inspector window, and selecting the Rules pane. There you can use the pop-up menus to view the current system rules and to add rules for which compiler to use for C, C++, and other types of files in that target. For related information, see More on GCC Compiler Versions.

When you import a CodeWarrior project, the rule for processing C files is left unchanged. This means that C files are compiled with the current system version of GCC, which depending on the system, is either 3.3 or 4.0. This document assumes that you will use version 4.0 to build your imported project.

Compile speed has improved dramatically in GCC 3.3 and 4.0, but does not yet quite equal CodeWarrior. However, Xcode sports features such as distributed and multiprocessor builds, where each compile is handled by a separate CPU, even on separate machines. These features can dramatically reduce build time for large projects. Xcode also provides additional features to improve the overall development process, including ZeroLink and Fix and Continue, described in Some Special Features of Xcode.

Figure 1-3 shows some GCC build settings in an inspector window for an Xcode target. Build settings in the Xcode user interface are converted to command-line options to GCC when you compile your source code. If you want to use a feature of GCC that isn’t available in the Xcode user interface, you can add flags to the Other C Flags setting. To view this setting, see the detailed steps provided in Inline ASM. Multiple flags should be separated by spaces.

There are a number of significant differences between GCC and the CodeWarrior compiler. One that you’re likely to notice right away is that GCC has a reputation for strictness, and is likely to generate many warnings for code that may produce few warnings in CodeWarrior. Because C and C++ are very permissive languages, most of these warnings have been found to be useful over the years. Getting a compiler error or warning about suspect code can save days or even weeks of difficult debugging.

Still, you have options to reduce the number of warnings. To change the warnings for a selected target, open the inspector window, select the Build pane, and choose Warnings under GNU C/C++ Compiler in the Collections menu. You can then select any of the warning settings and see a description for it displayed beneath the list of settings, as shown in Figure 1-5.

You can also set additional GCC warnings by modifying the Other Warning Flags build setting in the Build pane.

C++ Code in C Files

GCC is literal in its interpretation of file suffixes. While CodeWarrior applies the C++ preprocessor and parser to C++ and C files alike, GCC will emit errors if C++ code is used in .c files. You can override this by changing the file's type to a C++ filetype (sourcecode.cpp) in the General pane of the file inspector. As long as the Compile Sources As (GCC_INPUT_FILETYPE) build setting is set to According to File Suffix, changing the filetype will cause Xcode to use the -x c++ option when compiling files whose type is a C++ filetype. Any explicitly set value for the Compile Sources As build setting overrides the filetype you specify in the General pane of the file inspector.

By default, when you import a CodeWarrior project, the Compile Sources As build setting is set to According to File Suffix. However, if you have Force C++ compilation set in your CodeWarrior target settings, the importer in Xcode 2.2 sets the Compile Sources As build setting for that target to sourcecode.cpp.cpp.

Inline ASM

GCC supports CodeWarrior-style inline asm code. To enable this support, you add the following flag to your build settings:

-fasm-blocks

When you import a CodeWarrior project that uses inline asm into Xcode, this flag is not set automatically, so you will have to add it yourself. You can do so with the following steps:

1. Select a target in the project window.

2. Open an inspector window like the one shown in Figure 1-3 by clicking the Info button or choosing File > Get Info.

3. Select the Build pane.

4. If the GNU C/C++ Compiler settings aren’t visible, select GNU C/C++ Compiler from the Collection menu.

5. Click the checkbox in the Value column next to the CodeWarrior-Style Inline Assembly setting.

In general, the GCC implementation works the same as the CodeWarrior implementation, and any discrepancies you note should be reported as bugs (see Feedback and Mail List). For example, if your project contains hand-tweaked asm code, it should work correctly in the new project, unless your code specifically targets CFM-related features. (CFM refers to the executable architecture supported by the Code Fragment Manager in Mac OS 9.)

Function calls, such as bl foo, don’t currently work, and are treated as though foo is a label whose definition is missing.

Calling conventions are generally the same as for CFM, but global variables are not available through the TOC register r2. For instance, in CFM, if aglob is a global, then lwz aglob(r2) works to get the value of aglob into r3. The Mach-O equivalent is complicated, involving multiple internal labels, and at present can’t be handled with inline asm.

GCC passes the inline asm through to the assembler and doesn’t interpret it, so any errors reported from the asm code come from the assembler. In unusual cases, such as when a typedef has the same name as an op code, GCC may parse the code differently from CodeWarrior. For example, the code in listing Listing 1-1 will result in warnings and a body with one nop if using CodeWarrior, and a body with two instructions (mr r1,r2 and nop 0 if using GCC. (This should probably be considered a bug in GCC’s implementation.)

Listing 1-1  A typedef with the same name as an op code

typedef int mr;

asm int foo()

{

 mr r1,r2;

 nop

}

For a related issue, see Inlining Thresholds.

The Linker

In CodeWarrior, you can choose from among several linkers in the Target Settings pane. The “Macintosh PowerPC linker” creates executables based on the format specified by the Code Fragment Manager (CFM) architecture. The “Apple Mach-O PowerPC linker” makes use of Apple’s ld linker and libtool command-line tool. The “Mac OS X PowerPC Mach-O linker” also creates Mach-O executables, but uses the Metrowerks Mac OS linker.

Xcode uses the ld linker, which is designed to work with Mach-O object files, and supports dynamic shared libraries, two-level and flat name spaces, and other features.

The ld linker supports the automatic stripping of unused (dead) code beginning with the June 2004 release of the Xcode tools. For more information, see Dead Code Stripping. Using the ld linker may also result in larger binary files than in your CodeWarrior project. You can display man page documentation for the linker in Xcode with Help > Open man page, or in a Terminal window by typing man ld.

The Information Property List and .plc Files

Any packaged Mac OS X software, including applications, bundles, plug-ins, and frameworks, requires an information property list file named Info.plist. That file contains key-value pairs that specify various information that is used at runtime, such as the version number for the software. This information is used by the application and by Launch Services (an API for launching applications in Mac OS X) as well.

In CodeWarrior, projects that create packaged Mac OS X software use a .plc file to specify information for the Info.plist file. For example, if you use CodeWarrior project stationery to create a project for a Mach-O based Mac OS X application or a bundled Carbon application, the project includes a default .plc file. CodeWarrior reads the .plc file at build time, follows any included header files or prefix file chains, and creates a property list from it, according to settings you specify in the Property List pane of the target settings window.

An advantage of this approach is that you can define symbols in header files and include them into both your code and your .plc file. As a result, you can be confident you are using the same data in both your code and your Info.plist file.

Xcode provides a user interface for directly specifying property list settings, but it does not support conversion of a .plc file into an information property list, so you cannot share symbols between your code and your property list file. However, Xcode does obtain information for the property list from your CodeWarrior project during the import process.

You supply or modify property list information by opening an Inspector window for a target, and making changes in the Properties pane. Xcode also supports preprocessing of the Info.plist file using the GNU C preprocessor; you can include headers, use conditional statements, and define preprocessor macros for use when preprocessing the file. You can also reference any build settings in effect for the target; Xcode evaluates those build settings and replaces them with the appropriate value at build time. For more information on editing property lists in Xcode, see Xcode 2.2 User Guide. For details, see Move Settings From the .plc File to an Info.plist File.

Working With Resources

CodeWarrior and Xcode both work with Resource Manager .r and .rsrc resource files. In CodeWarrior, you can set Rez Options, Derez Options, and Common Options in the Rez target settings pane. In Xcode, you can set Resource Manager settings in the Build pane of a target inspector window. If you drag resources into your Xcode project, or import them as part of a CodeWarrior project, Xcode should place those resources in the Build ResourceManager Resources build phase. Xcode compiles .r files in this build phase and copies any .rsrc files into the product bundle. For more information on build phases in Xcode, see Build Phases in Xcode 2.2 User Guide.

Xcode does not provide a user interface to rez and derez individual files, but the Rez and DeRez tools are available in /Developer/Tools and you can run them from the command line and in scripts. There are man pages for Rez and DeRez, but documentation for the rez language is a bit hard to find. It’s documented in Appendix C of Building and Managing Programs with MPW.

In Mac OS X and for Carbon applications generally, resources should be put in the data fork of a separate resource file, not in the resource fork of the executable, as described in the section "Move Resources to Data Fork–Based Files" in Carbon Porting Guide. The primary reason for moving application resources out of resource forks is to enable applications to be seamlessly moved around different file systems without loss of their resources.

In addition to using .r and .rsrc files for resources, Carbon applications can use Interface Builder resource files (called nib files because they have an extension of .nib). When you create a new project in Xcode, the Carbon Application project template creates a nib-based Carbon application. Interface Builder provides an easy-to-use graphical method for designing and implementing a GUI, so there is potentially a lot to gain by using nib files for your resources. Interface Builder is described in Companion Applications. To learn more about using Interface Builder with Carbon applications, see Interface Builder, Unarchiving Interface Objects With Interface Builder Services and Interface Builder Services Reference.

Mac OS X also provides a very useful mechanism for storing language-dependent resources in localized directories within an application or other bundle. By using APIs such as CFBundle, your application can work with localized resources in a seamless manner. For more information on resources, application packaging, and bundles, see the document Mac Technology Overview, as well as the document Bundle Programming Guide.

Building Code

In CodeWarrior, you can have one or more named build targets, each of which specifies a set of files and project settings used to build an output file. The project manager keeps track of project dependencies and calls on the build system to build the current target.

With Xcode, you also define named targets, containing all the files and instructions required to create a final product. In addition, you can define different build configurations for each target, which allow you to build the target with different build settings without creating a whole new target.

The following sections describe the Xcode build system and compare various build-related features in CodeWarrior and Xcode. For additional details on building code, such as how to modify build settings, start a build, display the Build Results window, and so on, see The Build System in Xcode 2.2 User Guide.

Build Configurations

A build configuration is a variation on a target that lets you build a target using different build settings without creating a whole new target. If you need to create products that differ only in their build settings, you might create one target with several build configuration. If you need to create products that differ in other types of settings (such as build phases or information property list entries), you should create separate targets for each.

The list of build configuration names is defined at the project level. To add or remove build configurations, select the project source group in the project window, click the Info button to open an inspector window, and select the Configurations pane, which is shown in Figure 1-6. By default, new projects created in Xcode contain both Debug and Release build configurations, described below. Projects you import from CodeWarrior have a single build configuration, named Imported CodeWarrior Settings.

To add a build configuration to a project, select an existing build configuration and copy it.

Although build configuration names are defined at the project level, each target in the project, and the project itself, can define a different set of build settings for a build configuration. You edit the build settings in a build configuration in the Build pane of the target or project inspector. In this pane, select the build configuration you want to edit in the Configuration menu, then add or delete settings and insert or modify values in the list below the menu. You use the minus and plus buttons at the bottom of the list to add or delete settings.

To select the current build configuration, use the Active Build Configuration pop-up menu in the toolbar of the project or Build Results window or choose Set Active Build Configuration.

Exporting Symbols

As part of building a shared library, plug-in, or other software that will export symbols, you want to specify which symbols are available to clients of the software. The fewer symbols your software exports, the more quickly it will load at runtime. In addition, you typically do not want to expose internal entry points, due to both competitive and support issues.

CodeWarrior provides several options for specifying which symbols a shared library will export.

• Use an export (or .exp) file. When you run the Make command on a library target, CodeWarrior creates a .exp file containing all the global variables and routines in the project. After creating this file, you can comment out any symbols you don’t want to export, including CodeWarrior runtime symbols. You then add the .exp file to the appropriate target and rebuild the project.

• You can use the pragma statements #pragma export on and #pragma export off to bracket any symbols you want to export. CodeWarrior exports only symbols bracketed by these statements.

• Combine the two previous mechanisms. Only the bracketed symbols are placed in the .exp file, which you can still edit as necessary.

You can include your export file in an Xcode project as well, by setting the Exported Symbols File build setting to the name of your export file. Xcode passes the appropriate options to the static linker.

You can’t use the pragma statements #pragma export on and #pragma export off to specify export symbols in Xcode because GCC does not support these pragma statements. However, GCC does have its own pragmas for controlling symbol visibility, described in C++ Runtime Environment Programming Guide.

Beginning with Xcode 2.2, the importer interprets the Export Symbols setting in your CodeWarrior target. Based on the following values for that setting, the importer configures the corresponding Xcode target differently:

• None. The importer enables the Symbols Hidden by Default (GCC_SYMBOLS_PRIVATE_EXTERN) and Inline Functions Hidden (GCC_INLINES_ARE_PRIVATE_EXTERN) build settings for the new Xcode target. When these build settings are enabled, all symbols are declared 'private extern' unless explicitly marked otherwise.

• All Globals. The importer disables the Symbols Hidden by Default (GCC_SYMBOLS_PRIVATE_EXTERN) build setting in the new Xcode target.

• 'Use ".exp" file' or 'Use #pragma and ".exp" file.' The importer sets the Exported Symbols File (EXPORTED_SYMBOLS_FILE) build setting to the path to the first export file that it finds in your CW target. It also enables the Symbols Hidden by Default and Inline Functions Hidden build settings.

  Note that, while CodeWarrior targets may have multiple .exp files, an Xcode target can have only one. If your CW target has more than one export file, the importer uses the first one it encounters and ignores the rest.

The importer does not interpret the Referenced Globals or Use #pragma settings.

For related information in this document, see Runtime and Library Issues, Dead Code Stripping, and Pragma Statements.

For additional information on examining and managing your software’s exported symbols, and on other techniques for producing more efficient code, see Code Size Performance Guidelines. In particular, the section Minimizing Your Exported Symbols describes how to reduce the symbols exported by your application.

Debugging

Basic debugging is very similar in CodeWarrior and Xcode, though Xcode uses the open source GDB debugger and provides some additional features, such as Fix and Continue (live patching), to make debugging more efficient. Xcode supplies a graphical interface to GDB, but you can also use the command line interface (in place of or in parallel to the UI) to get full access to any GDB feature not supported in the user interface. Figure 1-7 shows the debugger window stopped in a simple Carbon application.

For GDB documentation, see Debugging with GDB.Note that some debugging features are currently unavailable in Xcode: for example, you cannot set event points in the UI.

In CodeWarrior, “event points” are the general name for a set of actions that the CodeWarrior IDE debugger can perform at a breakpoint (such as perform a test, log a message, play a sound, speak a phrase, or execute a script). A “watch point” is a range of memory that you are watching while debugging to note changes; the debugger stops execution when it notices that a certain range of memory has been changed.

Beginning with Xcode 2.1, Xcode includes support for both breakpoint actions and watchpoints. Similar to event points, breakpoint actions let you perform an action at a breakpoint. Xcode includes breakpoint actions that let you execute a script, print a message to the console, send a command to the debugger, and more.

While CodeWarrior supplies nonstandard flags to perform diagnostics on use of the standard template library (STL), Xcode does not include a debug version of the STL. However, Xcode does support breaking on C++ try, catch and throw constructs, and allows stepping through template instantiation.

Prebinding

Prebinding is the process of computing at build time the addresses for the symbols imported by libraries and applications, so that less work needs to be performed by the dynamic linker at runtime.

If a user installs your software on a system with a set of libraries that is different than those present when the application was built, the prebinding information cannot be used and application launch is slower. If you use the PackageMaker application to package your software and let users install it with the Installer application, Installer automatically attempts to update prebinding information for the software it installs by running the update_prebinding tool. If your software uses drag-and-drop installation, you can provide instructions for how to run this tool through a Read Me file, printed documentation, or other mechanism.

Prebinding is only applicable for Mach-O executables. (Mach-O is the native executable format in Mac OS X and is the only format supported by Xcode.) In addition, there are some circumstances where prebinding information cannot be updated or used. For details, see the following:

• Prebinding Your Application in Launch Time Performance Guidelines.

• The man pages for update_prebinding and redo_prebinding. (You can search for and view man pages in Xcode with Help > Open man page.)

For more information on distributing your software, see Software Distribution.

Source Trees

CodeWarrior supports the use of source trees, a kind of root path commonly used in projects that will be worked on by developers in different locations and on different machines. Source trees can be used to define common access paths and target outputs. Global source trees (defined in the CodeWarrior preferences) apply to all projects, while project source trees (defined in the Target Settings for a project) apply only to files in that project.

Xcode supports only a global source tree, defined in the Source Trees pane of the Preferences window (though it does also support search paths for headers, libraries, and frameworks, on a project basis).

When you import a CodeWarrior project (see Importing a Project), Xcode determines the location of the CodeWarrior root folder (commonly referred to as {Compiler} in CodeWarrior’s access paths). It then adds an entry to the Source Trees list in the Preferences window, with the Setting Name “CodeWarrior,” Display Name “CodeWarrior Folder,” and the specified path. If a Source Tree entry for CodeWarrior already exists, it is overwritten.

Depending on where CodeWarrior is located, a typical path will look something like /Applications/Metrowerks_CodeWarrior_8.0/Metrowerks CodeWarrior. This CodeWarrior-relative source tree is very useful for building projects that use PowerPlant.

Source Control

CodeWarrior provides a Version Control System (VCS) menu that supports Perforce and other systems through plug-ins. Plug-ins can provide features that are very specific to the particular system, but are not tightly integrated into CodeWarrior itself.

Xcode takes a different approach. It currently supports three systems: the open source standard Concurrent Versions System (CVS), Subversion, and Perforce. Whichever system you choose, the Source Code Management (SCM) menu has the same commands. The number of supported commands is deliberately kept limited, but the commands are more tightly integrated into the environment. You’ll find the most commonly used source control commands, but no access is provided to more specific (and possibly obscure) commands that are supported only by a particular system. This allows for a cleaner integration; for example, status output is more usefully integrated into the user interface.

PowerPlant

If you move a project that uses CodeWarrior’s PowerPlant framework to Xcode, you’ll have to build PowerPlant as part of the project. When you import such a project, Xcode should add all the required PowerPlant files to the new Xcode project. You’ll then have to supply a prefix file and make a few minor modifications to the PowerPlant source code to build successfully with GCC 4.0. These steps are described in Make Changes to PowerPlant.

Maintaining Parallel Projects in Xcode and CodeWarrior

This section provides tips on maintaining parallel projects in Xcode and CodeWarrior that operate on the same code base.

    #include <Carbon/Carbon.h>

#ifdef __MWERKS__

    // CodeWarrior-only code should go here

#endif

#ifdef __GNUC__

    // GCC-only code should go here

#endif