BUILD SETTING PATH SYSTEM_APPS_DIR /Applications SYSTEM_ADMIN_APPS_DIR /Applications/Utilities DEVELOPER_DIR /Developer DEVELOPER_APPLICATIONS_DIR /Developer/Applications DEVELOPER_BIN_DIR /Developer/usr/bin DEVELOPER_TOOLS_DIR /Developer/Tools SYSTEM_LIBRARY_DIR /System/Library LOCAL_LIBRARY_DIR /Library USER_LIBRARY_DIR ~/Library XCODE_APP_SUPPORT_DIR /Library/Application Support/Apple/Developer Tools THE XCODEBUILD TOOL The development tools include an xcodebuild command - line tool for building Xcode projects. The xcodebuild tool is installed in your /usr/bin directory by the developer tools installer, so you do not have to add the /Developer/Tools directory to your shell path to use it. The installer also installs a man page for xcodebuild . Having the ability to build Xcode projects via a command - line tool provides a great deal of fl exibility in your development workfl ow. You can build complex shell scripts to build different product confi gurations automatically. You could schedule nightly builds of large projects. You can integrate Xcode projects into other make tools, like gnumake or Ant. It ’ s also used to defi ne custom build commands in the Organizer (see chapter 22). Besides being able to drive the build process externally, you can also use xcodebuild to add a layer of intelligence inside Xcode. Using custom build scripts and external build targets, you can invoke scripts that make decisions, and then build another target or project using xcodebuild . Here ’ s an example: one limitation of Xcode targets is that you can ’ t change the input fi les to a target based on a build confi guration. That is, you can ’ t have a target that links to one library when built using one build confi guration and a different library for another. You could easily create two targets: MyApp - Release and MyApp - Debug. A custom script can examine the build settings and build the appropriate target using something like xcodebuild - target MyApp - ${CONFIGURATION} . The possibilities are almost limitless. Using the xcodebuild Tool To use the xcodebuild tool, the working directory must be set to the project folder. The tool does not accept a path to a project folder or document elsewhere. When you execute xcodebuild , you can optionally specify the name of the project, the target, and the build confi guration to be built as arguments. If any are omitted, xcodebuild will choose a project, target, and build confi guration for you. The xcodebuild Tool ❘ 429 c17.indd 429c17.indd 429 1/22/10 12:51:23 PM1/22/10 12:51:23 PM Download at getcoolebook.com 430 ❘ CHAPTER 17 BUILDING PROJECTS xcodebuild reads and respects the Xcode preferences you’ve defi ned. However, preferences are stored on a per-user basis. If you run xcodebuild under a different user ID, namely root, the Xcode preferences used will be those of that other user. Unless you’ve run and confi gured the Xcode application while logged in as that user, there will be no Xcode preferences fi le, and xcodebuild will use the defaults for all settings. A project name can be specifi ed using the - project projectname argument. This name is the complete fi lename of the project document, including its extension. If this argument is absent, xcodebuild fi nds and builds the one and only project document in the folder. If there is more than one project, xcodebuild throws an error and stops. This argument is only needed for project folders that have multiple project documents. You can choose a target using the - target targetname argument. If this argument is omitted, the fi rst target defi ned in the project is built. For projects you intend to build using xcodebuild , arrange your targets so that your top - level aggregate target is the fi rst target in the Targets group. That way, you don ’ t have to specify a target for your most common builds. Alternatively, you can use either the - activetarget or - alltargets switch. The - activetarget switch builds the last active target set in the Xcode application. The - alltargets switch builds all of the targets in your project; something you can ’ t do in Xcode, except for clean builds. The - configuration configurationname switch selects a build confi guration to use. You can specify the build confi guration or use the - activeconfiguration switch instead. These switches select either the named build confi guration or the last active build confi guration set in the Xcode application. If both are omitted, the default build confi guration is used. Go to the Confi gurations tab of the project ’ s Info window to set the default build confi guration for your project. Two additional arguments are used to modify the build. The fi rst is the build action. This can be one of the values described in the following table. COMMAND DESCRIPTION build Builds the target or targets. clean Runs a clean build on the target or targets. install Performs a build, enabling all deployment postprocessing phases. This option sets the DEPLOYMENT_POSTPROCESSING build setting. You should defi ne the DSTROOT location if you want the fi nal products installed someplace other than the build folder. installsrc Copies the source of the project to SRCROOT . Rarely used. If you don ’ t specify any action, build is assumed. You can specify more than one action. The actions will be executed in order, just as if you had invoked the xcodebuild tool multiple times. For example, xcodebuild clean build fi rst runs a clean build followed by a normal build. c17.indd 430c17.indd 430 1/22/10 12:51:24 PM1/22/10 12:51:24 PM Download at getcoolebook.com You can also pass build settings to the xcodebuild tool using the following guidelines: Build settings passed as arguments to xcodebuild supersede any other build settings defi ned elsewhere. See “ The Scope of Build Settings, ” earlier in this chapter. The syntax for a build setting is SETTING_NAME=value . Each setting is a separate argument. The shell may require you to quote the contents of some build settings. You can include as many build settings as will fi t on the command line. The following listing shows xcodebuild being passed two build settings: DSTROOT and DEPLOYMENT_LOCATION : xcodebuild DSTROOT=/ DEPLOYMENT_LOCATION=YES install There are many other miscellaneous xcodebuild options. Three you might be interested in are listed in the following table: OPTION DESCRIPTION - version Outputs the version of the xcodebuild tool to stdout. - list List the names of the targets and the build confi gurations defi ned in the project. The active target and both the active and default build confi gurations are all noted. No build is performed. - help Outputs a concise summary of xcodebuild ’ s argument syntax. Compatibility xcodebuild is capable of building .xcodeproj (Xcode 2.1 and later) documents as well as earlier .xcode project documents. If you run xcodebuild without specifying a project document name, it fi rst searches for an .xcodeproj document and reads that if found. If there are no .xcodeproj documents present, it looks for an .xcode document. In the latter case, xcodebuild internally upgrades the .xcode document, turning it into an .xcodeproj document, and then builds using that .xcodeproj document. The intermediate .xcodeproj document exists only in memory, and is discarded once the build is complete. XCODE AUTOMATOR ACTIONS In addition to the xcodebuild tool, the Xcode Development Tools also install a suite of Automator actions, shown in Figure 17 - 37. ➤ ➤ ➤ ➤ ➤ Xcode Automator Actions ❘ 431 c17.indd 431c17.indd 431 1/22/10 12:51:27 PM1/22/10 12:51:27 PM Download at getcoolebook.com 432 ❘ CHAPTER 17 BUILDING PROJECTS There are actions to perform CVS source control actions (see Chapter 21), create installation package, and perform builds. The Build Xcode Project Action is just a wrapper that ultimately invokes the xcodebuild tool to perform the build, but the Automator action interface makes it far easier to confi gure and integrate the build with a larger workfl ow. The Build Xcode Project action expects an Xcode project document as its input. The action options let you choose the action (clean, build, and so on), specify a target, choose a build confi guration, and supply an arbitrary set of build settings. DISTRIBUTED BUILDS One of the more amazing features of Xcode is distributed builds. It ’ s not so much the technology that performs it, which is sophisticated to be sure, but how incredibly easy it is to set up and use. Distributed builds allow the compilation of source fi les to be distributed among a group of computers, where they can be compiled in parallel. Every build can call upon the resources of two or — if you have them — more than a dozen computers to simultaneously compile the fi les in your project. This allows a single developer to harness the power of other (probably) idle machines on his network, such as fi le servers. Teams of users can share and make more effective use of their resources. It ’ s also a great equalizer. A team member developing programs on a single - core MacMini can harness nearly the same power for his builds as the next developer, who ’ s using a multi - processor, multi - core system. FIGURE 17-37 c17.indd 432c17.indd 432 1/22/10 12:51:27 PM1/22/10 12:51:27 PM Download at getcoolebook.com Here are a few prerequisites and limitations to using distributed builds: All machines must be accessible via TCP/IP. All systems must be running the exact same version of the operating system and compiler. When you ’ re upgrading your operating system or Xcode, perform the upgrade on all of your development machines simultaneously. This ensures that there is no difference between compilers and the system frameworks between distributed machines. All computers must be of the same architecture. Intel computers can only distribute builds to other Intel - based systems. Distributed building only distributes the Compile Sources phase of native targets for C language fi les. This includes C, C++, and Objective - C. Java, AppleScript, Link, Copy Files, custom scripts, and Jam - based targets can ’ t be parallelized. Precompiling headers, linking, and product packaging are all performed on the local machine. To be effective, you need a fairly high - speed network. 100MB Ethernet is considered a minimum, with 1GB Ethernet or better preferred. You won ’ t get much benefi t from distributed builds over a wireless network. Remember too that FireWire can be daisy - chained to create a very high - speed TCP/IP network. Firewalls can block distributed builds. Computers employing fi rewalls must allow traffi c on ports 3632 and 7264. Using distributed builds couldn ’ t be easier. Every machine with Xcode installed can be a provider (will compile fi les for other developers), a client (will distribute builds to other providers), or both. Each client can also be selective about machines to which it distributes builds. Open the Distributed Builds pane of the Xcode Preferences of each development machine on the network. The Distributed Builds pane is shown in Figure 17 - 38. ➤ ➤ ➤ ➤ ➤ ➤ FIGURE 17-38 Distributed Builds ❘ 433 c17.indd 433c17.indd 433 1/22/10 12:51:28 PM1/22/10 12:51:28 PM Download at getcoolebook.com 434 ❘ CHAPTER 17 BUILDING PROJECTS Sharing Your System with Others In order to share your computer — offer to compile fi les for other developers — you must fi rst unlock the padlock in the lower - left corner. You are asked to supply an administrator username and password. Authenticating as an administrator allows Xcode to install the background services that provide distributed building. Check the box next to the Share My Computer for Shared Workgroup Builds option to make this computer available on the network to perform builds for other developers. The pop - up menu next to the option allows you to choose a process priority for the distributed build process. If you regularly perform time - sensitive, CPU - intensive, tasks such as multi - media processing, you might consider setting this to medium or low priority. Lowering the priority also gives local builds an edge over builds for other developers. Remember that process priority only comes into play when two or more processes are competing to use the CPU. If the computer is idle, it doesn ’ t matter what the priority is; the build will use all of the available CPU time. Xcode uses the distcc tool and distccd daemon to perform distributed builds. When you share your system with a workgroup, Xcode starts up a distccd daemon for each processor core in your CPU. These daemons run all the time; you don’t have to be running the Xcode application in order to build products for other workgroup members. Distributing Your Builds to the Workgroup In the lower portion of the pane is a list of computers you can distribute builds to. Available computers are organized into sets, listed on the left. The Bonjour set is a smart set that lists all active build providers on the local subnet. This set is assembled using the Bonjour (ZeroConfi g) protocol, and automatically adjusts to refl ect the available build providers on the local subnet. For most installations, this is the only set you will need. The computers in the list display their status and suitability. The Host column contains the IP address of the system. The OS and Resources columns list the versions of the provider ’ s operating system and compilers. You can only distribute a build to a computer with the same version of OS and compiler. The compiler in question will be the compiler required by the target being built. In the example in Figure 17 - 38, the computer marchhare.local has a compatible version of gcc 4.0.1, but an incompatible version of gcc 4.2.1. This computer could accept builds for targets that use the gcc 4.0.1 compiler, but not ones that required gcc 4.2.1. The computer mini.local, on the other hand, is running an older operating system and cannot accept any builds. Incompatible computers, tools, and Xcode installations are listed in red. If you want to limit the distribution of builds to a specifi c subset of local computers, or if you want to add computers that do not appear in the Bonjour list, you need to create a custom set. Click the + button below the list of sets to create a new set, and then give the set a name. You can also duplicate an existing set. Selecting a set, or sets, lists only the computers in those sets. The list is always a c17.indd 434c17.indd 434 1/22/10 12:51:29 PM1/22/10 12:51:29 PM Download at getcoolebook.com union of the sets selected, so computers in multiple sets are listed only once. To delete a set, select it and click the – button. You cannot delete the Bonjour set. To add a computer to a custom set, either drag a computer from the list into the set, or click the + button below the list with that set selected. Enter the address of the new system, using either a domain name or a numeric address. Xcode adds the new system to every set currently selected and automatically queries the system to discover its status and suitability. To remove a computer from a set, select it in the list and click the – button. You cannot add or remove computers from the Bonjour set. Consequently, having the Bonjour set selected disables both the add and remove buttons for all sets. To add or remove computers from the list, select only custom sets. To distribute your builds to other computers, check the box next to Distribute Building Via Shared Workgroup Builds, and then check the box next to each set that you want Xcode to include in distributed builds. The computers in all of the checked sets will be considered when Xcode distributes builds to other computers. That ’ s all there is to it. If you ’ ve elected to distribute your builds with other computers, your next build will employ distributed building. Figure 17 - 39 shows the build of a large project on a laptop computer. Normally, it would only compile one or two fi les at a time, but with distributed building, it can now compile a score of fi les simultaneously by exploiting the other computer systems in its workgroup. FIGURE 17-39 Distributed Builds ❘ 435 c17.indd 435c17.indd 435 1/22/10 12:51:34 PM1/22/10 12:51:34 PM Download at getcoolebook.com 436 ❘ CHAPTER 17 BUILDING PROJECTS SUMMARY Controlling the build process is a critical step in any successful development project. You should now be able to start and stop builds at will, examine the results of the build, and locate errors that occurred while building. Using build settings and build confi gurations, you can customize many features of the compiler, linker, and Xcode itself. Using build setting layers and build confi gurations, you can create complex sets of build settings, allowing you to customize specifi c features of specifi c targets for specifi c variations. Just as important as control is the speed of your development. By learning to enable such features as prefi x headers and distributed builds, you can radically reduce the amount of time it takes to build and test your application. Even after building your project successfully, you ’ re still not quite done. The next chapter shows you how to run and test your application from within Xcode. c17.indd 436c17.indd 436 1/22/10 12:51:34 PM1/22/10 12:51:34 PM Download at getcoolebook.com . shown in Figure 17 - 38 . ➤ ➤ ➤ ➤ ➤ ➤ FIGURE 17 -38 Distributed Builds ❘ 433 c17.indd 433 c17.indd 433 1/22/10 12:51:28 PM1/22/10 12:51:28 PM Download at getcoolebook.com 434 ❘ CHAPTER 17 BUILDING. to the xcodebuild tool, the Xcode Development Tools also install a suite of Automator actions, shown in Figure 17 - 37 . ➤ ➤ ➤ ➤ ➤ Xcode Automator Actions ❘ 431 c17.indd 431 c17.indd 431 1/22/10. systems in its workgroup. FIGURE 17 -39 Distributed Builds ❘ 435 c17.indd 435 c17.indd 435 1/22/10 12:51 :34 PM1/22/10 12:51 :34 PM Download at getcoolebook.com 436 ❘ CHAPTER 17 BUILDING PROJECTS SUMMARY