Helix SwarmHelix Swarm
Loading...

Jam.html

  • //
  • guest/
  • dick_dunbar/
  • jam/
  • src/
  • Jam.html #2
  • View
  • Commits
  • Open Download .zip Download (46 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.  
  8. 	<META NAME="GENERATOR" Content="Visual Page 2.0 for Windows">
  9. 	<TITLE>Jam - Make(1) Redux</TITLE>
  10. </HEAD>
  11.  
  12. <BODY>
  13.  
  14. <H1 ALIGN="CENTER">Jam - Command</H1>
  15. <P ALIGN="CENTER">The <A HREF="http://ddunbar/Analytics/Jam/Jam.html">Jam</A> Executable</P>
  16.  
  17. <DL>
  18. 	<H2>USAGE</H2>
  19. 	<PRE>jam [ -a ] [ -g ] [ -n ] [ -q ] [ -v ]
  20.     [ -d <I>display</I> ]
  21.     [ -f <I>Jambase</I> ]
  22.     [ -j <I>jobs</I> ]
  23.     [ -o <I>actionsfile</I> ]
  24.     [ -s <I>var</I>=<I>value</I> ]
  25.     [ -t <I>target</I> ]
  26.     [ <I>target</I> ... ]</PRE>
  27. 	<P>
  28. 	<H2>DESCRIPTION</H2>
  29. 	<P><B>Jam</B> is a program construction tool, like <B>make</B>(1).</P>
  30. 	<P><B>Jam</B> recursively builds target files from source files, using dependency information and updating actions
  31. 	expressed in the Jambase file, which is written in <B>jam</B>'s own interpreted language. The default Jambase is
  32. 	compiled into <B>jam</B> and provides a boilerplate for common use, relying on a user-provide file &quot;Jamfile&quot;
  33. 	to enumerate actual targets and sources.</P>
  34. 	<P>The Jambase is described in the <A HREF="Jambase.html">Jambase Reference</A> and the document <A HREF="Jamfile.html">Using
  35. 	Jamfile, Jamrules and Jambase</A>.</P>
  36. 	<H2><A NAME="options"></A>OPTIONS</H2>
  37. 	<P>If <I>target</I> is provided on the command line, <B>jam</B> builds <I>target;</I> otherwise <B>jam</B> builds
  38. 	the target 'all'.</P>
  39. 	<P><B>Jam</B> may be invoked with the following options:</P>
  40. 	<P>
  41. 	<TABLE BORDER="1" CELLPADDING="2" WIDTH="85%">
  42. <tbody>       																				<TR>
  43. 			<TD WIDTH="20%" VALIGN="TOP"><CODE> -a</CODE></TD>
  44. 			<TD>Build all targets anyway, even if they are up-to-date.</TD>
  45. 		</TR>
  46. 		<TR>
  47. 			<TD WIDTH="20%" VALIGN="TOP"><CODE>-d <I>c<BR>
  48. 				-d n<BR>
  49. 				-d +n</I></CODE></TD>
  50. 			<TD>Display: <BR>
  51. 				change default option to <I>c</I><BR>
  52. 				change default option to 1 thru n<BR>
  53. 				add default option +n <BR>
  54. 				<BR>
  55. 				
  56. 				<TABLE BORDER="1" WIDTH="100%">
  57. 					<TR>
  58. 						<TD WIDTH="7%">
  59. 							<P ALIGN="CENTER">a
  60. 						</TD>
  61. 						<TD WIDTH="93%">Show summary info, actions, quiet actions, temporary targets (-d2)</TD>
  62. 					</TR>
  63. 					<TR>
  64. 						<TD WIDTH="7%">
  65. 							<P ALIGN="CENTER">c
  66. 						</TD>
  67. 						<TD WIDTH="93%">Show the cause (file names) cause rebuilds; new sources, missing targets</TD>
  68. 					</TR>
  69. 					<TR>
  70. 						<TD WIDTH="7%">
  71. 							<P ALIGN="CENTER">d
  72. 						</TD>
  73. 						<TD WIDTH="93%">Display a dependency graph (in <B>jam</B> syntax).</TD>
  74. 					</TR>
  75. 					<TR>
  76. 						<TD WIDTH="7%">
  77. 							<P ALIGN="CENTER">m
  78. 						</TD>
  79. 						<TD WIDTH="93%">Display the dependency analysis, and target/source timestamps and paths (-d3)</TD>
  80. 					</TR>
  81. 					<TR>
  82. 						<TD WIDTH="7%">
  83. 							<P ALIGN="CENTER">x
  84. 						</TD>
  85. 						<TD WIDTH="93%">Show shell arguments (-d2)</TD>
  86. 					</TR>
  87. 					<TR>
  88. 						<TD WIDTH="7%">
  89. 							<P ALIGN="CENTER">0
  90. 						</TD>
  91. 						<TD WIDTH="93%">Turn off all display. Only errors are emitted.</TD>
  92. 					</TR>
  93. 					<TR>
  94. 						<TD WIDTH="7%">
  95. 							<P ALIGN="CENTER">1
  96. 						</TD>
  97. 						<TD WIDTH="93%">Show actions and summary info (the default)</TD>
  98. 					</TR>
  99. 					<TR>
  100. 						<TD WIDTH="7%">
  101. 							<P ALIGN="CENTER">3
  102. 						</TD>
  103. 						<TD WIDTH="93%">dependency analysis (-dm)</TD>
  104. 					</TR>
  105. 					<TR>
  106. 						<TD WIDTH="7%">
  107. 							<P ALIGN="CENTER">5
  108. 						</TD>
  109. 						<TD WIDTH="93%">Show rule invocations and variable expansions</TD>
  110. 					</TR>
  111. 					<TR>
  112. 						<TD WIDTH="7%">
  113. 							<P ALIGN="CENTER">6
  114. 						</TD>
  115. 						<TD WIDTH="93%">Show directory/header file/archive scans</TD>
  116. 					</TR>
  117. 					<TR>
  118. 						<TD WIDTH="7%">
  119. 							<P ALIGN="CENTER">7
  120. 						</TD>
  121. 						<TD WIDTH="93%">Show variable settings</TD>
  122. 					</TR>
  123. 					<TR>
  124. 						<TD WIDTH="7%">
  125. 							<P ALIGN="CENTER">8
  126. 						</TD>
  127. 						<TD WIDTH="93%">Show variable fetches</TD>
  128. 					</TR>
  129. 					<TR>
  130. 						<TD WIDTH="7%">
  131. 							<P ALIGN="CENTER">9
  132. 						</TD>
  133. 						<TD WIDTH="93%">Show variable manipulation, scanner tokens</TD>
  134. 					</TR>
  135. 				</TABLE>
  136. 			</TD>
  137. 		</TR>
  138. 		<TR>
  139. 			<TD WIDTH="20%" VALIGN="TOP"><CODE> -f <I>Jambase</I></CODE></TD>
  140. 			<TD>Read <I>Jambase</I> instead of using the built-in Jambase. <BR>
  141. 				Multiple -f flags are permitted.</TD>
  142. 		</TR>
  143. 		<TR>
  144. 			<TD WIDTH="20%" VALIGN="TOP"><CODE> -g</CODE></TD>
  145. 			<TD>Build targets with the newest sources first, rather than the order of appearance in the Jambase/Jamfiles.</TD>
  146. 		</TR>
  147. 		<TR>
  148. 			<TD WIDTH="20%" VALIGN="TOP"><CODE> -j <I>n</I></CODE></TD>
  149. 			<TD>Run up to <I>n</I> shell commands concurrently. The default is 1.</TD>
  150. 		</TR>
  151. 		<TR>
  152. 			<TD WIDTH="20%" VALIGN="TOP"><CODE> -n</CODE></TD>
  153. 			<TD>Don't actually execute the updating actions, but do everything else. This changes the debug level to -dax.</TD>
  154. 		</TR>
  155. 		<TR>
  156. 			<TD WIDTH="20%" VALIGN="TOP"><CODE> -o <I>file</I></CODE></TD>
  157. 			<TD>Write the updating actions to the specified file instead of running them. These are the actual compiler commands;
  158. 				 different from the output from -dx.</TD>
  159. 		</TR>
  160. 		<TR>
  161. 			<TD WIDTH="20%" VALIGN="TOP"><CODE> -q</CODE></TD>
  162. 			<TD>Quit quickly (as if an interrupt was received) as soon as any target build fails.</TD>
  163. 		</TR>
  164. 		<TR>
  165. 			<TD WIDTH="20%" VALIGN="TOP"><CODE> -s <I>var</I>=<I>value</I></CODE></TD>
  166. 			<TD>Set the variable <I>var</I> to <I>value</I>, overriding both internal variables and variables imported from the
  167. 				environment.</TD>
  168. 		</TR>
  169. 		<TR>
  170. 			<TD WIDTH="20%" VALIGN="TOP"><CODE> -t <I>target</I></CODE></TD>
  171. 			<TD>Touch <I>target</I> and rebuild everything that depends on it, even if it is up-to-date.</TD>
  172. 		</TR>
  173. 		<TR>
  174. 			<TD WIDTH="20%" VALIGN="TOP"><CODE> -v</CODE></TD>
  175. 			<TD>Print the version of <B>jam</B> and exit.</TD>
  176. 		</TR>
  177. </tbody>    										</TABLE>
  178. </P>
  179. 	<H2>OPERATION</H2>
  180. 	<P><B>Jam</B> has four phases of operation: start-up, parsing, binding, and updating.</P>
  181. 	<H3>Start-up</H3>
  182. 	<P>Upon start-up, <B>jam</B> imports environment variable settings into <B>jam</B> variables. Environment variables
  183. 	are split at blanks with each word becoming an element in the variable's list of values. Environment variables
  184. 	whose names end in PATH are split at $(SPLITPATH) characters (e.g., &quot;:&quot; for Unix).</P>
  185. 	<P>To set a variable's value on the command line, overriding the variable's environment value, use the -s option.
  186. 	To see variable assignments made during <B>jam</B>'s execution, use the -d+7 option.</P>
  187. 	<H3>Parsing</H3>
  188. 	<P>In the parsing phase, <B>jam</B> reads and executes the Jambase file, by default the built-in one. It is written
  189. 	in the <B>jam</B> language. See <A HREF="#language">Language</A> below. The last action of the Jambase is to read
  190. 	(via the &quot;include&quot; rule) a user-provided file called &quot;Jamfile&quot;.</P>
  191. 	<P>Collectively, the purpose of the Jambase and the Jamfile is to name built target and source files, construct
  192. 	the dependency graph among them, and associate build actions with targets. The Jambase defines boilerplate rules
  193. 	and variable assignments, and the Jamfile uses these to specify the actual relationship among the target and source
  194. 	files. See the <A HREF="Jambase.html">Jambase Reference</A> and the document <A HREF="Jamfile.html">Using Jamfiles
  195. 	and Jambase</A> for information. <A NAME="binding"></A></P>
  196. 	<H3><A NAME="binding"></A> Binding</H3>
  197. 	After parsing, <B>jam</B> recursively descends the dependency graph and binds every file target with a location
  198. 	in the filesystem.
  199. 	<P>
  200. 	<H5><A NAME="targets"></A><FONT SIZE="4">Targets</FONT></H5>
  201. 	<DD>Any string value in <B>jam</B> can represent a target, and it does so if the Depends or Includes rules make
  202. 	it part of the dependency graph. Build targets are files to be updated. Source targets are the files used in updating
  203. 	build targets. Build targets and source targets are collectively referred to as file targets, and frequently build
  204. 	targets are source targets for other build targets. Pseudotargets are symbols which represent dependencies on other
  205. 	targets, but which are not themselves associated with any real file.
  206. 	<P>A file target's identifier is generally the file's name, which can be absolutely rooted, relative to the directory
  207. 	of <B>jam</B>'s invocation, or simply local (no directory). Most often it is the last case, and the actual file
  208. 	path is bound using the $(SEARCH) and $(LOCATE) special variables. See <A HREF="#search">SEARCH and LOCATE Variables</A>
  209. 	below. A local filename is optionally qualified with &quot;grist,&quot; a string value used to assure uniqueness.
  210. 	A file target with an identifier of the form <I>file(member)</I> is a library member (usually an ar(1) archive
  211. 	on UNIX).</P>
  212. 	<P>The use of $(SEARCH) and $(LOCATE) allows <B>jam</B> to separate the the location of files from their names,
  213. 	so that Jamfiles can refer to files locally (i.e. relative to the Jamfile's directory), yet still be usable when
  214. 	<B>jam</B> is invoked from a distant directory. The use of grist allows files with the same name to be identified
  215. 	uniquely, so that <B>jam</B> can read a whole directory tree of Jamfiles and not mix up same-named targets.</P>
  216. 	<P><B>ToDo: </B>LOCATE_SEARCH and LOCATE_TARGET
  217. 	<H5><FONT SIZE="4">Update Determination</FONT></H5>
  218. 	After binding each target, <B>jam</B> determines whether the target needs updating, and if so marks the target
  219. 	for the updating phase. A target is normally so marked if it is missing, it is older than any of its sources, or
  220. 	any of its sources are marked for updating. This behavior can be modified by the application of special built-in
  221. 	rules. See <A HREF="#bindingmods">Modifying Binding</A> below.
  222. 	<P>
  223. 	<H5><FONT SIZE="4">Header File Scanning</FONT></H5>
  224. 	During the binding phase, <B>jam</B> also performs header file scanning, where it looks inside source files for
  225. 	the implicit dependencies on other files caused by C's #include syntax. This is controlled by the special variables
  226. 	$(HDRSCAN) and $(HDRRULE). The result of the scan is formed into a rule invocation, with the scanned file as the
  227. 	target and the found included file names as the sources. Note that this is the only case where rules are invoked
  228. 	outside the parsing phase. See <A HREF="#hdrscan">HDRSCAN and HDRRULE Variables</A> below.
  229. 	<DT></DT>
  230. 	<P>
  231. 	<H3>Updating</H3>
  232. 	<P>After binding, <B>jam</B> again recursively descends the dependency graph, this time executing the update actions
  233. 	for each target marked for update during the binding phase. If a target's updating actions fail, then all other
  234. 	targets which depend on that target are skipped.</P>
  235. 	<P>The -j flag instructs <B>jam</B> to build more than one target at a time. If there are multiple actions on a
  236. 	single target, they are run sequentially. The -g flag reorders builds so that targets with newest sources are built
  237. 	first. Normally, they are built in the order of appearance in the Jamfiles.</P>
  238. 	<H2><A NAME="language"></A> LANGUAGE</H2>
  239. 	<H3>Overview</H3>
  240. 	<DD><B>Jam</B> has an interpreted, procedural language with a few select features to effect program construction.
  241. 	Statements in <B>jam</B> are rule (procedure) definitions, rule invocations, updating action definitions, flow-of-control
  242. 	structures, variable assignments, and sundry language support.
  243. 	<P>
  244. 	<H3>Lexical Features</H3>
  245. 	<P><B>Jam</B> treats its input files as whitespace-separated tokens, with two exceptions: double quotes (&quot;)
  246. 	can enclose whitespace to embed it into a token, and everything between the matching curly braces ({}) in the definition
  247. 	of updating actions is treated as a single string. A backslash (\) can escape a double quote, or any single whitespace
  248. 	character. <B>ToDo: </B>rephrase this.</P>
  249. 	<P><B>Jam</B> requires whitespace (blanks, tabs, or newlines) to surround all tokens, <B>including the colon (:)
  250. 	and semicolon (;) tokens</B>.</P>
  251. 	<P><B>Jam</B> keywords (as mentioned in this document) are reserved and generally must be quoted with double quotes
  252. 	(&quot;) to be used as arbitrary tokens, such as variable or target names.</P>
  253. 	<P><B>Name conventions:<BR>
  254. 	</B>
  255. 	<TABLE BORDER="1" WIDTH="63%">
  256. 		<TR>
  257. 			<TD WIDTH="12%"><I>lowercase</I></TD>
  258. 			<TD WIDTH="88%">pseudo target names (<FONT SIZE="2" FACE="Courier New, Courier">all, clean, obj, exe </FONT>... ), language syntax
  259. 				(<FONT SIZE="2" FACE="Courier New, Courier">if, on, case</FONT> ...)</TD>
  260. 		</TR>
  261. 		<TR>
  262. 			<TD WIDTH="12%"><I>InitialCap</I></TD>
  263. 			<TD WIDTH="88%">rule name convention</TD>
  264. 		</TR>
  265. 		<TR>
  266. 			<TD WIDTH="12%"><I>UPPER</I></TD>
  267. 			<TD WIDTH="88%">variable name convention</TD>
  268. 		</TR>
  269. 	</TABLE>
  270.  
  271. 	<H3>Datatype</H3>
  272. 	<P><B>Jam</B>'s only data type is a one-dimensional list of arbitrary strings. <BR>
  273. 	They arise as literal (whitespace-separated) tokens in the Jambase or included files, as the result of variable
  274. 	expansion of those tokens, or as the return value from a rule invocation.</P>
  275. 	<H3>Rules</H3>
  276. 	<P>The basic <B>jam</B> language entity is called a rule. A rule is simply a procedure definition, with a body
  277. 	of <B>jam</B> statements to be run when the rule is invoked. The syntax of rule invocation makes it possible to
  278. 	write Jamfiles that look a bit like Makefiles.</P>
  279. 	<P>Rules take up to 9 arguments ($(1) through $(9), each a list) and can have a return value (a single list). <BR>
  280. 	A rule's return value can be expanded in a list by enclosing the rule invocation with <TT>[</TT> and <TT>]</TT>.
  281. 	<B>ToDo: </B>examples<BR>
  282. 	$(&lt;) is a synonym for $(1) ... the argument before the (<B>:</B>)<BR>
  283. 	$(&gt;) is a synonym for $(2) ... the argument after the (<B>:</B>) <B>ToDo: </B>so where are $(3) - $(9) ?</P>
  284. 	<H3>Updating Actions</H3>
  285. 	<P>A rule may have updating actions associated with it, in which case arguments $(1) and $(2) are treated as built
  286. 	targets and sources, respectively. Updating actions are the OS shell commands to execute when updating the built
  287. 	targets of the rule.</P>
  288. 	<P>When a rule with updating actions is invoked, the actions are added to those associated with its built targets
  289. 	($(1)) before the rule's procedure is run. To build the targets in the updating phase, the actions are passed to
  290. 	the OS command shell ($JAMSHELL), with $(1) and $(2) replaced by bound versions of the target names. See <A HREF="#binding">Binding</A>
  291. 	above.</P>
  292. 	<H3>Statements</H3>
  293. 	<P><B>Jam</B>'s language has the following statements: <BR>
  294. 	<B>ToDo: </B>what happened to &quot;set&quot;? &quot;set variable&quot; ??
  295. </DL>
  296.  
  297. <P>
  298. <TABLE BORDER="0">
  299. 	<CAPTION>
  300. 		<P>actions <I>Rule</I> { <I>commands</I> ; }
  301. 	</CAPTION>
  302. <BLOCKQUOTE>
  303. 			<P>Causes jam to invoke <I>commands </I>to build the target specified by <I>Rule</I> name.
  304. 		</BLOCKQUOTE>
  305. 	</CAPTION>
  306. 					<TR>
  307. 		<TD WIDTH="15%">
  308. 			<P ALIGN="CENTER"><CODE>bind <I>vars</I></CODE>
  309. 		</TD>
  310. 		<TD>$(vars) will be replaced with bound values.</TD>
  311. 	</TR>
  312. 	<TR>
  313. 		<TD WIDTH="15%">
  314. 			<P ALIGN="CENTER"><CODE>existing</CODE>
  315. 		</TD>
  316. 		<TD>$(&gt;) includes only source targets that currently exist.</TD>
  317. 	</TR>
  318. 	<TR>
  319. 		<TD WIDTH="15%">
  320. 			<P ALIGN="CENTER"><CODE>ignore</CODE>
  321. 		</TD>
  322. 		<TD>The return status of the <I>commands</I> is ignored.</TD>
  323. 	</TR>
  324. 	<TR>
  325. 		<TD WIDTH="15%">
  326. 			<P ALIGN="CENTER"><CODE>piecemeal</CODE>
  327. 		</TD>
  328. 		<TD><I>commands</I> are repeatedly invoked with a subset of $(&gt;) small enough to fit in the command buffer on this
  329. 			OS.</TD>
  330. 	</TR>
  331. 	<TR>
  332. 		<TD WIDTH="15%">
  333. 			<P ALIGN="CENTER"><CODE>quietly</CODE>
  334. 		</TD>
  335. 		<TD>The action is not echoed to the standard output.</TD>
  336. 	</TR>
  337. 	<TR>
  338. 		<TD WIDTH="15%">
  339. 			<P ALIGN="CENTER"><CODE>together</CODE>
  340. 		</TD>
  341. 		<TD>The $(&gt;) from multiple invocations of the same action on the same built target are glommed together.</TD>
  342. 	</TR>
  343. 	<TR>
  344. 		<TD WIDTH="15%">
  345. 			<P ALIGN="CENTER"><CODE>updated</CODE>
  346. 		</TD>
  347. 		<TD>$(&gt;) includes only source targets themselves marked for updating.</TD>
  348. 	</TR>
  349. </tbody>                
  350. <B>ToDo: </B>Where does NoCare fit in?</P>
  351. 					<P>
  352. 					<DT><CODE>break</CODE></DT>
  353. 					<P>
  354. 					<DD>Breaks out of the closest enclosing <I>for</I> or <I>while</I> loop.
  355. 					<P>
  356. 					<DT><CODE>continue</CODE></DT>
  357. 					<P>
  358. 					<DD>Jumps to the end of the closest enclosing <I>for</I> or <I>while</I> loop.
  359. 					<P>
  360. 					<DT><CODE>for <I>var</I> in <I>list</I> { <I>statements</I> }</CODE></DT>
  361. 					<P>
  362. 					<DD>Executes <I>statements</I> for each element in <I>list</I>, setting the variable <I>var</I> to the element
  363. 					value. <A NAME="if"></A>
  364. 					<P>
  365. 					<DT><A NAME="if"></A><CODE> if <I>cond</I> { <I>statements</I> } [ else <I>statement</I> ]</CODE></DT>
  366. 					<P>
  367. 					<DD>Does the obvious; the else clause is optional. <I>cond</I> is built of: 
  368. 					<TABLE BORDER="1" WIDTH="587">
  369. <tbody>                       																														<TR>
  370. 		<TD WIDTH="15%">
  371. 			<P ALIGN="CENTER"><CODE><I>a</I></CODE>
  372. 		</TD>
  373. 		<TD>true if any <I>a</I> element is a non-zero-length string</TD>
  374. 	</TR>
  375. 	<TR>
  376. 		<TD WIDTH="15%">
  377. 			<P ALIGN="CENTER"><CODE><I>a</I> = <I>b</I></CODE>
  378. 		</TD>
  379. 		<TD>list <I>a</I> matches list <I>b</I> string-for-string</TD>
  380. 	</TR>
  381. 	<TR>
  382. 		<TD WIDTH="15%">
  383. 			<P ALIGN="CENTER"><CODE><I>a</I> != <I>b</I></CODE>
  384. 		</TD>
  385. 		<TD>list <I>a</I> does not match list <I>b</I></TD>
  386. 	</TR>
  387. 	<TR>
  388. 		<TD WIDTH="15%">
  389. 			<P ALIGN="CENTER"><CODE><I>a</I> &lt; <I>b</I></CODE>
  390. 		</TD>
  391. 		<TD><I>a[i]</I> string is less than <I>b[i]</I> string, where <I>i</I> is first mismatched element in lists <I>a</I>
  392. 			and <I>b</I></TD>
  393. 	</TR>
  394. 	<TR>
  395. 		<TD WIDTH="15%">
  396. 			<P ALIGN="CENTER"><CODE><I>a</I> &lt;= <I>b</I></CODE>
  397. 		</TD>
  398. 		<TD>every <I>a</I> string is less than or equal to its <I>b</I> counterpart</TD>
  399. 	</TR>
  400. 	<TR>
  401. 		<TD WIDTH="15%">
  402. 			<P ALIGN="CENTER"><CODE><I>a</I> &gt; <I>b</I></CODE>
  403. 		</TD>
  404. 		<TD><I>a[i]</I> string is greater than <I>b[i]</I> string, where <I>i</I> is first mismatched element</TD>
  405. 	</TR>
  406. 	<TR>
  407. 		<TD WIDTH="15%">
  408. 			<P ALIGN="CENTER"><CODE><I>a</I> &gt;= <I>b</I></CODE>
  409. 		</TD>
  410. 		<TD>every <I>a</I> string is greater than or equal to its <I>b</I> counterpart</TD>
  411. 	</TR>
  412. 	<TR>
  413. 		<TD WIDTH="15%">
  414. 			<P ALIGN="CENTER"><CODE><I>a</I> in <I>b</I></CODE>
  415. 		</TD>
  416. 		<TD>true if all elements of <I>a</I> can be found in <I>b</I>, or if <I>a</I> has no elements</TD>
  417. 	</TR>
  418. 	<TR>
  419. 		<TD WIDTH="15%">
  420. 			<P ALIGN="CENTER"><CODE>! <I>cond</I></CODE>
  421. 		</TD>
  422. 		<TD>condition not true</TD>
  423. 	</TR>
  424. 	<TR>
  425. 		<TD WIDTH="15%">
  426. 			<P ALIGN="CENTER"><CODE><I>cond</I> &amp;&amp; <I>cond</I></CODE>
  427. 		</TD>
  428. 		<TD>conjunction</TD>
  429. 	</TR>
  430. 	<TR>
  431. 		<TD WIDTH="15%">
  432. 			<P ALIGN="CENTER"><CODE><I>cond</I> || <I>cond</I></CODE>
  433. 		</TD>
  434. 		<TD>disjunction</TD>
  435. 	</TR>
  436. 	<TR>
  437. 		<TD WIDTH="15%">
  438. 			<P ALIGN="CENTER"><CODE>( <I>cond</I> )</CODE>
  439. 		</TD>
  440. 		<TD>precedence grouping</TD>
  441. 	</TR>
  442. </tbody>                    																				</TABLE>
  443. </P>
  444. <P><CODE>include <I>file</I> ;</CODE>
  445.  
  446. <DL>
  447. 	<DD>Causes <B>jam</B> to read the named <I>file</I>. The file is bound like a regular target (see <A HREF="#binding">Binding</A>
  448. 	above) but unlike a regular target the include file cannot be built. Marking an include file target with the <B>NoCare</B>
  449. 	rule makes it optional: if it is missing, it causes no error.
  450. 	<P>The include file is inserted into the input stream during the parsing phase. The primary input file and all
  451. 	the included file(s) are treated as a single file; that is, <B>jam</B> infers no scope boundaries from included
  452. 	files.</P>
  453. 	<P>
  454. 	<DT><CODE>local <I>vars</I> [ = <I>values</I> ] ;</CODE></DT>
  455. 	<P>
  456. 	<DD>Creates new <I>vars</I> inside to the enclosing {} block, obscuring any previous values they might have. The
  457. 	previous values for <I>vars</I> are restored when the current block ends. Any rule called or file included will
  458. 	see the local and not the previous value (this is sometimes called Dynamic Scoping). The local statement may appear
  459. 	anywhere, even outside of a block (in which case the previous value is restored when the input ends). The <I>vars</I>
  460. 	are initialized to <I>values</I> if present, or left uninitialized otherwise.
  461. 	<P>
  462. 	<DT><CODE>on <I>target</I> <I>statement</I> ;</CODE></DT>
  463. 	<P>
  464. 	<DD>Run <I>statement</I> under the influence of <I>target</I>'s target-specific variables. These variables become
  465. 	local copies during <I>statement</I>'s run, but they may be updated as target-specific variables using the usual
  466. 	&quot;<I>variable</I> on <I>targets</I> =&quot; syntax.
  467. 	<P>
  468. 	<DT><CODE>return <I>values</I> ;</CODE></DT>
  469. 	<P>
  470. 	<DD>Within a rule body, the return statement sets the return value for an invocation of the rule and terminates
  471. 	the rule's execution.
  472. 	<P>
  473. 	<DT><CODE>rule <I>Rulename</I> [ : <I>vars</I> ] { <I>statements</I> }</CODE></DT>
  474. 	<P>
  475. 	<DD>Define a rule's procedure, replacing any previous definition. If <I>vars</I> are provided, they are assigned
  476. 	the values of the parameters ($(1) to $(9)) when <I>statements</I> are executed, as with the <B>local</B> statement.
  477. 	<DT>set <I>var</I> = <I>value</I> ; <B></B></DT>
  478. 	<DD>Assigns a value to symbol.
  479. 	<P>
  480. 	<DT><A NAME="switch"></A><CODE> switch <I>value</I> {</CODE></DT>
  481. 	<DL>
  482. 		<DT><CODE>case <I>pattern1</I> : <I>statements</I> ; <BR>
  483. 		case <I>pattern2</I> : <I>statements</I> ; <BR>
  484. 		... <BR>
  485. 		}</CODE></DT>
  486. 	</DL>
  487. 	<DD>The switch statement executes zero or one of the enclosed <I>statements</I>, depending on which, if any, is
  488. 	the first case whose <I>pattern</I> matches <I>value</I>. The <I>pattern</I> values are not variable-expanded.
  489. 	The <I>pattern</I> values may include the following wildcards: 
  490. 	<TABLE BORDER="0">
  491. <tbody>                       																																				<TR>
  492. 			<TD><CODE> ?</CODE></TD>
  493. 			<TD>match any single character</TD>
  494. 		</TR>
  495. 		<TR>
  496. 			<TD><CODE> *</CODE></TD>
  497. 			<TD>match zero or more characters</TD>
  498. 		</TR>
  499. 		<TR>
  500. 			<TD><CODE> [<I>chars</I>]</CODE></TD>
  501. 			<TD>match any single character in <I>chars</I></TD>
  502. 		</TR>
  503. 		<TR>
  504. 			<TD><CODE> [^<I>chars</I>]</CODE></TD>
  505. 			<TD>match any single character not in <I>chars</I></TD>
  506. 		</TR>
  507. 		<TR>
  508. 			<TD><CODE> \<I>x</I></CODE></TD>
  509. 			<TD>match <I>x</I> (escapes the other wildcards)</TD>
  510. 		</TR>
  511. </tbody>                    																										</TABLE>
  512.  
  513. 	<DT><CODE>while <I>cond</I> { <I>statements</I> }</CODE></DT>
  514. 	<P>
  515. 	<DD>Repeatedly execute <I>statements</I> while <I>cond</I> remains true upon entry. (See the description of <I>cond</I>
  516. 	expression syntax under <A HREF="#if">if</A>, above).
  517. 	<P>
  518. </DL>
  519.  
  520. <H3>Flow-of-Control</H3>
  521. <P>In addition to statements for defining and invoking rules and setting variables, the Jam language contains statements
  522. for flow-of-control and file inclusion. The statements are:</P>
  523. <PRE>    if &lt;cond&gt; { &lt;statements&gt; } [ else { &lt;statements&gt; } ]
  524.     for &lt;var&gt; in &lt;list&gt; { &lt;statements&gt; } 
  525.     while &lt;cond&gt; { &lt;statements&gt; } ;
  526.     switch &lt;value&gt; { case &lt;pattern1&gt; : &lt;statements&gt; ; ... }
  527.     break ;
  528.     continue ;
  529.     return &lt;values&gt; ;
  530.     include &lt;file&gt; ;
  531. </PRE>
  532. <P>The <CITE>if</CITE> statement does the obvious; the &lt;condition&gt; is the usual mix of comparison and logical
  533. operators applied to variables.</P>
  534. <P>The <CITE>for</CITE> statement iterates over the elements of &lt;value&gt;, assigning the (global) variable
  535. &lt;var&gt; to each element and executing the statement block.</P>
  536. <P>The <CITE>switch</CITE> statement executes the statement block whose case &lt;value&gt; matches the switch's
  537. &lt;value&gt;.</P>
  538. <P>The <CITE>include</CITE> statement sources another file containing Jam statements. </tbody></P>
  539. <P>
  540. <H3>Variables</H3>
  541. <P><B>Jam</B> variables are lists of zero or more elements, with each element being a string value. An undefined
  542. variable is indistinguishable from a variable with an empty list, however, a defined variable may have one more
  543. elements which are null strings. All variables are referenced as $(<I>variable</I>) or with modifiers $(<I>variable:BS</I>).</P>
  544.  
  545. <P>Variables are either global or target-specific. In the latter case, the variable takes on the given value only
  546. during the target's binding, header file scanning, and updating; and during the &quot;on <I>target</I> <I>statement</I>&quot;
  547. statement.</P>
  548. <P>
  549. <TABLE BORDER="0" WIDTH="75%">
  550. 	<CAPTION><B>A variable is defined with:</B></CAPTION>
  551. <tbody>       														<TR>
  552. 		<TD><CODE><I>variable</I> = <I>elements</I> ;<BR>
  553. 			<I>variable</I> += <I>elements</I> ;<BR>
  554. 			<I>variable =+ elements ; <B>ToDo: Unique addition of element</B></I><BR>
  555. 			<I>variable</I> ?= <I>elements</I> ;<BR>
  556. 			<I>variable</I> on <I>targets</I> = <I>elements</I> ;<BR>
  557. 			<I>variable</I> on <I>targets</I> += <I>elements</I> ;<BR>
  558. 			<I>variable</I> on <I>targets</I> ?= <I>elements</I> ;<BR>
  559. 			<I>set variable = elements ;</I></CODE></TD>
  560. 	</TR>
  561. </tbody>    				</TABLE>
  562. </P>
  563. <P>The first three forms set <I>variable</I> globally. The last three forms set a target-specific variable. The
  564. = operator replaces any previous elements of <I>variable</I> with <I>elements</I>; the += operation adds <I>elements</I>
  565. to <I>variable</I>'s list of elements; the ?= operator sets <I>variable</I> only if it was previously unset. The
  566. last form &quot;<I>variable</I> on <I>targets</I> ?= <I>elements</I>&quot; checks to see if the target-specific,
  567. not the global, variable is set.</P>
  568. <P>Variables referenced in updating commands will be replaced with their values; target-specific values take precedence
  569. over global values. Variables passed as arguments ($(1) and $(2)) to actions are replaced with their bound values;
  570. the &quot;bind&quot; modifier can be used on actions to cause other variables to be replaced with bound values.
  571. See <A HREF="#actionmods">Action Modifiers</A> above.</P>
  572. <P><B>Jam</B> variables are not re-exported to the environment of the shell that executes the updating actions,
  573. but the updating actions can reference <B>jam</B> variables with $(<I>variable</I>).</P>
  574. <H3><A NAME="varexp"></A> Variable Expansion</H3>
  575.  
  576. <DL>
  577. 	<DD>
  578. 	<P>During parsing, <B>jam</B> performs variable expansion on each token that is not a keyword or rule name. Such
  579. 	tokens with embedded variable references are replaced with zero or more tokens. Variable references are of the
  580. 	form $(<I>v</I>) or $(<I>vm</I>), where <I>v</I> is the variable name, and <I>m</I> are optional modifiers. For
  581. 	example,<BR>
  582. 	<FONT SIZE="2" FACE="Courier New, Courier">$(v:D)</FONT> is the directory path for the variable <FONT SIZE="2"
  583. 	FACE="Courier New, Courier">$(v)</FONT>. See table below.
  584. 	<DL>
  585. 		<P>
  586. 	</DL>
  587. 	<P>Variable expansion in a rule's actions is similar to variable expansion in statements, except that the action
  588. 	string is tokenized at whitespace regardless of quoting.</P>
  589. 	<P>The result of a token after variable expansion is the <I>product</I> of the components of the token, where each
  590. 	component is a literal substring or a list substituting a variable reference. For example:</P>
  591. 	<P>
  592. 	<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" WIDTH="47%">
  593. <tbody>       																				<TR>
  594. 			<TD><CODE> <BR>
  595. 				$(X) -&gt; a b c <BR>
  596. 				t$(X) -&gt; ta tb tc <BR>
  597. 				$(X)z -&gt; az bz cz <BR>
  598. 				$(X)-$(X) -&gt; a-a a-b a-c b-a b-b b-c c-a c-b c-c</CODE></TD>
  599. 		</TR>
  600. </tbody>    										</TABLE>
  601. </P>
  602. 	<P>The variable name and modifiers can themselves contain a variable reference:</P>
  603. 	<P>
  604. 	<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" WIDTH="23%">
  605. <tbody>       																				<TR>
  606. 			<TD><CODE>$(X) -&gt; a b c <BR>
  607. 				$(Y) -&gt; 1 2 <BR>
  608. 				$(Z) -&gt; X Y <BR>
  609. 				$($(Z)) -&gt; a b c 1 2</CODE></TD>
  610. 		</TR>
  611. </tbody>    										</TABLE>
  612. </P>
  613. 	<P>If any variable reference in a token is undefined, the result of the expansion is an empty list. If any variable
  614. 	element is a null string, the result propagates the non-null elements:</P>
  615. 	<P>
  616. 	<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" WIDTH="31%">
  617. <tbody>       																				<TR>
  618. 			<TD><CODE>$(X) -&gt; a &quot;&quot; <BR>
  619. 				$(Y) -&gt; &quot;&quot; 1 <BR>
  620. 				$(Z) -&gt; <BR>
  621. 				*$(X)$(Y)* -&gt; *a* *a1* ** *1* <BR>
  622. 				*$(X)$(Z)* -&gt;</CODE></TD>
  623. 		</TR>
  624. </tbody>    										</TABLE>
  625. </P>
  626. 	<P>A variable element's string value can be parsed into grist and filename-related components. Modifiers to a variable
  627. 	are used to select elements, select components, and replace components.</P>
  628. 	<P>
  629. 	<TABLE BORDER="1" WIDTH="75%">
  630. 		<CAPTION>
  631. 			<P><B><FONT SIZE="4">Variable Modifiers</FONT></B>
  632. 		</CAPTION>
  633. <tbody>       																				<TR>
  634. 			<TD><CODE> [<I>n</I>]</CODE></TD>
  635. 			<TD>Select element number <I>n</I> (starting at 1). If the variable contains fewer than <I>n</I> elements, the result
  636. 				is a zero-element list.</TD>
  637. 		</TR>
  638. 		<TR>
  639. 			<TD><CODE> [<I>n</I>-<I>m</I>]</CODE></TD>
  640. 			<TD>Select elements number <I>n</I> through <I>m</I>.</TD>
  641. 		</TR>
  642. 		<TR>
  643. 			<TD><CODE> [<I>n</I>-]</CODE></TD>
  644. 			<TD>Select elements number <I>n</I> through the last.</TD>
  645. 		</TR>
  646. 		<TR>
  647. 			<TD><CODE> :<I>chars</I></CODE></TD>
  648. 			<TD>Select the components listed in <I>chars</I>.</TD>
  649. 		</TR>
  650. 		<TR>
  651. 			<TD><CODE> :B</CODE></TD>
  652. 			<TD>Select filename base.</TD>
  653. 		</TR>
  654. 		<TR>
  655. 			<TD><CODE> :B=<I>base</I></CODE></TD>
  656. 			<TD>Replace the base part of file name with <I>base</I></TD>
  657. 		</TR>
  658. 		<TR>
  659. 			<TD><CODE> :D</CODE></TD>
  660. 			<TD>Select directory path.</TD>
  661. 		</TR>
  662. 		<TR>
  663. 			<TD><CODE> :D=<I>path</I></CODE></TD>
  664. 			<TD>Replace directory with <I>path.</I></TD>
  665. 		</TR>
  666. 		<TR>
  667. 			<TD><CODE> :E=<I>value</I></CODE></TD>
  668. 			<TD>Use <I>value</I> instead if the variable is unset.</TD>
  669. 		</TR>
  670. 		<TR>
  671. 			<TD><CODE> :G</CODE></TD>
  672. 			<TD>Select grist.</TD>
  673. 		</TR>
  674. 		<TR>
  675. 			<TD><CODE> :G=<I>grist</I></CODE></TD>
  676. 			<TD>Replace grist with <I>grist</I>.</TD>
  677. 		</TR>
  678. 		<TR>
  679. 			<TD><CODE> :J=<I>joinval</I></CODE></TD>
  680. 			<TD>Concatenate list elements into single element, separated by <I>joinval</I>.</TD>
  681. 		</TR>
  682. 		<TR>
  683. 			<TD><CODE> :L</CODE></TD>
  684. 			<TD>Replace uppercase characters with lowercase.</TD>
  685. 		</TR>
  686. 		<TR>
  687. 			<TD><CODE> :M</CODE></TD>
  688. 			<TD>Select archive member name.</TD>
  689. 		</TR>
  690. 		<TR>
  691. 			<TD><CODE> :M=<I>mem</I></CODE></TD>
  692. 			<TD>Replace the archive member name with <I>mem</I>.</TD>
  693. 		</TR>
  694. 		<TR>
  695. 			<TD><CODE> :P</CODE></TD>
  696. 			<TD>Select parent directory.</TD>
  697. 		</TR>
  698. 		<TR>
  699. 			<TD><CODE> :R=<I>root</I></CODE></TD>
  700. 			<TD>Prepend <I>root</I> to the whole file name, if not already rooted.</TD>
  701. 		</TR>
  702. 		<TR>
  703. 			<TD><CODE> :S</CODE></TD>
  704. 			<TD>Select (last) filename suffix.</TD>
  705. 		</TR>
  706. 		<TR>
  707. 			<TD><CODE> :S=<I>suf</I></CODE></TD>
  708. 			<TD>Replace the suffix of file name with <I>suf</I>.</TD>
  709. 		</TR>
  710. 		<TR>
  711. 			<TD><CODE> :U</CODE></TD>
  712. 			<TD>Replace lowercase characters with uppercase.</TD>
  713. 		</TR>
  714. </tbody>    										</TABLE>
  715. </P>
  716. 	<P>$(var:P) is the parent directory of $(var:D).</P>
  717. 	<H3>Built-in Rules</H3>
  718. 	<DD>
  719. 	<P><B>Jam</B> has twelve built-in rules, all of which are pure procedure rules without updating actions. They are
  720. 	in three groups: the first builds the dependency graph; the second modifies it; and the third are just utility
  721. 	rules.</P>
  722. 	<H4>Dependency Building</H4>
  723. 	<P>
  724. 	<TABLE BORDER="0" WIDTH="75%">
  725. <tbody>       																				<TR>
  726. 			<TD>
  727. 				<DL>
  728. 					<P>
  729. 					<DT><CODE>Depends <I>targets1</I> : <I>targets2</I> ;</CODE></DT>
  730. 					<DD>Builds a direct dependency: makes each of <I>targets1</I> depend on each of <I>targets2</I>. Generally, <I>targets1</I>
  731. 					will be rebuilt if <I>targets2</I> are themselves rebuilt or are newer than <I>targets1</I>.
  732. 					<P>
  733. 					<DT><CODE>Includes <I>targets1</I> : <I>targets2</I> ;</CODE></DT>
  734. 					<DD>Builds a sibling dependency. Makes any target that depends on any of <I>targets1</I> also depend on each of
  735. 					<I>targets2</I>. This reflects the dependencies that arise when one source file includes another. The object built
  736. 					from the source file depends both on the original and included source file, but the two sources files don't depend
  737. 					on each other. For example:
  738. 					<P>Depends foo.o : foo.c ; <BR>
  739. 					Includes foo.c : goo.c ;</P>
  740.  
  741. 					<P>&quot;foo.o&quot; depends on &quot;foo.c&quot; and &quot;goo.c&quot; in this example.
  742. 				</DL>
  743. 			</TD>
  744. 		</TR>
  745. </tbody>    										</TABLE>
  746. </P>
  747. 	<H4><A NAME="bindingmods"></A> Modifying Binding</H4>
  748. 	<P>The six rules Always, Leaves, NoCare, NotFile, NoUpdate, and Temporary modify the dependency graph so that <B>jam</B>
  749. 	treats the targets differently during its target binding phase. See <A HREF="#binding">Binding</A> above. Normally,
  750. 	<B>jam</B> updates a target if it is missing, if its filesystem modification time is older than any of its dependencies
  751. 	(recursively), or if any of its dependencies are being updated. This basic behavior can be changed by invoking
  752. 	utility rules:</P>
  753. 	<H5>Utility Rules</H5>
  754. 	The remaining rules are utility rules.
  755. 	<P>
  756. 	<TABLE BORDER="0" WIDTH="75%">
  757. <tbody>       																				<TR>
  758. 			<TD>
  759. 				<DL>
  760. 					<DT><CODE><BR>
  761. 					Echo <I>args</I> ;</CODE></DT>
  762. 					<DD>Blurts out the message <I>args</I> to stdout.
  763. 					<DT><CODE>Exit <I>args</I> ;</CODE></DT>
  764. 					<DD>Blurts out the message <I>args</I> to stdout and then exits with a failure status.
  765. 					<P>
  766. 					<DT><CODE>Glob <I>directories</I> : <I>patterns</I> ;</CODE></DT>
  767. 					<DD>Scans <I>directories</I> for files matching <I>patterns</I>, returning the list of matching files (with directory
  768. 					prepended). <I>patterns</I> uses the same syntax as in the <B>switch</B> statement. Only useful within the <TT>[
  769. 					]</TT> construct, to change the result into a list.
  770. 					<P>
  771. 					<DT><CODE>Match <I>regexps</I> : <I>list</I> ;</CODE></DT>
  772. 					<DD>Matches the <B>egrep</B>(1) style regular expressions <I>regexps</I> against the strings in <I>list</I>. The
  773. 					result is the concatenation of matching <TT>()</TT> subexpressions for each string in <I>list</I>, and for each
  774. 					regular expression in <I>regexps</I>. Only useful within the <TT>[ ]</TT> construct, to change the result into
  775. 					a list.
  776. 				</DL>
  777. 			</TD>
  778. 		</TR>
  779. </tbody>    										</TABLE>
  780. </P>
  781. 	<H3>Built-in Variables</H3>
  782. 	<P>This section discusses variables that have special meaning to <B>jam</B>. By convention, variables names are
  783. 	in CAPS.</P>
  784. 	<H4><A NAME="search"></A> SEARCH and LOCATE Variables</H4>
  785. 	<P>These two variables control the binding of file target names to locations in the file system. Generally, $(SEARCH)
  786. 	is used to find existing sources while $(LOCATE) is used to fix the location for built targets.</P>
  787. 	<P>Rooted (absolute path) file targets are bound as is. Unrooted file target names are also normally bound as is,
  788. 	and thus relative to the current directory, but the settings of $(LOCATE) and $(SEARCH) alter this:
  789. 	<UL>
  790. 		<LI>If $(LOCATE) is set then the target is bound relative to the first directory in $(LOCATE). Only the first element
  791. 		is used for binding.
  792. 		<LI>If $(SEARCH) is set then the target is bound to the first directory in $(SEARCH) where the target file already
  793. 		exists.
  794. 		<LI>If the $(SEARCH) search fails, the target is bound relative to the current directory anyhow.
  795. 	</UL>
  796. 	<P>Both $(SEARCH) and $(LOCATE) should be set target-specific and not globally. If they were set globally, <B>jam</B>
  797. 	would use the same paths for all file binding, which is not likely to produce sane results. When writing your own
  798. 	rules, especially ones not built upon those in Jambase, you may need to set $(SEARCH) or $(LOCATE) directly. Almost
  799. 	all of the rules defined in Jambase set $(SEARCH) and $(LOCATE) to sensible values for sources they are looking
  800. 	for and targets they create, respectively.</P>
  801. 	<H4><A NAME="hdrscan"></A> HDRSCAN, HDRRULE and HDRGRIST Variables</H4>
  802. 	<P>These two variable control header file scanning. $(HDRSCAN) is an <B>egrep</B>(1) pattern, with ()'s surrounding
  803. 	the file name, used to find file inclusion statements in source files. Jambase uses $(HDRPATTERN) as the pattern
  804. 	for $(HDRSCAN). $(HDRRULE) is the name of a rule to invoke with the results of the scan: the scanned file is the
  805. 	target, the found files are the sources. $(HDRRULE) is run under the influence of the scanned file's target-specific
  806. 	variables.</P>
  807. 	<P>Both $(HDRSCAN) and $(HDRRULE) must be set for header file scanning to take place, and they should be set target-specific
  808. 	and not globally. If they were set globally, all files, including executables and libraries, would be scanned for
  809. 	header file include statements.</P>
  810. 	<P>The scanning for header file inclusions is not exact, but it is at least dynamic, so there is no need to run
  811. 	something like <B>makedepend</B>(GNU) to create a static dependency file. The scanning mechanism errs on the side
  812. 	of inclusion (i.e., it is more likely to return filenames that are not actually used by the compiler than to miss
  813. 	include files) because it can't tell if #include lines are inside #ifdefs or other conditional logic. In Jambase,
  814. 	HdrRule applies the NOCARE rule to each header file found during scanning so that if the file isn't present yet
  815. 	doesn't cause the compilation to fail, <B>jam</B> won't care.</P>
  816. 	<P>Also, scanning for regular expressions only works where the included file name is literally in the source file.
  817. 	It can't handle languages that allow including files using variable names (as the Jam language itself does).</P>
  818. 	<P>
  819. 	<H4>Platform Identifier Variables</H4>
  820. 	<P>A number of Jam built-in variables can be used to identify runtime platform:</P>
  821. 	<P>
  822. 	<TABLE BORDER="0" WIDTH="75%">
  823. <tbody>       																				<TR>
  824. 			<TD>OS</TD>
  825. 			<TD>OS identifier string</TD>
  826. 		</TR>
  827. 		<TR>
  828. 			<TD>OSPLAT</TD>
  829. 			<TD>Underlying architecture, when applicable</TD>
  830. 		</TR>
  831. 		<TR>
  832. 			<TD>NT</TD>
  833. 			<TD>true on NT platform</TD>
  834. 		</TR>
  835. 		<TR>
  836. 			<TD>AIX</TD>
  837. 			<TD>true on AIX platform (see also OSVER)</TD>
  838. 		</TR>
  839. 		<TR>
  840. 			<TD>HPUX</TD>
  841. 			<TD>true on HPUX platform</TD>
  842. 		</TR>
  843. 		<TR>
  844. 			<TD>SOLARIS</TD>
  845. 			<TD>true on Solaris platform</TD>
  846. 		</TR>
  847. 		<TR>
  848. 			<TD>UNIX</TD>
  849. 			<TD>true on Unix platforms</TD>
  850. 		</TR>
  851. </tbody>    										</TABLE>
  852. </P>
  853. 	<P>
  854. 	<H4>Jam Version Variables</H4>
  855. 	<P>
  856. 	<TABLE BORDER="0" WIDTH="75%">
  857. <tbody>       																				<TR>
  858. 			<TD>JAMDATE</TD>
  859. 			<TD>Time and date at <B>jam</B> start-up.</TD>
  860. 		</TR>
  861. 		<TR>
  862. 			<TD>JAMUNAME</TD>
  863. 			<TD>Output of <B>uname</B>(1) command (Unix only)</TD>
  864. 		</TR>
  865. 		<TR>
  866. 			<TD>JAMVERSION</TD>
  867. 			<TD><B>jam</B> version, as reported by jam -v.</TD>
  868. 		</TR>
  869. 		<TR>
  870. 			<TD>JAMUSER</TD>
  871. 			<TD>username that invoked jam.</TD>
  872. 		</TR>
  873. </tbody>    										</TABLE>
  874. </P>
  875. 	<H4>JAMSHELL Variable</H4>
  876. 	<P>When <B>jam</B> executes a rule's action block, it forks and execs a shell, passing the action block as an argument
  877. 	to the shell. The invocation of the shell can be controlled by $(JAMSHELL). The default on Unix is, for example:</P>
  878. 	<P><CODE>JAMSHELL = &quot;/bin/sh -c %&quot; ;</CODE></P>
  879. 	<P>The % is replaced with the text of the action block.</P>
  880. 	<P><B>Jam</B> does not directly support building in parallel across multiple hosts, since that is heavily dependent
  881. 	on the local environment. To build in parallel across multiple hosts, you need to write your own shell that provides
  882. 	access to the multiple hosts. You then reset $(JAMSHELL) to reference it.</P>
  883. 	<P>Just as <B>jam</B> expands a % to be the text of the rule's action block, it expands a ! to be the multi-process
  884. 	slot number. The slot number varies between 1 and the number of concurrent jobs permitted by the -j flag given
  885. 	on the command line. Armed with this, it is possible to write a multiple host shell. For example:</P>
  886. 	<P>
  887. 	<TABLE BORDER="0" WIDTH="75%">
  888. <tbody>       																				<TR>
  889. 			<TD><CODE> <BR>
  890. 				#!/bin/sh <BR>
  891. 				<BR>
  892. 				# This sample JAMSHELL uses the SunOS on(1) command to execute a <BR>
  893. 				# command string with an identical environment on another host. <BR>
  894. 				<BR>
  895. 				# Set JAMSHELL = jamshell ! % <BR>
  896. 				# <BR>
  897. 				# where jamshell is the name of this shell file. <BR>
  898. 				# <BR>
  899. 				# This version handles up to -j6; after that they get executed <BR>
  900. 				# locally. <BR>
  901. 				<BR>
  902. 				case $1 in <BR>
  903. 				1|4) on winken sh -c &quot;$2&quot;;; <BR>
  904. 				2|5) on blinken sh -c &quot;$2&quot;;; <BR>
  905. 				3|6) on nod sh -c &quot;$2&quot;;; <BR>
  906. 				*) eval &quot;$2&quot;;; <BR>
  907. 				esac</CODE></TD>
  908. 		</TR>
  909. </tbody>    										</TABLE>
  910. </P>
  911. 	<H2>DIAGNOSTICS</H2>
  912. 	<DD>
  913. 	<P>In addition to generic error messages, <B>jam</B> may emit one of the following:</P>
  914. 	<P>
  915. 	<TABLE BORDER="0" WIDTH="75%">
  916. <tbody>       																				<TR>
  917. 			<TD>
  918. 				<DL>
  919. 					<P>
  920. 					<DT><CODE>warning: unknown rule X</CODE></DT>
  921. 					<DD>A rule was invoked that has not been defined with an &quot;actions&quot; or &quot;rule&quot; statement.
  922. 					<P>
  923. 					<DT><CODE>using N temp target(s)</CODE></DT>
  924. 					<DD>Targets marked as being temporary (but nonetheless present) have been found.
  925. 					<P>
  926. 					<DT><CODE>updating N target(s)</CODE></DT>
  927. 					<DD>Targets are out-of-date and will be updated.
  928. 					<P>
  929. 					<DT><CODE>can't find N target(s)</CODE></DT>
  930. 					<DD>Source files can't be found and there are no actions to create them.
  931. 					<P>
  932. 					<DT><CODE>can't make N target(s)</CODE></DT>
  933. 					<DD>Due to sources not being found, other targets cannot be made.
  934. 					<P>
  935. 					<DT><CODE>warning: X depends on itself</CODE></DT>
  936. 					<DD>A target depends on itself either directly or through its sources.
  937. 					<P>
  938. 					<DT><CODE>don't know how to make X</CODE></DT>
  939. 					<DD>A target is not present and no actions have been defined to create it.
  940. 					<P>
  941. 					<DT><CODE>X skipped for lack of Y</CODE></DT>
  942. 					<DD>A source failed to build, and thus a target cannot be built.
  943. 					<P>
  944. 					<DT><CODE>warning: using independent target X</CODE></DT>
  945. 					<DD>A target that is not a dependency of any other target is being referenced with $(&lt;) or $(&gt;).
  946. 					<P>
  947. 					<DT><CODE>X removed</CODE></DT>
  948. 					<DD><B>Jam</B> removed a partially built target after being interrupted.
  949. 				</DL>
  950. 			</TD>
  951. 		</TR>
  952. </tbody>    										</TABLE>
  953. </P>
  954. 	<H2>BUGS, LIMITATIONS</H2>
  955. 	<DD>
  956. 	<P>The -j flag can cause <B>jam</B> to get confused when single actions update more than one target at a time.
  957. 	<B>jam</B> may proceed as if the targets were built even though they are still under construction.</P>
  958. 	<P>For parallel building to be successful, the dependencies among files must be properly spelled out, as targets
  959. 	tend to get built in a quickest-first ordering. Also, beware of un-parallelizable commands that drop fixed-named
  960. 	files into the current directory, like <B>yacc</B>(1) does.</P>
  961. 	<P>With the -j flag, errors from failed commands can get staggeringly mixed up.</P>
  962. 	<P>A poorly set $(JAMSHELL) is likely to result in silent failure.</P>
  963. 	<H2>SEE ALSO</H2>
  964. 	<UL>
  965. 		<LI><A HREF="Jambase.html">Jambase Reference</A>
  966. 		<LI><A HREF="Jamfile.html">Using Jamfiles, Jamrules and Jambase</A>
  967. 	</UL>
  968. 	<P>Jam documentation and source are available from the <A HREF="http://public.perforce.com/public/index.html">Perforce
  969. 	Public Depot</A>.<BR>
  970. 	Siebel development on <FONT FACE="Courier New, Courier">sdch70a014: /vol1/users/ddunbar/Jam</FONT></P>
  971. 	<H2>AUTHOR</H2>
  972. 	<DD>
  973. 	<P>Jam's author is Christopher Seiwald (<A HREF="mailto:seiwald@perforce.com">seiwald@perforce.com</A>).<BR>
  974. 	Siebel modifications by Dick Dunbar (<A HREF="mailto:Dick.Dunbar@Siebel.com">Dick.Dunbar@Siebel.com</A>) 2004</P>
  975. </DL>
  976.  
  977. <P>
  978. <HR ALIGN="CENTER">
  979. </P>
  980. <H1>Appendix A: Relationship to make</H1>
  981. <P>AIX make flags:</P>
  982. <P>make Command<BR>
  983. <BR>
  984. Purpose<BR>
  985. <BR>
  986. Maintains, updates, and regenerates groups of programs.<BR>
  987. <BR>
  988. Syntax<BR>
  989. <BR>
  990. make [ -DVariable ] [ -d Option] ] [ -e ] [ -i ] [ -k ] [ -n ] [ -p ] [ -q ] [<BR>
  991. -r ] [ -S ] [ -s ] [ -t ] [ -f MakeFile ... ] [ Target ... ]</P>
  992. <P>$&lt;<BR>
  993. Represents either the full name of a prerequisite that made a target<BR>
  994. out-of-date (inference rule), or the full name of a target (.DEFAULT rule).<BR>
  995. <BR>
  996. $*<BR>
  997. Represents the file name section of a prerequisite that made a target<BR>
  998. out-of-date (in an inference rule) without a suffix.<BR>
  999. <BR>
  1000. $@<BR>
  1001. Represents the full target name of the current target or the archive file name<BR>
  1002. part of the library archive target.<BR>
  1003. <BR>
  1004. $%<BR>
  1005. Represents a library member in a target rule if the target is a member of the<BR>
  1006. archive library.<BR>
  1007. <BR>
  1008. You can also use these local variables appended with D or F:</P>
  1009. <P>D<BR>
  1010. Indicates that the local variable applies to the directory part of the name.<BR>
  1011. This is the path name prefix without a trailing / (slash). For current<BR>
  1012. directories, D is a . (period).<BR>
  1013. <BR>
  1014. F<BR>
  1015. Indicates that the local variable applies to the file name part of the name.<BR>
  1016. <BR>
  1017. In addition, the make command sets or knows about the following variables:<BR>
  1018. <BR>
  1019. $ A single $ (dollar sign); that is, $$ expands to a single dollar sign.<BR>
  1020. Flags<BR>
  1021. <BR>
  1022. -DVariable Sets the value of Variable to 1.<BR>
  1023. -dOption Displays detailed information ...<BR>
  1024. A<BR>
  1025. Displays all possible debug information.<BR>
  1026. <BR>
  1027. a<BR>
  1028. Displays debug information about archive searching and caching.<BR>
  1029. <BR>
  1030. d<BR>
  1031. Displays debug information about directory searching.<BR>
  1032. <BR>
  1033. g1<BR>
  1034. Displays debug information about input graph before making anything.</P>
  1035. <P>g2<BR>
  1036. Displays debug information about input graph after making everything, or<BR>
  1037. before exiting on an error.<BR>
  1038. <BR>
  1039. m<BR>
  1040. Displays debug information about making targets, including modification dates.<BR>
  1041. <BR>
  1042. s<BR>
  1043. Displays debug information about suffix searching.<BR>
  1044. <BR>
  1045. v<BR>
  1046. Displays debug information about variable assignments.<BR>
  1047. <BR>
  1048. -e Specifies that environmental variables override macro assignments within<BR>
  1049. makefiles.<BR>
  1050. <BR>
  1051. -f MakeFile Specifies a makefile to read instead of the default makefile. If<BR>
  1052. MakeFile is - (dash), standard input is read. Multiple makefiles can be<BR>
  1053. specified and are read in the order specified.<BR>
  1054. <BR>
  1055. -i Ignores nonzero exit of shell commands in the makefile. Equivalent to<BR>
  1056. specifying - (dash) before each command line in the makefile.<BR>
  1057. <BR>
  1058. -k Continues processing after errors are encountered, but only on those targets<BR>
  1059. that do not depend on the target whose creation caused the error.<BR>
  1060. <BR>
  1061. -n Displays commands, but does not run them. However, lines beginning with a +<BR>
  1062. (plus sign) are executed.<BR>
  1063. <BR>
  1064. -p Displays the complete set of macro definitions and target descriptions before<BR>
  1065. performing any commands.<BR>
  1066. -q Returns a zero status code if the target file is up-to-date; returns a one<BR>
  1067. status code if the target file is not up-to-date. However, a command line with<BR>
  1068. the + (plus sign) prefix will be executed.<BR>
  1069. <BR>
  1070. -r Does not use the default rules.<BR>
  1071. <BR>
  1072. -S Terminates the make command if an error occurs. This is the default and the<BR>
  1073. opposite of -k flag.<BR>
  1074. <BR>
  1075. -s Does not display commands on the screen as they are performed.<BR>
  1076. <BR>
  1077. -t Creates a target or updates its modification time to make it appear<BR>
  1078. up-to-date. Executes command lines beginning with a + (plus) sign.<BR>
  1079. <BR>
  1080. Target Specifies a target name of the form Target or sets the value of<BR>
  1081. variables.</P>
  1082.  
  1083. <P>Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc.
  1084.  
  1085. </BODY>
  1086.  
  1087. </HTML>
