Practical_Perforce.pdf - Practical Perforce Laura Wingerd Beijing \u2022 Cambridge \u2022 Farnham \u2022 K\u00f6ln \u2022 Paris \u2022 Sebastopol \u2022 Taipei \u2022 Tokyo

Practical_Perforce.pdf - Practical Perforce Laura Wingerd...

This preview shows page 1 out of 360 pages.

You've reached the end of your free preview.

Want to read all 360 pages?

Unformatted text preview: Practical Perforce Laura Wingerd Beijing • Cambridge • Farnham • Köln • Paris • Sebastopol • Taipei • Tokyo Practical Perforce by Laura Wingerd Copyright © 2006 O’Reilly Media, Inc. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (safari.oreilly.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or [email protected] Editor: Jonathan Gennick Production Editor: Adam Witwer Cover Designer: Karen Montgomery Interior Designer: David Futato Printing History: November 2005: First Edition. Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. Practical Perforce, the image of herring, and related trade dress are trademarks of O’Reilly Media, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. This book uses RepKover™, a durable and flexible lay-flat binding. ISBN: 0-596-10185-6 [M] Table of Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii 1. Files in the Depot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 The Perforce Filespec Syntax Browsing Depot Files File Types at a Glance 1 7 15 2. Working with Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 An Overview Creating a Workspace Synchronizing a Workspace Local Syntax, Wildcard Expansion, and Special Characters Working with Local Files Working with Pending Changelists and Submitting Files Removing and Restoring Files Useful Recipes 17 20 26 29 31 39 44 46 3. Resolving and Merging Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Resolving: When, What, and How How Perforce Merges Text Files Reconciling Structural Changes Tips for Smoother Collaboration The Arcana of Merging 49 62 66 74 78 4. Branching and Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 The Classic Case for a Branch Creating Branches Integrating Changes from Branch to Branch 88 89 96 iii Reconciling Structural Changes The Arcana of Integration 112 118 5. Labels and Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Saving Important Configurations Using Labels Using Jobs Jobs as Changelist Markers 127 129 137 142 6. Controlling and Automating Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Depot and File Access Accessing Files in Other Domains Saving and Restoring Specs Change Notification and Change Monitoring Scripting Tips Behind-the-Scenes Version Control 144 146 150 152 157 163 7. How Software Evolves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 The Story of Ace Engineering The Mainline Model Ace Engineering Revisited Containerizing 167 169 183 186 8. Basic Codeline Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Organizing Your Depot General Care and Feeding of Codelines Nightly Builds Is Bug X Fixed in Codeline Y? 189 199 205 208 9. Release Codelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Creating a Release Codeline Working in a Release Codeline Integrating Changes into the Mainline Making a Release Distributing Releases Breaking the Rules Retiring a Release Codeline Task Branches and Patch Branches iv | Table of Contents 216 222 227 231 235 237 240 242 10. Development Codelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Creating a Development Codeline Working in a Development Codeline Keeping a Development Codeline Up to Date Working with Third-Party Software Delivering Completed Development Work The Soft Codelines 249 255 258 263 267 275 11. Staging Streams and Web Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 Staging Web Content Visual Content Development Bug Fixes and Staging Streams Major Web Development 282 288 297 302 A. Setting Up a Perforce Test Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 B. Perforce Terminology and P4 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 Table of Contents | v Preface What Is Perforce? If you’ve picked up this book simply because of its riveting title, you may be wondering what Perforce is. Perforce is a software configuration management (SCM) system. SCM systems are used by software developers to keep track of all the software they build and all the components that go into it. A good SCM system can explain the mysteries of software development and head off its disasters—mysteries like lost bug fixes, and disasters like botched file merges. In large-scale and commercial environments, good SCM is absolutely essential to producing good software. It’s All Software and We’re All Software Developers SCM was once concerned with files that computer programmers produced. Now it is concerned with files of all types that a business produces. Software, when viewed from the perspective of SCM, is any endeavor that calls a computer home. Documention, web content, spreadsheets, schematics, graphics, sound—it’s all software. If it’s stored in computer files and gets built, embedded, or packaged into a deliverable result, it’s software. The term software developer may not sound like it applies to web content authors, graphic artists, test engineers, and technical writers, but for the purpose of this book, anyone whose work involves creating computer files from intellectual thought is a software developer. Perforce, like all SCM systems, keeps track of changes as people do concurrent, parallel work on files. It logs activity; reports who did what; compares, merges, and vii This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. branches files; and stores files and file configurations. Some of Perforce’s most salient features are: The depot Perforce stores files in a protected repository known as the depot. The depot is a centrally located, permanent archive of all file content submitted by users.* Workspaces Perforce users work on files in workspaces, private disk areas of their own that contain copies of depot files. In this book we’ll describe effective ways that developers can use workspaces, and we’ll also discuss how workspaces can be used to automate nightly builds, release packaging, web staging, and other software production tasks. Changelists Perforce changelists tie files changed together into single units of work. Every change to the depot can be traced to a changelist, and every changelist marks a known, reproducible state of the depot; the depot evolves as changelists are submitted. In the Perforce view of SCM, it is the changelist—not the file revision, nor the delta—that is the atomic transaction of software development. This book will discuss a variety of ways changelists can be used, including treating them as snapshots and using them to identify file dependencies. Filespecs and views The Perforce filespec syntax, and the views that use it, allow selection of files for Perforce operations. Filespecs can define not only the common file collections, like directories, but arbitrary collections of files that constitute codelines, modules, delivery streams, and other containers. They are the key to treating collections of files as versioned objects that can be inspected, rolled back, branched, labeled, compared, and merged at any version. Jobs In Perforce you can record externally defined tasks and states—bug reports, feature requests, and project milestones, for example—in objects it calls jobs. Jobs can be linked to changelists to provide a record of software changes related to tasks. Jobs are also the linchpin of any integration between Perforce and external systems, as we’ll see in later chapters. Branching Perforce uses Inter-File Branching to model file variants. In the traditional version tree branching model used by most SCM systems, a file can be branched and merged only into revisions of itself. In Perforce, any two files can have a branching relationship; branched files are peers, not offshoots, of their originals. A number of chapters in this book are dedicated to describing Perforce branching and its unexpectedly useful applications. * The data format of the Perforce depot is not proprietary; it is, in fact, consistent with the RCS archive format. Because of this, there is a common misperception that Perforce is an RCS wrapper. It’s not. viii | Preface This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. Integration history In Perforce, branching and merging are referred to as integration. Perforce records a history of integration events and uses it to direct merges and prevent unnecessary remerging. In this book you’ll see how Perforce does that and learn how to anticipate the effect of merges you perform. Change tracking Perforce combines filespecs, changelists, jobs, and integration history to track changes as they are merged from branch to branch. In this book you’ll learn how these objects can be used to determine whether a change—a bug fix, for example—made in one branch has been merged to another, no matter how distantly related. In addition to these features, which could be considered the interesting capabilities of Perforce, there are also the standard housekeeping and productivity features you’re likely to find in any SCM system, including labels, triggers, change notification, graphical merge tools, file histories, and so forth. The Perforce System in a Nutshell Perforce is a client/server system (see Figure P-1). The domain of a Perforce system encompasses a master file repository (the depot), a database, and a constellation of users running client programs. One Perforce Server typically serves an entire Perforce domain. Its job is to communicate with Perforce client programs, analyze and execute user commands, archive and serve up file content, run event triggers, and record system activity in the Perforce database. It also performs a variety of database housekeeping tasks, some on demand and some automatically. The client component of Perforce, shown in Figure P-2, manages workspace files and communicates with the server. It’s implemented in a variety of tools designed for users at almost every technical level. Perforce client tools can be divided roughly into three categories: Graphical user interfaces The Perforce GUIs are the point-and-click client applications. This category includes P4V, P4Win, and P4Web. (The latter is actually more of a plug-in, but because it turns your browser into a Perforce GUI it is marketed as a GUI itself.) Although they don’t support every possible Perforce command, the GUIs do support the day-to-day operations of the typical software developer, and they are easy on the eyes. They also provide a variety of data-mining features, including some very nice visualizations of branching and file evolution. For these reasons, even die-hard command-line adherents find them useful. P4V, P4Win, and P4Web can be used interchangeably, although there are some variations in the range of operations they support. All three come with embedded help files that provide rudimentary coaching in how to use Perforce. Preface | This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. ix Database Depot Client program Client program Perforce Server Client program Client program Server machine Client program Figure P-1. The Perforce client/server system Preforce Server User’s machine Workspace Perforce Client Program (P4, P4V, P4Web . . .) Local files Workspace Local files Figure P-2. The Perforce client component x | Preface This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. Plug-ins The Perforce plug-ins category consists of client programs that run behind the scenes, usually on the user’s machine, to enable other applications to work with Perforce. The most widely used is the Perforce SCC Plug-in, which integrates Perforce with Visual Studio .NET. (That’s SCC as in Microsoft Source Code Control API; any Windows application that supports the Microsoft SCC API is likely to work just fine with the Perforce SCC Plug-in.) As Perforce’s popularity grows, plug-ins are emerging that wed less technical applications to Perforce. P4FTP, for example, makes Perforce transparent to people using applications that rely on FTP, and P4Report turns the Perforce database into an ODBC data source for Windows spreadsheet and database tools. Programmable clients The programmable interfaces to Perforce are P4 and P4API. P4, the Perforce Command-Line Client, can be used in interactive shells and in scripts. It’s the canonical client program—if you can’t do it with P4, it can’t be done. P4API, the Perforce C/C++ API, is available to embed the client component in applications, scripting languages, and other software. P4 and P4API run on all the operating system platforms Perforce supports—and there are a lot of them—and they support all Perforce operations, including administrative and privileged operations. Why Perforce? The features and capabilities of an SCM system are important, but equally so is its ability to meet expectations and thrive in its habitat. Perforce runs as a self-reliant, self-contained system, and you don’t need other software or hardware components installed to use it. Unlike many other SCM systems, Perforce fits into almost any computing environment, thanks to the following features: Speed Perforce is fast. It doesn’t make developers wait to check out, check in, compare, or update files, and it doesn’t add a processing burden to developers’ machines. Centralized repository In the Perforce system, there is one centralized repository per domain for files and SCM data. Very large companies may have several Perforce domains, but that’s typically an organizational choice, not a limitation of domain size. (Perforce domains at some large companies are known to encompass over 1,000 users each.) While it may be argued that a centralized repository puts your SCM system at risk of a single point of failure, that risk is vastly outweighed by several advantages. First, you have only one machine per domain to take care of to protect your assets. Second, you don’t have to worry about where your assets Preface | This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. xi are. Office moves and machine upgrades don’t perturb your central SCM repository. And third, as long as your central SCM server is running, all your users have access to it. The failure of one machine doesn’t impede SCM access for users elsewhere in your system. No external database required Some SCM systems require you to configure and administer an external database system like SQL Server or MySQL. Perforce provides its own database. When you install Perforce, you’re installing a reliable, self-contained database, customized for Perforce SCM. Because the Perforce database can’t be accessed by any other means than the Perforce Server, there’s not much that can go wrong. It does require that the system administrator schedule regular checkpoints and backups, but other than that, very little hands-on administration is required. Database recovery performed after a disk failure or other misfortune can be done manually by the system administrator or through automated tools. Perforce provides tools for checkpointing, for recovery, and for automatically upgrading the database when a new release is installed. No reliance on networked file sharing Some SCM tools rely on networked file sharing (NFS) of one kind or another. NFS is not an ideal solution for SCM; network file sharing can be slow, and make it difficult for the SCM tool to handle file format differences. (Have you ever opened up a file in Notebook only to see all its lines running together? Or opened up a file in vi and seen ^M characters at the end of every line?) NFS is also very machine-dependent; clock synchronization and other interoperability issues make version control difficult. Perforce does not use NFS. Instead, it does its own file transport using TCP/IP. This approach gives it control over the files it cares about and, because TCP/IP is so universally supported, makes it capable of running on more operating system platforms. No HTTP server required Some SCM systems require you to configure an HTTP server, like Apache or IIS, to perform the duties of an SCM server. Perforce provides its own server and runs independently of your web servers. Traditionally, software development organizations were formed of developers working together at the same company, at the same location. Most SCM systems, including Perforce, are suited for that kind of organization. But Perforce has built-in features that make it suitable for nontraditional teams, including teams formed of developers who work outside of the office, developers who work in separate divisions, and even developers who work for completely different companies: xii | Preface This is the Title of the Book, eMatter Edition Copyright © 2005 O’Reilly & Associates, Inc. All rights reserved. Process impartiality Perforce imposes almost no built-in workflow or process rules. It’s designed with certain software development activities in mind (all of which will be discussed in later chapters), but it can accommodate almost any procedure or methodology. Any workflow or process you have established (or that you would like to establish) can be automated with Perforce. File types While some SCM systems have restrictions on handling certain file types, Perforce can store and manage text files, binary files, Unicode files, native Apple files on the Macintosh, Mac resource forks, and Unix symlinks in its repository. Product distribution and vendor drops The Perforce Server can access file repositories in other Perforce domains. This makes a seamless, Perforce-to-Perforce distribution of software products possible. In other words, you can distribute your product directly from your Perforce repository to other organizations, as long as they have Perforce, too. And you can receive vendor drops from other organizations directly from their Perforce repositories. In fact, you can even branch or merge files from their repositories directly into yours. All the while, a history of what you’ve released and received is being collected and recorded in your SCM database. Firewalls and tunnels As mentioned, Perforce uses TCP/IP to communicate between its com...
View Full Document

  • Spring '14
  • Test, Computer file, Perforce

  • Left Quote Icon

    Student Picture

  • Left Quote Icon

    Student Picture

  • Left Quote Icon

    Student Picture