| blob | fda4c4359c960dff6da8da28d6ef2bb2be8f0de3 |
1 <HTML>
3 <BODY>
4 <CENTER>
8 </P>
9 </CENTER>
11 <DL>
13 <PRE>
14 jam [ -a ] [ -g ] [ -n ] [ -q ] [ -v ]
22 </PRE>
27 using dependency information and updating actions expressed in
30 provides a boilerplate for common use, relying on a user-provide
39 'all'.</P>
48 display (summary info and actions):
52 use of temporary targets
54 new sources, missing targets, etc.
57 timestamps and paths
59 </DL>
60 </TD></TR>
64 Interesting values are:
74 </DL>
75 </TD></TR>
85 Multiple -f flags are permitted.</TD></TR>
88 <TD>Build targets with the newest sources first, rather than
89 in the order of appearance in the Jambase/Jamfiles.</TD></TR>
96 <TD>Don't actually execute the updating actions, but do
97 everything else. This changes the debug level to -dax.</TD></TR>
100 <TD>Write the updating actions to the specified file instead
101 of running them (or outputting them, as on the Mac).</TD></TR>
104 <TD>Quit quickly (as if an interrupt was received)
105 as soon as any target build fails.</TD></TR>
109 both internal variables and variables imported from the
110 environment.</TD></TR>
114 even if it is up-to-date.</TD></TR>
118 </TABLE></P>
122 binding, and updating.</P>
127 blanks with each word becoming an element in the variable's list
128 of values. Environment variables whose names end in PATH are
131 <P>To set a variable's value on the command line, overriding the
132 variable's environment value, use the -s option. If a command
133 line argument includes, but doesn't start with a "=", it is
134 treated as an implicit "-s" option. To see variable
136 option.</P>
142 last action of the Jambase is to read (via the "include" rule)
145 <P>Collectively, the purpose of the Jambase and the Jamfile is to
146 name built target and source files, construct the dependency
147 graph among them, and associate build actions with targets.
148 The Jambase defines boilerplate rules and variable assignments,
149 and the Jamfile uses these to specify the actual relationship
150 among the target and source files. See the
156 </A>
159 graph and binds every file target with a location in the
160 filesystem.</P>
164 does so if the DEPENDS or INCLUDES rules make it part of the
165 dependency graph. Build targets are files to be updated. Source
166 targets are the files used in updating build targets. Build
167 targets and source targets are collectively referred to as file
168 targets, and frequently build targets are source targets for
169 other build targets. Pseudotargets are symbols which represent
170 dependencies on other targets, but which are not themselves
171 associated with any real file.</P>
173 <P>A file target's identifier is generally the file's name, which can
175 invocation, or simply local (no directory). Most often it is the
176 last case, and the actual file path is bound using the $(SEARCH)
177 and $(LOCATE) special variables. See
179 filename is optionally qualified with "grist," a string value used
180 to assure uniqueness. A file target with an identifier of the form
182 on UNIX).</P>
185 the the location of files from their names, so that Jamfiles can
186 refer to files locally (i.e. relative to the Jamfile's directory),
188 directory. The use of grist allows files with the same name
190 directory tree of Jamfiles and not mix up same-named targets.</P>
194 target needs updating, and if so marks the target for the updating
195 phase. A target is normally so marked if it is missing, it is
196 older than any of its sources, or any of its sources are marked
197 for updating. This behavior can be modified by the application
198 of special built-in rules. See
203 scanning, where it looks inside source files for the implicit
204 dependencies on other files caused by C's #include syntax. This
205 is controlled by the special variables $(HDRSCAN) and $(HDRRULE).
206 The result of the scan is formed into a rule invocation, with
207 the scanned file as the target and the found included file names
208 as the sources. Note that this is the only case where rules
209 are invoked outside the parsing phase. See
214 graph, this time executing the update actions for each target
215 marked for update during the binding phase. If a target's
216 updating actions fail, then all other targets which depend on
217 that target are skipped.</P>
220 at a time. If there are multiple actions on a single target,
221 they are run sequentially. The -g flag reorders builds so that
222 targets with newest sources are built first. Normally, they are
223 built in the order of appearance in the Jamfiles.</P>
227 </A>
230 select features to effect program construction. Statements in
232 updating action definitions, flow-of-control structures, variable
233 assignments, and sundry language support.</P>
237 with two exceptions: double quotes (") can enclose whitespace to
238 embed it into a token, and everything between the matching curly
239 braces ({}) in the definition of a updating actions is treated
240 as a single string. A backslash (\) can escape a double quote,
241 or any single whitespace character.</P>
243 <P><B>Jam</b> requires whitespace (blanks, tabs, or newlines) to
244 surround all tokens, <b>including the colon (:) and semicolon
245 (;) tokens</b>.</P>
247 <P><B>Jam</b> keywords (as mentioned in this document) are reserved
248 and generally must be quoted with double quotes (") to be used
249 as arbitrary tokens, such as variable or target names.</P>
253 strings. They arise as literal (whitespace-separated) tokens in
254 the Jambase or included files, as the result of variable expansion
255 of those tokens, or as the return value from a rule invocation.</P>
260 statements to be run when the rule is invoked. The syntax of
261 rule invocation make it possible to write Jamfiles that look
262 a bit like Makefiles.</P>
265 and can have a return value (a single list). A rule's return
266 value can be expanded in a list by enclosing the rule invocation
270 <P>A rule may have updating actions associated with it, in which
272 sources, respectively. Updating actions are the OS shell commands
273 to execute when updating the built targets of the rule.</P>
275 <P>When an rule with updating actions is invoked, those actions are
276 added to those associated with its built targets ($(1)) before
277 the rule's procedure is run. Later, to build the targets in the
278 updating phase, the actions are passed to the OS command shell,
285 <P><DT><CODE>
287 </CODE></P>
288 <P><DD>Invoke a rule. A rule is invoked with values in
295 expansion</A>. If the resulting list is more than one value,
296 each rule is invoked with the same arguments, and the result
297 of the invocation is the concatenation of all the results.</P>
299 <P><DT><CODE>
301 </CODE></P>
302 <P><DD> Define a rule's updating actions, replacing any previous
303 definition. The first two arguments may be referenced in
311 </TR>
314 </TR>
317 </TR>
320 of $(>) small enough to fit in the command buffer on this
321 OS.</TD>
322 </TR>
325 </TR>
328 on the same built target are glommed together.</TD>
329 </TR>
332 for updating.</TD>
333 </TR>
334 </TABLE></P>
342 <P><DT><CODE>
344 </CODE></P>
349 <P><DT><CODE>
351 </CODE></P>
356 </TR>
359 </TR>
362 </TR>
364 <TD><I>a[i]</I> string is less than <I>b[i]</I> string, where <i>i</i> is first mismatched element
366 </TR>
369 </TR>
371 <TD><I>a[i]</I> string is greater than <I>b[i]</I> string, where <i>i</i> is first mismatched element</TD>
372 </TR>
375 </TR>
377 <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>
378 </TR>
381 </TR>
384 </TR>
387 </TR>
390 </TR>
391 </TABLE></P>
396 above) but unlike a regular target the include file cannot be built.
398 if it is missing, it causes no error.</P>
400 <P>The include file is inserted into the input stream during
401 the parsing phase. The primary input file and all the included
403 infers no scope boundaries from included files.</P>
407 block, obscuring any previous values they might have. The
409 block ends. Any rule called or file included will see the
410 local and not the previous value (this is sometimes called
411 Dynamic Scoping). The local statement may appear anywhere,
412 even outside of a block (in which case the previous value
415 otherwise.</P>
421 may be updated as target-specific variables using the usual
425 <P><DD>Within a rule body, the return statement sets the return
426 value for an invocation of the rule and terminates the rule's
427 execution.</P>
430 <P><DD>Define a rule's procedure, replacing any previous
437 <BR> {
440 <BR> ...
441 <BR> }
442 </CODE></P>
443 <P><DD>The switch statement executes zero or one of the
448 <TABLE>
451 <TR><TD><CODE>[<i>chars</i>]</CODE></TD><TD>match any single character in <i>chars</i></TD></TR>
452 <TR><TD><CODE>[^<i>chars</i>]</CODE></TD><TD>match any single character not in <i>chars</i></TD></TR>
453 <TR><TD><CODE>\<i>x</i></CODE></TD><TD>match <i>x</i> (escapes the other wildcards)</i></TD></TR>
454 </TABLE>
455 Note that escaping isn't working in range definitions. To include "]" in range, one can
462 </DL></TD></TR></TABLE></P>
467 each element being a string value. An undefined variable is
468 indistinguishable from a variable with an empty list, however,
469 a defined variable may have one more elements which are null
472 <P>Variables are either global or target-specific. In the latter
473 case, the variable takes on the given value only during the
474 target's binding, header file scanning, and updating; and during
485 </DL></TD></TR></TABLE>
488 three forms set a target-specific variable. The = operator
493 "<I>variable</I> on <I>targets</I> ?= <I>elements</I>" checks
494 to see if the target-specific, not the global, variable is set.
497 <P>Variables referenced in updating commands will be replaced with
498 their values; target-specific values take precedence over global
500 are replaced with their bound values; the "bind" modifier can
501 be used on actions to cause other variables to be replaced with
503 above.</P>
506 the shell that executes the updating actions, but the updating
512 token that is not a keyword or rule name. Such tokens with
513 embedded variable references are replaced with zero or more
516 are optional modifiers.</P>
518 <P>Variable expansion in a rule's actions is similar to variable
519 expansion in statements, except that the action string is
520 tokenized at whitespace regardless of quoting.</P>
522 <P>The result of a token after variable expansion is the
524 component is a literal substring or a list substituting a variable
525 reference. For example:</P>
531 </CODE></TD></TR></TABLE></P>
533 <P>The variable name and modifiers can themselves contain
534 a variable reference, and this partakes of the product
535 as well:</P>
541 </CODE></TD></TR></TABLE></P>
543 <P>Because of this product expansion, if any variable reference in
544 a token is undefined, the result of the expansion is an empty
545 list. If any variable element is a null string, the result
546 propagates the non-null elements:</P>
553 </CODE></TD></TR></TABLE></P>
555 <P>A variable element's string value can be parsed into grist and
556 filename-related components. Modifiers to a variable are used
557 to select elements, select components, and replace components.
558 The modifiers are:</P>
563 the result is a zero-element list.
564 </TD></TR>
578 <TR><TD><CODE>:<i>chars</I></CODE></TD><TD>Select the components listed in <i>chars</i>.</TD></TR>
581 <TR><TD><CODE>:B=<I>base</I></CODE></TD><TD>Replace the base part of file name with <I>base</I>.</TD></TR>
582 <TR><TD><CODE>:S=<I>suf</I></CODE></TD><TD>Replace the suffix of file name with <I>suf</I>.</TD></TR>
583 <TR><TD><CODE>:M=<I>mem</I></CODE></TD><TD>Replace the archive member name with <I>mem</I>.</TD></TR>
584 <TR><TD><CODE>:R=<I>root</I></CODE></TD><TD>Prepend <I>root</I> to the whole file name, if not already rooted.</TD></TR>
585 <TR><TD><CODE>:E=<I>value</I></CODE></TD><TD>Use <I>value</I> instead if the variable is unset.</TD></TR>
586 <TR><TD><CODE>:J=<I>joinval</I></CODE></TD><TD>Concatentate list elements into single element, separated by <I>joinval</I>.</TD></TR>
587 </TABLE></P>
591 </P>
596 procedure rules without updating actions. They are in
597 three groups: the first builds the dependency graph;
598 the second modifies it; and the third are just utility
599 rules.</P>
609 <DD>Builds a sibling dependency: makes any target that depends
611 This reflects the dependencies that arise when one source file
612 includes another: the object built from the source file depends
613 both on the original and included source file, but the two
614 sources files don't depend on each other. For example:
615 <CODE>
616 <P>DEPENDS foo.o : foo.c ;
617 <BR>INCLUDES foo.c : foo.h ;
618 </P></CODE></P>
620 </DL></TD></TR></TABLE></P>
624 <P>The six rules ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, and
626 the targets differently during its target binding phase. See
628 updates a target if it is missing, if its filesystem modification
629 time is older than any of its dependencies (recursively), or if
630 any of its dependencies are being updated. This basic behavior
631 can be changed by invoking the following rules:</P>
635 they are up-to-date (they must still be in the dependency graph).
636 This is used for the clean and uninstall targets, as they have
637 no dependencies and would otherwise appear never to need building.
638 It is best applied to targets that are also NOTFILE targets,
639 but it can also be used to force a real file to be updated as
640 well.</P>
643 and not on any intermediate targets. This makes it immune to
644 its dependencies being updated, as the "leaf" dependencies are
645 those without their own dependencies and without updating actions.
646 This allows a target to be updated only if original source files
647 change.</P>
650 can be found nor have updating actions to build them. Normally
652 other targets that depend on these missing targets. The HdrRule
653 in Jambase uses NOCARE on the header file names found during
655 files may not exist. For example, if a #include is within an
656 #ifdef, the included file may not actually be around.</P>
659 No timestamp is checked, and so the actions on such a target
660 are only executed if the target's dependencies are updated, or
662 target "all" is a pseudotarget. In Jambase, NOTFILE is used to
663 define several addition convenient pseudotargets.</P>
666 This has two effects: first, once the target has been created
667 it will never be updated; second, manually updating target will
668 not cause other targets to be updated. In Jambase, for example,
669 this rule is applied to directories by the MkDir rule, because
670 MkDir only cares that the target directory exists, not when it
671 has last been updated.</P>
674 removed after other targets that depend upon them have been
676 timestamp of the target's parent. Jambase uses TEMPORARY to
677 mark object files that are archived in a library after they are
678 built, so that they can be deleted after they are archived.</P>
679 </DL></TD></TR></TABLE></P>
682 The remaining rules are utility rules.
684 <P><DT><CODE>
688 </CODE>
690 <P><DT><CODE>
694 </CODE>
696 with a failure status.</P>
697 <P><DT><CODE>
700 </CODE>
702 returning the list of matching files (with directory prepended).
706 be automatically ommited.</P>
707 <P><DT><CODE>
710 </CODE>
716 to change the result into a list.</P>
717 <P><DT><CODE>
720 </CODE>
721 <DD>Execute external command and return exit code and/or command output.
747 </TABLE></P>
748 </P>
749 <P><DT><CODE>
752 </CODE>
753 <DD>Sort list alphabetically (ascending).
755 </P>
756 <P><DT><CODE>
757 PWD ;
758 Pwd ;
759 </CODE>
761 </P>
762 </DL></TD></TR></TABLE></P>
768 <P>These two variables control the binding of file target names to
769 locations in the file system. Generally, $(SEARCH) is used to
770 find existing sources while $(LOCATE) is used to fix the location
771 for built targets.</P>
773 <P>Rooted (absolute path) file targets are bound as is. Unrooted
774 file target names are also normally bound as is, and thus relative
775 to the current directory, but the settings of $(LOCATE) and
776 $(SEARCH) alter this:</P>
778 <P><UL>
779 <LI>If $(LOCATE) is set then the target is bound relative to
780 the first directory in $(LOCATE). Only the first element is
781 used for binding.</LI>
782 <LI>If $(SEARCH) is set then the target is bound to the first
783 directory in $(SEARCH) where the target file already exists.</LI>
784 <LI>If the $(SEARCH) search fails, the target is bound relative
785 to the current directory anyhow.</LI>
786 </UL></P>
788 <P>Both $(SEARCH) and $(LOCATE) should be set target-specific and
790 the same paths for all file binding, which is not likely to
791 produce sane results. When writing your own rules, especially
792 ones not built upon those in Jambase, you may need to set
793 $(SEARCH) or $(LOCATE) directly. Almost all of the rules defined
794 in Jambase set $(SEARCH) and $(LOCATE) to sensible values for
795 sources they are looking for and targets they create, respectively.</P>
799 <P>These two variable control header file scanning. $(HDRSCAN) is
801 used to find file inclusion statements in source files. Jambase
802 uses $(HDRPATTERN) as the pattern for $(HDRSCAN). $(HDRRULE)
803 is the name of a rule to invoke with the results of the scan:
804 the scanned file is the target, the found files are the sources.
805 $(HDRRULE) is run under the influence of the scanned file's
806 target-specific variables.</P>
808 <P>Both $(HDRSCAN) and $(HDRRULE) must be set for header file
809 scanning to take place, and they should be set target-specific
810 and not globally. If they were set globally, all files, including
811 executables and libraries, would be scanned for header file
812 include statements.</P>
814 <P>The scanning for header file inclusions is not exact, but it is
815 at least dynamic, so there is no need to run something like
817 scanning mechanism errs on the side of inclusion (i.e., it is
818 more likely to return filenames that are not actually used by
819 the compiler than to miss include files) because it can't tell
820 if #include lines are inside #ifdefs or other conditional logic.
821 In Jambase, HdrRule applies the NOCARE rule to each header file
822 found during scanning so that if the file isn't present yet
825 <P>Also, scanning for regular expressions only works where the
826 included file name is literally in the source file. It can't
827 handle languages that allow including files using variable names
828 (as the Jam language itself does).</P>
831 <P>A number of Jam built-in variables can be used to identify
832 runtime platform:</P>
838 </TABLE></P>
847 </TABLE></P>
850 <P>A new builting variable has been defined. When K8Jam start, it defines
851 the variable JAMCMDARGS which contains the list of targets used on the
852 command line when Jam was invoked.</P>
854 <P>This is useful to provide richer control flow in the Jambase depending
855 on command line arguments.</P>
859 execs a shell, passing the action block as an argument to the
860 shell. The invocation of the shell can be controlled by
861 $(JAMSHELL).The default on Unix is, for example:</P>
867 multiple hosts, since that is heavily dependent on the local
868 environment. To build in parallel across multiple hosts, you
869 need to write your own shell that provides access to the multiple
870 hosts. You then reset $(JAMSHELL) to reference it.</P>
873 action block, it expands a ! to be the multi-process slot number.
874 The slot number varies between 1 and the number of concurrent
875 jobs permitted by the -j flag given on the command line. Armed
876 with this, it is possible to write a multiple host shell. For
877 example:</P>
880 <BR>#!/bin/sh
881 <BR>
883 <BR># command string with an identical environment on another host.
884 <BR>
885 <BR># Set JAMSHELL = jamshell ! %
886 <BR>#
887 <BR># where jamshell is the name of this shell file.
888 <BR>#
889 <BR># This version handles up to -j6; after that they get executed
890 <BR># locally.
891 <BR>
897 <BR>esac
898 </CODE></TD></TR></TABLE></P>
907 Targets marked as being temporary (but nonetheless present) have been found.
909 Targets are out-of-date and will be updated.
911 Source files can't be found and there are no actions to create them.
913 Due to sources not being found, other targets cannot be made.
915 A target depends on itself either directly or through its sources.
917 A target is not present and no actions have been defined to create it.
919 A source failed to build, and thus a target cannot be built.
921 A target that is not a dependency of any other target is being referenced with $(<) or $(>).
924 </DL></TD></TR></TABLE></P>
929 proceed as if the targets were built even though they are still
930 under construction.</P>
932 <P>For parallel building to be successful, the dependencies among
933 files must be properly spelled out, as targets tend to get built
934 in a quickest-first ordering. Also, beware of un-parallelizable
935 commands that drop fixed-named files into the current directory,
938 <P>With the -j flag, errors from failed commands can get staggeringly
939 mixed up.</P>
944 <P><UL>
947 </UL></P>
949 <P>Jam documentation and source are available from the
953 <P>Jam's author is Christopher Seiwald (<a href="mailto:seiwald@perforce.com">seiwald@perforce.com</A>).<BR/>
956 See <a href="http://www.freetype.org/jam/">http://www.freetype.org/jam/</a> for more details.<BR/>
957 "K8Jam" is a derivative of FT-Jam.
958 See <a href="http://gitorious.org/projects/kjam">gitorious repository</a> for the latest sources.
959 </P>
960 </DL>
962 <P><HR>
964 </P>
965 </BODY>
966 </HTML>