# Change User Description Committed
#2 4362 Dick Dunbar Documentation updates. 21 years ago
#1 4356 Dick Dunbar Jam 2.5 base established 21 years ago
//guest/perforce_software/jam/src/Jam.html
#19 2559 rmg Fix 'var on target ?= value' so that var is only set if it
did not have a target-specific... value.  Previously, it would
just overwrite the var's value.

Bug fix documented in RELNOTES.

=== computer:1666: Change 39566 by seiwald@play-seiwald on 2002/12/27 14:44:01 «		 22 years ago
#18 2557 rmg Shuffle mechanism for optional Jamrules includes: now no error
message is issued for a mi...ssing include file marked with NOCARE.

Previously, we used Glob to try to find the optional Jamrules
files, but on VMS that doesn't work so well: Glob returns all
uppercase file names with .'s at the end, which doesn't match
"Jamrules" at all.

The NOCARE part is a user-visible change documented in RELNOTES.

=== computer:1666: Change 39273 by seiwald@waffle-cyg-seiwald on 2002/12/19 22:44:03 «		 22 years ago
#17 2529 rmg Fix "on target" variables during header scan, from Matt Armstrong.

Setting target-speci...fic variables while under the influence of
the target's target-specific variables caused the _global_ values
to be modified.  This happened both during header file scanning
and with the "on target statement" syntax.

