I read through the manual about branching, but I just can't figure out how to apply it to our daily build procedures here. Our old SCM system has a completely different branching model. How do I set up our builds to work with Perforce? [Detailed build description abridged.]

Perforce approaches branching completely differently than other systems. It's very easy to use once you understand it, but most of our customers start out asking questions exactly like this.

From your description, it sounds like development is so fast-paced that by the time a daily build is done, the project has evolved considerably, so files the build engineer may have checked out and changed are no longer at the head revisions. Thus the only way to label a buildable set of files is for the build engineer to check his changes in on a branch.

Say your project code is stored in the //depot/main path. Developers all submit their changes directly into that path. They are using client workspaces with views like:

        
	//depot/main/...  //my_client/main/...

I'd create a build branch right off -- call it //depot/mainbuild, for example. It will be a mirror of the mainline, but the build engineer has total control over changes that affect it.

To create //depot/mainbuild, first make sure the client workspace you use for the builds has both branches in its view. Say your client is "my_build_client" -- the client spec should look something like:

        Client: my_build_client
        Root:   c:\ws
        View:
                //depot/main/...  //my_build_client/main/...
                //depot/mainbuild/...  //my_build_client/mainbuild/...

Then, using the build client workspace, use "integrate" to branch the depot files. (I'll show you the p4 commands here -- if you're using P4Win, you can look up the operations in the "P4 to P4Win Translation Guide".)

	p4 integ -v //depot/main/... //depot/mainbuild/...
	p4 submit

This creates the "//depot/mainbuild" files in the depot. (Note that "lazy copies" are made -- the files aren't actually duplicated.) In your workspace, the //depot/mainbuild files will be put in your c:\ws\mainbuild directory. That's the directory you will use for your builds.

After you've set up your build branch, you can implement your automated build process. What it should do is this:

1. Get the number of the latest changelist submitted into //depot/main:

   	p4 changes -m1 //depot/main/...
   

   For demonstration purposes, let's say that changelist number is "1001".

2. Integrate the main changes into mainbuild, so you can build with everything up to and including changelist 1001:

   	p4 sync //depot/mainbuild/...
   	p4 integ //depot/main/...@1001 //depot/mainbuild/...
   	p4 resolve -at
   	p4 submit
   

   Assume this submit creates changelist 1015.

3. Do a build. Find out what's wrong, and fix the files:

   	(...build...)
   
   	p4 edit c:\ws\mainbuild\complex.h  c:\ws\mainbuild\problem.c
   
   	(...fix complex.h and problem.c...rebuild, refix, rebuild...)
   
   	p4 submit
   

   Assume the last submit you did to get a good build created changelist 1019.

4. Once your build is good, you can explicitly label the files, or you can simply use the number of last changelist submitted into mainbuild as a label. To create a label takes two steps -- first you create the label spec, then you apply (sync) the files to the label. To create a spec for an explicit label called "good_build":

   	p4 label good_build
   

   This brings up an editor form. Set up the label view thus:

   	View:
   		//depot/mainbuild/...
   

   To apply the files to the label:

   	p4 labelsync -l good_build //depot/mainbuild/...
   

   However, the set of files labelled by "good_build" is exactly the same as the set of files identified by "//depot/mainbuild/...@1019", so you may not need to create a label at all, depending on what you use it for.

5. In order for developers to see the build change you had to make, you have to integrate from //depot/mainbuild back into //depot/main. Still using your build client workspace, here's how you do it:

   	p4 sync //depot/main/...  
   	p4 integ //depot/mainbuild/...  //depot/main/...
   

   The files you had to change in order to get a good build are now opened in your workspace and scheduled for resolve. I always like to do the resolve in two steps:

   	p4 resolve -as
   

   This automatically resolves files which have not been changed by developers since you did the build. Any remaining unresolved files are ones you changed and developers changed. So you have to resolve them manually so that nobody's changes get lost:

   	p4 resolve
   

   This puts you in the resolve program, where you can see diffs, edit conflicts, and choose the result you want.

   	p4 submit
   

   Now, developers who want to update their workspaces can simply sync to pick up your changes.

As an aside, let me point out some reporting commands that give you information about the state of your depot. You may find a need for these in your automated build process.

• Before integrating your build fixes back into //depot/main, you can list all the changelists submitted by developers since you did your build. The highest changelist you built with is 1001, so use 1002 as the threshold:

       p4 changes //depot/main/...@1002,#head
  

• You can list the affected files with:

       p4 files //depot/main/...@1002,#head
  

• And you can show the diffs with:

       p4 diff2 //depot/main/...@1001 //depot/main/...#head
  

• Similarly, here's how to list the changelists, files, and diffs for the changes you had to make to get a good build:

       p4 changes //depot/mainbuild/...@1016,#head
       p4 files //depot/mainbuild/...@1016,#head
       p4 diff2 //depot/mainbuild/...@1015 //depot/mainbuild/...#head
  

  Hope this helps -- sorry for the verboseness.

(September 1998)

[INDEX]

This is file $Id: //guest/laura_wingerd/perforce/faq/br11.html#2 $ in the Perforce Public Depot