Helix SwarmHelix Swarm

GettingStarted.html

  • //
  • guest/
  • dick_dunbar/
  • jam/
  • src/
  • GettingStarted.html #1
  • View
  • Commits
  • Open Download .zip Download (39 KB) 
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
  2. <HTML>
  3.  
  4. <HEAD>
  5. 	<META HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=iso-8859-1">
  6. <meta name="VPSiteProject" content="file:///D|/rld/Docs/Project.vpp">
  7. <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  8.  
  9. 	<META NAME="GENERATOR" Content="Visual Page 2.0 for Windows">
  10. 	<TITLE>Getting Started with Jam/MR A Tutorial</TITLE>
  11.  
  12. 	<STYLE TYPE="text/css">
  13. 	<!--
  14. 	.goohl0	 {
  15. 			Color : black ;
  16. 			Background-Color : #FFFF66
  17. 		}
  18. 	-->
  19. 	</STYLE>
  20.  
  21. </HEAD>
  22.  
  23. <BODY BGCOLOR="white" LINK="blue" VLINK="blue">
  24.  
  25. <P>
  26.  
  27. <DIV ALIGN="CENTER">
  28. <nobr>
  29. 	<P>Getting Started with Jam/MR </nobr>
  30. </DIV>
  31.  
  32.  
  33. <DIV ALIGN="CENTER">
  34. 	<P>Laura Wingerd<BR>
  35. 	Perforce Software<BR>
  36. 	Perforce User Conference 2001<BR>
  37. 	<SPAN STYLE="Font-Weight : Bold">Abstract</SPAN>
  38. </DIV>
  39.  
  40.  
  41. <DIV ALIGN="CENTER">
  42. 	<P><SPAN STYLE="Font-Style : Italic">Jam/MR (&quot;Jam - make(1)Redux&quot;) is a software build tool. Its command
  43. 	language and processing logic are enough unlike make </SPAN><BR>
  44. 	<SPAN STYLE="Font-Style : Italic">that new users often have trouble learning how to use it to its best advantage.
  45. 	</SPAN><BR>
  46. 	<SPAN STYLE="Font-Style : Italic">In this talk, I'll demonstrate some of Jam's most useful features in a series
  47. 	of progressively </SPAN><BR>
  48. 	<SPAN STYLE="Font-Style : Italic">interesting examples. The basic knowledge gleaned from these examples will give
  49. 	you the insight you need to </SPAN><BR>
  50. 	<SPAN STYLE="Font-Style : Italic">incorporate very sophisticated Jam features into a powerful build system. You'll
  51. 	find it helpful to have the</SPAN><BR>
  52. 	<SPAN STYLE="Font-Style : Italic">Jam documentation at hand as you follow along.</SPAN>
  53. </DIV>
  54.  
  55. <P>
  56. <H2><SPAN STYLE="Font-Weight : Bold">1. Background</SPAN></H2>
  57. <PRE><SPAN STYLE="Font-Weight : Bold"></SPAN></PRE>
  58. <P>Jam was written by Christopher Seiwald. It has been freely available as C++ source for many years. <BR>
  59. It is widely used to build commercial and academic software, and has evolved into a few variants.<BR>
  60. It's even shipped with the Macintosh OS/X operating system. <BR>
  61. Nevertheless, it hasn't supplanted make and the O'Reilly book on Jam has yet to be written.<BR>
  62. <BR>
  63. Jam's distinguishing strengths are its portability and speed. Its portability comes from the way the Jam<BR>
  64. command language segregates platform-dependent specifications, like compile and link commands, from<BR>
  65. platform-independent specifications, like dependencies. (More on this in a bit.) Its speed comes in part<BR>
  66. from its single-invocation processing logic. The Jam executable is invoked once -- unlike make which<BR>
  67. must invoke itself recursively -- to gather, analyze, and act on its input.
  68. <H2><SPAN STYLE="Font-Weight : Bold">2. How Jam Works</SPAN></H2>
  69. <P>Jam is a stand-alone executable program. When you invoke it, it does three things. <BR>
  70. First, it reads in &quot;Jamfiles&quot; (akin to &quot;Makefiles&quot;) containing your instructions. <BR>
  71. Next, it scans directories (and sometimes files) looking for 'targets' defined by your instructions; <BR>
  72. a Jam 'target' is a file that is used, created or updated during a build. <BR>
  73. Finally, it executes system commands to create or update targets. <BR>
  74. These three phases of Jam processing are called parsing, binding, and updating. <BR>
  75. At the end of this presentation you'll understand why it's important to know about the three phases.
  76. <H3><SPAN STYLE="Font-Weight : Bold">2.1 Running Jam</SPAN></H3>
  77. <P><SPAN STYLE="Font-Weight : Bold"><BR>
  78. </SPAN>If you have a 'jam' executable available, you can try any of the Jam examples shown here yourself.<BR>
  79. Simply put the example text in a file and run:<BR>
  80. <FONT FACE="Courier New, Courier">jam -f </FONT><SPAN STYLE="Font-Style : Italic"><FONT FACE="Courier New, Courier">yourfile</FONT></SPAN><SPAN
  81. STYLE="Font-Style : Italic"><BR>
  82. <BR>
  83. </SPAN>(Normally you'd put your Jam commands in a file called 'Jamfile'. That's the file Jam looks for by<BR>
  84. default when you don't use the '-f' flag. However, by default, Jam also invokes a setup file called the Jambase,<BR>
  85. which would add unnecessary complexity to the examples here.)<BR>
  86. <BR>
  87. You can use a number of Jam command line flags to show revealing diagnostic information:<BR>
  88. <FONT FACE="Courier New, Courier">-d2 </FONT>Diagnostic output level two: shows the OS commands used to create
  89. or update files being built.<BR>
  90. <FONT FACE="Courier New, Courier">-d5</FONT> Diagnostic output level five: shows you how your Jamfiles are being
  91. interpreted (which<BR>
  92. procedures are being run, which variables are being set, etc.). Try using this flag with the simple<BR>
  93. examples discussed below.<BR>
  94. <FONT FACE="Courier New, Courier">-n</FONT> Run without actually executing any update commands.<BR>
  95. <FONT FACE="Courier New, Courier">-a </FONT>Rebuild all targets, whether they need it or not.<BR>
  96. <BR>
  97. You can combine these flags, e.g.:<BR>
  98. <FONT FACE="Courier New, Courier">jam -nd5a -f </FONT><SPAN STYLE="Font-Style : Italic"><FONT FACE="Courier New, Courier">yourfile</FONT></SPAN>
  99. <H2><SPAN STYLE="Font-Weight : Bold">3. The Jam Language</SPAN></H2>
  100. <P><BR>
  101. Before we get started with example Jamfiles, let's take a look at some interesting aspects of <BR>
  102. Jam's simple yet intuitive language.
  103. <H3><SPAN STYLE="Font-Weight : Bold">3.1 Syntax</SPAN></H3>
  104. <P>The Jam language has a very straightforward syntax. Even so, it manages to confound new users. The most<BR>
  105. misunderstood rules of the language are:<BR>
  106. * Case is significant.<BR>
  107. * Statement elements (called &quot;tokens&quot;)<SPAN STYLE="Font-Style : Italic"> must be separated by whitespace.</SPAN><BR>
  108. * Every statement ends with a semicolon --- in its own token!<BR>
  109. <BR>
  110. Here are some examples:<BR>
  111. <FONT FACE="Courier New, Courier">X = foo.c ;</FONT><BR>
  112. <SPAN STYLE="Font-Style : Italic">This is a single Jam statement that sets the value of &quot;X&quot; to &quot;foo.c&quot;.</SPAN><BR>
  113. <BR>
  114. <FONT FACE="Courier New, Courier">X = foo.c ; x = bar.c ;</FONT><BR>
  115. <SPAN STYLE="Font-Style : Italic">This pair of statements sets two Jam variables.</SPAN><BR>
  116. <SPAN STYLE="Font-Style : Italic">First it sets a variable named 'X&quot; to &quot;foo.c&quot;, then it sets a
  117. variable named &quot;x&quot; to &quot;bar.c&quot;.<BR>
  118. <BR>
  119. </SPAN><FONT FACE="Courier New, Courier">X = foo.c;</FONT><BR>
  120. <SPAN STYLE="Font-Style : Italic">This is an incomplete statement that will cause a syntax error, or worse, unexplainable</SPAN><BR>
  121. <SPAN STYLE="Font-Style : Italic">results. When Jam reads this it will set the value of X to &quot;foo.c;&quot;
  122. plus whatever happens</SPAN><BR>
  123. <SPAN STYLE="Font-Style : Italic">to be on the next line. Why? Because there is no whitespace before the semicolon
  124. that is<BR>
  125. meant to end the statement.</SPAN><BR>
  126. <BR>
  127. Each statement in the Jam language either sets a variable or invokes a &quot;rule&quot;. <BR>
  128. (A &quot;rule&quot; is basically a procedure.) You can tell whether a statement is setting <BR>
  129. a variable or invoking a rule by the presence of an equal sign. <BR>
  130. For example, all the statements above set variables. <BR>
  131. Here are some statements that invoke rules:<BR>
  132. <FONT FACE="Courier New, Courier">X foo.c ;</FONT><BR>
  133. <SPAN STYLE="Font-Style : Italic">This invokes a rule called &quot;X&quot; and passes it one argument, &quot;foo.c&quot;.<BR>
  134. <BR>
  135. </SPAN><FONT FACE="Courier New, Courier">X=foo.c ;</FONT><BR>
  136. <BR>
  137. <SPAN STYLE="Font-Style : Italic">This is a perfectly acceptable Jam statement, but it doesn't do what you think
  138. </SPAN><BR>
  139. <SPAN STYLE="Font-Style : Italic">it's going to do. This statement invokes a rule named &quot;X=foo.c&quot; with
  140. no arguments. </SPAN><BR>
  141. <SPAN STYLE="Font-Style : Italic">Why is this not treated as an assignment statement? </SPAN><BR>
  142. <SPAN STYLE="Font-Style : Italic">Because there is no whitespace delimiting the &quot;=&quot; sign.</SPAN><BR>
  143. <BR>
  144. Actually, Jam recognizes a third type of statement as well. <BR>
  145. Statements that begin with certain keywords are &quot;flow-of-control&quot; statements. <BR>
  146. These keywords are fairly easy to recognize; they include &quot;if&quot;, &quot;for&quot;,<BR>
  147. &quot;switch&quot;, and &quot;include&quot;.<BR>
  148. <BR>
  149. Flow-of-control statements and additional Jam language syntax will be introduced in later examples. By the<BR>
  150. end of this presentation you'll be familiar enough with how Jam works that any syntax or functionality<BR>
  151. not shown here will make perfect sense to you when you read about it in the Jam documentation.
  152. <H3><SPAN STYLE="Font-Weight : Bold">3.2 Liberals</SPAN></H3>
  153. <P><SPAN STYLE="Font-Weight : Bold"><BR>
  154. </SPAN>Literals don't have to be quoted in the Jam language. <BR>
  155. Anything that is not a variable name, a rule name, or an operator is assumed to be a literal. <BR>
  156. And every literal is a string. (There is no other data type in Jam!)<BR>
  157. For example:<BR>
  158. <FONT FACE="Courier New, Courier">X = foo.c ;<BR>
  159. foo.c = X ;</FONT><BR>
  160. This assigns the literal value &quot;foo.c&quot; to a variable named X, <BR>
  161. then assigns the literal value &quot;X&quot; to a variable named &quot;foo.c&quot;.<BR>
  162. <BR>
  163. Quotes <SPAN STYLE="Font-Style : Italic">are </SPAN>necessary, however, to refer to a literal that contains spaces,
  164. <BR>
  165. &quot;=&quot;, or other characters that Jam would interpret differently. For example:<BR>
  166. <FONT FACE="Courier New, Courier">X = &quot;this ; and ; this&quot; ;</FONT><BR>
  167. <SPAN STYLE="Font-Style : Italic">This assigns the string value &quot;this ; and ; this&quot; to variable X.</SPAN>
  168. <H3><SPAN STYLE="Font-Weight : Bold">3.3 Variables</SPAN></H3>
  169. <P><SPAN STYLE="Font-Weight : Bold"><BR>
  170. </SPAN>Jam variable values are strings. A single Jam variable can hold a list of values, each value is a string:<BR>
  171. <FONT FACE="Courier New, Courier">X = a b 1 '2 3' ;</FONT><BR>
  172. <SPAN STYLE="Font-Style : Italic">Assigns a list of string values, &quot;a&quot;, &quot;b&quot;, &quot;1&quot;
  173. and &quot;2 3&quot; to variable X.<BR>
  174. <BR>
  175. </SPAN>Jam variable names are also strings. You can name a variable almost anything you want:<BR>
  176. <FONT FACE="Courier New, Courier">&quot;My dog has fleas!&quot; = yes ;</FONT><BR>
  177. <BR>
  178. <SPAN STYLE="Font-Style : Italic">name of the variable set here is &quot;My dog has fleas!&quot; and its value
  179. is a </SPAN><BR>
  180. <SPAN STYLE="Font-Style : Italic">single-element list containing the string &quot;yes&quot;.</SPAN><BR>
  181. <BR>
  182. You can also set more than one variable at once:<BR>
  183. <FONT FACE="Courier New, Courier">My dog has fleas! = yes ;</FONT><BR>
  184. <BR>
  185. <SPAN STYLE="Font-Style : Italic">The one-element list containing the string &quot;yes&quot; is assigned to variables
  186. named &quot;My&quot;,</SPAN><BR>
  187. <SPAN STYLE="Font-Style : Italic">&quot;dog&quot;, &quot;has&quot; and &quot;fleas!&quot;.</SPAN>
  188. <H3><SPAN STYLE="Font-Weight : Bold">3.3.1 Variable Expansion</SPAN></H3>
  189. <P><BR>
  190. Referring to a variable's value is called expansion in Jam. <BR>
  191. In its simplest form, you use &quot;$(name)&quot; to expand a variable. For example:<BR>
  192. <FONT FACE="Courier New, Courier">X = This is a message. ;<BR>
  193. Echo $(X) ;</FONT><BR>
  194. <SPAN STYLE="Font-Style : Italic">Invokes Jam's built-in &quot;Echo&quot; rule to output the list of strings assigned
  195. to X.</SPAN><BR>
  196. <SPAN STYLE="Font-Style : Italic">In other words, this outputs: This is a message.</SPAN><BR>
  197. <BR>
  198. You can use variable expansion on the left-hand side of an assignment statement as well:<BR>
  199. <FONT FACE="Courier New, Courier">X = Hello ;<BR>
  200. $(X) = Bye ;</FONT><BR>
  201. <BR>
  202. <SPAN STYLE="Font-Style : Italic">Assigns &quot;Hello&quot; to X, then assigns &quot;Bye&quot; to a variable named
  203. Hello.<BR>
  204. <BR>
  205. </SPAN>When a variable list contains more than one item, its expansion results in a list:<BR>
  206. <FONT FACE="Courier New, Courier">X = A B C ;<BR>
  207. $(X) = Hi there ;</FONT><BR>
  208. <SPAN STYLE="Font-Style : Italic">Assigns strings &quot;A&quot;, &quot;B&quot;, and &quot;C&quot; to variable X.
  209. Then assigns the list of strings</SPAN><BR>
  210. <SPAN STYLE="Font-Style : Italic">&quot;Hi&quot; and &quot;there&quot; to each of variables A, B, and C.</SPAN><BR>
  211. <BR>
  212. You can use a &quot;subscript&quot; to refer to specific list items, with the syntax &quot;$(name[subscript])&quot;:<BR>
  213. <FONT FACE="Courier New, Courier">X = A B C ;<BR>
  214. Echo $(X[2]) ;</FONT><BR>
  215. <SPAN STYLE="Font-Style : Italic">Outputs &quot;B&quot;.</SPAN><BR>
  216. <BR>
  217. You can add elements to a list with the &quot;+=&quot; operator:<BR>
  218. <FONT FACE="Courier New, Courier">X = A B C ;<BR>
  219. X += $(X) ;</FONT><BR>
  220. <SPAN STYLE="Font-Style : Italic">Now X contains the list: A B C A B C</SPAN>
  221. <H3><SPAN STYLE="Font-Weight : Bold">3.3.2 Variable Expansion Products</SPAN></H3>
  222. <P><SPAN STYLE="Font-Weight : Bold"><BR>
  223. </SPAN>When variable expansions are combined with each other or with literals in a single Jam token they are<BR>
  224. expanded to a <SPAN STYLE="Font-Style : Italic">product</SPAN>. That product is itself a list. Here are some examples:<BR>
  225. <FONT FACE="Courier New, Courier">X = A B C ;<BR>
  226. Y = E F ;<BR>
  227. Echo $(X)$(Y) ;</FONT><BR>
  228. <SPAN STYLE="Font-Style : Italic">Outputs: AE AF BE BF CE CF</SPAN><BR>
  229. <BR>
  230. <FONT FACE="Courier New, Courier">X = A B C ;<BR>
  231. Y = test_$(X).result</FONT><BR>
  232. <SPAN STYLE="Font-Style : Italic">Y now contains this list of strings: &quot;test_A.result&quot;, &quot; test_B.result&quot;,
  233. and &quot;test_C.result&quot;</SPAN><BR>
  234. <BR>
  235. <FONT FACE="Courier New, Courier">X = A B C D E F G H ;<BR>
  236. Selected = 3 7 8 ;<BR>
  237. Echo $(X[$(Selected)]) ;<BR>
  238. </FONT><SPAN STYLE="Font-Style : Italic"><FONT FACE="Courier New, Courier">Outputs: C G H</FONT></SPAN><BR>
  239. <BR>
  240. Remember that a Jam &quot;token&quot; is a statement element delimited by whitespace. <BR>
  241. To identify a single token that contains a blank, use quotes. Compare these two examples:<BR>
  242. <FONT FACE="Courier New, Courier">X = Bob Sue Pat ;<BR>
  243. Echo 'Hello $(X)!' ;</FONT><BR>
  244. <SPAN STYLE="Font-Style : Italic">Outputs: Hello Bob! Hello Sue! Hello Pat!</SPAN><BR>
  245. <BR>
  246. <FONT FACE="Courier New, Courier">X = Bob Sue Pat ;<BR>
  247. Echo Hello $(X)! ;</FONT><BR>
  248. <SPAN STYLE="Font-Style : Italic">Outputs Hello Bob! Sue! Pat!</SPAN><BR>
  249. <BR>
  250. When a token in a Jam statement contains a reference to a variable whose value list is empty, the expanded<BR>
  251. result is an empty list. (Think of it as multiplying by zero.) A variable that has not been set is the same<BR>
  252. as a variable whose value list is empty. You can also explicitly set a variable to an empty list. Note that an<BR>
  253. empty list is not the same as a list of one or more null strings. Here are some examples:<BR>
  254. <BR>
  255. <FONT FACE="Courier New, Courier">X = Bob Sue Pat ;<BR>
  256. Echo Hello $(X)$(Y) ;</FONT><BR>
  257. <SPAN STYLE="Font-Style : Italic">Y has not been set, so this outputs simply: Hello<BR>
  258. <BR>
  259. </SPAN><FONT FACE="Courier New, Courier">X = Bob Sue Pat ;<BR>
  260. Y = &quot;&quot; &quot;&quot; ;<BR>
  261. Echo Hello $(X)$(Y) ;</FONT><BR>
  262. <SPAN STYLE="Font-Style : Italic">Y is set to a list of two null strings, so this outputs: Hello Bob Sue Pat Bob
  263. Sue</SPAN><BR>
  264. <BR>
  265. <FONT FACE="Courier New, Courier">Y Z = test ;<BR>
  266. X = Bob Sue Pat ;<BR>
  267. Y = ;<BR>
  268. Z = $(X)$(Y) ;</FONT><BR>
  269. <SPAN STYLE="Font-Style : Italic">Because Y was unset, the $(X)$(Y) product is an empty list. As a result, this</SPAN><BR>
  270. <SPAN STYLE="Font-Style : Italic">explicitly unsets Z.</SPAN>
  271. <H3><SPAN STYLE="Font-Weight : Bold">3.3.3 Variable Expansion Modifiers</SPAN></H3>
  272. <P><BR>
  273. &quot;Modifiers&quot; in Jam variable expansions can be used to change the resulting values. <BR>
  274. Modifier syntax in variable expansion is &quot;$(name:modifier)&quot;. <BR>
  275. For example, you can use the &quot;U&quot; and &quot;L&quot; modifiers to force the case of the expanded result:<BR>
  276. <BR>
  277. <FONT FACE="Courier New, Courier">X = This is<BR>
  278. Y = A TEST ;<BR>
  279. Echo $(X:U) $(Y:L) ;</FONT><BR>
  280. <SPAN STYLE="Font-Style : Italic">Outputs: THIS IS a test</SPAN><BR>
  281. <BR>
  282. Most Jam modifiers are specifically designed for handling file names and directory paths. Of those, some<BR>
  283. trim down the expanded result, and some replace parts of the expanded result. For example, the &quot;S=suffix&quot;<BR>
  284. modifier can be used to replace the filename suffix:<BR>
  285. <FONT FACE="Courier New, Courier">X = foo.c ;<BR>
  286. Y = $(X:S=.obj) ;</FONT><BR>
  287. <SPAN STYLE="Font-Style : Italic">Assigns the value &quot;foo.obj&quot; to Y.<BR>
  288. <BR>
  289. </SPAN>You can combine modifiers with each other, with list item subscripts, and with product expansions. <BR>
  290. Here's a hideous example:<BR>
  291. <FONT FACE="Courier New, Courier">X = foo.c bar.c ola.c ;<BR>
  292. Y = .c .obj .exe .dll ;<BR>
  293. Echo $(X[2]:S=$(Y):U) ;</FONT><BR>
  294. <SPAN STYLE="Font-Style : Italic">Outputs: BAR.C BAR.OBJ BAR.EXE BAR.DLL</SPAN>
  295. <H3><SPAN STYLE="Font-Weight : Bold">3.3.4 Variables Are Expanded During Parsing!</SPAN></H3>
  296. <P><BR>
  297. Remember the three phases of Jam execution? Variable expansion in your Jamfiles occurs<BR>
  298. <SPAN STYLE="Font-Style : Italic">during the parsing phase</SPAN>, before Jam scans your filesystem, and before
  299. it executes<BR>
  300. <SPAN STYLE="Font-Style : Italic">any</SPAN> system commands.<BR>
  301. This means that <B>you can't assign the output of system commands</B> (e.g. &quot;ls&quot;, or &quot;find&quot;)<BR>
  302. to Jam variables!
  303. <H3><SPAN STYLE="Font-Weight : Bold">3.4 Rules</SPAN></H3>
  304. <P><BR>
  305. Jam &quot;rules&quot; are procedures that are interpreted and executed during the parsing phase. <BR>
  306. They can be invoked with arguments passed to them. <BR>
  307. Each argument is a list; arguments are separated by colon tokens. <BR>
  308. For example:<BR>
  309. <FONT FACE="Courier New, Courier">Depends a : b c d ;</FONT><BR>
  310. <SPAN STYLE="Font-Style : Italic">Invokes the built-in &quot;Depends&quot; rule with two arguments. </SPAN><BR>
  311. <SPAN STYLE="Font-Style : Italic">The first argument is a list of one item, &quot;a&quot;. </SPAN><BR>
  312. <SPAN STYLE="Font-Style : Italic">The second argument is a list of three items, &quot;b&quot;, &quot;c&quot;, and
  313. &quot;d&quot;.</SPAN><BR>
  314. <BR>
  315. Here's an example of how a rule is defined:<BR>
  316. <FONT FACE="Courier New, Courier">rule MyRule {<BR>
  317. Echo First arg is $(1) ;<BR>
  318. Echo Second arg is $(2) ;<BR>
  319. Echo Third arg is $(3) ;<BR>
  320. }</FONT><BR>
  321. And here's how you might invoke it:<BR>
  322. <BR>
  323. <FONT FACE="Courier New, Courier">MyRule a : b c : d e f</FONT><BR>
  324. <SPAN STYLE="Font-Style : Italic">Outputs:</SPAN><BR>
  325. <SPAN STYLE="Font-Style : Italic">First arg is a</SPAN><BR>
  326. <SPAN STYLE="Font-Style : Italic">Second arg is b c</SPAN><BR>
  327. <SPAN STYLE="Font-Style : Italic">Third arg is d e f</SPAN><BR>
  328. <BR>
  329. For backward compatibility, $(&lt;) and $(&gt;) are allowed in place of $(1) and $(2) in the body of a rule.<BR>
  330. In older Jamfiles you may see rule definitions that look like:<BR>
  331. <FONT FACE="Courier New, Courier">rule MyRule {<BR>
  332. Echo First arg is $(&lt;) ;<BR>
  333. Echo Second arg is $(&gt;) ;<BR>
  334. }</FONT>
  335. <H3><SPAN STYLE="Font-Weight : Bold">3.5 Actions</SPAN></H3>
  336. <P>An &quot;action&quot; in Jam is a special-purpose rule used to specify system commands that will be run<BR>
  337. during Jam's updating phase. <BR>
  338. The &quot;actions&quot; keyword identifies an action definition. <BR>
  339. The body of an action definition contains system commands, not Jam language statements. <BR>
  340. However, it<SPAN STYLE="Font-Style : Italic"> can </SPAN>contain Jam variables.<BR>
  341. Here's a simple action definition:<BR>
  342. <FONT FACE="Courier New, Courier">actions MyAction {<BR>
  343. touch $(1)<BR>
  344. cat $(2) &gt;&gt; $(1)<BR>
  345. }</FONT><BR>
  346. If this action were invoked thus:<BR>
  347. <FONT FACE="Courier New, Courier">MyAction ola : foo bar ;</FONT><BR>
  348. this command sequence would be passed to the OS command shell to update &quot;ola&quot;:<BR>
  349. <FONT FACE="Courier New, Courier">touch ola<BR>
  350. cat foo bar &gt;&gt; ola</FONT><BR>
  351. <BR>
  352. Actions have these special characteristics which set them apart from rules:<BR>
  353. <BR>
  354. * They accept only two arguments. <BR>
  355. In other words, you can refer to $(1) and $(2), but not $(3) in<BR>
  356. the body of an action.<BR>
  357. * All arguments passed to an action are assumed to be targets. (See below.)<BR>
  358. * Whereas rules are run during Jam's parsing phase, <BR>
  359. actions are run during its updating phase.<BR>
  360. Jam variables in an action body are expanded before the action is passed to the OS command shell.
  361. <H3><BR>
  362. <SPAN STYLE="Font-Weight : Bold">3.6 Targets and Dependencies</SPAN></H3>
  363. <P>When you run Jam, it assumes you want to build one ore more targets. <BR>
  364. I said earlier that a Jam &quot;target&quot; is a filesystem object (file, directory, or library member). <BR>
  365. Jam also recognizes &quot;symbolic targets&quot;, which can be used to organize dependencies. <BR>
  366. Jam provides one built-in symbolic target called &quot;all&quot;.<BR>
  367. If you don't specify a target on the Jam command line, Jam will try to build 'all'. <BR>
  368. This is best explained with demonstration. <BR>
  369. Put the following commands in a file called 'test':<BR>
  370. <FONT FACE="Courier New, Courier">rule MyRule {<BR>
  371. TouchFile $(1) ;<BR>
  372. }<BR>
  373. actions TouchFile {<BR>
  374. touch $(1)<BR>
  375. }<BR>
  376. MyRule test.output1 ;<BR>
  377. MyRule test.output2 ;<BR>
  378. MyRule test.output3 ;</FONT><BR>
  379. Now run:<BR>
  380. <FONT FACE="Courier New, Courier">jam -ftest</FONT><BR>
  381. You'll see that this outputs:<BR>
  382. <SPAN STYLE="Font-Style : Italic">don't know how to make all</SPAN><BR>
  383. <SPAN STYLE="Font-Style : Italic">...found 1 target(s)...</SPAN><BR>
  384. <SPAN STYLE="Font-Style : Italic">...can't find 1 target(s)...</SPAN><BR>
  385. To tell Jam what you really want to build you could specify a target on the command line:<BR>
  386. <FONT FACE="Courier New, Courier">jam -ftest test.output2</FONT><BR>
  387. This outputs:<BR>
  388. <SPAN STYLE="Font-Style : Italic">...found 1 target(s)...</SPAN><BR>
  389. <SPAN STYLE="Font-Style : Italic">...updating 1 target(s)...</SPAN><BR>
  390. <SPAN STYLE="Font-Style : Italic">TouchFile test.output2</SPAN><BR>
  391. <SPAN STYLE="Font-Style : Italic">...updated 1 target(s)...</SPAN><BR>
  392. But the efficient way to tell Jam what to update is to use the built-in 'Depends' <BR>
  393. rule to make all your targets dependencies of 'all':<BR>
  394. <FONT FACE="Courier New, Courier">rule MyRule {<BR>
  395. TouchFile $(1) ;<BR>
  396. Depends all : $(1) ;<BR>
  397. }<BR>
  398. actions TouchFile {<BR>
  399. touch $(1)<BR>
  400. }<BR>
  401. MyRule test.output1 ;<BR>
  402. MyRule test.output2 ;<BR>
  403. MyRule test.output3 ;</FONT><BR>
  404. Now you can build your files without having to specify any targets on the command line:<BR>
  405. <FONT FACE="Courier New, Courier">jam -ftest</FONT><BR>
  406. <BR>
  407. Since one target was built in the previous test, only two remain to be built. Here's what Jam outputs:<BR>
  408. <SPAN STYLE="Font-Style : Italic">...found 4 target(s)...</SPAN><BR>
  409. <SPAN STYLE="Font-Style : Italic">...updating 2 target(s)...</SPAN><BR>
  410. <SPAN STYLE="Font-Style : Italic">TouchFile test.output1</SPAN><BR>
  411. <SPAN STYLE="Font-Style : Italic">TouchFile test.output3</SPAN><BR>
  412. <SPAN STYLE="Font-Style : Italic">...updated 2 target(s)...</SPAN><BR>
  413. Jam also takes it upon itself to tell you when it's building something that isn't in the chain of dependencies.<BR>
  414. For example, modify your test file so it looks like this:<BR>
  415. <FONT FACE="Courier New, Courier">rule MyRule {<BR>
  416. TouchFile $(1) ;<BR>
  417. Depends all : $(1) ;<BR>
  418. }<BR>
  419. actions TouchFile {<BR>
  420. touch $(1)<BR>
  421. }<BR>
  422. MyRule test.output1 test.output2 test.output3 ;</FONT><BR>
  423. <BR>
  424. Now run this command to try to rebuild only one of the three files (the '-a' tells Jam to rebuild<BR>
  425. it even if it already exists):<BR>
  426. <FONT FACE="Courier New, Courier">jam -ftest -a test.output2</FONT><BR>
  427. <BR>
  428. The output shows you the additional targets Jam had to build even though they were not in the dependency<BR>
  429. chain for your requested target:<BR>
  430. <SPAN STYLE="Font-Style : Italic">...found 1 target(s)...</SPAN><BR>
  431. <SPAN STYLE="Font-Style : Italic">...updating 1 target(s)...</SPAN><BR>
  432. <SPAN STYLE="Font-Style : Italic">warning: using independent target test.output1</SPAN><BR>
  433. <SPAN STYLE="Font-Style : Italic">warning: using independent target test.output3</SPAN><BR>
  434. <SPAN STYLE="Font-Style : Italic">TouchFile test.output1 test.output2 test.output3</SPAN><BR>
  435. <SPAN STYLE="Font-Style : Italic">...updated 1 target(s)...</SPAN>
  436. <H3><SPAN STYLE="Font-Weight : Bold">3.7 Implicitly Invoked Actions</SPAN></H3>
  437. <P>When an action and a rule have the same name, Jam implicitly invokes the action with the same arguments<BR>
  438. that were used in the rule invocation. Here's an example of an implicitly invoked action:<BR>
  439. <FONT FACE="Courier New, Courier">rule MyRule {<BR>
  440. Depends all : $(1) ;<BR>
  441. }<BR>
  442. actions MyRule {<BR>
  443. p4 info &gt; $(1)<BR>
  444. } <BR>
  445. MyRule info.output</FONT><BR>
  446. A single statement invokes 'MyRule'. <BR>
  447. The &quot;MyRule&quot; rule will be run during the parsing phase, <BR>
  448. and the &quot;MyRule&quot; action will be run during the updating phase. <BR>
  449. Both are passed the same argument, &quot;info.output&quot;.
  450. <H3><SPAN STYLE="Font-Weight : Bold">3.8 Target-specific Variables</SPAN></H3>
  451. <P><BR>
  452. Another syntax for setting Jam variables allows you to set values specific to individual targets. <BR>
  453. Values set this way are expanded only in actions. <BR>
  454. The syntax is &quot;variable on target =&quot;. <BR>
  455. For example:<BR>
  456. <FONT FACE="Courier New, Courier">X on foo = A B C ;<BR>
  457. X on bar = 1 2 3 ;</FONT><BR>
  458. <BR>
  459. The usefulness of this can be demonstrated by a working example:<BR>
  460. <FONT FACE="Courier New, Courier">rule MyRule {<BR>
  461. CMD on $(1) = $(2) ;<BR>
  462. PORT on $(1) = $(3) ;<BR>
  463. Depends all : $(1) ;<BR>
  464. MyTest $(1) ;<BR>
  465. }<BR>
  466. actions MyTest {<BR>
  467. p4 -p$(PORT) $(CMD) &gt; $(1)<BR>
  468. }<BR>
  469. MyRule test1.output : info ;<BR>
  470. MyRule test2.output : info : mars:1666 ;<BR>
  471. MyRule test3.output : users : mars:1666 ;</FONT><BR>
  472. Run Jam with this input and you get:<BR>
  473. <SPAN STYLE="Font-Style : Italic">...found 4 target(s)...</SPAN><BR>
  474. <SPAN STYLE="Font-Style : Italic">...updating 3 target(s)...</SPAN><BR>
  475. <SPAN STYLE="Font-Style : Italic">MyTest test1.output</SPAN><BR>
  476. <SPAN STYLE="Font-Style : Italic">p4 info &gt; test1.output</SPAN><BR>
  477. <SPAN STYLE="Font-Style : Italic">MyTest test2.output</SPAN><BR>
  478. <SPAN STYLE="Font-Style : Italic">p4 -pmars:1666 info &gt; test2.output</SPAN><BR>
  479. <SPAN STYLE="Font-Style : Italic">MyTest test3.output</SPAN><BR>
  480. <SPAN STYLE="Font-Style : Italic">p4 -pmars:1666 users &gt; test3.output</SPAN><BR>
  481. <SPAN STYLE="Font-Style : Italic">...updated 3 target(s)...</SPAN><BR>
  482. <BR>
  483. In this demonstration, two variables, CMD and PORT, were set on each target. <BR>
  484. The same action updates each target, but when the action body is expanded, <BR>
  485. the resulting command is different for each.
  486. <H3><SPAN STYLE="Font-Weight : Bold">4. Working Example: Jam as a Test Driver</SPAN></H3>
  487. <P><BR>
  488. To build on the Jam language and behavior presented so far, <BR>
  489. I've put together a series of working Jamfile implementing a simple test driver. <BR>
  490. Each example refines the previous one to demonstrate various Jam strengths. <BR>
  491. You can run these examples yourself if you have a working &quot;jam&quot; and a working &quot;p4&quot;.<BR>
  492. <BR>
  493. Note that this sequence of examples has nothing to do with traditional compile-and-link builds. <BR>
  494. I've chosen these examples because they are small and self-contained. <BR>
  495. Once you've studied these examples and have an understanding of how Jam works <BR>
  496. you'll be ready to look at the compile-and-link rules in the Jam-provided Jambase. <BR>
  497. These are the rules you'd use to implement large build systems. However, they are far too<BR>
  498. intricate (and boring) to use in a learning example.
  499. <H3><SPAN STYLE="Font-Weight : Bold">4.1 Simple Command Tester</SPAN></H3>
  500. <P><BR>
  501. The first example shows a very simple Jamfile that tests 'p4' commands. <BR>
  502. It merely runs each test and captures the output in a file. <BR>
  503. For each test, the test result file is the target to be updated, <BR>
  504. and the action that updates it is the 'p4' command to be tested.<BR>
  505. <BR>
  506. This example demonstrates how Jam behaves when actions fail. <BR>
  507. When Jam passes an action to the OS to update a file, <BR>
  508. it checks the result of the final command. <BR>
  509. If that result indicates that the command failed, <BR>
  510. Jam removes the file that was just updated. <BR>
  511. (This is how Jam normally behaves; it's not anything coded in this particular example.) <BR>
  512. <BR>
  513. Thus, the only result files left by this first test driver example will be those left by tests. <BR>
  514. With respect to what a test driver should do, that's good, <BR>
  515. because rerunning Jam will only rerun the tests that fail. <BR>
  516. <BR>
  517. But it's also bad, because it leaves no trace of failed tests!<BR>
  518. <BR>
  519. This example also introduces the Jam 'local' declaration. <BR>
  520. It is used to restrict the scope of a variable to the<BR>
  521. rule in which is declared and any rule invoked from it.<BR>
  522. <FONT FACE="Courier New, Courier">rule Test {<BR>
  523. local f = $(1:S=.out) ;<BR>
  524. Depends all : $(f) ;<BR>
  525. RunTest $(f) ;<BR>
  526. CMD on $(f) = $(1) ;<BR>
  527. }<BR>
  528. actions RunTest {<BR>
  529. p4 $(CMD) &gt; $(1)<BR>
  530. }<BR>
  531. Test info ;<BR>
  532. Test users ;<BR>
  533. Test clients ;</FONT>
  534. <H3><SPAN STYLE="Font-Weight : Bold">4.2 Capturing Failed Commands</SPAN></H3>
  535. <P><BR>
  536. A test driver isn't much use if it doesn't show you the output of failed tests. <BR>
  537. In this example, the previous version has been modified to capture the error <BR>
  538. message from the 'p4' command being tested. <BR>
  539. This example introduces the 'ignored' action modifier. <BR>
  540. (See the Jam documentation for other action modifiers.)<BR>
  541. <BR>
  542. &quot;Ignored&quot; changes Jam's behavior when an action fails: instead of removing the target file, <BR>
  543. Jam leaves it, and continues to build any targets dependent on it.<BR>
  544. <BR>
  545. Each test now produces a result file whether or not the test succeeded. <BR>
  546. However, there's no way to tell whether a test succeeded other than by <BR>
  547. looking at the result file. <BR>
  548. Furthermore, once a result file exists, Jam thinks that test is done; <BR>
  549. rerunning Jam no longer reruns the failed tests.<BR>
  550. <BR>
  551. <FONT FACE="Courier New, Courier">rule Test {<BR>
  552. local f = $(1:S=.out) ;<BR>
  553. Depends all : $(f) ;<BR>
  554. RunTest $(f) ;<BR>
  555. CMD on $(f) = $(1) ;<BR>
  556. }</FONT></P>
  557. <P><FONT FACE="Courier New, Courier">actions ignore RunTest {<BR>
  558. p4 $(CMD) &gt; $(1) 2&gt;&amp;1<BR>
  559. }<BR>
  560. Test info ;<BR>
  561. Test clients ;<BR>
  562. Test users ;</FONT>
  563. <H3><SPAN STYLE="Font-Weight : Bold">4.3 Comparing Canonical Results</SPAN></H3>
  564. <P><BR>
  565. A more useful test driver compares test results to previously stored results, called &quot;canons&quot;. <BR>
  566. Our example has been enhanced to run each test, diff the test output with the canon, <BR>
  567. and output the diff to a 'match' file.<BR>
  568. <BR>
  569. After the test run, the presence of match files shows the tester which tests succeeded, and 'jam -nd1'<BR>
  570. shows which tests failed.<BR>
  571. <BR>
  572. Notice the dependencies in this example. 'All' is dependent on the match files, and each match file is<BR>
  573. dependent on its corresponding test result file, which is in turn dependent on its corresponding canon file.<BR>
  574. With this dependency chain, only the tests with canons will be run, <BR>
  575. and of those, only the ones that have not previously produced match files will be run.<BR>
  576. <BR>
  577. Also, take a close look at the targets passed to the actions. <BR>
  578. The match file is a target of both 'RunTest',<BR>
  579. which creates the result file, and 'DiffResults', <BR>
  580. which compares the result to the canon. <BR>
  581. If a match file is missing, Jam will invoke both actions to create it. <BR>
  582. The first of the two actions, however, doesn't create it at all -- <BR>
  583. it only creates the result file. This is a trick to make Jam rerun the test if the match file missing.<BR>
  584. <BR>
  585. The 'DiffResults' action, on the other hand, is invoked with only the match file as the target. <BR>
  586. If the diff fails, only the match file will be removed; the result file will remain for the tester to examine.<BR>
  587. <FONT FACE="Courier New, Courier">rule Test {<BR>
  588. local f = $(1:S=.out) ;<BR>
  589. CMD on $(f) = $(1) ;<BR>
  590. local canon = $(1:S=.canon) ;<BR>
  591. local match = $(1:S=.match) ;<BR>
  592. Depends all : $(match) ;<BR>
  593. Depends $(match) : $(f) ;<BR>
  594. Depends $(f) : $(canon) ;<BR>
  595. RunTest $(f) $(match) ;<BR>
  596. DiffResults $(match) : $(f) $(canon) ;<BR>
  597. }<BR>
  598. actions ignore RunTest {<BR>
  599. p4 $(CMD) &gt; $(1) 2&gt;&amp;1<BR>
  600. }<BR>
  601. <BR>
  602. actions DiffResults {<BR>
  603. diff $(2) &gt; $(1) 2&gt;&amp;1<BR>
  604. }<BR>
  605. Test info ;<BR>
  606. Test clients ;<BR>
  607. Test users ;</FONT>
  608. <H3><SPAN STYLE="Font-Weight : Bold">4.4 Capturing Canonical Results</SPAN></H3>
  609. <P><BR>
  610. Another enhancement has been added to the test driver: <BR>
  611. it can now create or update canon files. <BR>
  612. This is optional behavior, triggered by the presence of a variable named 'CAPTURE'.<BR>
  613. <BR>
  614. Since nothing in the Jamfile sets CAPTURE, it must be set externally before running Jam. <BR>
  615. You can set CAPTURE in your environment,<BR>
  616. or you can simply set it on the Jam command line:<BR>
  617. <FONT FACE="Courier New, Courier">jam -sCAPTURE=1 ...</FONT><BR>
  618. <BR>
  619. When CAPTURE is set, Jam follows a completely different logic with different dependencies. <BR>
  620. 'All' now depends on canon files, and if any of those are missing they are copied from <BR>
  621. corresponding result files.<BR>
  622. Missing result files are created by simply running the tests.<BR>
  623. <BR>
  624. (This is an admittedly complex alternative to simply writing a script that <BR>
  625. copies result files into canon files, but it serves to illustrate two things, <BR>
  626. setting Jam variables externally, and conditional logic.)<BR>
  627. <FONT FACE="Courier New, Courier">rule Test {<BR>
  628. if $(CAPTURE) {<BR>
  629. CaptureCanon $(1) ;<BR>
  630. } else {<BR>
  631. DoTest $(1) ;<BR>
  632. }<BR>
  633. }<BR>
  634. rule CaptureCanon{<BR>
  635. local canon = $(1:S=.canon) ;<BR>
  636. local result = $(1:S=.out) ;<BR>
  637. CMD on $(result) = $(1) ;<BR>
  638. Depends all : $(canon) ;<BR>
  639. Depends $(canon) : $(result) ;<BR>
  640. RunTest $(result) ;<BR>
  641. CopyResult $(canon) : $(result) ;<BR>
  642. }<BR>
  643. actions CopyResult{<BR>
  644. cp $(&gt;) $(&lt;)<BR>
  645. }<BR>
  646. <BR>
  647. rule DoTest{<BR>
  648. local f = $(1:S=.out) ;<BR>
  649. CMD on $(f) = $(1) ;<BR>
  650. local canon = $(1:S=.canon) ;<BR>
  651. local match = $(1:S=.match) ;<BR>
  652. Depends all : $(match) ;<BR>
  653. Depends $(match) : $(f) ;<BR>
  654. Depends $(f) : $(canon) ;<BR>
  655. RunTest $(f) $(match) ;<BR>
  656. DiffResults $(match) : $(f) $(canon) ;<BR>
  657. }<BR>
  658. actions ignore RunTest {<BR>
  659. p4 $(CMD) &gt; $(1) 2&gt;&amp;1<BR>
  660. }<BR>
  661. actions DiffResults {<BR>
  662. diff $(2) &gt; $(1) 2&gt;&amp;1<BR>
  663. }<BR>
  664. Test info ;<BR>
  665. Test clients ;<BR>
  666. Test users ;</FONT>
  667. <H3><SPAN STYLE="Font-Weight : Bold">4.5 Removing Old Results and Canons</SPAN></H3>
  668. <P><BR>
  669. Now I've enhanced the example to demonstrate a 'Clean' rule. <BR>
  670. This is used to removed built targets from the filesystem. <BR>
  671. I've added two invocations of the Clean rule, <BR>
  672. one to clean up result and match files, <BR>
  673. one to clean up canons. <BR>
  674. Note the symbolic target, 'clean'. <BR>
  675. Nothing depends or is dependent on 'clean',<BR>
  676. thus the only way to activate the Clean action is to use 'clean' as an explicit target on the Jam command line.<BR>
  677. In other words, run:<BR>
  678. <FONT FACE="Courier New, Courier">jam clean</FONT><BR>
  679. <BR>
  680. to remove the result and match files, or:<BR>
  681. <FONT FACE="Courier New, Courier">jam -sCAPTURE=1 clean</FONT><BR>
  682. <BR>
  683. to remove the canon files.<BR>
  684. <BR>
  685. The Clean action has a number of behavior modifiers:<BR>
  686. * <SPAN STYLE="Font-Style : Italic">ignore</SPAN> you've seen before. <BR>
  687. It doesn't really have much purpose in this context other than to<BR>
  688. suppress 'failed to build' messages if file permissions prevent their removal.<BR>
  689. * <SPAN STYLE="Font-Style : Italic">together</SPAN> tells Jam this action need only be run once, <BR>
  690. and that the $(1) that appears in the action definition body can be expanded <BR>
  691. to all the targets it was invoked with. <BR>
  692. (Without <SPAN STYLE="Font-Style : Italic">together</SPAN> an action would be run once per invocation. <BR>
  693. The end result is the same, but for certain actions, <BR>
  694. like running a compiler, <SPAN STYLE="Font-Style : Italic">together</SPAN> can make builds much more efficient.)<BR>
  695. * <SPAN STYLE="Font-Style : Italic">existing </SPAN>tells Jam to not include any targets not already present in
  696. the filesystem<BR>
  697. when it expands $(1) in the action body.<BR>
  698. * <SPAN STYLE="Font-Style : Italic">piecemeal</SPAN> tells Jam that if the size of the expanded action gets too
  699. large for<BR>
  700. the OS command shell, divide the targets up into groups and run the <BR>
  701. action on each group separately.<BR>
  702. <BR>
  703. <FONT FACE="Courier New, Courier">rule Test {<BR>
  704. if $(CAPTURE) {<BR>
  705. CaptureCanon $(1) ;<BR>
  706. } else {<BR>
  707. DoTest $(1) ;<BR>
  708. }<BR>
  709. }<BR>
  710. rule CaptureCanon {<BR>
  711. local canon = $(1:S=.canon) ;<BR>
  712. local result = $(1:S=.out) ;<BR>
  713. CMD on $(result) = $(1) ;<BR>
  714. <BR>
  715. Depends all : $(canon) ;<BR>
  716. Depends $(canon) : $(result) ;<BR>
  717. <BR>
  718. RunTest $(result) ;<BR>
  719. CopyResult $(canon) : $(result) ;<BR>
  720. Clean clean : $(canon) ;<BR>
  721. }</FONT></P>
  722. <P><FONT FACE="Courier New, Courier"><BR>
  723. actions CopyResult {<BR>
  724. cp $(&gt;) $(&lt;)<BR>
  725. }<BR>
  726. rule DoTest {<BR>
  727. local f = $(1:S=.out) ;<BR>
  728. CMD on $(f) = $(1) ;<BR>
  729. local canon = $(1:S=.canon) ;<BR>
  730. local match = $(1:S=.match) ;<BR>
  731. Depends all : $(match) ;<BR>
  732. Depends $(match) : $(f) ;<BR>
  733. Depends $(f) : $(canon) ;<BR>
  734. RunTest $(f) $(match) ;<BR>
  735. DiffResults $(match) : $(f) $(canon) ;<BR>
  736. Clean clean : $(f) $(match) ;<BR>
  737. }</FONT></P>
  738. <P><FONT FACE="Courier New, Courier"><BR>
  739. actions piecemeal together existing Clean {<BR>
  740. rm $(2)<BR>
  741. }<BR>
  742. actions ignore RunTest {<BR>
  743. p4 $(CMD) &gt; $(1) 2&gt;&amp;1<BR>
  744. }<BR>
  745. actions DiffResults {<BR>
  746. diff $(2) &gt; $(1) 2&gt;&amp;1<BR>
  747. }<BR>
  748. Test info ;<BR>
  749. Test clients ;<BR>
  750. Test users ;</FONT>
  751. <H3>4.6 Writing Portable Actions</H3>
  752. <P><BR>
  753. The final refinement is this series of examples illustrates how the <BR>
  754. same action invocations can be used to run commands that vary among OS platforms. <BR>
  755. Before defining my actions, I've set some variables to OS-specific command names. <BR>
  756. In the action definitions I use those variables instead of hard-coded commands.<BR>
  757. <BR>
  758. In some cases the commands needed to perform equivalent actions will differ so much between platforms<BR>
  759. that simply substituting command names won't work. <BR>
  760. For those cases you can actually define actions differently for each platform, as demonstrated here.<BR>
  761. <FONT FACE="Courier New, Courier">if $(NT){<BR>
  762. REMOVE = del/f/q ;<BR>
  763. COPY = copy ;<BR>
  764. actions DiffResults { echo n|comp $(2) &gt; $(1) 2&gt;&amp;1 }<BR>
  765. }<BR>
  766. if $(UNIX){<BR>
  767. REMOVE = rm ;<BR>
  768. COPY = cp ;<BR>
  769. actions DiffResults { diff $(2) &gt; $(1) 2&gt;&amp;1 }<BR>
  770. }<BR>
  771. <BR>
  772. rule Test{<BR>
  773. if $(CAPTURE){<BR>
  774. CaptureCanon $(1) ;<BR>
  775. }else{<BR>
  776. DoTest $(1) ;<BR>
  777. }<BR>
  778. }<BR>
  779. <BR>
  780. rule CaptureCano{<BR>
  781. local canon = $(1:S=.canon) ;<BR>
  782. local result = $(1:S=.out) ;<BR>
  783. CMD on $(result) = $(1) ;<BR>
  784. <BR>
  785. Depends all : $(canon) ;<BR>
  786. Depends $(canon) : $(result) ;<BR>
  787. <BR>
  788. RunTest $(result) ;<BR>
  789. CopyResult $(canon) : $(result) ;<BR>
  790. Clean clean : $(canon) ;<BR>
  791. }<BR>
  792. <BR>
  793. actions CopyResult{<BR>
  794. $(COPY) $(&gt;) $(&lt;)<BR>
  795. }<BR>
  796. rule DoTest {<BR>
  797. local f = $(1:S=.out) ;<BR>
  798. CMD on $(f) = $(1) ;<BR>
  799. local canon = $(1:S=.canon) ;<BR>
  800. local match = $(1:S=.match) ;<BR>
  801. Depends all : $(match) ;<BR>
  802. Depends $(match) : $(f) ;<BR>
  803. Depends $(f) : $(canon) ;<BR>
  804. RunTest $(f) $(match) ;<BR>
  805. DiffResults $(match) : $(f) $(canon) ;<BR>
  806. Clean clean : $(f) $(match) ;<BR>
  807. }<BR>
  808. actions piecemeal together existing Clean {<BR>
  809. $(REMOVE) $(2)<BR>
  810. }<BR>
  811. actions ignore RunTest {<BR>
  812. p4 $(CMD) &gt; $(1) 2&gt;&amp;1<BR>
  813. }<BR>
  814. Test info ;<BR>
  815. Test clients ;<BR>
  816. Test users ;</FONT>
  817. <H2><SPAN STYLE="Font-Weight : Bold">5. Conclusion</SPAN></H2>
  818. <P><SPAN STYLE="Font-Weight : Bold"><BR>
  819. </SPAN>Although I certainly have not showed you everything Jam can do, <BR>
  820. by now you probably have a clear enough understanding that you <BR>
  821. can fill in the blanks by reading the Jam documentation. <BR>
  822. I'd recommend reading through all of the documents that come with the Jam source:<BR>
  823. <BR>
  824. * Jam/MR - Make(1) Redux <BR>
  825. Describes the Jam language and executable command flags.<BR>
  826. * Using Jamfiles and Jambase<BR>
  827. Chatty overview of how to use the already-written rules that<BR>
  828. come with the Jam source.<BR>
  829. (These are the rules you'd use to implement a system that builds<BR>
  830. objects by compiling, archiving, linking, etc.<BR>
  831. These rules also provide methods of managing source and generated<BR>
  832. files in a directory hierarchy.)<BR>
  833. * Jambase Reference <BR>
  834. Terse reference to those rules.<BR>
  835. <BR>
  836. I'd also recommend reading through the Jambase source file itself.<BR>
  837. It's a little long, but it demonstrates a number of techniques you<BR>
  838. can use in your own Jamfiles.
  839. <PRE></PRE>
  840.  
  841. </BODY>
  842.  
  843. </HTML>
# Change User Description Committed
#1 4362 Dick Dunbar Documentation updates. 21 years ago