The multi - fi le search window is described in Chapter 8. It ’ s identical to using the project fi nd window, except that the target fi le set is permanently set to In Selected Organizer Folder. Taking Snapshots You can take and restore snapshots of any top - level folder in the organizer. To take a snapshot, choose Make Snapshot from the action menu. To review, compare, restore, or delete a snapshot, choose Snapshots from the action menu. Using snapshots in the organizer is identical to using snapshots in a project, described in Chapter 11. When taking snapshots from within your project, the project folder gets copied. In the organizer, the snapshot is whatever top - level folder you ’ ve selected in the organizer. Organizer snapshots and project snapshots are maintained independently. That is, making a snapshot of a project folder in the organizer does not add a snapshot to that project’s snapshot window, and vice versa. USING ORGANIZER ACTIONS The action buttons in the toolbar execute action scripts that (can potentially) perform an almost unlimited variety of tasks. Actions can only be defi ned for folder items in the organizer. A newly added non - project folder will (probably) have no actions defi ned. Xcode automatically generates a number of useful actions whenever you add a project folder to the organizer. You are free to use, modify, remove, and add your own actions, as you ’ ll see in the next few sections. Each action toolbar button is a combination of a button and a menu. Click and hold the button — don ’ t Right/Control + click the button, you ’ ll only get the toolbar menu — to reveal its action menu, as shown in the upper left of Figure 22 - 2. It lists the actions defi ned for the selected folder along with an Edit Actions command. Notice that one of the actions in the menu is checked. This is the default action . If you simply click the action button, this is the action that will be performed. Executing a different action in the list also makes it the new default. Just remember that clicking the button will perform the last selected action again. Automatically Created Actions When you add a project folder to the organizer, Xcode generates a number of actions automatically — the exception to this is described in the “ Preserving and Sharing Actions ” section later in this chapter. The actions it generates are based on the project documents found in the project folder. After adding a project folder you will fi nd: The Build button has a build action for each build confi guration in the project. The Clean button has a clean action and a clean all action for each build confi guration in the project. ➤ ➤ Using Organizer Actions ❘ 621 c22.indd 621c22.indd 621 1/21/10 4:38:01 PM1/21/10 4:38:01 PM Download at getcoolebook.com 622 ❘ CHAPTER 22 USING THE ORGANIZER The Run button has a run action and a debug action for each build confi guration in the project. The Action button has an install action for the project. Normally, a project folder only has a single project document. If your project folder has multiple project documents, a complete set of actions is added for each project. Thus, a folder with two project documents, each with three build confi gurations, will result in six actions being generated for the Build button and 12 actions in each of the Clean and Run buttons. The progress and output of the Build, Clean, and Run buttons appear in a separate organizer window. The output of Action button actions is determined by the action (described later). All organizer actions run scripts — either shell scripts or Automator actions — that run, more or less, independently of Xcode. The build actions are performed by the xcodebuild tool (see Chapter 17). Starting a build action does not open the project in Xcode, nor will it start building an open project in Xcode. The build runs in a separate process and an organizer build window collects the results. Notice also that ’ s there ’ s no mention of targets, or the active executable in the automatically generated actions. The actions generated by Xcode build the default target and use the default executable. If you want some control over those, you ’ ll want to customize your actions, as described in the next section. Creating Custom Actions Choose the Edit Actions command from the action toolbar button ’ s menu to redefi ne its actions. The Edit Actions command presents an action sheet, as shown in Figure 22 - 3. ➤ ➤ FIGURE 22 - 3 c22.indd 622c22.indd 622 1/21/10 4:38:13 PM1/21/10 4:38:13 PM Download at getcoolebook.com The action sheet lists the actions defi ned for the button. Here you can: Rename, reorder, and delete actions Assign action to a keyboard shortcut Edit the defi nition of an action Create new actions Rename the action ’ s name in the menu by clicking its name. Reorder it by dragging items in the list. Choose the New Separator command from the Add button menu in the lower - left corner of the window to insert a gray menu separator. Choose Edit ➪ Delete or click the – button at the bottom to delete an action or separator. To assign an action a keyboard shortcut, select the shortcut cell in the ⌘ column and type the key combination you want to assign. If the combination you ’ ve chosen confl icts with one already assigned, Xcode will alert you at the bottom of the window, as shown in Figure 22 - 3. Choose a different combination and press it (the key combination). Click the – button next to the shortcut to delete a key combination — pressing the Delete key simply assigns the Delete key to the action. To assign multiple shortcuts to the same action, click the + button. Keyboard shortcuts are only active when the folder item that owns the action is selected in the organizer. Thus, you can assign the same keyboard shortcut to one action of every top - level folder in your organizer without creating any shortcut confl icts. The defi nitions of actions are edited in the right side of the action sheet. What appears there depends on the type of action, explained in the next section. The actions automatically generated by Xcode are all shell script actions. The script of the action is displayed in an editing pane, where you are free to customize it in any way you see fi t. For example, you may want to add a - target argument so that the action consistently builds the same target, rather than relying on the project ’ s last active target setting. Just remember to update the action ’ s title appropriately if you signifi cantly alter what it does. You can create a new action by choosing New Shell Script, Add Script File, or Add Automator Workfl ow from the Add menu button. The different types of actions and how they can be customized are described in the next few sections. The Anatomy of an Action Every action has four attributes: The shell script or Automator action to execute A working directory An input source An output destination The script is what defi nes the action. You have all of the POSIX and Automator tools at your disposal, which gives you an immense amount of latitude in designing your action. ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ Using Organizer Actions ❘ 623 c22.indd 623c22.indd 623 1/21/10 4:38:16 PM1/21/10 4:38:16 PM Download at getcoolebook.com 624 ❘ CHAPTER 22 USING THE ORGANIZER To some degree, the distinctions between the Build, Clean, Run, and Actions menus are purely taxonomic. You can attach a script that builds your project to the Action button and a script that cleans your project to the Build button. The different buttons do impose different constraints, consistent with their intended purpose, but your scripts are in no way limited to the implied purpose of the button to which they’re attached. The Directory setting of the script is the working (default) directory that ’ s set before the script is run. Action directories are described after the section “ The Action Folder Hierarchy. ” The input and output sources are different depending on which button you attach the action to. Actions in the Build, Clean, and Run buttons have no input and their output is always directed to the details pane or a new organizer window. Scripts in the Actions menu have an optional input source and a number of choices for output destinations. Action Types The three types of actions are described in the following table: ACTION TYPE DESCRIPTION Shell Script Executes a shell script that ’ s part of the action defi nition. Script File Runs an existing executable script fi le. Automator Workfl ow Runs an existing Automator workfl ow document. The script of either a shell script or script fi le action can be any executable POSIX script. The script interpreter is typically the default shell ( /bin/sh ), but could just as easily be bash , tcsh , perl , or ruby . The Run button is an exception; the settings for a shell script in the Run button menu allow you to choose an executable and provide it with a list of command - line arguments — presumably the executable that you want launched. You can choose an optional debugger to attach to the process. To run an arbitrary script, use a script fi le action or direct the shell to launch an existing script. The Build, Clean, and Run buttons distinguish themselves by setting the ACTION environment variable before they start a script. Your script can test this environment variable for the values BUILD , CLEAN , or RUN and adjust its behavior. This allows you to create a single script that behaves differently depending on which organizer button it ’ s attached to. For example, a script attached to the Build button could build a complex product and stop, but when attached to the Run button could perform the same build and then immediately launch it. The Action Folder Hierarchy Actions can be attached to any folder in the organizer. When you select a folder in the organizer, the actions that appear in the action toolbar buttons are an aggregate of the actions attached to that folder and all of the actions attached to any of its enclosing folders. Take the example project shown in Figure 22 - 4. c22.indd 624c22.indd 624 1/21/10 4:38:17 PM1/21/10 4:38:17 PM Download at getcoolebook.com FIGURE 22 - 4 The MyProject project folder contains a Classes subfolder, which itself contains Controllers , Data Models , Utilities , and Views subfolders. Actions have been attached to the MyProject , Classes , and Data Models folders — these folders appear with a “ tool ” stamp on their folder icon. When you select the Data Model folder and open the Build action menu, as shown in Figure 22 - 4, the menu includes all of the actions defi ned for the MyProject , Classes , and Data Models folders, organized by the folders that defi ne them. If you had selected the Classes or Controllers folder, only the actions for the MyProject and Classes folders would have been listed. When you ’ re editing the contents of an action toolbar button, a navigation bar appears at the top of the action sheet. Use this to navigate to the actions attached to enclosing folders. An example is shown at the top of Figure 22 - 5. Action Directory The working directory is set to a specifi c path before the action ’ s script or workfl ow executes. By default, it ’ s the directory of the item that owns the action, but can be any of the following: ACTION DIRECTORY DESCRIPTION Defi ning Organizer Item The folder in which the action is defi ned Selection The selected folder in the organizer Top - Level Organizer Item The highest enclosing folder in the organizer; the folder item you added to the organizer Home Directory Your account ’ s home folder File System Root The root directory Using Organizer Actions ❘ 625 c22.indd 625c22.indd 625 1/21/10 4:38:23 PM1/21/10 4:38:23 PM Download at getcoolebook.com 626 ❘ CHAPTER 22 USING THE ORGANIZER The Defi ning Organizer Item is the folder where the action is defi ned. This choice is appropriate when the action performs something — like a build — that ’ s permanently associated with the folder to which it ’ s attached. This is the default setting and the setting used by all automatically generated actions. The Selection and Top - Level Organizer Item choices allow your action to play off the hierarchical organization of action folders. Selection sets the directory to the selected folder in the organizer, which might not be the folder where the action is defi ned. This allows you to create an action that can be individually applied to different subfolders. In the example in Figure 22 - 4, the Classes folder defi nes a Localize Strings action. By setting its directory to Selected, the action will run on the selected folder. This allows you to choose an individual source folder (like Views ) and run the enclosed action (from Classes ) on just the contents of that folder. The Top - Level Organizer Item is just the opposite of Selection. It sets the directory to the highest enclosing folder in the organizer, essentially anchoring itself in the folder you added to the organizer — never any of the subfolders that it contains. Home Directory and File System Root are alternatives that ignore the organizer folder structure and set the working directory to your home folder ( ~ ) or the POSIX fi le system root ( / ). Input and Output Only actions attached to the Action button can specify where they get their input and what happens to the script ’ s output. For all other action buttons, scripts receive no input ( /dev/null ) and their output is captured in a build window (Build and Clean) or a console window (Run). Action input can be set to either Selection or No Input, as shown in Figure 22 - 5. FIGURE 22 - 5 c22.indd 626c22.indd 626 1/21/10 4:38:24 PM1/21/10 4:38:24 PM Download at getcoolebook.com Selection doesn ’ t mean that the contents of the selected item are piped to the script. It means that the path of the selected item is piped to the script. This allows you to write action scripts that act on individual fi les, but might require some fi nesse in obtaining that information. The example shown in Figure 22 - 5 presents a simple action that counts the lines, words, and characters in the selected fi le. To accomplish this, it obtains the path of the selected fi le in the organizer using the statement file= “ $(cat) ” . This bash statement pipes the contents of stdin into a literal string, and then assigns it to the file variable. The output of an action script ( stdout ) can be directed to any of the following destinations: Discard Output Display in Alert Place on Clipboard Open in New Document Open as HTML The default is Open in New Document and presents the output of your action in either the organizer details pane or a new window. The remaining choices are self - evident. Be careful when choosing Display in Alert that the output of your script is never too verbose. Xcode can optionally direct any error messages ( stderr ) from your script to one of the following destinations: Ignore Errors Display in Alert Place on Clipboard Merge with Script Output Ignore Errors discards the stderr output. Merge combines stderr with stdout . The rest take independent action with any error messages. Note that setting both output and errors to either Display in Alert or Place on Clipboard is equivalent to setting errors to Merge with Script Output. Preserving and Sharing Actions Deleting a top - level item from the organizer discards all actions defi ned for it, or any of its enclosing folders. If you add the folder back to the organizer, only the automatically generated actions will appear. This is a shame, because you might have put a lot of thought and effort into those actions. You can preserve your actions, automatically restore them in the future, and share your actions with other developers by fi rst exporting your actions to an .xccommands fi le. To export a set of actions, follow these steps: 1. Defi ne the actions for an organizer folder. 2. Select the folder in the organizer. ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ Using Organizer Actions ❘ 627 c22.indd 627c22.indd 627 1/21/10 4:38:24 PM1/21/10 4:38:24 PM Download at getcoolebook.com 628 ❘ CHAPTER 22 USING THE ORGANIZER 3. Choose the Export Actions command from the actions menu. 4. Give the .xccommands fi le a name and save it in a folder — the obvious choice being the one where you exported the commands, but it can be any folder. Importing and sharing your actions is devilishly simple. Place the exported .xccommands fi le in a folder. The next time you add a folder to the organizer, here ’ s what happens: Xcode looks for an .xccommands fi le in each folder it adds to the organizer. If it fi nds an .xccommands fi le, the fi le is imported and defi nes the actions for that folder. An .xccommands fi le overrides any automatic actions that would normally be generated by Xcode. Only the fi rst .xccommands fi le found is imported per folder. To preserve the actions you ’ ve defi ned for a project, simply export your actions to an .xccommands fi le and save it in that project ’ s folder. The next time you, or anyone, adds that project folder to the organizer, your custom set of actions will appear. Action Ideas The use of actions is almost unlimited, but here are a few of my favorites: Clean builds of a specifi c target and confi guration: The script performs a clean build, immediately followed by a full build. Release builds: Perform a clean build of the project, and then package the resulting product in a disk image, archive, or Installer package. If your product release process isn ’ t completely automated, it should be. Tag releases in source control: My script, shown here, extracts the product version from a header fi le in the project, then uses that value to tag the entire project in the Subversion repository. Once I ’ ve built my release product and am happy with the results, I use this action to tag it in source control. #!/bin/bash PROJ_DIR="${PWD}" PROJ_NAME="$(basename "${PROJ_DIR}")" # Extract the short version string from the source fi le VERSION=$(awk '/#defi ne.*VERSION_SHORT[ \t]/ { print $3 }' "${PROJ_DIR}/Version.h") echo "version ${VERSION}" REPOS="svn+ssh://mini.local/Users/Shared/Subversion/${PROJ_NAME}" TAG=$(tr '.' '-' < < < ${VERSION}) echo "creating tag release-${TAG}" svn copy -m "Release ${VERSION}" "${REPOS}/trunk" "${REPOS}/tags/ release-${TAG}" Automating your workfl ow will make you more productive and your development more consistent. The organizer is the perfect place to collect and manage those processes. ➤ ➤ ➤ ➤ ➤ ➤ ➤ c22.indd 628c22.indd 628 1/21/10 4:38:25 PM1/21/10 4:38:25 PM Download at getcoolebook.com DEVICES The Devices and iPhone Development groups in the organizer are designed specifi cally to support the special needs of iPhone and iPod developers. Much of the information in these two groups overlap. The difference is in their perspective; the Devices group displays information about actively connected devices, whereas the iPhone Development group — described in a later section — aggregates historical development information from all of your devices. Adding and Removing Devices iPhone and iPod Touch devices are automatically added to the organizer whenever you connect one to your computer while Xcode is running. Once added, they persist until removed from the organizer. The organizer shown in Figure 22 - 6 has had two devices added. The device named “ iPhone ” is currently connected, as indicated by the green dot next to its name, whereas the device named “ Tea tray ” is not. FIGURE 22 - 6 The activities in the Devices group interact directly with the connected device. A device that ’ s not connected does little but display the message “ This device is not currently connected. ” You ’ ll see the identity of the device and you can browse previously downloaded crash reports — but that ’ s about it. To remove an obsolete device from your organizer, Right/Control+click the device name and choose the Remove From Organizer command. You can also have Xcode ignore a particular device, such as a personal iPod that you do not use for development. To do that, plug in the device and choose the Ignore Device command from the same menu. You interact with your development device by connecting it to your computer, selecting it in the organizer, and then choosing the desired tab that appears in the details pane. The tabs are Summary, Crash Logs, Console, and Screenshots. The functions of each are described in the next few sections. Devices ❘ 629 c22.indd 629c22.indd 629 1/21/10 4:38:26 PM1/21/10 4:38:26 PM Download at getcoolebook.com . REPOS="svn+ssh://mini.local/Users/Shared/Subversion/${PROJ_NAME}" TAG=$(tr '.' '-' < < < ${VERSION}) echo "creating tag release-${TAG}" svn copy -m "Release ${VERSION}" "${REPOS}/trunk" "${REPOS}/tags/ release-${TAG}". assign. If the combination you ’ ve chosen confl icts with one already assigned, Xcode will alert you at the bottom of the window, as shown in Figure 22 - 3. Choose a different combination and press. the POSIX and Automator tools at your disposal, which gives you an immense amount of latitude in designing your action. ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ Using Organizer Actions ❘ 6 23 c22.indd 623c22.indd 623