<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>