Lập trình Wrox Professional Xcode 3 cho Mac OS part 74 docx

582 ❘ CHAPTER 21 SHARING SOURCE If you open a project that refers to a source tree that is not defi ned on your system, Xcode attempts to locate the fi le at the same path it used the last time that tree was defi ned. If this path is wrong, the fi le will turn red, indicating that it cannot be located. Defi ne the required source tree, then close and reopen the project to resolve the reference. To redefi ne your source trees, close all projects, redefi ne your source trees, and open the projects again. Xcode resolves the source fi le paths using the new source tree locations. SOURCE CONTROL Source control systems work by storing the master copies of your project fi les in a repository . A repository is a database of fi les. A repository might be on the same fi le system or on a remote system. Xcode might access a repository using direct fi le access or by sending requests over a network to a source control server . Regardless of the confi guration, you interact with the source control system through Xcode or via a source control client installed on your system. A fi le stored in a repository is called a managed fi le . When you want to work with a managed fi le, you check out the fi le from the repository. The copy of the fi le you checked out is called the working copy . If you make changes to the working copy, you later check in the fi le to record those changes in the repository. After the changes have been recorded, other developers can check out the fi le to incorporate your changes into their working projects. You can compare your working copy with other versions in the repository to see exactly what has changed. You can also check out an earlier version of any fi le and use it instead — maybe because you don ’ t like the changes made by another developer. Xcode has integrated support for three major source control systems: Concurrent Versions System (CVS), Subversion, and Perforce. CVS was the reigning king of open source control systems but has since been usurped by Subversion. An installation of Subversion is included in the Xcode Developer Tools. You can get more information about CVS at http://www.nongnu.org/cvs/ . Learn more about Subversion at http://subversion.tigris.org/ . You ’ ll also want to read Version Control with Subversion , available at http://svnbook.red-bean.com/ . You can purchase a printed copy of the book or download an electronic version for free. Perforce is a commercial source control system available from Perforce Software Inc. If you need a commercial source control management system, you ’ ll want to check out Perforce at http://perforce.com/perforce/products.html . This chapter concentrates on setting up Subversion and confi guring Xcode to use it. Subversion was chosen for this book over CVS and Perforce for four reasons: Subversion is, in many ways, superior to CVS — which it was designed to replace. Subversion is less expensive than Perforce (it ’ s free). Subversion is very popular among open source projects. Subversion comes pre - installed with Snow Leopard and is the de facto standard for Xcode source control. ➤ ➤ ➤ ➤ ➤ ➤ ➤ c21.indd 582c21.indd 582 1/21/10 4:34:53 PM1/21/10 4:34:53 PM Download at getcoolebook.com That ’ s not to say that CVS or Perforce are bad choices. If you already have a CVS or Perforce repository, then your best choice is clear. SOURCE CONTROL BEYOND XCODE You’re not limited to using the source control systems that are integrated into Xcode, and you’re not limited to using your source control system via Xcode. The Git SCM system has attracted a lot of attention lately, and may someday overshadow Subversion. You can use Git — or any other source control system — to manage your project’s fi les; you just can’t use it from within Xcode (unless your SCM has a Subversion or CVS emulation mode). Source control systems also provide many features and commands that Xcode doesn’t support. Xcode’s source control commands focus on common tasks you’re likely to perform during development (check out, check in, compare, merge). Regardless of whether you use a source control via Xcode, you will still need to reach for your favorite source control client to perform advanced activities like repository creation, branching, tagging, migration, and fi ltering. Even for those actions that can be performed from within Xcode, you may still prefer using your source control client or a third-party application. For example, when I’m about to release a product I use a third-party Subversion utility for collecting, organizing, and reviewing the changes made since my last release. Though the same information can be found in the Info window of my project, it’s not nearly as easy to sift through. Using Source Control Using source control through Xcode can be broadly divided into three phases: 1. Defi ne a repository. 2. Check out a project from a repository. 3. Use source control from within the project. The next section describes how to defi ne a repository. The sections starting with “ Browsing Repositories ” describe how to view the contents of a repository and check out an Xcode project. Once you have a project checked out under source control, all of your subsequent interaction will be through the project, described starting in the “ Source Control Interface ” section. Defi ning a Repository As mentioned earlier, a repository is a centralized collection of managed fi les. Before you can use source control, you must defi ne the location and characteristics of the repository, or repositories, that you want to use. Just like source trees, each developer must create an equivalent repository defi nition if they expect to share the same set of managed fi les. The defi nitions might be the same or Source Control ❘ 583 c21.indd 583c21.indd 583 1/21/10 4:34:54 PM1/21/10 4:34:54 PM Download at getcoolebook.com 584 ❘ CHAPTER 21 SHARING SOURCE different. For example, you might create a source control repository on your local drive. Later, you decide to collaborate with another programmer and open access to that repository via the Internet. Your repository defi nition would still refer to your local fi le system while his would refer to a remote repository. All of the repositories you use are defi ned in the SCM tab of the Xcode Preferences (Command+,), as shown in Figure 21 - 4. FIGURE 21-4 Each repository defi nition has three parts: The source control client used to access the repository The access method and parameters A path to the root directory within the repository ➤ ➤ ➤ c21.indd 584c21.indd 584 1/21/10 4:34:55 PM1/21/10 4:34:55 PM Download at getcoolebook.com Click the + button below the list of repositories to defi ne a new repository. A dialog sheet will prompt you for a repository name and the client that will be used to access the repository. The client you choose — SVN, Subversion, or Perforce — will determine what settings are needed to defi ne the repository. The name identifi es the repository defi nition in Xcode and can be changed later. Clicking OK creates a new repository defi nition. Fill in the settings as required. What those settings are is entirely dependent on how the repository was created and where it resides. If you didn ’ t set up the repository, contact the administrator of the repository for the correct settings. In some situations they may need to create a user account and password for you, or you might have to register an SSH key. For Subversion repositories, the settings to confi gure are: SUBVERSION SCM SETTING DESCRIPTION Scheme http , https , file , svn+ssh , and so on Host Host name or IP address of server (for network schemes) Path Path to root directory in repository (may include the path to the repository itself) Port Network port to use (for network schemes) User User account name (if required) Password Password for user (if required) The URL setting and the other settings mirror each other. Whatever you enter for the other settings is combined into a single URL, and whatever you enter into the URL setting is decomposed into its individual settings. If your Subversion administrator or open source project provides an URL to the repository, paste that into the URL fi eld; Xcode will fi ll in the settings for you. Conversely, if you need an URL to access your repository via the source control client or some third - party tool, Xcode has already constructed it for you. Copy the URL and paste it into your client. The path setting defi nes the top - level directory within the repository where this repository defi nition is anchored. You may create a single repository defi nition that points to the top - level directory in the repository, or you can defi ne multiple repository defi nitions that point to individual subdirectories within a single repository. Which you choose is a matter of personal preference, style, and any security restrictions that might be in place. I tend to defi ne a repository defi nition for each set of related projects, even if more than one set shares a single repository. When I browse that repository, I ’ m not distracted by unrelated directories. The path setting might also describe the location of the repository itself. That is, the fi rst part of the path is the location of the repository database, and any remainder is a path within the Source Control ❘ 585 c21.indd 585c21.indd 585 1/21/10 4:34:56 PM1/21/10 4:34:56 PM Download at getcoolebook.com 586 ❘ CHAPTER 21 SHARING SOURCE repository structure. It ’ s not obvious where the path to the repository ends and the path within the repository begins, but it ’ s usually immaterial. Repository on a Local File System If you ’ ve created a Subversion repository on a local volume, you can use the fi le scheme to access it directly. Set the following two settings: Scheme: file Path: /Complete/Path/To/Repository/Subpath/To/Root The file scheme path defi nes the location of the repository database and must begin with an absolute fi le system path to the repository database. Any remaining path components are interpreted as subdirectories within the repository. Creating a local repository is best when you need source control for archiving and version tracking. If you plan to collaborate with other developers, you ’ ll probably want to create your repository on a networked server. If you don ’ t have access to an existing Subversion repository, or just want to get started using Subversion for your own projects, jump ahead to the “ Creating a Subversion Repository ” section, and then come back here to defi ne it in Xcode. Repository Access via a Web Server Subversion repositories designed for wide consumption are often set up behind a web server, such as Apache. Source control requests are made through the web server and passed along to the source control server. This is very common with open source projects. If you don ’ t have a URL for the project ’ s repository, you will need to confi gure the following settings: Scheme: http or https Host: www.host.net or 10.0.254.1 Path: /path/to/repository/root/directory Port: alternate port (optional) User: account name (optional) Password: account password (optional) Setting up Subversion to work behind a web server is a non - trivial exercise. You ’ re most likely to encounter this for repositories that have already been created. Subversion Server via a Network or SSH Subversion supports a couple of its own client/server schemes. The svn scheme lets you set up a Subversion server on a computer and interact with it via a dedicated IP port. This is useful for development groups on a local area network, and is much easier to set up than a web - hosted ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ c21.indd 586c21.indd 586 1/21/10 4:34:56 PM1/21/10 4:34:56 PM Download at getcoolebook.com Source Control ❘ 587 Subversion server. It has the disadvantage of limited security, and the non - HTTP IP port might be blocked by fi rewalls, neither of which are typically concerns on a private LAN. To set up a Subversion server, see the “ Server Confi guration ” chapter of the Version Control with Subversion book. A less well - known scheme is svn+ssh — also described in Version Control with Subversion . This scheme performs Subversion actions by executing source control client requests on a remote computer via SSH. The remote computer doesn ’ t need to be running a Subversion server, but it does need to be transparently accessible via SSH. This usually means that you ’ ve installed pre - authorized SSH keys for the remote account on the server. Because there ’ s no server process involved, the svn+ssh scheme is easy to set up — not that much more diffi cult that setting up a local repository. You will also want to install pre - authorized SSH keys so that Xcode doesn ’ t prompt you for a password or passphrase every time it needs to interact with the repository. If you followed the instructions for setting up remote debugging in Chapter 18, you ’ re already done. Security in svn+ssh is excellent, because it ’ s supplied by SSH. The primary disadvantage to svn+ssh is performance; invoking the source control client via SSH is slower than a dedicated server would be. Nevertheless, I highly recommend this confi guration for small, geographically scattered teams that need secure source control with modest performance and minimal maintenance. Checking Your Repository Defi nition The repository defi nition pane automatically tests the settings as you enter them. A status indicator at the bottom of the pane shows Xcode ’ s success in using those settings. The possible results are: Incomplete Confi guration Authenticated Error: Description of error The fi rst message means that your defi nition is still missing some required setting or settings. A green “ Authenticated ” message means that Xcode has successfully accessed the described repository using your settings. Congratulations, you are ready to start using your repository! A red “ Error ” message indicates that the settings are wrong or that some other confi guration or communications issue is preventing Xcode from accessing the repository. Read the error description for clues and carefully review your settings. Source Control Options Before running off to use your newly defi ned repository, take a quick look at the Options tab of the SCM preferences pane, as shown in Figure 21 - 5. ➤ ➤ ➤ c21.indd 587c21.indd 587 1/21/10 4:34:57 PM1/21/10 4:34:57 PM Download at getcoolebook.com 588 ❘ CHAPTER 21 SHARING SOURCE I recommend checking the Confi gure SCM Automatically option. When you check out a project via source control, the working fi les are under the infl uence of the source control system — but the project will not necessarily be confi gured to use source control. Turning this option on allows Xcode to confi gure your project automatically to use source control when it detects that it ’ s appropriate. Otherwise, you ’ ll have to confi gure the project manually as described later in the “ Confi guring a Project for Source Control ” section. The Save File Before SCM Operations automatically saves your fi les to disk before performing any source control action (check in, check out, and so on). I recommend setting this option for the same reasons I recommend setting the Always Save Files option in the Building pane. The remaining options control how fi les are compared in Xcode. Most often this is when you want to compare the working version of your fi le with a different version in the repository. Some of these settings also apply to comparing fi les in snapshots. The Comparisons Handling option selects the application and layout used when comparing two fi les. Xcode will obtain both versions of the fi le and pass them to the application for side - by - side comparison. Your choices are : FIGURE 21-5 c21.indd 588c21.indd 588 1/21/10 4:34:58 PM1/21/10 4:34:58 PM Download at getcoolebook.com Source Control ❘ 589 Xcode FileMerge BBEdit Other Using Xcode is the fastest, but also the least capable. Xcode ’ s built - in comparison window is adequate for comparing two fi les but is awkward if you want to selectively replace individual sections of your working fi les with those from the revision. The FileMerge application is a standalone fi le comparison utility included in the Xcode Development Tools package. If you own Bare Bone ’ s BBEdit application, you can use its excellent fi le comparison interface instead. The Other setting lets you select any third - party comparison tool that accepts two fi lename arguments and compares them. Xcode can also compare fi les using the traditional POSIX diff tool. The settings under Differencing defi ne some format arguments that Xcode will pass to diff . See the diff man page for a complete description of these settings. Your SSH Certifi cates If access to your repositories requires a private SSH encryption key, those keys will appear in the SSH tab of the SCM preferences pane. The keys that appear here will be any keys installed in your account ’ s .ssh directory and any SSH keys in your keychain. You can add security by entering a passphrase for one or more keys. Xcode will prompt you for this phrase whenever it needs to use the selected SSH key. Leave the passphrase fi eld empty to bypass the prompt. Creating a Subversion Repository If you ’ re setting up Subversion for your own personal use, or just want to try out source control, the simplest solution is to create a local repository. The following Terminal command creates an empty repository named Subversion in your Documents folder: svnadmin create ~/Documents/Subversion Now go to Xcode ’ s SCM preferences pane and create a repository defi nition, as described in the “Defi ning a Repository” section. For the example given, your settings will be: Client: Subversion Scheme: file Path: /User/ youraccount /Documents/Subversion You can elect to use a different repository name and location as you see fi t. Note that you can ’ t use a user - relative path ( ~/Documents/ ) in the repository defi nition setting. ➤ ➤ ➤ ➤ ➤ ➤ ➤ c21.indd 589c21.indd 589 1/21/10 4:34:58 PM1/21/10 4:34:58 PM Download at getcoolebook.com 590 ❘ CHAPTER 21 SHARING SOURCE Filtering Out Noise Ideally, your source control repository should contain only the fi les needed to build your project. This includes your project document, source fi les, resources fi les, and so on. It should not contain any intermediate products (object fi les, compiled data models, help indexes), superfi cial fi les (code sense index, disassembly fi les), or any fi nal products (applications, bundles). There are a number of techniques for excluding these so - called noise fi les from your repository. The “no products” rule isn’t universal. Repositories are sometimes used to store fi nished products. This is particularly true of frameworks, libraries, and other products that are source fi les for other projects. A fi nished framework that’s used by a large number of developers can be checked into a repository and treated like any other immutable project resource. This spares the project from having to check out, and maintain a dependency on, the project that produces the framework. Xcode ’ s default folder organization conveniently places all intermediate fi les, project indexes, and products inside the project ’ s build folder. Wow, that makes it easy! All you have to do is leave the build folder out of your repository and 98 percent of your noise fi les have been eliminated. There are basically two approaches to this, and which one you take determines whether you address other noise fi les at the same time. Omitting the build Folder The simplest technique — as long as you consistently remember to do it — is simply to leave the build folder out of repository. With no build folder in the repository, your project ’ s build folder will not be a working folder (that is, managed by source control), and the source control system will ignore its content. To accomplish this, make sure the project has no build folder when it ’ s fi rst imported (see the “ Adding a Project to Source Control ” section). Do this by either: Closing the project and deleting the build folder before importing it into the repository Redefi ning the location of the build folder so that the intermediate fi les and products are written to a location outside the project folder Either of these will eliminate the build folder from the project when it is imported, so there will be no build folder in the repository. After that, just be careful not to do anything that would inadvertently add or import the build folder. Excluding the build Folder A more rational approach, in my mind, is to confi gure Subversion so that it automatically ignores the build folder. Once that ’ s done, you don ’ t have to think about it. Whenever you import a project or check in fi les, Subversion will automatically ignore the contents of the build folder. To do that, set Subversion ’ s global - ignores property in the ~/.subversion/config fi le. An excerpt of my ~/.subversion/config fi le is shown here: ### Set global-ignores to a set of whitespace-delimited globs ### which Subversion will ignore in its 'status' output. # global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store global-ignores = .DS_Store build *.mode* *~.nib *~ ➤ ➤ c21.indd 590c21.indd 590 1/21/10 4:34:59 PM1/21/10 4:34:59 PM Download at getcoolebook.com Source Control ❘ 591 I commented out the default defi nition of global - ignores and replaced it with my own. The global - ignores property is a space - separated list of fi lename patterns (globbing) that Subversion will exclude/ignore on your entire system. The patterns I defi ned exclude the following: PATTERN FILE DESCRIPTION .DS_Store The hidden .DS_Store fi le used by Mac OS X to manage the appearance of folders in the Finder build Any fi le or folder named ‘ build ’ *.mode* Window position, toolbar, and other superfi cial layout information stored per - user inside the project document *~.nib Backup .nib fi les created by Interface Builder *~ Generic backup fi les created by some editor applications These patterns automatically exclude all intermediate, product, and noise fi les from my repository. The hazard of setting an exclude pattern like “build” is that you might someday encounter a project that has a subdirectory named build that contains source fi les. It’s unlikely, but if it did happen Subversion would dutifully ignore that folder too, probably to the detriment of the project. You can confi gure per-folder fi lters in Subversion. These can add additional ignore rules for a specifi c project or override the global rule. See the Version Control with Subversion book for the details. Excluding Other Noise Files Generally, noise fi les are fi les that are not signifi cant to building the project. It ’ s not that they don ’ t contain any useful information, but deleting them won ’ t affect the build. The advantage of checking noise fi les into source control is that they often contain information that you want to preserve or share. When I check out a project, it would be nice if that project remembered all of my settings and preferences. The disadvantage is that noise fi les tend to change often. The source control system will want you to check any modifi ed fi les back into the repository along with a change comment. This often results in many revisions to the repository that don ’ t represent signifi cant changes to the project. This can be annoying to other developers who must constantly wade through repository changes that have no real impact on their work. The noise fi les I exclude are .DS_Store and the *.mode* fi les found inside the project document. These are classic noise fi les because they store window position and other ephemeral layout information that has little bearing on my workfl ow. If I export a project, and it doesn ’ t save the size of the project window, it won ’ t cause me any grief. The noise fi les that are most contentious are the per - user *.pbxuser fi les stored inside the project document. Each user .pbxuser fi le stores preferences and other settings for that developer, such as c21.indd 591c21.indd 591 1/21/10 4:35:10 PM1/21/10 4:35:10 PM Download at getcoolebook.com [...]... merged version from the following table: ACTION ITEM KEYBOARD SHORTCUT RESULT Choose left ← Use content from left file Choose right → Use content from right file Choose both (left first) Include contents of left file followed by the right file Choose both (right first) Include contents of right file followed by the left file Choose neither Ignore the contents of both files Using the ↑ and ↓ keys, navigate to... latter, and the fi le exists in the repository, Xcode presents a second dialog, shown in Figure 21-18 FIGURE 21-18 Download at getcoolebook.com c21.indd 606 1/21/10 4 :35 :45 PM Source Control ❘ 607 If you choose to remove the fi le, a repository remove action is added to the SCM smart group and the fi le is removed from the repository when the action is committed If you choose not to remove the fi le, the fi... data Browsing Repositories Once you have one or more repositories defi ned, you can open the Repositories window by choosing the SCM ➪ Repositories command The repository window, shown in Figure 21- 6, is where you can browse the content of a repository, perform some maintenance, and where you will ultimately check out a project under source control FIGURE 21-6 On the left are the repositories that you’ve... adding folders to your project, you first add them to the repository using your source control client After the enclosing folder is added, you can add files to the repository using either Xcode or your client tool Choose the SCM ➪ Refresh Entire Project to update the SCM status of every fi le in your project Double- clicking the SCM smart group or choosing the SCM ➪ SCM Results (Shift+Command+V) command opens... the fi rst place In the repositories window, select the repository directory where you want the project folder copied into the repository, or select just the repository to import it into the repository’s root directory Click the Import button in the toolbar and choose the project folder to import, as shown in Figure 21-8 Download at getcoolebook.com c21.indd 594 1/21/10 4 :35 :18 PM Source Control ❘ 595... -level folder that contains the working (checked out) assets Choose the repository that the working fi les came from Naturally, if your additional root directories were checked out of repositories other than the one your project is in, you’ll fi rst have to defi ne those repositories in the SCM pane of the Xcode preferences There are a number of scenarios in which a project would have multiple roots: ➤ The... Source Control ❘ 6 13 When a confl ict occurs, you have two choices You can abandon the changes that you’ve made, replacing them wholesale with the changes made in the latest revision of the file To abandon your changes, select the confl icting fi le and choose SCM ➪ Discard Changes The other choice is to merge your changes manually with those checked into source control Select the fi le and choose the SCM ➪... Renaming a fi le in a source control repository is as simple as renaming the source item in your project In the repository, the action consists of removing an existing fi le and adding a new fi le with a different name When you rename a source fi le in Xcode, it presents the dialog box shown in Figure 21-19 FIGURE 21-19 If you choose to rename the fi le in the repository, Xcode creates two SCM actions: the... the project, choose SCM ➪ Refresh Entire Project to update Xcode s status of the working fi les Deleting Files under Source Control Deleting a fi le requires that you remove it from both the project and the source control repository When you delete a fi le reference from a project, Xcode gives you the option of removing just the fi le reference or physically deleting the source fi le If you choose the latter,... before embarking on any major repository design Adding a Project to Source Control So far, you’ve created a repository, defi ned it in Xcode, and can browse the repository in the repository window Now you want to place your project under source control The basic steps for putting a project under source control are: 1 2 3 4 Create the project Import the project into the repository Check out the project . extra data. Browsing Repositories Once you have one or more repositories defi ned, you can open the Repositories window by choosing the SCM ➪ Repositories command. The repository window, shown. 5 83 c21.indd 583c21.indd 5 83 1/21/10 4 :34 :54 PM1/21/10 4 :34 :54 PM Download at getcoolebook.com 584 ❘ CHAPTER 21 SHARING SOURCE different. For example, you might create a source control repository. repository where this repository defi nition is anchored. You may create a single repository defi nition that points to the top - level directory in the repository, or you can defi ne multiple repository