---

Creating a Project

Once you know what product you are working on, you need an Xcode project. If you are working on a new product, and do not already have an Xcode project, you can create one from scratch. Xcode provides project templates to help you create a wide variety of products.

If you are working on an existing product, you probably already have a project. If you have an existing Xcode project, you can simply open the project in Xcode, as described in “Opening and Closing Projects.” If you have an existing CodeWarrior project, you can import your project into a new Xcode project. Or, if you have an existing Project Builder project, you can simply open it in Xcode.

This chapter shows you how to create a new project and describes the available project templates. It also shows you how to import CodeWarrior, Project Builder, and ProjectBuilderWO projects.

In this section:

Choosing a Project Template
Creating a New Project
Importing a Project
Opening and Closing Projects

Choosing a Project Template

Fairly early in your design process, you make decisions related to the type of product (application, library, command-line tool, and so on) and language or languages (C, C++, Objective-C, Java, and others) you plan to use. For a Mac OS X product, you also decide which Apple technologies to use, and whether to use an application framework, such as Cocoa or Java.

Once you’ve resolved these issues, you’ll find that Xcode provides a wide variety of project templates to support your goals. Table 3-1 provides brief descriptions for the project templates currently supplied by Xcode. You can find similar descriptions when you select a project template in the New Project Assistant in Xcode. When you add a target to a project, you’ll get a selection of targets to choose from that is similar to the list of available project templates. For more information on targets and target templates, see “Creating Targets.”

The project template you choose specifies a default target and it also determines the default source files, resources, framework references, and other information that Xcode includes automatically in the project. A project generally contains all the information it needs to build a product for its default target. This includes a minimal set of source files that you can compile into a running product, as well as default build settings.

The project template names and descriptions should give you a good idea of which project template is right for your product. One way to learn more about a project template is to create a project with that template, examine its contents, and see what happens when you build it. Project templates may change, and new templates are added from time to time with releases of Xcode, but by trying out a template, you can easily examine its default contents in that version of Xcode.

Creating a New Project

To create a new project, choose File > New Project. Xcode displays the New Project Assistant, shown here.

The first screen of the assistant shows the available project templates; these are described in “Choosing a Project Template.” You can choose a project template from this list, or you can select Empty Project to create a new project with nothing in it.

When you select a template from this list, a brief description appears in the text field directly below the template list. If there is no text field visible, grab the resize control below the template list and drag it upward.

After you select a project template, click Next; Xcode displays the second screen of the assistant. In this screen, assign a name to the new project and select a location for the project folder. If you type in a path containing directories that do not exist on disk, Xcode will create those directories for you before creating the new project. By default, the Project Directory path is set to '~/' which specifies that the project directory be placed at the top-level of your home directory. When you click Finish, Xcode creates a new project from the specified template.

Importing a Project

If you already have existing code in another IDE, you can import your project contents into Xcode. Xcode provides an assistant for importing CodeWarrior and ProjectBuilderWO projects. Xcode also opens Project Builder projects. This section describes how to use Xcode’s project importer and open Project Builder projects in Xcode.

Importing CodeWarrior Projects

If you have existing code in a CodeWarrior project, you can use the Xcode importer to import your CodeWarrior project and create a corresponding Xcode project. This section gives a brief description of how to import a CodeWarrior project into Xcode and lists a few steps that you can take to make the conversion process easier. While this section assumes that you are converting a project that builds an application, many of the steps apply to other types of software as well.

Before You Import

To make it easier to get your project building in Xcode, you may need to make some changes to your project before you import it. Each of these steps is described in further detail in Moving Projects from CodeWarrior to Xcode.

1. Convert your code to use Carbon.

2. Set the Project Type setting of your CodeWarrior project to Application Package to build your application as a package.

3. Build the application in the Mach-O format. Mach-O is the native executable format in Mac OS X and is the only format supported by Xcode.

4. Remove unnecessary targets from the project.

Importing Your CodeWarrior Project into Xcode

To import your project:

• Choose File > Import Project, which opens the Import Project Assistant.

• Select Import CodeWarrior Project and click the Next button.

• Click the Choose button and navigate to the CodeWarrior project file to import (or type in the path and filename).

  You can specify a name for the new project in the New Project Name field. Otherwise, Xcode automatically uses the same name as that of the project that you are importing. The Xcode importer creates the new project in the same folder as the CodeWarrior project file.

• When you import a CodeWarrior project, Xcode determines the location of the CodeWarrior root folder (referred to as {Compiler} in CodeWarrior’s search path) and adds it to the Source Trees list in the Preferences window.

  Select Import “Global Source Trees” from CodeWarrior if you want the importer to add any global source trees from CodeWarrior’s preferences to the Source Trees list in Xcode.

• Select 'Import referenced projects' to import any additional CodeWarrior projects referenced by the project you are currently importing.

• Click the Finish button to dismiss the assistant and start the import.

  When the import is complete, the new project window opens.

Most projects will not build immediately; see Moving Projects from CodeWarrior to Xcode for more information on how to get your new Xcode project to build.

Converting a Project Builder Project

If you already have an existing Project Builder project, there is very little you have to do to get it converted to, and building in, Xcode. Xcode works seamlessly with Project Builder projects. You can simply open the project in Xcode, by double-clicking on the project (.pbproj) bundle, dragging the project bundle to the Xcode application, or using the Open command in Xcode and selecting the project bundle.

Note that if you also have Project Builder installed on your computer, double-clicking the .pbproj bundle will open the project in Project Builder. To open the project in Xcode, you will have to use one of the other methods mentioned here.

Once you have opened your Project Builder project in Xcode, it should build with little or no additional work on your part. If you wish to take advantage of some of Xcode’s more significant features, such as ZeroLink, Fix and Continue, and the like, you will have to convert the targets in your project to use the native build system. Xcode does not automatically upgrade the existing targets, which use Project Builder’s Jam-based build system, when you open the project. To learn more about converting native targets, see “Converting a Project Builder Target.”

Importing Projects From ProjectBuilderWO

Xcode also supports importing projects from ProjectBuilderWO. To import a ProjectBuilderWO project, do the following:

1. Choose File > Import Project.

2. From the Import Project Assistant, choose Import ProjectBuilderWO Project and click Next.

3. Type the path to the ProjectBuilderWO project in the ProjectBuilderWO Project field or click Choose to select the project from an Open dialog.

4. Type the name you want to use for the new Xcode project in the New Project Name field and click Finish. If you do not specify a different name, Xcode uses the name of the existing project.

Xcode imports the ProjectBuilderWO project and creates a new Xcode project file. Where possible, Xcode imports the targets in the ProjectBuilderWO project as native targets. If the ProjectBuilderWO project contains targets not supported by Xcode’s native build system, the importer imports those targets as Jam-based targets.

Opening and Closing Projects

To open any project, choose File > Open. To open a project you’ve recently used, select the project from the File > Recent Projects menu. To close a project, you can choose File > Close Project, or close the project window.

You can have Xcode automatically remember the state of a project’s windows and restore them when you next open the project. To do so, choose Xcode > Preferences, click General, and select “Save window state” in the Environment options. If this option is disabled, opening a project displays only the project window. If this option is enabled, opening the project restores the project window and any other open windows to the state they were in when you last closed the project.

---