- <html>
- <head>
- <title>The Branching Papers -- Perforce FAQs</title>
- <head>
- <body bgcolor=#ffffff>
- <font size=-2><b><a href="branching.html#br11">[INDEX]</a></b></font>
- <p>
- <b>
- 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? <i>[Detailed build
- description abridged.]</i>
- </b>
- <blockquote>
- 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.
- <p>
- 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.
- <p>
- 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:
- <pre>
- //depot/main/... //my_client/main/...
- </pre>
- 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.
- <p>
- 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:
- <pre>
- Client: my_build_client
- Root: c:\ws
- View:
- //depot/main/... //my_build_client/main/...
- //depot/mainbuild/... //my_build_client/mainbuild/...
- </pre>
- 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".)
- <pre>
- p4 integ -v //depot/main/... //depot/mainbuild/...
- p4 submit
- </pre>
- 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.
- <p>
- After you've set up your build branch, you can implement your
- automated build process. What it should do is this:
- <p>
- <ol>
- <p><li>
- Get the number of the latest changelist submitted into
- //depot/main:
- <pre>
- p4 changes -m1 //depot/main/...
- </pre>
- For demonstration purposes, let's say that changelist
- number is "1001".
-
- <p><li>
- Integrate the main changes into mainbuild, so you can build
- with everything up to and including changelist 1001:
- <pre>
- p4 sync //depot/mainbuild/...
- p4 integ //depot/main/...@1001 //depot/mainbuild/...
- p4 resolve -at
- p4 submit
- </pre>
- Assume this submit creates changelist 1015.
-
- <p><li>
- Do a build. Find out what's wrong, and fix the files:
- <pre>
- <small><i>(...build...)</i></small>
-
- p4 edit c:\ws\mainbuild\complex.h c:\ws\mainbuild\problem.c
-
- <small><i>(...fix complex.h and problem.c...rebuild, refix, rebuild...)</i></small>
-
- p4 submit
- </pre>
- Assume the last submit you did to get a good build
- created changelist 1019.
-
- <p><li>
- 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":
- <pre>
- p4 label good_build
- </pre>
- This brings up an editor form. Set up the label view thus:
- <pre>
- View:
- //depot/mainbuild/...
- </pre>
- To apply the files to the label:
- <pre>
- p4 labelsync -l good_build //depot/mainbuild/...
- </pre>
- 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.
-
- <p><li>
- 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:
- <pre>
- p4 sync //depot/main/...
- p4 integ //depot/mainbuild/... //depot/main/...
- </pre>
- 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:
- <pre>
- p4 resolve -as
- </pre>
- This automatically resolves files which have not been
- changed by developers since you did the build. Any
- remaining unresolved files are ones you changed <i>and</i>
- developers changed. So you have to resolve them
- manually so that nobody's changes get lost:
- <pre>
- p4 resolve
- </pre>
- This puts you in the resolve program, where you can
- see diffs, edit conflicts, and choose the result you want.
- <pre>
- p4 submit
- </pre>
- Now, developers who want to update their workspaces can simply
- sync to pick up your changes.
-
- </ol>
-
- <p>
- 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.
- <ul>
- <p><li>
- Before integrating your build fixes back into //depot/main, you can
- list all the changelists submitted by developers <i>since</i> you did
- your build. The highest changelist you built with is 1001, so use 1002 as
- the threshold:
- <pre>
- p4 changes //depot/main/...@1002,#head
- </pre>
- <p><li>
- You can list the affected files with:
- <pre>
- p4 files //depot/main/...@1002,#head
- </pre>
- <p><li>
- And you can show the diffs with:
- <pre>
- p4 diff2 //depot/main/...@1001 //depot/main/...#head
- </pre>
- <p><li>
- Similarly, here's how to list the changelists, files, and diffs for the
- changes <i>you</i> had to make to get a good build:
- <pre>
- p4 changes //depot/mainbuild/...@1016,#head
- p4 files //depot/mainbuild/...@1016,#head
- p4 diff2 //depot/mainbuild/...@1015 //depot/mainbuild/...#head
- </pre>
-
- <p>
- Hope this helps -- sorry for the verboseness.
-
- </blockquote>
- <p>
- <i>(September 1998)</i>
- <p>
- <font size=-2><b><a href="branching.html#br11">[INDEX]</a></b></font>
-
- <hr>
- <h6>This is file $Id: //guest/laura_wingerd/perforce/faq/br11.html#2 $ in the
- <a href="http://public.perforce.com/public/index.html">Perforce Public Depot</a></h6>
- </body>
- </html>