The manifestation of this was if a file #included itself, HdrRule
would accidentally set HDRRULE/HDRSCAN globally, and then all
files (executables, etc) would get scanned for includes.

While this borrows from Matt's fix, it is a slightly different
implementation.

User visible fix documented in RELNOTES.

=== computer:1666: Change 39095 by seiwald@play-seiwald on 2002/12/17 14:00:58 «		 22 years ago
#16 2504 rmg Fix erroneous statement about :E modifier.
doc change only. 		22 years ago
#15 2490 rmg Jam langauge work: make 'return' actually return from the rule,
rather than just setting... the return value.  Introduce new
break/continue statements for managing loops.

User visible change to be documented in Jam.html.

=== computer:1666: Change 37200 by seiwald@play-seiwald on 2002/10/22 15:41:28

Gross rework of Jam.html documentation, including:

- the description of parameters for rules
- description of -g flag
- a new description of targets
- more about rules and their return values
- better separation of rules and updating actions
- putting borders around the tables

(Undocumented) change to documentation.

=== computer:1666: Change 37551 by seiwald@waffle-cyg-seiwald on 2002/11/03 23:17:12

Document jam's new and working break/continue/return statements.

=== computer:1666: Change 37574 by seiwald@play-seiwald on 2002/11/04 13:13:01 «		 22 years ago
#14 2488 rmg Remove the /MR suffix from Jam.

