Helix SwarmHelix Swarm

build.html

  • //
  • guest/
  • laura_wingerd/
  • perforce/
  • faq/
  • build.html #2
  • View
  • Commits
  • Open Download .zip Download (24 KB) 
  1. <HTML>
  2. <HEAD>
  3.    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
  4.    <META NAME="GENERATOR" CONTENT="Mozilla/4.05 [en] (X11; U; OSF1 V4.0 alpha) [Netscape]">
  5.    <META NAME="Author" CONTENT="Jeff A. Bowles">
  6.    <TITLE>FAQ for integrating Perforce with builds</TITLE>
  7. <x-html>
  8. </HEAD>
  9. <BODY>
  10.  
  11. <H1>
  12. FAQ for integrating Perforce with your build scripts</H1>
  13. <p>
  14. Contributed by Jeff Bowles
  15.  
  16. <H3>
  17. Note - the intended audience for this FAQ is a shell/perl hacker who writes
  18. or maintains local build scripts and wants to integrate Perforce into them.</H3>
  19. <OL>
  20. <H5>
  21. <B>Labels</B></H5>
  22.  
  23. <LI>
  24. <A HREF="#How do I create a label? What should I include in">How do I create
  25. a label? What should I include in a label?</A></LI>
  26.  
  27. <LI>
  28. <A HREF="#If I want to create a new label for each overnight">If I want
  29. to create a new label for each overnight build, how would I do it?</A></LI>
  30.  
  31. <LI>
  32. <A HREF="#Should I use labels or change numbers to track the">Should I
  33. use labels or change numbers to track the contents of overnight builds?</A></LI>
  34.  
  35. <LI>
  36. <A HREF="#So the release needs to be remade three months">So the release
  37. needs to be remade three months after it went out. What do I do?</A></LI>
  38.  
  39. <LI>
  40. <A HREF="#I like this overnight build and want to officially">I like this
  41. overnight build and want to officially designate it as a "release" build.
  42. What should I do?</A></LI>
  43.  
  44. <LI>
  45. <A HREF="#I need to create a release build - what's">I need to create a
  46. release build - what's different in that process?</A></LI>
  47.  
  48. <H5>
  49. <B>Clients</B></H5>
  50.  
  51. <LI>
  52. <A HREF="#How do I populate the build area? What are the">How do I populate
  53. the build area from a nightly build script? What are the problems that
  54. will come up?</A></LI>
  55.  
  56. <H5>
  57. &nbsp;Updating depot files from a script</H5>
  58.  
  59. <LI>
  60. <A HREF="#How do I update the depot to include a new log, or">How do I
  61. update the depot to include a new log, or to include a new line in a logfile?</A></LI>
  62.  
  63. <LI>
  64. <A HREF="#Should I check in my .log files?">Should l check in my log files?
  65. What files might need to be modified and checked in as part of a build?</A></LI>
  66.  
  67. <H5>
  68. Putting a release out</H5>
  69.  
  70. <LI>
  71. <A HREF="#What should I back up when I put a release">What should I back
  72. up when I put a release out?</A></LI>
  73.  
  74. <LI>
  75. <A HREF="#How do I make an escrow copy of the files (that">How do I make
  76. an "escrow" copy of the files (that built the release) for the off-site
  77. vaults?</A></LI>
  78.  
  79. </ol>
  80. <HR>
  81. <ol>
  82. <LI>
  83. <A NAME="How do I create a label? What should I include in"></A><B>How
  84. do I create a build label? What should I include in a label?</B></LI>
  85.  
  86. <BR>&nbsp;
  87. <DL>
  88. <LI>
  89. Pick a regular format for the label name, e.g. "<I>bld_xxx_1</I>" where
  90. '<I>xxx</I>' is the name of the codeline you're building and '<I>1</I>'
  91. is just a counter, i.e. the first such label. Remember this format - you'll
  92. need it in the next question!</LI>
  93.  
  94. <LI>
  95. Make the label itself:</LI>
  96.  
  97.  
  98. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp; p4 label bld_xxx_1</FONT></TT>
  99.  
  100. <P>It'll dump you into an editor, and you can change the default "Views:"
  101. lines from
  102.  
  103. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp; //depot/...</FONT></TT>
  104.  
  105. <P>to look solely at the codeline you want, e.g.
  106.  
  107. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp; //depot/xxx/...</FONT></TT>
  108.  
  109. <P>Save/Quit the editor.
  110. <BR>&nbsp;
  111. <LI>
  112. Populate the label with the file/revision list you want:</LI>
  113.  
  114.  
  115. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp; p4 labelsync -l bld_xxx_1&nbsp;
  116. //depot/xxx/...</FONT></TT>
  117.  
  118. <P><FONT COLOR="#000000">or</FONT>
  119.  
  120. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp; p4 labelsync -l bld_xxx_1
  121. //depot/...</FONT></TT>
  122.  
  123. <P>In this second example, it's okay to include all files in the depot
  124. - it'll really only include files described in the label spec you edited
  125. when you ran "<TT><FONT COLOR="#990000">p4 label</FONT></TT>".
  126. <BR>&nbsp;
  127. <LI>
  128. <B>Always include all files [that are under source management] that are
  129. needed to recreate the build</B> . If your build scripts aren't in codeline
  130. "xxx" you'll want to have the label specification include the directory
  131. where they are, and "<TT><FONT COLOR="#990000">p4 labelsync</FONT></TT>"
  132. needs to include them.</LI>
  133. </DL>
  134.  
  135. <HR>
  136. <LI>
  137. <A NAME="If I want to create a new label for each overnight"></A><B>If
  138. I want to create a new label for each overnight build, how would I do it?</B></LI>
  139.  
  140. <BR>&nbsp;
  141. <DL>
  142. <LI>
  143. Make sure you're using a regular name for the label, e.g. "bld_xxx_yyy"
  144. where "xxx" is the codeline name and "yyy" is a counter.</LI>
  145.  
  146. <LI>
  147. Create the first label in the sequence, which would be "bld_xxx_1". See
  148. the previous question for that.</LI>
  149.  
  150. <LI>
  151. In the Unix shell, you would do the following (cut and paste):</LI>
  152.  
  153.  
  154. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; CodeLineName=xxx</FONT></TT>
  155. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; LabelSpec=tst_${CodeLineName}_</FONT></TT>
  156. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; toplabelnumber=`p4 labels |
  157. grep $LabelSpec | sed "s/^Label $LabelSpec//" | \</FONT></TT>
  158. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  159. sed "s/ .*//" | sort -r -n | head -1`</FONT></TT>
  160. <BR><I><TT><FONT COLOR="#990000">&nbsp;&nbsp; # at this point, we know
  161. the most recent label in this codeline and just need</FONT></TT></I>
  162. <BR><I><TT><FONT COLOR="#990000">&nbsp;&nbsp; # to create a new label and
  163. populate it.</FONT></TT></I>
  164. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; TopLabel=$LabelSpec$toplabelnumber</FONT></TT>
  165. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; echo Current Label is $LabelSpec$toplabelnumber</FONT></TT>
  166. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; if [ "$toplabelnumber" != ""
  167. ]</FONT></TT>
  168. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; then</FONT></TT>
  169. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  170. newlabelnumber=`expr $toplabelnumber + 1`</FONT></TT>
  171. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  172. NewLabel=$LabelSpec$newlabelnumber</FONT></TT>
  173. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  174. echo "New Label is $NewLabel"</FONT></TT>
  175. <BR>&nbsp;
  176. <BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <I><FONT COLOR="#990000">#
  177. the following two commands are from the previous FAQ item.</FONT></I></TT>
  178. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  179. <U>p4 label -o -t $TopLabel $NewLabel | p4 label -i</U></FONT></TT>
  180. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  181. p4 labelsync -l $NewLabel //depot/...</FONT></TT>
  182. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  183. <I># It's best to obsolete labels that are kinda of old, so we</I></FONT></TT>
  184. <BR><I><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  185. # do it here.</FONT></TT></I>
  186. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  187. if [ "$toplabelnumber" -gt 10 ]</FONT></TT>
  188. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  189. then</FONT></TT>
  190. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  191. obsoletelabelnumber=`expr $toplabelnumber - 10`</FONT></TT>
  192. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  193. ObsoleteLabel=$LabelSpec$obsoletelabelnumber</FONT></TT>
  194. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  195. p4 label -d $ObsoleteLabel</FONT></TT>
  196. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  197. fi</FONT></TT>
  198. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; else</FONT></TT>
  199. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  200. echo "There was no label to match!" 1>&amp;2</FONT></TT>
  201. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  202. exit 1</FONT></TT>
  203. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; fi</FONT></TT>
  204. <BR>&nbsp;
  205. <LI>
  206. Perl hackers will look at the previous "Bourne shell" example and use it
  207. as an example of why you don't want to do string processing in "Bourne
  208. shell". One perl treatment of this follows:</LI>
  209. </DL>
  210. &nbsp;
  211. <DL><TT><FONT COLOR="#990000">&nbsp;&nbsp; $CodeLineName = "xxx";</FONT></TT>
  212. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; $LabelSpec="tst_" . $CodeLineName
  213. . "_";</FONT></TT>
  214.  
  215. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; @AllLabels = `p4 labels`;</FONT></TT>
  216. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; @ThisCodeLineLabels = sort(sortrevlabel
  217. grep(/$LabelSpec/, @AllLabels));</FONT></TT>
  218. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; $TopLabelLine = $ThisCodeLineLabels[0];</FONT></TT>
  219. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; $TopLabel = $1 if ($TopLabelLine
  220. =~ /^Label\s(\S+)\s/);</FONT></TT>
  221. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; $TopLabelNumber = $1 if ($TopLabel
  222. =~ /^\S+_(\d+)$/);</FONT></TT>
  223.  
  224. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; print "The last label in this
  225. codeline is $TopLabel\n";</FONT></TT>
  226. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; $NewLabelNumber = $TopLabelNumber
  227. + 1;</FONT></TT>
  228. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; $NewLabel = "$LabelSpec$NewLabelNumber";</FONT></TT>
  229. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; print "New Label is $NewLabel\n";</FONT></TT>
  230. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; system("<U>p4 label -o -t $TopLabel
  231. $NewLabel | p4 label -i</U>");</FONT></TT>&nbsp;&nbsp;&nbsp;<i># in real life, return code would be checked!</i>
  232. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; system("p4 labelsync -l $NewLabel
  233. //depot/...");</FONT></TT>
  234. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; if ($TopLabelNumber > 10 )</FONT></TT>
  235. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; {</FONT></TT>
  236. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  237. $ObsoleteLabelNumber = $TopLabelNumber - 10;</FONT></TT>
  238. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  239. $ObsoleteLabel = "$LabelSpec$ObsoleteLabelNumber";</FONT></TT>
  240. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  241. system("p4 label -d $ObsoleteLabel");</FONT></TT>
  242. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; }</FONT></TT>
  243.  
  244. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; sub sortrevlabel {</FONT></TT>
  245. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  246. my($labelnum_a, $labelnum_b) = ();</FONT></TT>
  247. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  248. $labelnum_a = $1 if ($a =~ /.*_(\d+)/);</FONT></TT>
  249. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  250. $labelnum_b = $1 if ($b =~ /.*_(\d+)/);</FONT></TT>
  251. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  252. return ($labelnum_b &lt;=> $labelnum_a);</FONT></TT>
  253. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  254. }</FONT></TT>
  255. <LI>
  256. <FONT COLOR="#000000">The underlined part in the above fragments probably
  257. should have a "sed" command between the two 'p4 label' commands, to change
  258. the description for each label.</FONT></LI>
  259. </DL>
  260.  
  261. <HR>
  262. <LI>
  263. <A NAME="Should I use labels or change numbers to track the"></A><B>Should
  264. I use labels or change numbers to track the contents of overnight builds?</B></LI>
  265.  
  266. <BR>&nbsp;
  267. <DL>
  268. <LI>
  269. There's no right answer. The command</LI>
  270.  
  271.  
  272. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp; p4 changes -m1 //depot/xxx/...</FONT></TT>
  273.  
  274. <P>will tell a build script what the top change number for codeline 'xxx'
  275. (assuming it's mapped there), so it can parse this output and use that
  276. in build logs and build e-mail. The developer would type:
  277.  
  278. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; p4 sync @12345</FONT></TT>
  279.  
  280. <P>to pull over all files current as of change #12345, but that has a problem:
  281. it'll pull over all files [that his/her client maps in] as of that revision,
  282. not just the files for codeline 'xxx'. You can tell them to type:
  283.  
  284. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; p4 sync //depot/xxx/...@12345</FONT></TT>
  285.  
  286. <P>but, by then, you've lost the simplicity that using the change numbers
  287. might've given you.
  288. <BR>&nbsp;
  289. <LI>
  290. You should probably always use labels for release builds - when you create
  291. a release you'll often need to include an additional change to one particular
  292. file that you need to track, and you want the label to include <U>exactly</U>
  293. the files used to build the release on the build client.</LI>
  294. </DL>
  295.  
  296. <HR>
  297. <LI>
  298. <A NAME="So the release needs to be remade three months"></A><B>So the
  299. release needs to be remade three months after it went out. What do I do?</B></LI>
  300.  
  301. <DL>You'll need a slightly-hacked version of your "get the source and do
  302. a build" script. The hacks are:
  303. <DL>
  304. <LI>
  305. It shouldn't use or touch any labels except for the release label you've
  306. remembered to create when you made the release. Delete the lines in the
  307. script that create labels or run "p4 labelsync" on them.</LI>
  308.  
  309. <LI>
  310. Change the line in the script that does the "<TT><FONT COLOR="#990000">p4
  311. sync -f&nbsp; ...#have</FONT></TT>" so that it looks like:</LI>
  312.  
  313.  
  314. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; p4 sync -f&nbsp; //depot/xxx/...@labelname</FONT></TT>
  315.  
  316. <P>where "xxx" is the name of the codeline, and "labelname" is the release
  317. label.
  318. <LI>
  319. Bug your system administrators about whether compiler versions, OS releases,
  320. etc, have changed since the release was created. Listen carefully to their
  321. answers.</LI>
  322.  
  323. <LI>
  324. Run the script. It should create the original release faithfully, although
  325. most compilers embed timestamps within the .exe and .obj files, so you
  326. might not have byte-for-byte identical files.</LI>
  327.  
  328. <LI>
  329. Rerun your regressions to gain confidence in the newly-built product.</LI>
  330. </DL>
  331. </DL>
  332.  
  333. <HR>
  334. <LI>
  335. <A NAME="I like this overnight build and want to officially"></A><B>I like
  336. this overnight build and want to officially designate it as a "release"
  337. build. What should I do?</B></LI>
  338.  
  339. <DL>See the previous step - you just need to run "p4 label" (to create
  340. a label) and then "p4 labelsync" to the overnight label or change number
  341. that created the build:
  342.  
  343. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; p4 labelsync -l release_label_name&nbsp;
  344. //depot/xxx/...@bld_xxx_23</FONT></TT>
  345.  
  346. <P>or
  347.  
  348. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; p4 labelsync -l release_label_name&nbsp;
  349. //depot/xxx/...@12345</FONT></TT>
  350.  
  351. <P>The first case is for "overnight build #23 for codeline xxx", if you're
  352. using that convention for overnight builds; the second case is if you use
  353. change numbers to track the overnight build contents.
  354. <BR>&nbsp;</DL>
  355.  
  356. <HR>
  357. <LI>
  358. <A NAME="I need to create a release build - what's"></A><B>I need to create
  359. a release build - what's different in that process?</B></LI>
  360.  
  361. <BR>&nbsp;
  362. <DL>This depends on what packages the release for deployment. If you use
  363. the same build mechanisms for overnight and release builds, you should
  364. only need to do 1-2 steps:
  365. <DL>
  366. <LI>
  367. Run the overnight build script to create the build.</LI>
  368.  
  369. <LI>
  370. Label the build area that created the release, using "p4 label" and then
  371. "p4 labelsync". <I>Pick the 'view' for the label carefully, so that it
  372. doesn't include parts of the depot not included in this release.</I></LI>
  373.  
  374. <LI>
  375. Run "p4 label" a second time on the new label, and change the status of
  376. the label to "locked" so that "p4 labelsync" cannot be run against it accidently.</LI>
  377. </DL>
  378. &nbsp;</DL>
  379.  
  380. <HR>
  381. <LI>
  382. <A NAME="How do I populate the build area? What are the"></A><B>How do
  383. I populate the build area for an overnight build? What are the problems
  384. that will come up?</B></LI>
  385.  
  386. <BR>&nbsp;
  387. <DL>
  388. <LI>
  389. If the Perforce client root is C:/p4root, and the codeline is C:/p4root/xxx,
  390. then you'll need to do 2-3 things to populate the area prior to building:</LI>
  391.  
  392. <DL>
  393. <LI>
  394. Make a copy of the scripts that'll do the populating, if there's a chance
  395. that you'll delete them in the next two steps! (Leave a place for your
  396. scripts to stand.)</LI>
  397.  
  398. <LI>
  399. Run the OS command to delete the codeline directory, e.g.</LI>
  400.  
  401.  
  402. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; del/s&nbsp; c:\p4root\xxx</FONT></TT>
  403.  
  404. <P>it's important to do this if you want a clean build - don't rely on
  405. incremental compile for overnight compiles unless the compilation process
  406. takes many hours.
  407. <LI>
  408. Repopulate the source:</LI>
  409.  
  410.  
  411. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; p4 sync -f C:/p4root/xxx/...#have</FONT></TT>
  412. <LI>
  413. Update the source to the most recent revisions:</LI>
  414.  
  415.  
  416. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; p4 sync&nbsp; C:/p4root/xxx/...</FONT></TT>
  417. <LI>
  418. <FONT COLOR="#000000">Update your build labels (or remember the current
  419. change numbers) to reflect this new content.</FONT></LI>
  420. </DL>
  421. Deleting the entire codeline build tree (and any "obj" or "lib" directories
  422. if they're not directly under C:\p4root\xxx) is important because old object
  423. files often can bite you.
  424. <BR>&nbsp;
  425. <LI>
  426. Most problems that come up in this area have to do with obsolete object/library
  427. files. <U>Entirely removing the source area and repopulating saves you
  428. from this headache completely.</U></LI>
  429. </DL>
  430.  
  431. <HR>
  432. <LI>
  433. <A NAME="How do I update the depot to include a new log, or"></A><B>How
  434. do I update the depot to include a new log, or to include a new line in
  435. a logfile?</B></LI>
  436.  
  437. <BR>&nbsp;
  438. <DL>
  439. <LI>
  440. To include a new log or edit a file, you should:</LI>
  441.  
  442. <DL>
  443. <LI>
  444. Open the file for either "add" or "edit";</LI>
  445.  
  446. <LI>
  447. Modify the file in whatever ways make sense;</LI>
  448.  
  449. <LI>
  450. Use "p4 change -o" and "p4 submit -i" to create the submitted change.</LI>
  451. </DL>
  452. An example of this, in a Unix shell script, follows:
  453.  
  454. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; operation=add</FONT></TT>
  455. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; filename=newfile.txt</FONT></TT>
  456. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; <U>filetype=ltext</U></FONT></TT>
  457. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; [ -f $filename ] &amp;&amp;
  458. operation=edit</FONT></TT>
  459. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; description="log of build for
  460. `date`"</FONT></TT>
  461.  
  462. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; p4 $operation -t $filetype $filename</FONT></TT>
  463.  
  464. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; echo New information as of `date`
  465. >> $filename</FONT></TT>
  466. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; <I># this point, we need to
  467. construct the change submission with</I></FONT></TT>
  468. <BR><I><TT><FONT COLOR="#990000">&nbsp;&nbsp; # an accurate description
  469. in the change text.</FONT></TT></I>
  470. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; p4 change -o&nbsp; > xx.tmp</FONT></TT>
  471. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; (</FONT></TT>
  472. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  473. echo "/^Files:/+1,\$v/$filename/d"</FONT></TT>
  474. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  475. echo "/&lt;enter description here>/s/.*/&nbsp;&nbsp;&nbsp; $description/"</FONT></TT>
  476. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  477. echo w</FONT></TT>
  478. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  479. echo q</FONT></TT>
  480. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; ) | ed - xx.tmp</FONT></TT>
  481. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; p4 submit -i &lt; xx.tmp</FONT></TT>
  482. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; rm xxx.tmp</FONT></TT>
  483.  
  484. <P><FONT COLOR="#000000"><I>Perl</I> hackers won't see substantial gains
  485. by doing this in <I>perl</I>, and the 'ed' is actually easier from the
  486. shell script.</FONT>
  487. <BR>&nbsp;
  488. <LI>
  489. <FONT COLOR="#000000">The underlined part above is important, if the file
  490. you're working with is a giant log file, because giant text files should
  491. include this <U>hint</U> so that the files will be stored in more efficient
  492. ways.</FONT></LI>
  493. </DL>
  494.  
  495. <HR>
  496. <LI>
  497. <A NAME="Should I check in my .log files?"></A><B>Should l check in my
  498. log files? What files might need to be modified and checked in as part
  499. of a build?</B></LI>
  500.  
  501. <BR>&nbsp;
  502. <DL>
  503. <LI>
  504. There's no good answer for this - log files are usually huge, and can start
  505. eating space quickly. It's probably best to keep them in a disk area that's
  506. backed up regularly, but not to check them in if you can avoid it.</LI>
  507.  
  508. <LI>
  509. If, however, you track overnight builds based on change numbers instead
  510. of labels, you might want to have a file somewhere in the <I>depot</I>
  511. that contains one-line entries of the form:</LI>
  512.  
  513. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; change #12345 - overnight build
  514. for 07/22/98</FONT></TT>
  515. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; change #12366 - overnight build
  516. for 07/23/98</FONT></TT>
  517. <BR>and so on. That should be modified (appended to) by the build scripts
  518. using code similar to the example above. <U>It gets really hard to track
  519. which change corresponded to which nightly build, otherwise.</U>
  520. <BR>&nbsp;</DL>
  521.  
  522. <HR>
  523. <LI>
  524. <A NAME="What should I back up when I put a release"></A><B>What should
  525. I back up when I put a release out?</B></LI>
  526.  
  527. <BR>&nbsp;
  528. <BR>As a minimum, you'll need to back up the source files and build scripts
  529. in Perforce that created the product. This makes several assumptions:
  530. <DL>
  531. <LI>
  532. That the build environment (machine, OS, compilers, etc) are easily recreateable
  533. from media you have in-hand;</LI>
  534.  
  535. <LI>
  536. That, if you only back up the top revision of those files, you won't need
  537. file revision history and the like.</LI>
  538. </DL>
  539. Usually, however, <U>you'll probably just want to back up the entire Perforce
  540. depot so that you have a complete snapshot of everything</U>, and then
  541. if you restore from this backup you can refer to current labels such as
  542. the <I>product release label</I> you made when you released the product.
  543. (You can also refer to intermediate build labels if you choose, since they'll
  544. be included in the backup.)
  545.  
  546. <P>To make the most comprehensive backup, you'll need to do the following:
  547. <DL>
  548. <LI>
  549. Checkpoint the Perforce database and save the checkpoint and the subdirectory
  550. $P4ROOT/depot with all its contents:</LI>
  551.  
  552.  
  553. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp; cd $P4ROOT</FONT></TT>
  554. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp; p4d&nbsp;&nbsp; -r&nbsp;&nbsp;
  555. .&nbsp;&nbsp; -jc</FONT></TT>
  556.  
  557. <P><FONT COLOR="#000000">Note that this is documented in the "FAQ for System
  558. Administrators" and also on-line in the Perforce manuals.</FONT>
  559. <LI>
  560. <FONT COLOR="#000000">Save a copy of the Perforce executables you're using,
  561. server and client versions.</FONT></LI>
  562.  
  563. <LI>
  564. <FONT COLOR="#000000">Do a full system backup of the build machine on which
  565. the product was created. This isn't so much to get the source onto media
  566. as to get compilers, OS, etc.</FONT></LI>
  567.  
  568. <LI>
  569. <FONT COLOR="#000000">Put this all onto a medium you trust, that'll be
  570. around for a while.</FONT></LI>
  571.  
  572. <LI>
  573. <FONT COLOR="#000000">Write the <I>product release label,</I> the one that
  574. you created when you built the product, on the media case. Include with
  575. the case a hard-copy printout of the exact commands you typed to create
  576. the media, e.g. <I>created using "tar rvf".</I></FONT></LI>
  577. </DL>
  578. <I><FONT COLOR="#000000">The second and third steps are slight overkill
  579. for many situations, but if you wanna be incredibly paranoid, that's the
  580. approach to take.</FONT></I>
  581. <BR>&nbsp;
  582.  
  583. <HR>
  584. <LI>
  585. <A NAME="How do I make an escrow copy of the files (that"></A><B>How do
  586. I make an "escrow" copy of the files (that built the release) for the off-site
  587. vaults?</B></LI>
  588.  
  589. <BR>&nbsp;
  590. <BR>You can use a label to create an initial fileset that you'll archive.
  591. It's pretty easy:
  592. <DL>
  593. <LI>
  594. Create a label using <TT><FONT COLOR="#990000">p4 label, <I>escrowlabelname1.0,
  595. </I></FONT></TT>that maps in only the directories you want. (You'll edit
  596. the label specification to either include as many directories as you choose,
  597. or perhaps the exact file list itself.)</LI>
  598.  
  599. <LI>
  600. Populate the label, using:</LI>
  601.  
  602.  
  603. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  604. p4 labelsync -l&nbsp; <I>escrowlabelname1.0</I>&nbsp;&nbsp; //buildclientname/...#have</FONT></TT>
  605.  
  606. <P>or,
  607.  
  608. <P><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  609. p4 labelsync -l&nbsp;&nbsp; <I>escrowlabelname1.0&nbsp;&nbsp;</I> @release_source_label</FONT></TT>
  610.  
  611. <P>The first example relies on the build client having the exact files,
  612. at this moment, that it did when it created the build; the second example
  613. relies on having a label of all the source files that were built to create
  614. the release.
  615. <LI>
  616. Create a new Perforce client that maps its client area to an empty part
  617. of the disk, and on that new client run the command:</LI>
  618.  
  619. <BR><TT><FONT COLOR="#990000">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  620. p4 sync&nbsp; @<I>escrowlabelname1.0</I></FONT></TT>
  621. <LI>
  622. Back up this new area.</LI>
  623.  
  624. <LI>
  625. Run <TT><FONT COLOR="#990000">p4 label <I>escrowlabel1.0</I>&nbsp;</FONT></TT>
  626. and mark the label "locked". This will prevent accidently updates of that
  627. label.</LI>
  628. </DL>
  629. When release 2.0 goes out and you need to do this again, follow the same
  630. steps. When you create the label, however, use the original (release 1.0)
  631. escrowlabel as a template, using<TT><FONT COLOR="#990000">&nbsp; p4&nbsp;
  632. label -t <I>escrowlabel1</I>.0&nbsp;</FONT></TT> escrowlabel2.0 .</OL>
  633.  
  634. <I>Last modified on 21 September 1998.</I>
  635. </BODY>
  636. </HTML>
# Change User Description Committed
#2 111 Laura Wingerd Put contributor attributions on FAQ pages. 26 years ago
#1 35 Laura Wingerd Create my guest branch. 26 years ago
//public/perforce/faq/build.html
#3 27 Jeff Bowles Adding important comment. 26 years ago
#2 20 Jeff Bowles Cleaning up numbered lists. 26 years ago
#1 1 laura Add FAQs.
(Still needs index page.) 		26 years ago