Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/tools/build/jam_src/index.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 17 years ago

added boost
File size: 45.9 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4<head>
5  <meta name="generator" content=
6  "HTML Tidy for Linux/x86 (vers 1st September 2003), see www.w3.org">
7  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
8  <link rel="stylesheet" type="text/css" href="../../../boost.css">
9
10  <title>Boost.Jam</title>
11  <meta name="author" content="Rene Rivera">
12  <meta name="description" content=
13  "Boost.Jam (bjam) is the core build tool for using the Boost.Build system. BJam is based on Perforce's Jam/MR.">
14  </head>
15
16<body link="#0000FF" vlink="#800080">
17  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
18  "header">
19    <tbody>
20      <tr>
21        <td valign="top" width="300">
22          <h3><a href="../../../index.htm"><img height="86" width="277" alt=
23          "C++ Boost" src="../../../boost.png" border="0"></a></h3>
24        </td>
25
26        <td valign="top">
27          <h1 align="center">Boost.Jam</h1>
28
29          <h2 align="center"></h2>
30        </td>
31      </tr>
32    </tbody>
33  </table>
34  <hr>
35
36  <dl class="index">
37    <dt><a href="#introduction">Introduction</a></dt>
38
39    <dt><a href="#features">Features</a></dt>
40
41    <dt><a href="#contents">Contents</a></dt>
42
43    <dt><a href="#building_bjam">Building Boost.Jam</a></dt>
44
45    <dt><a href="#core_extensions">Core Jam Extensions</a></dt>
46
47    <dd>
48      <dl class="index">
49        <dt><a href="#variable_quoting">Command-line and Environment Variable
50        Quoting</a></dt>
51
52        <dt><a href="#jambase_replacement">Startup Behavior</a></dt>
53
54        <dt><a href="#rule_indirection">Rule Indirection</a></dt>
55
56        <dt><a href="#argument_lists">Argument Lists</a></dt>
57
58        <dt><a href="#module_support">Module Support</a></dt>
59
60        <dd>
61          <dl class="index">
62            <dt><a href="#module_declaration">Declaration</a></dt>
63
64            <dt><a href="#module_locals">Variable Scope</a></dt>
65
66            <dt><a href="#local_rules">Local Rules</a></dt>
67
68            <dt><a href="#RULENAMES_rule">The <tt>RULENAMES</tt>
69            rule</a></dt>
70
71            <dt><a href="#VARNAMES_rule">The <tt>VARNAMES</tt> rule</a></dt>
72
73            <dt><a href="#IMPORT_rule">The <tt>IMPORT</tt> rule</a></dt>
74
75            <dt><a href="#EXPORT_rule">The <tt>EXPORT</tt> rule</a></dt>
76
77            <dt><a href="#CALLER_MODULE_rule">The
78            <tt>CALLER_MODULE</tt></a></dt>
79
80            <dt><a href="#DELETE_MODULE_rule">The <tt>DELETE_MODULE</tt>
81            rule</a></dt>
82          </dl>
83        </dd>
84
85        <dt><a href="#local_foreach">Local for Loop Variables</a></dt>
86
87        <dt><a href="#negative_indexing">Negative Indexing</a></dt>
88
89        <dt><a href="#cygwin_support">Support for Cygwin</a></dt>
90
91        <dt><a href="#BINDRULE">Target Binding Detection</a></dt>
92
93        <dt><a href="#FAIL_EXPECTED">Return Code Inversion</a></dt>
94
95        <dt><a href="#NOCARE">Ignoring Return Codes</a></dt>
96
97        <dt><a href="#RMOLD">Removing outdated targets</a></dt>
98
99        <dt><a href="#SUBST_rule">The <tt>SUBST</tt> Rule</a></dt>
100
101        <dt><a href="#JAM_VERSION">The <tt>JAM_VERSION</tt> global
102        variable</a></dt>
103
104        <dt><a href="#debugging_support">Debugging Support</a></dt>
105
106        <dd>
107          <dl class="index">
108            <dt><a href="#BACKTRACE_rule">The BACKTRACE rule</a></dt>
109
110            <dt><a href="#profiling">Profiling</a></dt>
111
112            <dt><a href="#parse_debugging">Parser Debugging</a></dt>
113
114            <dt><a href="#dependency_graph">Dependency Graph Output</a></dt>
115          </dl>
116        </dd>
117
118        <dt><a href="#UPDATE">The <tt>UPDATE</tt> rule and changes to command
119        line handling</a></dt>
120
121        <dt><a href="#semaphores">Semaphores</a></dt>
122
123        <dt><a href="#w32_getreg">The W32_GETREG rule</a></dt>
124
125        <dt><a href="#ISFILE_rule">The <tt>ISFILE</tt> rule</a></dt>
126
127        <dt><a href="#SHELL_rule">The <tt>SHELL</tt> rule</a></dt>
128      </dl>
129    </dd>
130
131    <dt><a href="#jam_fundamentals">Jam Fundamentals</a></dt>
132  </dl>
133
134  <h2><a name="introduction" id="introduction"></a>Introduction</h2>
135
136  <p>Boost.Jam (BJam) &nbsp;is a build tool based on FTJam, which in turn is
137  based on Perforce Jam. It contains significant improvements made to
138  facilitate its use in the Boost Build System, but should be backward
139  compatible with Perforce Jam.</p>
140
141  <p>This is version 3.1.10 of BJam and is based on version 2.4 of
142  Jam/MR:</p>
143  <pre>
144/+\
145+\  Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc.
146\+/
147This is Release 2.4 of Jam/MR, a make-like program.
148License is hereby granted to use this software and distribute it
149freely, as long as this copyright notice is retained and modifications
150are clearly marked.
151ALL WARRANTIES ARE HEREBY DISCLAIMED.
152</pre>
153
154  <h2><a name="features" id="features"></a>Features</h2>
155
156  <p>Jam is a make(1) replacement that makes building simple things simple
157  and building complicated things manageable.</p>
158
159  <p>Jam's language is expressive, making Jamfiles (c.f. Makefiles) compact.
160  Here's a sample:</p>
161  <pre>
162Main smail : main.c map.c resolve.c deliver.c
163     misc.c parser.y alias.c pw.c headers.c
164     scanner.l getpath.c str.c ;
165</pre>
166
167  <p>This builds "smail" from a dozen source files. Jam handles header file
168  dependencies automatically and on-the-fly.</p>
169
170  <p>Jam is very portable: it runs on UNIX, VMS, Mac, and NT. Most Jamfiles
171  themselves are portable, like the sample above.</p>
172
173  <p>Jam is unintrusive: it is small, it has negligible CPU overhead, and it
174  doesn't create any of its own funny files (c.f. Odin, nmake, SunOS
175  make).</p>
176
177  <p>Jam can build large projects spread across many directories in one pass,
178  without recursing, tracking the relationships among all files. Jam can do
179  this with multiple, concurrent processes.</p>
180
181  <p>Jam isn't under the blinkin GNU copyright, so you can incorporate it
182  into commercial products.</p>
183
184  <h2><a name="contents" id="contents"></a>Contents</h2>
185
186  <table cellpadding="2" cellspacing="2" border="0" summary=
187  "Contents of Jam documents.">
188    <tr>
189      <td valign="top"><a href="Jam.html">Jam.html</a></td>
190
191      <td valign="top">Jam and language reference.</td>
192    </tr>
193
194    <tr>
195      <td valign="top"><a href="Porting">Porting</a></td>
196
197      <td valign="top">Notes on porting jam to wildcat platforms.</td>
198    </tr>
199  </table>
200
201  <h2><a name="building_bjam" id="building_bjam"></a>Building Boost.Jam</h2>
202
203  <p>Installing BJam after building it is simply a matter of copying the
204  generated executables someplace in your <tt>PATH</tt>. For building the
205  executables there are a set of <tt>build</tt> bootstrap scripts to
206  accomodate particular environments. The scripts take one optional argument,
207  the name of the toolset to build with. When the toolset is not given an
208  attempt is made to detect an available toolset and use that. The build
209  scripts accept these areguments:</p>
210  <pre>
211&lt;build script name&gt; [toolset]
212</pre>
213
214  <p>Running the scripts without arguments will give you the best chance of
215  success. On Windows platforms from a command console do:</p>
216  <pre>
217cd &lt;jam source location&gt;
218.\build.bat
219</pre>
220
221  <p>On Unix type platforms do:</p>
222  <pre>
223cd &lt;jam source location&gt;
224sh ./build.sh
225</pre>
226
227  <p>For the Boost.Jam source included with the Boost distribution the
228  <tt>&lt;jam source location&gt;</tt> is
229  <tt>BOOST_ROOT/tools/build/jam_src.</tt></p>
230
231  <p>If the scripts fail to detect an appropriate toolset to build with your
232  particular toolset may not be auto-detectable. In that case, you can
233  specify the toolset as the first argument, this assumes that the toolset is
234  readily available in the <tt>PATH</tt>. NOTE: The toolset used to build
235  Boost.Jam is independent of the toolsets used for Boost.Build. Only one
236  version of Boost.Jam is needed to use Boost.Build. The supported toolsets,
237  and wether they are auto-detected, are:</p>
238
239  <table cellpadding="2" cellspacing="2" border="1" summary=
240  "Bootstrap supported platforms and toolsets.">
241    <tr>
242      <th valign="top">Script</th>
243
244      <th valign="top">Platforms</th>
245
246      <th valign="top">Toolsets</th>
247
248      <th valign="top">Detection</th>
249    </tr>
250
251    <tr>
252      <td valign="top" rowspan="9" colspan="1"><tt>build.bat</tt></td>
253
254      <td valign="top" rowspan="9" colspan="1">Windows NT, 2000, and XP</td>
255
256      <td valign="top"><a href=
257      "http://www.comeaucomputing.com"><tt>como</tt></a>, Comeau.Computing
258      C/C++</td>
259
260      <td valign="top"></td>
261    </tr>
262
263    <tr>
264      <td valign="top"><a href=
265      "http://www.borland.com/bcppbuilder/freecompiler"><tt>borland</tt></a>,
266      <a href="http://www.borland.com/">Borland</a> C++Builder (BCC 5.5)</td>
267
268      <td valign="top">* Common install location:
269      <tt>"C:\Borland\BCC55"</tt><br>
270      * <tt>BCC32.EXE</tt> in <tt>PATH</tt></td>
271    </tr>
272
273    <tr>
274      <td valign="top"><a href="http://gcc.gnu.org">gcc</a>, GNU GCC</td>
275
276      <td valign="top"></td>
277    </tr>
278
279    <tr>
280      <td valign="top"><a href="http://gcc.gnu.org">gcc-nocygwin</a>, GNU
281      GCC</td>
282
283      <td valign="top"></td>
284    </tr>
285
286    <tr>
287      <td valign="top"><a href=
288      "http://www.intel.com/software/products/compilers/c60"><tt>intel-win32</tt></a>,
289      Intel C++ Compiler for Windows</td>
290
291      <td valign="top">* <tt>ICL.EXE</tt> in <tt>PATH</tt></td>
292    </tr>
293
294    <tr>
295      <td valign="top"><a href=
296      "http://www.metrowerks.com"><tt>metrowerks</tt></a>, MetroWerks
297      CodeWarrior C/C++ 7.x, 8.x</td>
298
299      <td valign="top">* <tt>CWFolder</tt> variable configured<br>
300      * <tt>MWCC.EXE</tt> in <tt>PATH</tt></td>
301    </tr>
302
303    <tr>
304      <td valign="top"><a href="http://www.mingw.org">mingw</a>, GNU <a href=
305      "http://gcc.gnu.org">GCC</a> as the <a href=
306      "http://www.mingw.org">MinGW</a> configuration</td>
307
308      <td valign="top">* Common install location: <tt>"C:\MinGW"</tt></td>
309    </tr>
310
311    <tr>
312      <td valign="top"><a href="http://msdn.microsoft.com/visualc/">msvc</a>,
313      Microsoft Visual C++ 6.x</td>
314
315      <td valign="top">* <tt>VCVARS32.BAT</tt> already configured<br>
316      * Common install locations: <tt>"C:\Program Files\Microsoft Visual
317      Studio"</tt>, <tt>"C:\Program Files\Microsoft Visual C++"<br></tt> *
318      <tt>CL.EXE</tt> in <tt>PATH</tt></td>
319    </tr>
320
321    <tr>
322      <td valign="top"><a href="http://msdn.microsoft.com/visualc/">vc7</a>,
323      Microsoft Visual C++ 7.x</td>
324
325      <td valign="top">* <tt>VCVARS32.BAT</tt> or <tt>VSVARS32.BAT</tt>
326      already configured<br>
327      * Common install location: <tt>"C:\Program Files\Microsoft Visual
328      Studio .NET"</tt><br>
329      * Common install location: <tt>"C:\Program Files\Microsoft Visual
330      Studio .NET 2003"</tt></td>
331    </tr>
332
333    <tr>
334      <td valign="top" rowspan="11" colspan="1"><tt>build.sh</tt></td>
335
336      <td valign="top" rowspan="10" colspan="1">Unix, Linux, Cygwin,
337      etc.</td>
338
339      <td valign="top"><a href="http://www.hp.com/go/c++">acc</a>, HP-UX
340      aCC</td>
341
342      <td valign="top">* <tt>aCC</tt> in <tt>PATH</tt><br>
343      * <tt>uname</tt> is "HP-UX"</td>
344    </tr>
345
346    <tr>
347      <td valign="top"><a href="http://www.comeaucomputing.com">como</a>,
348      Comeau.Computing C/C++</td>
349
350      <td valign="top">* <tt>como</tt> in <tt>PATH</tt></td>
351    </tr>
352
353    <tr>
354      <td valign="top"><a href="http://gcc.gnu.org">gcc</a>, GNU GCC</td>
355
356      <td valign="top">* <tt>gcc</tt> in <tt>PATH</tt></td>
357    </tr>
358
359    <tr>
360      <td valign="top"><a href=
361      "http://www.intel.com/software/products/compilers/c60l/">intel-linux</a>,
362      Intel C++ for Linux</td>
363
364      <td valign="top">* <tt>icc</tt> in <tt>PATH</tt><br>
365      * Common install locations: <tt>"/opt/intel/compiler70"</tt>,
366      <tt>"/opt/intel/compiler60"</tt>, <tt>"/opt/intel/compiler50"</tt></td>
367    </tr>
368
369    <tr>
370      <td valign="top">kcc, Intel KAI
371      C++</td>
372
373      <td valign="top">* <tt>KCC</tt> in <tt>PATH</tt></td>
374    </tr>
375
376    <tr>
377      <td valign="top"><a href=
378      "http://www.borland.com/bcppbuilder/freecompiler"><tt>kylix</tt></a>,
379      <a href="http://www.borland.com/">Borland</a> C++Builder</td>
380
381      <td valign="top">* <tt>bc++</tt> in <tt>PATH</tt></td>
382    </tr>
383
384    <tr>
385      <td valign="top"><a href=
386      "http://www.sgi.com/developers/devtools/languages/mipspro.html">mipspro</a>,
387      SGI MIPSpro C</td>
388
389      <td valign="top"></td>
390    </tr>
391
392    <tr>
393      <td valign="top">sunpro, Sun Workshop 6 C++</td>
394
395      <td valign="top">* Standard install location:
396      <tt>"/opt/SUNWspro"</tt></td>
397    </tr>
398
399    <tr>
400      <td valign="top"><a href=
401      "http://www.tru64unix.compaq.com/cplus/">true64cxx</a>, Compaq C++
402      Compiler for True64 UNIX</td>
403
404      <td valign="top"></td>
405    </tr>
406
407    <tr>
408      <td valign="top"><a href=
409      "http://www-3.ibm.com/software/ad/vacpp/">vacpp</a>, IBM VisualAge
410      C++</td>
411
412      <td valign="top">* <tt>xlc</tt> in <tt>PATH</tt></td>
413    </tr>
414
415    <tr>
416      <td valign="top">MacOS X<br></td>
417
418      <td valign="top"><a href=
419      "http://developer.apple.com/tools/compilers.html">darwin</a>, Apple
420      MacOS X GCC</td>
421
422      <td valign="top">* <tt>uname</tt> is <tt>"Darwin"</tt></td>
423    </tr>
424  </table>
425
426  <p>The built executables are placed in a subdirectory specific to your
427  platform. For example, in Linux running on an Intel x86 compatible chip,
428  the executables are placed in: <tt>"bin.linuxx86"</tt>.
429  The <tt>bjam[.exe]</tt> executable can be used to invoke Boost.Build.</p>
430
431  <p>The <tt>build</tt> scripts support additional invocation arguments for
432  use by developers of Boost.Jam. The extra arguments come after the toolset,
433  and can take the form of <tt>"--option"</tt> or targets for the
434  <tt>build.jam</tt> script:</p>
435  <pre>
436&lt;build script name&gt; [toolset] [--option+ target*]
437</pre>
438
439  <p>There is current only one available option, <tt>"--debug"</tt>, which
440  builds debugging versions of the executable. When built they are placed in
441  their own directory <tt>"bin.&lt;platform&gt;.debug"</tt>. To specify
442  targets without options, one can suply a special ignore option
443  <tt>"---"</tt>.</p>
444
445  <p>Currently there are two targets supported: <tt>dist</tt>, and
446  <tt>clean</tt>. Respectively they: generate packages (compressed archives)
447  as appropriate for distribution in the platform, or remove all the built
448  executables and objects.</p>
449
450  <h2><a name="core_extensions" id="core_extensions">Core Jam
451  Extensions</a></h2>
452
453  <p>A number of enhancements have been made to the core language of Classic
454  Jam. These changes were aimed primarily at making it easier to manage the
455  complexity of a large system such as Boost.Build.</p>
456
457  <h3><a name="variable_quoting" id="variable_quoting"></a>Command-line and
458  Environment Variable Quoting</h3>
459
460  <p>Classic Jam had an <a href="#variable_splitting">odd behavior</a> with
461  respect to command-line variable ( <tt>-s...</tt>) and environment variable
462  settings which made it impossible to define an arbitrary variable with
463  spaces in the value. Boost Jam remedies that by treating all such settings
464  as a single string if they are surrounded by double-quotes. Uses of this
465  feature can look interesting, since shells require quotes to keep
466  characters separated by whitespace from being treated as separate
467  arguments:</p>
468  <pre>
469jam -sMSVCNT="\"\"C:\Program Files\Microsoft Visual C++\VC98\"\"" ...
470</pre>
471
472  <p>The outer quote is for the shell. The middle quote is for Jam, to tell
473  it to take everything within those quotes literally, and the inner quotes
474  are for the shell again when paths are passed as arguments to build
475  actions. Under NT, it looks a lot more sane to use environment variables
476  before invoking jam when you have to do this sort of quoting:</p>
477  <pre>
478set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""
479</pre>
480
481  <h3><a name="jambase_replacement" id="jambase_replacement">Startup
482  Behavior</a></h3>
483
484  <p>The Boost.Build v2 initialization behavior has been implemented. This
485  behavior only applies when the executable being invoked is called
486  "<code>bjam</code>" or, for backward-compatibility, when the
487  <code>BOOST_ROOT</code> variable is set.</p>
488
489  <ol>
490    <li>We attempt to load "boost-build.jam" by searching from the current
491    invocation directory up to the root of the file-system. This file is
492    expected to invoke the <tt>boost-build</tt> rule to indicate where the
493    Boost.Build system files are, and to load them.</li>
494
495    <li>If boost-build.jam is not found we error and exit, giving brief
496    instructions on possible errors.
497
498      <blockquote>
499        As a backward-compatibility measure for older versions of
500        Boost.Build, when the <code>BOOST_ROOT</code> variable is set, we
501        first search for <code>boost-build.jam</code> in
502        <code>$(BOOST_ROOT)/tools/build</code> and
503        <code>$(BOOST_BUILD_PATH)</code>. If found, it is loaded and
504        initialization is complete.
505      </blockquote>
506    </li>
507
508    <li>The <code>boost-build</code> rule adds its (optional) argument to the
509    front of <code>BOOST_BUILD_PATH</code>, and attempts to load
510    <code>bootstrap.jam</code> from those directories. If a relative path is
511    specified as an argument, it is treated as though it was relative to the
512    <code>boost-build.jam</code> file.</li>
513
514    <li>If the bootstrap.jam file was not found, we print a likely error
515    message and exit.</li>
516  </ol>
517
518  <h3><a name="rule_indirection" id="rule_indirection">Rule
519  Indirection</a></h3>
520
521  <p>Boost Jam allows you to call a rule whose name is held in a variable or
522  computed as the result of an expression:</p>
523  <pre>
524x = foo ;
525rule foobar { ECHO foobar ; }   # a trivial rule
526$(x)bar ;                       # invokes foobar
527</pre>
528
529  <p>Furthermore, if the first expression expands to more than one list item,
530  everything after the first item becomes part of the first argument. This
531  allows a crude form of argument binding:</p>
532  <pre>
533# return the elements of sequence for which predicate returns non-nil
534rule filter ( sequence * : predicate + )
535{
536    local result ;
537    for local x in $(sequence)
538    {
539        if [ $(predicate) $(x) ] { result += $(x); }
540    }
541    return $(result);
542}
543# true iff x == y
544rule equal ( x y )
545{
546    if $(x) = $(y) { return true; }
547}
548# bind 3 to the first argument of equal
549ECHO [ filter 1 2 3 4 5 4 3 : equal 3 ] ; # prints "3 3"
550</pre>
551
552  <h3><a name="argument_lists" id="argument_lists">Argument lists</a></h3>
553
554  <p>You can now describe the arguments accepted by a rule, and refer to them
555  by name within the rule. For example, the following prints ``I'm sorry,
556  Dave'' to the console:</p>
557  <pre>
558rule report ( pronoun index ? : state : names + )
559{
560    local he.suffix she.suffix it.suffix = s ;
561    local I.suffix = m ;
562    local they.suffix you.suffix = re ;
563    ECHO $(pronoun)'$($(pronoun).suffix) $(state), $(names[$(index)]) ;
564}
565report I 2 : sorry : Joe Dave Pete ;
566</pre>
567
568  <p>Each name in a list of formal arguments (separated by ``<tt>:</tt>'' in
569  the rule declaration) is bound to a single element of the corresponding
570  actual argument unless followed by one of these modifiers:</p>
571
572  <table border="1" summary="Argument modifiers">
573    <tr>
574      <th>Symbol</th>
575
576      <th>Semantics of preceding symbol</th>
577    </tr>
578
579    <tr>
580      <td><tt>?</tt></td>
581
582      <td>optional</td>
583    </tr>
584
585    <tr>
586      <td><tt>*</tt></td>
587
588      <td>Bind to zero or more unbound elements of the actual argument. When
589      ``<tt>*</tt>'' appears where an argument name is expected, any number
590      of additional arguments are accepted. This feature can be used to
591      implement "varargs" rules.</td>
592    </tr>
593
594    <tr>
595      <td><tt>+</tt></td>
596
597      <td>Bind to one or more unbound elements of the actual argument.</td>
598    </tr>
599  </table>
600
601  <p>The actual and formal arguments are checked for inconsistencies, which
602  cause Jam to exit with an error code:</p>
603  <pre>
604### argument error
605# rule report ( pronoun index ?  : state  : names + )
606# called with: ( I 2 foo  : sorry  : Joe Dave Pete )
607# extra argument foo
608### argument error
609# rule report ( pronoun index ?  : state  : names + )
610# called with: ( I 2  : sorry )
611# missing argument names
612</pre>
613
614  <p>If you omit the list of formal arguments, all checking is bypassed as in
615  ``classic'' Jam. Argument lists drastically improve the reliability and
616  readability of your rules, however, and are <b>strongly recommended</b> for
617  any new Jam code you write.</p>
618
619  <h3><a name="module_support" id="module_support">Module Support</a></h3>
620
621  <p>Boost Jam introduces support for modules, which provide some rudimentary
622  namespace protection for rules and variables. A new keyword,
623  ``<tt>module</tt>'' was also introduced. The features described in this
624  section are <i>primitives</i>, meaning that they are meant to provide the
625  operations needed to write Jam rules which provide a more elegant module
626  interface.</p>
627
628  <h4><a name="module_declaration" id=
629  "module_declaration">Declaration</a></h4>
630  <pre>
631module <i>expression</i> { ... }
632</pre>
633
634  <p>Code within the <tt>{</tt> ... <tt>}</tt> executes within the module
635  named by evaluating <i>expression</i>. Rule definitions can be found in the
636  module's own namespace, and in the namespace of the global module as
637  <i>module-name</i><tt>.</tt><i>rule-name</i>, so within a module, other
638  rules in that module may always be invoked without qualification:</p>
639  <pre>
640<b>module my_module
641{</b>
642    rule salute ( x ) { ECHO $(x), world ; }
643    rule greet ( ) { salute hello ; }
644    greet ;
645<b>}
646my_module.salute</b> goodbye ;
647</pre>
648
649  <p>When an invoked rule is not found in the current module's namespace, it
650  is looked up in the namespace of the global module, so qualified calls work
651  across modules:</p>
652  <pre>
653module your_module
654{
655    rule bedtime ( ) { <b>my_module.salute</b> goodnight ; }
656}
657</pre>
658
659  <h4><a name="module_locals" id="module_locals">Variable Scope</a></h4>
660
661  <p>Each module has its own set of dynamically nested variable scopes. When
662  execution passes from module A to module B, all the variable bindings from
663  A become unavailable, and are replaced by the bindings that belong to B.
664  This applies equally to local and global variables:</p>
665  <pre>
666module A
667{
668    x = 1 ;
669    rule f ( )
670    {
671        local y = 999 ; # becomes visible again when B.f calls A.g
672        B.f ;
673    }
674    rule g ( )
675    {
676        ECHO $(y) ;     # prints "999"
677    }
678}
679module B
680{
681    y = 2 ;
682    rule f ( )
683    {
684        ECHO $(y) ; # always prints "2"
685        A.g ;
686    }
687}
688</pre>
689
690  <p>The only way to access another module's variables is by entering that
691  module:</p>
692  <pre>
693rule peek ( module-name ? : variables + )
694{
695    module $(module-name)
696    {
697        return $($(&gt;)) ;
698    }
699}
700</pre>Note that because existing variable bindings change whenever a new
701module scope is entered, argument bindings become unavailable. That explains
702the use of "<code>$(&gt;)</code>" in the <code>peek</code> rule above.
703
704  <h4><a name="local_rules" id="local_rules">Local Rules</a></h4>
705  <pre>
706local rule <i>rulename...</i>
707</pre>
708
709  <p>The rule is declared locally to the current module. It is not entered in
710  the global module with qualification, and its name will not appear in the
711  result of:</p>
712  <pre>
713[ RULENAMES <i>module-name</i> ]
714</pre>
715
716  <h4><a name="RULENAMES_rule" id="RULENAMES_rule">The <tt>RULENAMES</tt>
717  Rule</a></h4>
718  <pre>
719rule RULENAMES ( module ? )
720</pre>
721
722  <p>Returns a list of the names of all non-local rules in the given module.
723  If <tt>module</tt> is omitted, the names of all non-local rules in the
724  global module are returned.</p>
725
726  <h4><a name="VARNAMES_rule" id="VARNAMES_rule">The <tt>VARNAMES</tt>
727  Rule</a></h4>
728  <pre>
729rule VARNAMES ( module ? )
730</pre>
731
732  <p>Returns a list of the names of all variable bindings in the given
733  module. If <tt>module</tt> is omitted, the names of all variable bindings
734  in the global module are returned. <b>Note:</b>this includes any local
735  variables in rules from the call stack which have not returned at the time
736  of the <code>VARNAMES</code> invocation.</p>
737
738  <h4><a name="IMPORT_rule" id="IMPORT_rule">The <tt>IMPORT</tt>
739  Rule</a></h4>
740
741  <p><tt>IMPORT</tt> allows rule name aliasing across modules:</p>
742  <pre>
743rule IMPORT ( source_module ? : source_rules *
744            : target_module ? : target_rules * )
745</pre>
746
747  <p>The <tt>IMPORT</tt> rule copies rules from the <tt>source_module</tt>
748  into the <tt>target_module</tt> as <tt>local</tt> rules. If either
749  <tt>source_module</tt> or <tt>target_module</tt> is not supplied, it refers
750  to the global module. <tt>source_rules</tt> specifies which rules from the
751  <tt>source_module</tt> to import; <tt>TARGET_RULES</tt> specifies the names
752  to give those rules in <tt>target_module</tt>. If <tt>source_rules</tt>
753  contains a name which doesn't correspond to a rule in
754  <tt>source_module</tt>, or if it contains a different number of items than
755  <tt>target_rules</tt>, an error is issued. For example,</p>
756  <pre>
757# import m1.rule1 into m2 as local rule m1-rule1.
758IMPORT m1 : rule1 : m2 : m1-rule1 ;
759# import all non-local rules from m1 into m2
760IMPORT m1 : [ RULENAMES m1 ] : m2 : [ RULENAMES m1 ] ;
761</pre>
762
763  <h4><a name="EXPORT_rule" id="EXPORT_rule">The <tt>EXPORT</tt>
764  Rule</a></h4>
765
766  <p><tt>EXPORT</tt> allows rule name aliasing across modules:</p>
767  <pre>
768rule EXPORT ( module ? : rules * )
769</pre>
770
771  <p>The <tt>EXPORT</tt> rule marks <tt>rules</tt> from the
772  <tt>source_module</tt> as non-local (and thus exportable). If an element of
773  <tt>rules</tt> does not name a rule in <tt>module</tt>, an error is issued.
774  For example,</p>
775  <pre>
776module X {
777  local rule r { ECHO X.r ; }
778}
779IMPORT X : r : : r ; # error - r is local in X
780EXPORT X : r ;
781IMPORT X : r : : r ; # OK.
782</pre>
783
784  <h4><a name="CALLER_MODULE_rule" id="CALLER_MODULE_rule">The
785  <tt>CALLER_MODULE</tt> Rule</a></h4>
786  <pre>
787rule CALLER_MODULE ( levels ? )
788</pre>
789
790  <p><tt>CALLER_MODULE</tt> returns the name of the module scope enclosing
791  the call to its caller (if levels is supplied, it is interpreted as an
792  integer number of additional levels of call stack to traverse to locate the
793  module). If the scope belongs to the global module, or if no such module
794  exists, returns the empty list. For example, the following prints "{Y}
795  {X}":</p>
796  <pre>
797module X {
798    rule get-caller { return [ CALLER_MODULE ] ; }
799    rule get-caller's-caller { return [ CALLER_MODULE 1 ] ; }
800    rule call-Y { return Y.call-X2 ; }
801}
802module Y {
803    rule call-X { return X.get-caller ; }
804    rule call-X2 { return X.get-caller's-caller ; }
805}
806callers = [ X.get-caller ] [ Y.call-X ] [ X.call-Y ] ;
807ECHO {$(callers)} ;
808</pre>
809
810  <h4><a name="DELETE_MODULE_rule" id="DELETE_MODULE_rule">The
811  <tt>DELETE_MODULE</tt> Rule</a></h4>
812  <pre>
813rule DELETE_MODULE ( module ? )
814</pre>
815
816  <p><tt>DELETE_MODULE</tt> removes all of the variable bindings and
817  otherwise-unreferenced rules from the given module (or the global module,
818  if no module is supplied), and returns their memory to the system.
819  <b>Note:</b> though it won't affect rules that are currently executing
820  until they complete, <code>DELETE_MODULE</code> should be used with extreme
821  care because it will wipe out any others and all variable (including locals
822  in that module) immediately. Because of the way dynamic binding works,
823  variables which are shadowed by locals will not be destroyed, so the
824  results can be really unpredictable.</p>
825
826  <h3><a name="local_foreach" id="local_foreach">Local For Loop
827  Variables</a></h3>
828
829  <p>Boost Jam allows you to declare a local <tt>for</tt> loop control
830  variable right in the loop:</p>
831  <pre>
832x = 1 2 3 ;
833y = 4 5 6 ;
834for <b>local</b> y in $(x)
835{
836    ECHO $(y) ; # prints "1", "2", or "3"
837}
838ECHO $(y) ;     # prints "4 5 6"
839</pre>
840
841  <h4><a name="negative_indexing" id="negative_indexing">Negative
842  Indexing</a></h4>
843
844  <p>Classic Jam supplies 1-based list indexing, and slicing on a closed
845  (inclusive) range:</p>
846  <pre>
847x = 1 2 3 4 5 ;
848ECHO $(x[3]) ;   # prints "3"
849ECHO $(x[2-4]) ; # prints "2 3 4"
850ECHO $(x[2-]) ;  # prints "2 3 4 5"
851</pre>
852
853  <p>Boost Jam adds Python-style negative indexing to access locations
854  relative to the <i>end</i> of the list.</p>
855  <pre>
856ECHO $(x[-1]) $(x[-3]) ; # prints "5 3"
857ECHO $(x[-3--1]) ;       # prints "3 4 5"
858ECHO $(x[-3-4]) ;        # prints "3 4"
859ECHO $(x[2--2]) ;        # prints "2 3 4"       
860</pre>
861
862  <p>Consistency with the 1-based, inclusive indexing of Classic Jam and the
863  use of ``<tt>-</tt>'' as the range separator make this feature a bit
864  clumsier than it would otherwise need to be, but it does work.</p>
865
866  <h4><a name="cygwin_support" id="cygwin_support">Support for
867  Cygwin</a></h4>
868
869  <p>When invoking Windows-based tools from <a href=
870  "http://www.cygwin.com">Cygwin</a> it can be important to pass them true
871  windows-style paths. Boost.Jam supplies the <code>:W</code> modifier which,
872  <em>under Cygwin only</em>, turns a cygwin path into a Win32 path using the
873  <a href=
874  "http://www.cygwin.com/cygwin-api/func-cygwin-conv-to-win32-path.html"><code>
875  cygwin_conv_to_win32_path</code></a> function. On other platforms, the
876  string is unchanged.</p>
877  <pre>
878x = /cygdrive/c/Program Files/Borland ;
879ECHO $(x:W) ; # prints "c:\Program Files\Borland" on Cygwin
880</pre>
881
882  <h4><a name="BINDRULE" id="BINDRULE">Target Binding Detection</a></h4>
883
884  <p>Whenever a target is <a href="#binding">bound</a> to a location in the
885  filesystem, Boost Jam will look for a variable called <tt>BINDRULE</tt>
886  (first ``<tt>on</tt>'' the target being bound, then in the global module).
887  If non-empty, <tt>$(BINDRULE[1])</tt> names a rule which is called with the
888  name of the target and the path it is being bound to. The signature of the
889  rule named by <tt>$(BINDRULE[1])</tt> should match the following:</p>
890  <pre>
891rule bind-rule ( target : path )
892</pre>
893
894  <p>This facility is useful for correct header file scanning, since many
895  compilers will search for <tt>#include</tt>d files first in the directory
896  containing the file doing the <tt>#include</tt> directive.
897  <tt>$(BINDRULE)</tt> can be used to make a record of that directory.</p>
898
899  <h4><a name="FAIL_EXPECTED" id="FAIL_EXPECTED">Return Code
900  Inversion</a></h4>
901
902  <p>For handling targets whose build actions are expected to fail (e.g. when
903  testing that assertions or compile-time type checkin work properly), Boost
904  Jam supplies a <tt>FAIL_EXPECTED</tt> rule in the same style as
905  <tt>NOCARE</tt>, et. al. During target updating, the return code of the
906  build actions for arguments to <tt>FAIL_EXPECTED</tt> is inverted: if it
907  fails, building of dependent targets continues as though it succeeded. If
908  it succeeds, dependent targets are skipped.</p>
909
910  <h4><a name="NOCARE" id="NOCARE">Ignoring Return Codes</a></h4>
911
912  <p>Perforce Jam supplied a <tt>NOCARE</tt> rule which is typically used for
913  header files to indicate that if they are not found, the dependent targets
914  should be built anyway. Boost Jam extends <tt>NOCARE</tt> to apply to
915  targets with build actions: if their build actions exit with a nonzero
916  return code, dependent targets will still be built.</p>
917
918  <h4><a name="RMOLD" id="RMOLD">Removing Outdated Targets</a></h4>
919  <pre>
920rule RMOLD ( targets * )
921</pre>
922
923  <p>Perforce Jam removes any target files that may exist on disk when the
924  rule used to build those targets fails. However, targets whose dependencies
925  fail to build are not removed by default. The <code>RMOLD</code> rule
926  causes its arguments to be removed if any of their dependencies fail to
927  build.</p>
928
929  <h3><a name="SUBST_rule" id="SUBST_rule">The <tt>SUBST</tt> Rule</a></h3>
930
931  <p><b>Note:</b> the <code>SUBST</code> rule is deprecated in favor of
932  Perforce Jam's built-in <code>MATCH</code> rule, which has been rolled into
933  Boost.Jam.</p>
934
935  <p>The behavior of the <tt>SUBST</tt> rule for regular-expression matching
936  and replacement (originally added in <a href=
937  "http://freetype.sourceforge.net/jam/index.html">FTJam</a>) has been
938  modified:</p>
939
940  <ul>
941    <li>One or more replacement patterns may be supplied. The new signature
942    for <tt>SUBST</tt> is:
943      <pre>
944SUBST ( source pattern replacements + )
945</pre>The return value is the concatenated results of applying each element
946of <tt>replacements</tt> in turn. For example, the following will print
947``<tt>[x] (y) {z}</tt>'':
948      <pre>
949ECHO [ SUBST xyz (.)(.)(.) [$1] ($2) {$3} ] ;
950</pre>
951    </li>
952
953    <li>If there is no match, <tt>SUBST</tt> now returns an empty list. In
954    FTJam, the original <tt>source</tt> string was returned, making it
955    awkward to check whether a pattern was matched.</li>
956
957    <li>Compiled regular expressions are now internally cached, making it
958    much faster to use <tt>SUBST</tt> multiple times with the same
959    string.</li>
960  </ul>
961
962  <h3><a name="JAM_VERSION" id="JAM_VERSION">The <tt>JAM_VERSION</tt> global
963  variable</a></h3>
964
965  <p>A predefined global variable with two elements indicates the version
966  number of Boost Jam. Boost Jam versions start at <tt>"03" "00"</tt>.
967  Earlier versions of Jam do not automatically define
968  <tt>JAM_VERSION</tt>.</p>
969
970  <h3><a name="debugging_support" id="debugging_support">Debugging
971  Support</a></h3>
972
973  <h4><a name="BACKTRACE_rule" id="BACKTRACE_rule">The BACKTRACE
974  rule</a></h4>
975  <pre>
976rule BACKTRACE ( )
977</pre>
978
979  <p>Returns a list of quadruples: <i>filename line module rulename</i>...,
980  describing each shallower level of the call stack. This rule can be used to
981  generate useful diagnostic messages from Jam rules.</p>
982
983  <p>The <tt>-d</tt> command-line option admits new arguments:</p>
984
985  <ul>
986    <li><tt>-d+10</tt> - enables <a name="profiling" id=
987    "profiling"><b>profiling</b></a> of rule invocations. When Jam exits, it
988    dumps all rules invoked, their gross and net times in platform-dependent
989    units, and the number of times the rule was invoked.</li>
990
991    <li><tt>-d+11</tt> - enables <a name="parse_debugging" id=
992    "parse_debugging"><b>parser debugging</b></a>, if Jam has been compiled
993    with the "--debug" option to the parser generator named by $(YACC).</li>
994
995    <li><tt>-d+12</tt> - enables <a name="dependency_graph" id=
996    "dependency_graph"><b>dependency graph output</b></a> . This feature was
997    ``stolen'' from a version of Jam modified by <a href=
998    "mailto:cmcpheeters@aw.sgi.com">Craig McPheeters</a>.</li>
999  </ul>
1000
1001  <h3><a name="UPDATE" id="UPDATE">The <tt>UPDATE</tt> rule and changes to
1002  command line handling</a></h3>
1003
1004  <p>Classic jam treats any non-option element of command line as a name of
1005  target to be updated. This prevented more sophisticated handling of command
1006  line. This is now enabled again but with additional changes to the
1007  <tt>UPDATE&gt;</tt> rule to allow for the flexibility of changing the list
1008  of targets to update. The <tt>UPDATE</tt> builtin rule is:</p>
1009  <pre>
1010rule UPDATE ( targets * )
1011</pre>
1012
1013  <p>The rule has two effects: 1. it clears the list of targets to update,
1014  and 2. causes the specified targets to be updated. If no target was
1015  specified with the <tt>UPDATE</tt> rule, no targets will be updated. To
1016  support changing of the update list in more usefull ways, the rule also
1017  returns the targets previously in the update list. This makes it possible
1018  to add targets as such:</p>
1019  <pre>
1020local previous-updates = [ UPDATE ] ;
1021UPDATE $(previous-updates) a-new-target ;
1022</pre>
1023
1024  <h3 id="semaphores">Semaphores</h3>
1025
1026  <p>It is sometimes desirable to disallow parallel execution of some
1027  actions. For example:</p>
1028
1029  <ul>
1030    <li>Old versions of <tt>yacc</tt> use files with fixed names. So, running
1031    two yacc actions is dangerous.</li>
1032
1033    <li>One might want to perform parallel compiling, but not do parallel
1034    linking, because linking is i/o bound and only gets slower.</li>
1035  </ul>Craig McPeeters has extended Perforce Jam to solve such problems, and
1036  that extension was integrated in Boost.Jam.
1037
1038  <p>Any target can be assigned a <em>semaphore</em>, by setting a variable
1039  called <tt>SEMAPHORE</tt> on that target. The value of the variable is the
1040  semaphore name. It must be different from names of any declared target, but
1041  is arbitrary otherwise.</p>
1042
1043  <p>The semantic of semaphores is that in a group of targets which have the
1044  same semaphore, only one can be updated at the moment, regardless of "-j"
1045  option.</p>
1046
1047  <h3 id="w32_getreg">The W32_GETREG rule</h3>
1048  <pre>
1049    rule W32_GETREG ( path : data ? )
1050</pre>
1051
1052  <p>Defined only for win32 platform. It reads the registry of Windows.
1053  'path' is the location of the information, and 'data' is the name of the
1054  value which we want to get. If 'data' is omitted, the default value of
1055  'path' will be returned. The 'path' value must conform to MS key path
1056  format and must be prefixed with one of the predefined root keys. As
1057  usual,</p>
1058
1059  <ul>
1060    <li>'HKLM' is equivalent to 'HKEY_LOCAL_MACHINE'.</li>
1061
1062    <li>'HKCU' is equivalent to 'HKEY_CURRENT_USER'.</li>
1063
1064    <li>'HKCR' is equivalent to 'HKEY_CLASSES_ROOT'.</li>
1065  </ul>
1066
1067  <p>Other predefined root keys are not supported.</p>
1068
1069  <p>Currently supported data types : 'REG_DWORD', 'REG_SZ', 'REG_EXPAND_SZ',
1070  'REG_MULTI_SZ'. The data with 'REG_DWORD' type will be turned into a
1071  string, 'REG_MULTI_SZ' into a list of strings, and for those with
1072  'REG_EXPAND_SZ' type environment variables in it will be replaced with
1073  their defined values. The data with 'REG_SZ' type and other unsupported
1074  types will be put into a string without modification. If it can't receive
1075  the value of the data, it just return an empty list. For example,</p>
1076  <pre>
1077    local PSDK-location =
1078    [ PROFILE HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\MicrosoftSDK\\Directories : "Install Dir" ] ;
1079</pre>
1080
1081  <h4><a name="ISFILE_rule" id="ISFILE_rule">The <tt>ISFILE</tt>
1082  Rule</a></h4>
1083  <pre>
1084rule ISFILE ( targets * )
1085</pre>
1086
1087  <p><tt>ISFILE</tt> marks targets as required to be files. This changes the
1088  way <b>jam</b> searches for the target such that it ignores mathes for file
1089  system items that are not file, like directories. This makes it possible to
1090  avoid <code>#include "exception"</code> matching if one happens to have a
1091  directory named <i>exception</i> in the header search path.</p>
1092
1093  <h4><a name="SHELL_rule" id="SHELL_rule">The <tt>SHELL</tt>
1094  Rule</a></h4>
1095  <pre>
1096rule SHELL ( command )
1097</pre>
1098
1099  <p><tt>SHELL</tt> executes <i>command</i>, and then returns the standard
1100  output of <i>command</i>.  SHELL only works on platforms with a popen() function
1101  in the C library.  On platforms without a working popen() function,
1102  SHELL is implemented as a no-op.  SHELL works on Unix, MacOS X,
1103  and most Windows compilers.  SHELL is a no-op on Metrowerks compilers
1104  under Windows.</p>. 
1105
1106  <h2><a name="jam_fundamentals" id="jam_fundamentals">Jam
1107  Fundamentals</a></h2>
1108
1109  <p>This section is derived from the official Jam documentation and from my
1110  experience using it and reading the Jambase rules. I repeat the information
1111  here mostly because it is essential to understanding and using Jam, but is
1112  not consolidated in a single place. Some of it is missing from the official
1113  documentation altogether. I hope it will be useful to anyone wishing to
1114  become familiar with Jam and the Boost build system.</p>
1115
1116  <p>&middot; Jam ``<b>rules</b>'' are actually simple procedural entities.
1117  Think of them as functions. Arguments are separated by colons.</p>
1118
1119  <p>&middot; A Jam <b>target</b> is an abstract entity identified by an
1120  arbitrary string. The build-in <tt>DEPENDS</tt> rule creates a link in the
1121  dependency graph between the named targets.</p>
1122
1123  <p>&middot; Note that the documentation for the built-in <tt>INCLUDES</tt>
1124  rule is incorrect: <tt>INCLUDES targets1 : targets2</tt> causes everything
1125  that depends on a member of <i>targets1</i> to depend on all members of
1126  <i>targets2</i>. It does this in an odd way, by tacking <i>targets2</i>
1127  onto a special tail section in the dependency list of everything in
1128  <i>targets1</i>. It seems to be OK to create circular dependencies this
1129  way; in fact, it appears to be the ``right thing to do'' when a single
1130  build action produces both <i>targets1</i> and <i>targets2</i>.</p>
1131
1132  <p>&middot; When a rule is invoked, if there are <b><tt>actions</tt></b>
1133  declared with the same name as the rule, the <tt>actions</tt> are added to
1134  the updating actions for the target identified by the rule's first
1135  argument. It is actually possible to invoke an undeclared rule if
1136  corresponding actions are declared: the rule is treated as empty.</p>
1137
1138  <p>&middot; <a name="binding" id="binding">Targets</a> (other than
1139  <tt>NOTFILE</tt> targets) are associated with paths in the file system
1140  through a process called <a href="./Jam.html#binding">binding</a>. Binding
1141  is a process of searching for a file with the same name as the target (sans
1142  grist), based on the settings of the <a href=
1143  "#target_specific">target-specific</a> <tt>SEARCH</tt> and <tt>LOCATE</tt>
1144  variables.</p>
1145
1146  <p>&middot; <a name="target_specific" id="target_specific">In addition
1147  to</a> local and global variables, jam allows you to set a variable
1148  <tt><b>on</b></tt> a target. Target-specific variable values can usually
1149  not be read, and take effect <i>only</i> in the following contexts:</p>
1150
1151  <ul>
1152    <li>In updating <tt>actions</tt>, variable values are first looked up
1153    <tt><b>on</b></tt> the target named by the first argument (the target
1154    being updated). Because Jam builds its entire dependency tree before
1155    executing <tt>actions</tt>, Jam rules make target-specific variable
1156    settings as a way of supplying parameters to the corresponding
1157    <tt>actions</tt>.</li>
1158
1159    <li>Binding is controlled <i>entirely</i> by the target-specific setting
1160    of the <tt>SEARCH</tt> and <tt>LOCATE</tt> variables, as described
1161    <a href="./Jam.html#search">here</a>.</li>
1162
1163    <li>In the special rule used for <a href="./Jam.html#hdrscan">header file
1164    scanning</a>, variable values are first looked up <tt><b>on</b></tt> the
1165    target named by the rule's first argument (the source file being
1166    scanned).</li>
1167  </ul>
1168
1169  <p>&middot; The ``<b>bound value</b>'' of a variable is the path associated
1170  with the target named by the variable. In build <tt>actions</tt>, the first
1171  two arguments are automatically replaced with their bound values.
1172  Target-specific variables can be selectively replaced by their bound values
1173  using the <a href="./Jam.html#actionmods">bind</a> action modifier.</p>
1174
1175  <p>&middot; Note that the term ``binding'' as used in the Jam documentation
1176  indicates a phase of processing that includes three sub-phases:
1177  <i>binding</i> (yes!), update determination, and header file scanning. The
1178  repetition of the term ``binding'' can lead to some confusion. In
1179  particular, the <a href="./Jam.html#bindingmods">Modifying Binding</a>
1180  section in the Jam documentation should probably be titled ``Modifying
1181  Update Determination''.</p>
1182
1183  <p>&middot; ``Grist'' is just a string prefix of the form
1184  <tt>&lt;</tt><i>characters</i><tt>&gt;</tt>. It is used in Jam to create
1185  unique target names based on simpler names. For example, the file name
1186  ``<tt>test.exe</tt>'' may be used by targets in separate subprojects, or
1187  for the debug and release variants of the ``same'' abstract target. Each
1188  distinct target bound to a file called ``<tt>test.exe</tt>'' has its own
1189  unique grist prefix. The Boost build system also takes full advantage of
1190  Jam's ability to divide strings on grist boundaries, sometimes
1191  concatenating multiple gristed elements at the beginning of a string. Grist
1192  is used instead of identifying targets with absolute paths for two
1193  reasons:</p>
1194
1195  <ol>
1196    <li>The location of targets cannot always be derived solely from what the
1197    user puts in a Jamfile, but sometimes depends also on the <a href=
1198    "#binding">binding</a> process. Some mechanism to distinctly identify
1199    targets with the same name is still needed.</li>
1200
1201    <li>Grist allows us to use a uniform abstract identifier for each built
1202    target, regardless of target file location (as allowed by setting
1203    <tt>ALL_LOCATE_TARGET</tt>.</li>
1204  </ol>
1205
1206  <p>When grist is extracted from a name with
1207  <tt>$(</tt><i>var</i><tt>:G)</tt>, the result includes the leading and
1208  trailing angle brackets. When grist is added to a name with
1209  <tt>$(</tt><i>var</i><tt>:G=</tt><i>expr</i><tt>)</tt>, existing grist is
1210  first stripped. Then, if <i>expr</i> is non-empty, leading <tt>&lt;</tt>s
1211  and trailing <tt>&gt;</tt>s are added if necessary to form an expression of
1212  the form <tt>&lt;</tt><i>expr2</i><tt>&gt;</tt>;
1213  <tt>&lt;</tt><i>expr2</i><tt>&gt;</tt> is then prepended.</p>
1214
1215  <p>&middot; <a name="variable_splitting" id="variable_splitting">When
1216  Jam</a> is invoked it imports all environment variable settings into
1217  corresponding Jam variables, followed by all command-line (<tt>-s...</tt>)
1218  variable settings. Variables whose name ends in <tt>PATH</tt>,
1219  <tt>Path</tt>, or <tt>path</tt> are split into string lists on OS-specific
1220  path-list separator boundaries (e.g. "<tt>:</tt>" for UNIX and "<tt>;</tt>"
1221  for Windows). All other variables are split on space (" ") boundaries.
1222  Boost Jam modifies that behavior by allowing variables to be <a href=
1223  "#variable_quoting">quoted</a>.</p>
1224
1225  <p>&middot; A variable whose value is an empty list <i>or</i> which
1226  consists entirely of empty strings has a negative logical value. Thus, for
1227  example, code like the following allows a sensible non-empty default which
1228  can easily be overridden by the user:</p>
1229  <pre>
1230MESSAGE ?= starting jam... ;
1231if $(MESSAGE) { ECHO The message is: $(MESSAGE) ; }
1232</pre>
1233
1234  <p>If the user wants a specific message, he invokes jam with
1235  <tt>"-sMESSAGE=</tt><i>message text</i><tt>"</tt>. If he wants no message,
1236  he invokes jam with <tt>-sMESSAGE=</tt> and nothing at all is printed.</p>
1237
1238  <p>&middot; The parsing of command line options in Jam can be rather
1239  unintuitive, with regards to how other Unix programs accept options. There
1240  are two variants accepted as valid for an option:</p>
1241
1242  <ol>
1243    <li><tt>-xvalue</tt>, and</li>
1244
1245    <li><tt>-x value</tt>.</li>
1246  </ol>
1247
1248  <p>Please also read <a href="./Jam.html">The Jam language reference</a> for
1249  the additional details.</p>
1250  <hr>
1251
1252  <p>Revised
1253  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
1254   18 November, 2004
1255  <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
1256
1257  <p>Copyright 2003-2004 Rene Rivera, David Abrahams, Vladimir Prus.</p>
1258
1259  <p>Distributed under the Boost Software License, Version 1.0. (See
1260  accompanying file LICENSE_1_0.txt or <a href=
1261  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt)</a></p>
1262</body>
1263</html>
Note: See TracBrowser for help on using the repository browser.