=== computer:1666: Change 37146 by seiwald@play-seiwald... on 2002/10/21 15:23:18 «		 22 years ago
#13 2486 rmg Fooling around with jam's -d flag, to make it possible to specify
useful display output w...ithout turning on loads of debugging crud.

New -dd flag to display dependencies.

Provisional changes not yet documented in jam.html.

=== computer:1666: Change 36374 by seiwald@play-seiwald on 2002/09/19 15:17:20

Jam -d change: the message "...using xxx..." now only shows
up with -da, rather than in the default output.  It made it
hard to see what was happening when there were a lot of temp
files lying around.

User visible change documented in RELNOTES.

=== computer:1666: Change 36430 by seiwald@play-seiwald on 2002/09/23 11:34:12

Put jam -dx flags into 'jam -h'.

Change to undocumented behavior (jam -h's output).

=== computer:1666: Change 36551 by seiwald@play-seiwald on 2002/09/26 14:39:54

Document jam's new -d debug flags.

=== computer:1666: Change 37367 by seiwald@waffle-cyg-seiwald on 2002/10/28 16:03:46

jam -n now implies -dax, just as the old jam -n implied -d2.

Change to unreleased functionality.

=== computer:1666: Change 37550 by seiwald@waffle-cyg-seiwald on 2002/11/03 23:12:15 «		 22 years ago
#12 2482 rmg Jam.html partial rewrite and the support for named
parameters to rules.

=== computer:1...666: Change 34516 by seiwald@play-seiwald on 2002/06/21 23:59:12 «		 22 years ago
#11 1614 Perforce staff Update Jam.html to reflect recent changes to Glob and Match
rules, and bring the date up... to 2002. «		 23 years ago
#10 1536 rmg Document indirect rule invokation (changes 1497, 1531). 23 years ago
#9 1530 rmg Document the new builtin MATCH rule which was added in change 1498. 23 years ago
#8 1351 rmg This change is integration history only.
(Accept -ay'ed
integrating:

    Ch...ange 216 by peter_glasscock@peter_glasscock on 1999/07/27 03:25:01

    Integrate recent changes to public source

So, these were apparently Matt's tweaks to changes being
integrated from //public/jam, and we'll ignore them here. «		 23 years ago
#7 1346 rmg Add an option that gets Jam to exit as soon as any target
fails (as if it had received an... "interrupt")

Integrates Change 233 by Peter Glasscock.

Added to Jam.html & RELNOTES - rmg «		 23 years ago
#6 1319 rmg Jam 2.3 + Perforce's internal changes.

This change is a drop of the Perforce internal J...am changes
since the 2.3 public release. The individual changes
represented herein are preserved in the
//guest/richard_geiger/intjam/ branch.

The intent of this drop is to provide a base, from which other
contributors' Jam branches may be integrated into. It is not
intended to become a packaged release in this state. We will
be integrating changes from other users prior to creating the
next packaged release.

Please refer to the src/RELNOTES file for an overview of the
changes present in this integration.

  - Richard Geiger
  Open Source Engineer at Perforce «		 23 years ago
#5 486 Perforce staff Jam 2.3.
 See RELNOTES for a list of changes from 2.2.x.

Just about every source... file was touched when jam got ANSI-fied. «		 24 years ago
#4 212 Perforce staff An interpretative integration of Peter Glasscock's -o file support.
This is handled in th...e make1() routine, rather than in all the
exec*.c files.  -o x writes the actions to file x rather than
actually running them.  Implies -n (but not -d2). «		 26 years ago
#3 76 Laura Wingerd Integrate command-block-too-long fix, plus minor doc
updates. Jam/MR release level is now... 2.2.5.
(change 72, change 73, change 74, change 75) «		 26 years ago
#2 51 Laura Wingerd Update copyright year. 26 years ago
#1 2 laura Add Jam/MR 2.2 source 27 years ago