<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>
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#1 $ in the
<a href="http://public.perforce.com/public/index.html">Perforce Public Depot</a></h6>
</body>
</html>