| blob | 238ccb59957cd3d011af1bf56119604a7899e740 |
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:
73 </DL>
74 </TD></TR>
84 Multiple -f flags are permitted.</TD></TR>
87 <TD>Build targets with the newest sources first, rather than
88 in the order of appearance in the Jambase/Jamfiles.</TD></TR>
95 <TD>Don't actually execute the updating actions, but do
96 everything else. This changes the debug level to -dax.</TD></TR>
99 <TD>Write the updating actions to the specified file instead
100 of running them (or outputting them, as on the Mac).</TD></TR>
103 <TD>Quit quickly (as if an interrupt was received)
104 as soon as any target build fails.</TD></TR>
108 both internal variables and variables imported from the
109 environment.</TD></TR>
113 even if it is up-to-date.</TD></TR>
124 </DL>
125 </TD></TR>
129 </TABLE></P>
133 binding, and updating.</P>
138 blanks with each word becoming an element in the variable's list
139 of values. Environment variables whose names end in PATH are
142 <P>To set a variable's value on the command line, overriding the
143 variable's environment value, use the -s option. If a command
144 line argument includes, but doesn't start with a "=", it is
145 treated as an implicit "-s" option. To see variable
147 option.</P>
153 last action of the Jambase is to read (via the "include" rule)
156 <P>Collectively, the purpose of the Jambase and the Jamfile is to
157 name built target and source files, construct the dependency
158 graph among them, and associate build actions with targets.
159 The Jambase defines boilerplate rules and variable assignments,
160 and the Jamfile uses these to specify the actual relationship
161 among the target and source files. See the
167 </A>
170 graph and binds every file target with a location in the
171 filesystem.</P>
175 does so if the DEPENDS or INCLUDES rules make it part of the
176 dependency graph. Build targets are files to be updated. Source
177 targets are the files used in updating build targets. Build
178 targets and source targets are collectively referred to as file
179 targets, and frequently build targets are source targets for
180 other build targets. Pseudotargets are symbols which represent
181 dependencies on other targets, but which are not themselves
182 associated with any real file.</P>
184 <P>A file target's identifier is generally the file's name, which can
186 invocation, or simply local (no directory). Most often it is the
187 last case, and the actual file path is bound using the $(SEARCH)
188 and $(LOCATE) special variables. See
190 filename is optionally qualified with "grist," a string value used
191 to assure uniqueness. A file target with an identifier of the form
193 on UNIX).</P>
196 the the location of files from their names, so that Jamfiles can
197 refer to files locally (i.e. relative to the Jamfile's directory),
199 directory. The use of grist allows files with the same name
201 directory tree of Jamfiles and not mix up same-named targets.</P>
205 target needs updating, and if so marks the target for the updating
206 phase. A target is normally so marked if it is missing, it is
207 older than any of its sources, or any of its sources are marked
208 for updating. This behavior can be modified by the application
209 of special built-in rules. See
214 scanning, where it looks inside source files for the implicit
215 dependencies on other files caused by C's #include syntax. This
216 is controlled by the special variables $(HDRSCAN) and $(HDRRULE).
217 The result of the scan is formed into a rule invocation, with
218 the scanned file as the target and the found included file names
219 as the sources. Note that this is the only case where rules
220 are invoked outside the parsing phase. See
225 graph, this time executing the update actions for each target
226 marked for update during the binding phase. If a target's
227 updating actions fail, then all other targets which depend on
228 that target are skipped.</P>
231 at a time. If there are multiple actions on a single target,
232 they are run sequentially. The -g flag reorders builds so that
233 targets with newest sources are built first. Normally, they are
234 built in the order of appearance in the Jamfiles.</P>
238 </A>
241 select features to effect program construction. Statements in
243 updating action definitions, flow-of-control structures, variable
244 assignments, and sundry language support.</P>
248 with two exceptions: double quotes (") can enclose whitespace to
249 embed it into a token, and everything between the matching curly
250 braces ({}) in the definition of a updating actions is treated
251 as a single string. A backslash (\) can escape a double quote,
252 or any single whitespace character.</P>
254 <P><B>Jam</b> requires whitespace (blanks, tabs, or newlines) to
255 surround all tokens, <b>including the colon (:) and semicolon
256 (;) tokens</b>.</P>
258 <P><B>Jam</b> keywords (as mentioned in this document) are reserved
259 and generally must be quoted with double quotes (") to be used
260 as arbitrary tokens, such as variable or target names.</P>
264 strings. They arise as literal (whitespace-separated) tokens in
265 the Jambase or included files, as the result of variable expansion
266 of those tokens, or as the return value from a rule invocation.</P>
271 statements to be run when the rule is invoked. The syntax of
272 rule invocation make it possible to write Jamfiles that look
273 a bit like Makefiles.</P>
276 and can have a return value (a single list). A rule's return
277 value can be expanded in a list by enclosing the rule invocation
281 <P>A rule may have updating actions associated with it, in which
283 sources, respectively. Updating actions are the OS shell commands
284 to execute when updating the built targets of the rule.</P>
286 <P>When an rule with updating actions is invoked, those actions are
287 added to those associated with its built targets ($(1)) before
288 the rule's procedure is run. Later, to build the targets in the
289 updating phase, the actions are passed to the OS command shell,
296 <P><DT><CODE>
298 </CODE></P>
299 <P><DD>Invoke a rule. A rule is invoked with values in
306 expansion</A>. If the resulting list is more than one value,
307 each rule is invoked with the same arguments, and the result
308 of the invocation is the concatenation of all the results.</P>
310 <P><DT><CODE>
312 </CODE></P>
313 <P><DD> Define a rule's updating actions, replacing any previous
314 definition. The first two arguments may be referenced in
322 </TR>
325 </TR>
328 </TR>
331 of $(>) small enough to fit in the command buffer on this
332 OS.</TD>
333 </TR>
336 </TR>
339 on the same built target are glommed together.</TD>
340 </TR>
343 for updating.</TD>
344 </TR>
345 </TABLE></P>
353 <P><DT><CODE>
355 </CODE></P>
360 <P><DT><CODE>
362 </CODE></P>
367 </TR>
370 </TR>
373 </TR>
375 <TD><I>a[i]</I> string is less than <I>b[i]</I> string, where <i>i</i> is first mismatched element
377 </TR>
380 </TR>
382 <TD><I>a[i]</I> string is greater than <I>b[i]</I> string, where <i>i</i> is first mismatched element</TD>
383 </TR>
386 </TR>
388 <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>
389 </TR>
392 </TR>
395 </TR>
398 </TR>
401 </TR>
402 </TABLE></P>
407 above) but unlike a regular target the include file cannot be built.
409 if it is missing, it causes no error.</P>
411 <P>The include file is inserted into the input stream during
412 the parsing phase. The primary input file and all the included
414 infers no scope boundaries from included files.</P>
418 block, obscuring any previous values they might have. The
420 block ends. Any rule called or file included will see the
421 local and not the previous value (this is sometimes called
422 Dynamic Scoping). The local statement may appear anywhere,
423 even outside of a block (in which case the previous value
426 otherwise.</P>
432 may be updated as target-specific variables using the usual
436 <P><DD>Within a rule body, the return statement sets the return
437 value for an invocation of the rule and terminates the rule's
438 execution.</P>
441 <P><DD>Define a rule's procedure, replacing any previous
448 <BR> {
451 <BR> ...
452 <BR> }
453 </CODE></P>
454 <P><DD>The switch statement executes zero or one of the
459 <TABLE>
462 <TR><TD><CODE>[<i>chars</i>]</CODE></TD><TD>match any single character in <i>chars</i></TD></TR>
463 <TR><TD><CODE>[^<i>chars</i>]</CODE></TD><TD>match any single character not in <i>chars</i></TD></TR>
464 <TR><TD><CODE>\<i>x</i></CODE></TD><TD>match <i>x</i> (escapes the other wildcards)</i></TD></TR>
465 </TABLE>
466 Note that escaping isn't working in range definitions. To include "]" in range, one can
473 </DL></TD></TR></TABLE></P>
478 each element being a string value. An undefined variable is
479 indistinguishable from a variable with an empty list, however,
480 a defined variable may have one more elements which are null
483 <P>Variables are either global or target-specific. In the latter
484 case, the variable takes on the given value only during the
485 target's binding, header file scanning, and updating; and during
498 </DL></TD></TR></TABLE>
501 three forms set a target-specific variable. The = operator
507 The last form "<I>variable</I> on <I>targets</I> ?= <I>elements</I>"
508 checks to see if the target-specific, not the global, variable is set.</P>
510 <P>Variables referenced in updating commands will be replaced with
511 their values; target-specific values take precedence over global
513 are replaced with their bound values; the "bind" modifier can
514 be used on actions to cause other variables to be replaced with
516 above.</P>
519 the shell that executes the updating actions, but the updating
525 token that is not a keyword or rule name. Such tokens with
526 embedded variable references are replaced with zero or more
529 are optional modifiers.</P>
531 <P>Variable expansion in a rule's actions is similar to variable
532 expansion in statements, except that the action string is
533 tokenized at whitespace regardless of quoting.</P>
535 <P>The result of a token after variable expansion is the
537 component is a literal substring or a list substituting a variable
538 reference. For example:</P>
544 </CODE></TD></TR></TABLE></P>
546 <P>The variable name and modifiers can themselves contain
547 a variable reference, and this partakes of the product
548 as well:</P>
554 </CODE></TD></TR></TABLE></P>
556 <P>Because of this product expansion, if any variable reference in
557 a token is undefined, the result of the expansion is an empty
558 list. If any variable element is a null string, the result
559 propagates the non-null elements:</P>
566 </CODE></TD></TR></TABLE></P>
568 <P>A variable element's string value can be parsed into grist and
569 filename-related components. Modifiers to a variable are used
570 to select elements, select components, and replace components.
571 The modifiers are:</P>
576 the result is a zero-element list.
577 </TD></TR>
591 <TR><TD><CODE>:<i>chars</I></CODE></TD><TD>Select the components listed in <i>chars</i>.</TD></TR>
594 <TR><TD><CODE>:B=<I>base</I></CODE></TD><TD>Replace the base part of file name with <I>base</I>.</TD></TR>
595 <TR><TD><CODE>:S=<I>suf</I></CODE></TD><TD>Replace the suffix of file name with <I>suf</I>.</TD></TR>
596 <TR><TD><CODE>:M=<I>mem</I></CODE></TD><TD>Replace the archive member name with <I>mem</I>.</TD></TR>
597 <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>
598 <TR><TD><CODE>:E=<I>value</I></CODE></TD><TD>Use <I>value</I> instead if the variable is unset.</TD></TR>
599 <TR><TD><CODE>:J=<I>joinval</I></CODE></TD><TD>Concatentate list elements into single element, separated by <I>joinval</I>.</TD></TR>
600 </TABLE></P>
604 </P>
609 procedure rules without updating actions. They are in
610 three groups: the first builds the dependency graph;
611 the second modifies it; and the third are just utility
612 rules.</P>
622 <DD>Builds a sibling dependency: makes any target that depends
624 This reflects the dependencies that arise when one source file
625 includes another: the object built from the source file depends
626 both on the original and included source file, but the two
627 sources files don't depend on each other. For example:
628 <CODE>
629 <P>Depends foo.o : foo.c ;
630 <BR>Includes foo.c : foo.h ;
631 </P></CODE></P>
635 </DL></TD></TR></TABLE></P>
639 <P>The six rules Always, Leaves, NoCare, ForceCare, NotFile, NoUpdate,
641 the targets differently during its target binding phase. See
643 updates a target if it is missing, if its filesystem modification
644 time is older than any of its dependencies (recursively), or if
645 any of its dependencies are being updated. This basic behavior
646 can be changed by invoking the following rules:</P>
650 they are up-to-date (they must still be in the dependency graph).
651 This is used for the clean and uninstall targets, as they have
652 no dependencies and would otherwise appear never to need building.
653 It is best applied to targets that are also NotFile targets,
654 but it can also be used to force a real file to be updated as
655 well.</P>
658 and not on any intermediate targets. This makes it immune to
659 its dependencies being updated, as the "leaf" dependencies are
660 those without their own dependencies and without updating actions.
661 This allows a target to be updated only if original source files
662 change.</P>
665 can be found nor have updating actions to build them. Normally
667 other targets that depend on these missing targets. The HdrRule
668 in Jambase uses NoCare on the header file names found during
670 files may not exist. For example, if a #include is within an
671 #ifdef, the included file may not actually be around.</P>
677 No timestamp is checked, and so the actions on such a target
678 are only executed if the target's dependencies are updated, or
680 target "all" is a pseudotarget. In Jambase, NotFile is used to
681 define several addition convenient pseudotargets.</P>
684 This has two effects: first, once the target has been created
685 it will never be updated; second, manually updating target will
686 not cause other targets to be updated. In Jambase, for example,
687 this rule is applied to directories by the MkDir rule, because
688 MkDir only cares that the target directory exists, not when it
689 has last been updated.</P>
692 removed after other targets that depend upon them have been
694 timestamp of the target's parent. Jambase uses Temporary to
695 mark object files that are archived in a library after they are
696 built, so that they can be deleted after they are archived.</P>
697 </DL></TD></TR></TABLE></P>
700 The remaining rules are utility rules.
702 <P><DT><CODE>
705 </CODE>
707 <P><DT><CODE>
710 </CODE>
712 with a failure status.</P>
713 <P><DT><CODE>
715 </CODE>
717 returning the list of matching files (with directory prepended).
721 be automatically ommited.<BR>
723 <UL>
733 </UL></P>
734 <P><DT><CODE>
736 </CODE>
742 to change the result into a list.<BR>
744 <UL>
748 </UL></P>
749 <P><DT><CODE>
751 </CODE>
752 <DD>Execute external command and return exit code and/or command output.
778 </TABLE></P>
779 </P>
780 <P><DT><CODE>
782 </CODE>
783 <DD>Sort list alphabetically (ascending).
785 </P>
786 <P><DT><CODE>
787 Pwd ;
788 </CODE>
790 </P>
791 <P><DT><CODE>
794 </CODE>
797 <UL>
801 </UL></P>
802 <P><DT><CODE>
804 </CODE>
806 <P><DT><CODE>
808 </CODE>
810 just split string to chars (explode)</P>
811 </DL>
813 </TD></TR></TABLE></P>
819 <P>These two variables control the binding of file target names to
820 locations in the file system. Generally, $(SEARCH) is used to
821 find existing sources while $(LOCATE) is used to fix the location
822 for built targets.</P>
824 <P>Rooted (absolute path) file targets are bound as is. Unrooted
825 file target names are also normally bound as is, and thus relative
826 to the current directory, but the settings of $(LOCATE) and
827 $(SEARCH) alter this:</P>
829 <P><UL>
830 <LI>If $(LOCATE) is set then the target is bound relative to
831 the first directory in $(LOCATE). Only the first element is
832 used for binding.</LI>
833 <LI>If $(SEARCH) is set then the target is bound to the first
834 directory in $(SEARCH) where the target file already exists.</LI>
835 <LI>If the $(SEARCH) search fails, the target is bound relative
836 to the current directory anyhow.</LI>
837 </UL></P>
839 <P>Both $(SEARCH) and $(LOCATE) should be set target-specific and
841 the same paths for all file binding, which is not likely to
842 produce sane results. When writing your own rules, especially
843 ones not built upon those in Jambase, you may need to set
844 $(SEARCH) or $(LOCATE) directly. Almost all of the rules defined
845 in Jambase set $(SEARCH) and $(LOCATE) to sensible values for
846 sources they are looking for and targets they create, respectively.</P>
850 <P>These two variable control header file scanning. $(HDRSCAN) is
852 used to find file inclusion statements in source files. Jambase
853 uses $(HDRPATTERN) as the pattern for $(HDRSCAN). $(HDRRULE)
854 is the name of a rule to invoke with the results of the scan:
855 the scanned file is the target, the found files are the sources.
856 $(HDRRULE) is run under the influence of the scanned file's
857 target-specific variables.</P>
859 <P>Both $(HDRSCAN) and $(HDRRULE) must be set for header file
860 scanning to take place, and they should be set target-specific
861 and not globally. If they were set globally, all files, including
862 executables and libraries, would be scanned for header file
863 include statements.</P>
865 <P>The scanning for header file inclusions is not exact, but it is
866 at least dynamic, so there is no need to run something like
868 scanning mechanism errs on the side of inclusion (i.e., it is
869 more likely to return filenames that are not actually used by
870 the compiler than to miss include files) because it can't tell
871 if #include lines are inside #ifdefs or other conditional logic.
872 In Jambase, HdrRule applies the NoCare rule to each header file
873 found during scanning so that if the file isn't present yet
876 <P>Also, scanning for regular expressions only works where the
877 included file name is literally in the source file. It can't
878 handle languages that allow including files using variable names
879 (as the Jam language itself does).</P>
882 <P>A number of Jam built-in variables can be used to identify
883 runtime platform:</P>
889 </TABLE></P>
898 </TABLE></P>
901 <P>A new builting variable has been defined. When K8Jam start, it defines
902 the variable JAMCMDARGS which contains the list of targets used on the
903 command line when Jam was invoked.</P>
905 <P>This is useful to provide richer control flow in the Jambase depending
906 on command line arguments.</P>
910 execs a shell, passing the action block as an argument to the
911 shell. The invocation of the shell can be controlled by
912 $(JAMSHELL).The default on Unix is, for example:</P>
918 multiple hosts, since that is heavily dependent on the local
919 environment. To build in parallel across multiple hosts, you
920 need to write your own shell that provides access to the multiple
921 hosts. You then reset $(JAMSHELL) to reference it.</P>
924 action block, it expands a ! to be the multi-process slot number.
925 The slot number varies between 1 and the number of concurrent
926 jobs permitted by the -j flag given on the command line. Armed
927 with this, it is possible to write a multiple host shell. For
928 example:</P>
931 <BR>#!/bin/sh
932 <BR>
934 <BR># command string with an identical environment on another host.
935 <BR>
936 <BR># Set JAMSHELL = jamshell ! %
937 <BR>#
938 <BR># where jamshell is the name of this shell file.
939 <BR>#
940 <BR># This version handles up to -j6; after that they get executed
941 <BR># locally.
942 <BR>
948 <BR>esac
949 </CODE></TD></TR></TABLE></P>
958 Targets marked as being temporary (but nonetheless present) have been found.
960 Targets are out-of-date and will be updated.
962 Source files can't be found and there are no actions to create them.
964 Due to sources not being found, other targets cannot be made.
966 A target depends on itself either directly or through its sources.
968 A target is not present and no actions have been defined to create it.
970 A source failed to build, and thus a target cannot be built.
972 A target that is not a dependency of any other target is being referenced with $(<) or $(>).
975 </DL></TD></TR></TABLE></P>
980 proceed as if the targets were built even though they are still
981 under construction.</P>
983 <P>For parallel building to be successful, the dependencies among
984 files must be properly spelled out, as targets tend to get built
985 in a quickest-first ordering. Also, beware of un-parallelizable
986 commands that drop fixed-named files into the current directory,
989 <P>With the -j flag, errors from failed commands can get staggeringly
990 mixed up.</P>
995 <P><UL>
998 </UL></P>
1000 <P>Jam documentation and source are available from the
1004 <P>Jam's author is Christopher Seiwald (<a href="mailto:seiwald@perforce.com">seiwald@perforce.com</A>).<BR/>
1005 Documentation is provided by <A HREF="http://www.perforce.com">Perforce Software, Inc.</A><BR/>
1007 See <a href="http://www.freetype.org/jam/">http://www.freetype.org/jam/</a> for more details.<BR/>
1008 "K8Jam" is a derivative of FT-Jam.
1010 Note that K8Jam is not 100% compatible with Perforce Jam or FT-Jam.
1011 </P>
1012 </DL>
1014 <P><HR>
1016 Changes and additions by Ketmar // Vampire Avalon
1017 </P>
1018 </BODY>
1019 </HTML>