21 Sharing Source WHAT'S IN THIS CHAPTER? Creating source trees Confi guring source control Adding a project to source control Checking out a project Sharing, checking in, comparing, and merging project fi les Software development has always been characterized as a rather solitary vocation. The stereotype of a single programmer working into the wee hours of the night, isolated in a basement or attic room, is now mostly the purview of fi ction writers. Most modern development is done in teams — even when those teams are scattered across the globe and connected only by the Internet. Members of a team need ready access to the assets of projects they are working on. They need to collaborate on changes and distribute their work to other team members. Software projects themselves may also need to share resources. A suite of applications developed for a single corporation might need to include a common set of graphics, or share a set of preprocessor defi nitions. It ’ s impractical to put all of the applications into a single project, and (as you saw in Chapter 5) source fi le references outside the project folder can be problematic. Projects need a way to share common assets rationally. Closely related to the subject of sharing source fi les is the concept of source control management (SCM), or just source control . Source control systems store and track the changes made to source fi les over time. It is usually the basis of a collaboration system among multiple developers, acting as a mediator between developers, arbitrating changes, and communicating those changes to others. Individual developers have come to appreciate the ➤ ➤ ➤ ➤ ➤ c21.indd 577c21.indd 577 1/21/10 4:34:47 PM1/21/10 4:34:47 PM Download at getcoolebook.com 578 ❘ CHAPTER 21 SHARING SOURCE discipline, security, and accountability that source control systems bring to their development. Even if you are a single programmer working on a single project, you may still want to set up a source control system. Source control is used for many, if not most, open source projects. If you want to participate in an open source project, you ’ ll want to plug your Xcode project directly into the source control system used by that project. After it is confi gured, you ’ ll be able to browse the comments and revisions for the project right in the Xcode interface. You can see what new fi les are available and immediately update your local copy. SHARING VIA XCODE Xcode provides two facilities for sharing source fi les between projects and developers: source trees and source control . Source Tree Basics Source trees defi ne folder locations where shared source fi les reside. There is no restriction on where these are located or on how the source fi les are maintained. An earlier chapter mentioned a suite of application projects that all need to include the same corporate artwork; a source tree folder could be defi ned for those graphic fi les. Any number of projects can refer to the fi les in a source tree ’ s location. Changing the location of the source tree changes all of the references in all of your projects simultaneously. For example, if the graphics art department sends you a new CD with updated artwork, all you have to do is pop the disc into the CD - ROM drive, point that source tree to a folder on the CD, and rebuild your projects. Source tree locations are defi ned individually for each user, so a different programmer can use the same project with source tree locations specifi c to their environment. Source Control Basics Source control, often referred to as version control, is the principal method of tracking historical changes made to source fi les and sharing source fi les among a group of developers. It provides three important services: A centralized repository Security Change history The fi rst service stores the master copy of all source fi les in a central repository. Changes made to a source fi le by one developer are sent back to the central repository, where those changes can then be distributed to other developers. This allows multiple developers to work on the same project in a rational manner. ➤ ➤ ➤ c21.indd 578c21.indd 578 1/21/10 4:34:50 PM1/21/10 4:34:50 PM Download at getcoolebook.com The second service provides a degree of security, protecting against accidental damage to local project fi les and providing a point for centralized backups. The third service, and probably the most important, keeps a record of all changes made to a project over time. Developers can quickly see exactly what has changed in each fi le, and review comments made by the programmer that explain why. Source control can also be used like a time machine. You can reconstruct the state of a project at any point during its lifetime. You don ’ t need to archive a copy of your entire project at every point in its development. For example, if you ’ re working on version 1.6 of your application, but suddenly need to debug version 1.2, simply query the source control system for a copy of your project as it existed on the day you fi nished version 1.2. Source trees and source control serve different needs and each is designed to solve a different problem. Some aspects overlap, but generally they complement each other. They can be used independently or in combination. For example, a project from one source control repository can refer to fi les in a source tree that ’ s being maintained in a different source control repository. What source fi le sharing and control techniques you employ will depend entirely on your needs and work environment. SOURCE TREES A source tree is a named path to a folder on your system. A source tree consists of a Symbolic name Display name Path to the tree ’ s location on your system Any source fi le reference in a project can be relative to a source tree location. The location of the tree is independent of the location of the project folder. For example, if you defi ne a source tree named “ buttons ” and set it to the location ~/Development/ Common/Buttons , any project that has a source reference relative to the “ buttons ” source tree will look for that fi le in the Buttons folder inside your local Development folder. If you move that folder, or decide to use a different folder, you simply redefi ne the “ buttons ” source tree and every source fi le reference based on that tree changes. The “ your ” in “ a source tree . . . on your system ” is important. Source trees are defi ned individually for each user account. For someone else to use a project that refers to fi les in the buttons source tree, they must also have defi ned a source tree named “ buttons. ” It doesn ’ t have to have the same display name or be the same path, but it does have to have the same symbolic name. In fact, it makes sense that it wouldn ’ t have the same path — another developer wouldn ’ t have access to your /Users/ yourname /Development/Common/Buttons folder. The source trees defi ned for your account are global to all Xcode projects that you open. Consider this when deciding on a name for your source tree. ➤ ➤ ➤ Source Trees ❘ 579 c21.indd 579c21.indd 579 1/21/10 4:34:50 PM1/21/10 4:34:50 PM Download at getcoolebook.com 580 ❘ CHAPTER 21 SHARING SOURCE Defi ne a Source Tree Open the Source Tree tab of the Xcode Preferences, as shown in Figure 21 - 1. FIGURE 21-1 Click the + button below the list to defi ne a new source tree. Give it a symbolic name or key, a display name, and a path where the tree can be accessed on your system. The symbolic name is how Xcode identifi es a source tree. It should be simple and must be unique. I prefer to use so - called “ reverse DNS ” notation, like com.wiley.proXcode3.shared . The symbolic name is stored in each project fi le reference that ’ s relative to a source tree. Any other developers you share the project with must defi ne a source tree with the exact same symbolic name, or their project fi le references will be broken. The display name is how the source tree will appear in the Xcode user interface. It can be anything you want, should be descriptive, and can be changed later. Different users can have different display names for the same source tree. To delete a tree, select it in the list and click the – button. Source Tree References After you ’ ve defi ned a tree, use it to refer to source fi les in your project. The source trees you ’ ve defi ned automatically appear in all dialogs that add an existing fi le, folder, or framework to your project, as shown in Figure 21 - 2. c21.indd 580c21.indd 580 1/21/10 4:34:51 PM1/21/10 4:34:51 PM Download at getcoolebook.com Source trees also appear in the reference section of every source fi le ’ s Info window, as shown in Figure 21 - 3. You can make any source fi le ’ s path type relative to any source tree that you ’ ve defi ned. If you are reorganizing a project to use source trees, select a group of source fi le references and change their path type to the new source tree as a group. Typically, you would set the path type of a group folder to that of a source tree, and leave the members of that group as Relative to Enclosing Group. FIGURE 21-2 FIGURE 21-3 Source Trees ❘ 581 c21.indd 581c21.indd 581 1/21/10 4:34:52 PM1/21/10 4:34:52 PM Download at getcoolebook.com 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 . 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. 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 . in a basement or attic room, is now mostly the purview of fi ction writers. Most modern development is done in teams — even when those teams are scattered across the globe and connected only by