4 The Project WHAT'S IN THIS CHAPTER? Creating a project and defi ning where it ’ s stored Choosing the right project template Juggling multiple projects Confi guring project - specifi c properties Now that you can navigate around the Xcode interface and customize its view, it ’ s time to learn how projects are created, stored, opened, and closed. Every project has two essential parts: the project document and the project folder . The project document, Simple.xcodeproj in Figure 4 - 1, contains all of the structure, references, layout, settings, preferences, and other attributes that defi ne the project. ➤ ➤ ➤ ➤ FIGURE 4-1 c04.indd 41c04.indd 41 1/21/10 1:20:30 PM1/21/10 1:20:30 PM Download at getcoolebook.com 42 ❘ CHAPTER 4 THE PROJECT The folder that contains the project document is the project folder, in this case the Simple folder. This is the root location for the project. The project document and project folder usually have the same name, but that ’ s not a requirement, and a project folder can contain multiple project documents. CREATING A NEW PROJECT You create a new, empty project using the File ➪ New Project command (Shift ϩ Command ϩ N). This opens the New Project Assistant, shown in Figure 4 - 2. FIGURE 4-2 “ Empty ” is a bit of a misnomer. The New Project Assistant creates a new project using one of the many project templates that are built into Xcode. The project it creates will be far from empty, and may actually have quite a lot in it before you even begin. The templates try to provide the basic framework — a main() function, an empty subclass of NSDocument , a menu bar with all the standard items, required driver entry points, scores of build settings, and so on — all appropriate to the type of project you are creating. The templates also include the libraries and frameworks a project of that type is expected to need. Some templates go the extra mile and include libraries and frameworks that you ’ re just likely to need. These frameworks are referred to by the project, but are not members of any targets. Being included in the project already, it ’ s a trivial matter to add them to a target; this is quite a bit easier than being forced to identify and add the framework yourself. c04.indd 42c04.indd 42 1/21/10 1:20:33 PM1/21/10 1:20:33 PM Download at getcoolebook.com The Xcode templates give you a huge head start in getting your project going, because so much of the basic groundwork is already done for you. In fact, most projects will build and run (albeit lacking any real functionality) as soon as they are created. Remember that there ’ s nothing done by the templates that will lock your project into a particular technology or confi guration. Any project can be modifi ed to produce any other project. You can obtain the same result by starting with an empty project and confi guring it appropriately, it ’ s just a lot more work. Choosing a Template The fi rst step in creating a new project is to choose the template that most closely matches the type of program or product you want to create. The templates are organized into broad categories on the left. Start by selecting a category, say Mac OS X Application, and a list of project templates appears in a panel on the right. Many templates include additional options for refi ning the kind of project you want to create. The Cocoa Application template asks whether your application will be document based, will use Core Data for storage, and whether you plan to include a custom Spotlight Importer plug - in that will integrate your application ’ s data with the Spotlight search facility. The options you choose infl uence what classes, boilerplate code, and targets are included in your new project. The Command Line Tool project, pictured in Figure 4 - 3, has a completely different kind of question. It wants to know in what kind of language you plan to write your command - line tool. The choice here will determine what kind of source fi les are initially added (C, C ϩ ϩ , Objective - C), what headers it will include, and with which frameworks it will link. FIGURE 4-3 Creating a New Project ❘ 43 c04.indd 43c04.indd 43 1/21/10 1:20:34 PM1/21/10 1:20:34 PM Download at getcoolebook.com 44 ❘ CHAPTER 4 THE PROJECT If you have no idea where to begin, you might want to read more about the kinds of programs you can develop for Apple platforms at http://developer.apple.com/gettingstarted/ . If you ’ re also working through a programming tutorial, say on iPhone development, the tutorial should indicate which template to choose. Naming the New Project After you have selected a project template, click the Choose button. A save dialog box appears prompting for the name and location of the new project. The location you choose determines where the new project folder is created. Inside the newly created project folder, Xcode creates a project document along with whatever additional source fi les and folders the template defi nes. This might be a single fi le or twenty. The project document and folder will have the same name. Choosing an existing project folder for the location just creates a new project folder inside the existing project folder. If you want to have multiple projects share the same project folder, create a new project outside the existing one, then manually migrate the contents of the new project into the existing one. It ’ s possible to “ overwrite ” a project by creating a new project with the same name and location. In this situation, Xcode warns that you are replacing an existing project. It then proceeds to create new fi les inside the existing project folder, warning you about template fi les that will overwrite existing ones. I wouldn ’ t recommend trying this, because the benefi ts are dubious and it ’ s hard to predict what existing fi les would be overwritten. What ’ s in a Name? The project ’ s name does more than just name the project folder and document. Your new project is customized in numerous places with the name you give the project. The easiest explanation is an example. Say that you are excited about creating a new Xcode project, and your exuberance infl uences your choice of project names, as shown in Figure 4 - 4. FIGURE 4-4 c04.indd 44c04.indd 44 1/21/10 1:20:34 PM1/21/10 1:20:34 PM Download at getcoolebook.com The project folder and documents were created from the iPhone OS, Tab Bar Application template. Looking at the project contents, shown in Figure 4 - 5, you fi nd some rather convoluted names. FIGURE 4-5 The project, shown in Figure 4 - 5, contains a class named Wow__My_first_tab_bar_iPhone_ AppAppDelegate . You might be happy living with the goofy application and target names, but really long class names like this will eventually be awkward. You have two choices: You can refactor the class names to something more reasonable, or you can throw the project away and try again. When creating your project, consider what else you are naming, and what you might want to rename. Ultimately, the name of your project should describe what it produces. I recommend naming your project after the application it produces, and then fi xing up class and fi lenames as needed. Who ’ s _MyCompanyName_? Beyond just using the project name to customize fi le and class names, Xcode uses a number of other values to fi ll in variables in the project template. Similar substitutions are performed when creating new project fi les. If you ’ ve created a few projects or fi les already, you ’ ve probably noticed the author credits that get inserted at the beginning of each source fi le, as shown in Figure 4 - 6. Creating a New Project ❘ 45 c04.indd 45c04.indd 45 1/21/10 1:20:39 PM1/21/10 1:20:39 PM Download at getcoolebook.com 46 ❘ CHAPTER 4 THE PROJECT The comments include today ’ s date, your name, and a copyright statement that includes your company ’ s name. The company name will either be your company ’ s name or the placeholder __MyCompanyName__ . Xcode gets your name from your user account information. It obtains your company ’ s name, rather cleverly, from your address book. If the company name in new projects is incorrect or missing, here ’ s how to fi x it: 1. Open the Address Book application. 2. Locate your address card, or create one for yourself if one doesn ’ t exist. 3. Fill in the card ’ s Company fi eld, if empty. 4. Select the card in the Name column and choose the Card ➪ Make This My Card command. The address book identifi es a single card as being “ you. ” You can jump directly to this card using the Card ➪ Go To My Card command. The thumbnail image of your card will show the word “ me ” in the lower left - hand corner, as shown in Figure 4 - 7. Xcode uses the company name of this card to customize your source fi les. FIGURE 4-7 FIGURE 4-6 c04.indd 46c04.indd 46 1/21/10 1:20:40 PM1/21/10 1:20:40 PM Download at getcoolebook.com Older versions of Xcode would obtain your company ’ s name from an obscure ORGANIZATIONNAME macro stored in Xcode ’ s preferences fi le, which had to be edited manually. Thankfully, those days are behind us. Closing a Project To close a project, close the project window or choose Close Project (Control ϩ Command ϩ W) from the File menu. Changes made to the project ’ s structure or attributes are always immediate, so there is no confi rmation dialog box asking whether you want to save the changes to your project. However, if any source fi les in the project have been modifi ed but not yet saved, you are prompted to save or discard the changes made to those. Closing a project closes all of the windows associated with that project. Windows that contain project content (editor windows, the build window, the Class Browser, and the debugger) are all closed along with the project window. Generic utility windows (Activity Viewer and Help) that do not apply to a particular project remain open. Opening One or More Projects To reopen a project, open the project document in the Finder, choose the project from the File ➪ Recent Projects menu, or choose the project from the Recent Projects list in the Welcome to Xcode window. Two Xcode preferences, both in the General tab, affect how and when projects are reopened: The Reopen Projects on Xcode Launch option automatically reopens projects that were open when you last quit Xcode. The Restore State of Auxiliary Windows option restores the position and size of all the windows that were open when you closed the project. Without this option, only the project window is reopened and any new windows open at default positions on the screen. You can have several projects open simultaneously, but Xcode focuses on only one project at a time. Whenever a project window, or any project - specifi c window, is the front (active) window, that project becomes the active project . Commands that act on a project, which include most of the commands in the Project, Build, and Debug menus, apply to the active project. You can (usually) tell which project is active by looking at the Window menu. The Window menu in Figure 4 - 8 shows two projects — LogInLogOutNotifi cationTest and Sketch — open at the same time. All of the windows belonging to the LogInLogOutNotifi cationTest project are listed immediately under the project ’ s name. This includes the project window itself and the main.c source fi le being edited in a second window. Note that if you are editing a fi le in a pane of the project ’ s window, the name of the project window changes to ➤ ➤ FIGURE 4-8 Creating a New Project ❘ 47 c04.indd 47c04.indd 47 1/21/10 1:20:40 PM1/21/10 1:20:40 PM Download at getcoolebook.com 48 ❘ CHAPTER 4 THE PROJECT that of the fi le, followed by the project name. Therefore, the title of the project window may or may not be the name of the project, depending on its state. The check mark in the Window menu indicates that main.c is the currently active window and, by inference, LogInLogOutNotifi cationTest is the currently active project. Selecting a window from the menu brings it to the front, making it, and its project, active. Selecting the name of the project itself brings that project ’ s window to the front. If the front window does not belong to any project, such as a window containing documentation or the Activity Viewer, things can get a little confusing. Some windows cause Xcode to disable all project - specifi c commands. In effect, no project is active until you switch back to a window belonging to one of the open projects. Other windows, like the documentation browser, don ’ t alter which project is active, but also don ’ t indicate which project was active, so it ’ s impossible to determine easily which project is still active. You might also become disoriented when editing a source fi le that is shared by two projects. A window belongs to the project you used to open the window, even if the fi le in that window is part of another project that is also open and active. When in doubt, activate the project window before starting a build or debugging session, or simply keep windows belonging to other projects closed when they are not the focus of your development. Renaming and Relocating Projects You can easily rename the project folder or the project document after the project is created. To rename either, fi rst close the project. In the Finder, rename the project folder or project document. Do not alter or remove the .xcodeproj suffi x of the project document. Reopen the project by opening the project document. The Project Structure Group in the Groups & Files list will refl ect its new name. The folder containing the project document is always the project folder. Moving a project document to another folder implicitly changes its project folder. The reason this may be signifi cant has to do with the way in which references to source fi les are kept. References to fi les used in your project can be relative to the location of the project folder. There are also other kinds of references, all explained thoroughly in Chapter 5. Changing the name or location of the project folder may affect these references. Moving the entire project folder to some other location is the safest relocation possible. This only breaks the project if it contains project - relative references to items outside the project folder, or absolute references to items inside the project folder. Both of these conditions are unlikely. Moving the project document to some other location can be hazardous. The most signifi - cant thing this does is change the project folder. Absolute references outside the project folder won ’ t be affected, but all project - relative references (both inside and out) will prob- ably break. Regardless, there are times when you will want to do this. There are very good reasons to have multiple project documents in the same project folder. See the “ Build Location ” section in Chapter 17 for some of them. ➤ ➤ c04.indd 48c04.indd 48 1/21/10 1:20:41 PM1/21/10 1:20:41 PM Download at getcoolebook.com Upgrading Projects Xcode 3.2 can open and use projects created with Xcode versions as old as Xcode 2.4. Older project formats might not support all of the current features, and Xcode will warn you if you try to use them. See the next section, “ Project Settings, ” about maintaining backward compatibility with older versions of Xcode. To work with a project created with Xcode versions 1.5 through 2.3 requires that the project be upgraded. When you open one of these old projects, Xcode presents a dialog box like the one shown in Figure 4 - 9. If you choose to upgrade the project, Xcode prompts you to provide the name of a new project document. Note that this is just the name and location of the project document — not the project folder — so it should be saved inside the project folder you are upgrading. Xcode will create a new, modern, project document and open it. The project folder will now have two project documents, as shown in Figure 4 - 10. FIGURE 4-10 Creating a New Project ❘ 49 FIGURE 4-9 If you only upgraded the project to view it, dispose of the new project when you are done. Otherwise, trash the obsolete project document. It is unlikely that you will want to keep both project documents, unless you plan to maintain them in parallel. Xcode no longer supports project documents created with versions of Xcode before 1.5, any version of Project Builder (Xcode ’ s ancestor), nor will it import CodeWarrior projects anymore. If you need to start with one of these ancient projects, either download and install Xcode 2.4 or 3.0 and use that as in inter- mediate step to import/upgrade the old project, or start with a new project and import all of the source fi les from the old project. It ’ s hard to predict which will be quicker. c04.indd 49c04.indd 49 1/21/10 1:20:42 PM1/21/10 1:20:42 PM Download at getcoolebook.com 50 ❘ CHAPTER 4 THE PROJECT PROJECT SETTINGS Now that you can create projects, take a look at the attributes of the project itself. Choose Project ➪ Edit Project Settings to open the project ’ s Info window. This is identical to opening the Info window for the project source group. The General tab of a typical project is shown in Figure 4 - 11. FIGURE 4-11 Here ’ s a brief overview of the General project settings: The topmost pane shows the location of the project and its source control root directories. Source control and root directories are described in Chapter 21. The Project Format establishes the earliest version of Xcode that ’ s compatible with this proj- ect document. Setting this to Xcode 3.0 means that this project can be opened by Xcode 3.0 and 3.1, but not 2.4. It also means you can ’ t use Xcode features that were added in 3.1 or 3.2 that aren ’ t supported by 3.0. If you lower the format level, there may be features you ’ ve already used that aren ’ t compatible with the old version. The Show Confl icts button will describe what features are incompatible. The next section sets the build locations for this project. Build locations are described in Chapter 17. ➤ ➤ ➤ c04.indd 50c04.indd 50 1/21/10 1:20:54 PM1/21/10 1:20:54 PM Download at getcoolebook.com [...]... this chapter, you learned how to create new projects More important, you now know how to choose a project template that will get you started in the right direction You can open, close, rename, relocate, and switch between multiple projects Finally, you know where to set the project attributes — although most of those attributes won’t make much sense until you get to the targets, build, and source control... Chapter 17 for a detailed explanation of build configurations and build settings That last tab is for comments The project, targets, and most other items in the project have a comments field This is for your personal use You can keep whatever information you fi nd useful here — Xcode will store the comments in the project document You might want to include build instructions for other developers, to -do lists,...Summary ❘ 51 ➤ The Organization Name is an alternate company name for this project When you create a new project, Xcode uses the company name in your address book card, as described earlier in “Who’s _MyCompanyName_?” To use a different company name in fi les created just for this project, supply an alternate name . of Xcode that ’ s compatible with this proj- ect document. Setting this to Xcode 3. 0 means that this project can be opened by Xcode 3. 0 and 3. 1, but not 2.4. It also means you can ’ t use Xcode. edited manually. Thankfully, those days are behind us. Closing a Project To close a project, close the project window or choose Close Project (Control ϩ Command ϩ W) from the File menu. Changes. document in the Finder, choose the project from the File ➪ Recent Projects menu, or choose the project from the Recent Projects list in the Welcome to Xcode window. Two Xcode preferences, both