From 893567e01c129e2af677c39200ea59af43a3020a Mon Sep 17 00:00:00 2001 From: Rene Rivera Date: Sun, 12 Feb 2006 17:24:46 +0000 Subject: [PATCH] Build of distribution archives. Remove now outdated Jam docs. [SVN r32860] --- historic/jam/build_dist.bat | 15 + historic/jam/build_dist.sh | 13 + historic/jam/doc/bjam.qbk | 2 +- historic/jam/doc/build.jam | 12 +- historic/jam/index.html | 15 + historic/jam/src/Jam.html | 1356 ------------------------------ historic/jam/src/Jambase.html | 931 --------------------- historic/jam/src/Jamfile.html | 1450 --------------------------------- historic/jam/src/Porting | 68 -- historic/jam/src/README | 150 ---- historic/jam/src/RELNOTES | 941 --------------------- historic/jam/src/build.jam | 26 +- historic/jam/src/index.html | 1263 ---------------------------- 13 files changed, 66 insertions(+), 6176 deletions(-) create mode 100644 historic/jam/build_dist.bat create mode 100644 historic/jam/build_dist.sh create mode 100644 historic/jam/index.html delete mode 100644 historic/jam/src/Jam.html delete mode 100644 historic/jam/src/Jambase.html delete mode 100644 historic/jam/src/Jamfile.html delete mode 100644 historic/jam/src/Porting delete mode 100644 historic/jam/src/README delete mode 100644 historic/jam/src/RELNOTES delete mode 100644 historic/jam/src/index.html diff --git a/historic/jam/build_dist.bat b/historic/jam/build_dist.bat new file mode 100644 index 000000000..d0bd6ceed --- /dev/null +++ b/historic/jam/build_dist.bat @@ -0,0 +1,15 @@ +@ECHO OFF + +REM ~ Copyright 2006 Rene Rivera. +REM ~ Distributed under the Boost Software License, Version 1.0. +REM ~ (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt) + +setlocal + +cd doc +del /F /S /Q html +bjam --v2 +del /F /S /Q ..\src\images ..\src\jam ..\src\*.html ..\src\*.png ..\src\*.css ..\src\LICENSE*.txt +xcopy /S /I /Y html ..\src +cd ..\src +call .\build.bat --- dist diff --git a/historic/jam/build_dist.sh b/historic/jam/build_dist.sh new file mode 100644 index 000000000..76517ad58 --- /dev/null +++ b/historic/jam/build_dist.sh @@ -0,0 +1,13 @@ +#!/bin/sh + +#~ Copyright 2002-2005 Rene Rivera. +#~ Distributed under the Boost Software License, Version 1.0. +#~ (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt) + +cd doc +rm -Rf html +bjam --v2 +rm -Rf ../src/images ../src/jam ../src/*.html ../src/*.png ../src/*.css ../src/LICENSE*.txt +cp -R html/* ../src +cd ../src +. ./build.sh --- dist diff --git a/historic/jam/doc/bjam.qbk b/historic/jam/doc/bjam.qbk index 48017dc3a..8e91a28b4 100644 --- a/historic/jam/doc/bjam.qbk +++ b/historic/jam/doc/bjam.qbk @@ -2,7 +2,7 @@ [quickbook 1.3] [version 3.1.12] [authors [Rivera, Rene], [Abrahams, David], [Prus, Vladimir]] - [copyright 2003 2004 2005 Rene Rivera, David Abrahams, Vladimir Prus] + [copyright 2003 2004 2005 2006 Rene Rivera, David Abrahams, Vladimir Prus] [category tool-build] [id jam] [dirname jam] diff --git a/historic/jam/doc/build.jam b/historic/jam/doc/build.jam index f9abbd9d1..1ff574490 100644 --- a/historic/jam/doc/build.jam +++ b/historic/jam/doc/build.jam @@ -9,14 +9,14 @@ xml bjam bjam.qbk ; -stage html-$(BOOST_VERSION) +stage html : ../../../LICENSE_1_0.txt ../../../boost.png ../../../doc/html/boostbook.css ; -stage html-$(BOOST_VERSION)/images +stage html/images : [ path.glob ../../../doc/html/images : *.png ] ; @@ -26,13 +26,13 @@ boostbook standalone bjam : html - html-$(BOOST_VERSION) - html-$(BOOST_VERSION) - html-$(BOOST_VERSION)/images + html + html + html/images boost.root=. nav.layout=none ; -# Copyright Rene Rivera 2005. Use, modification, and distribution are +# Copyright Rene Rivera 2005-2006. Use, modification, and distribution are # subject to the Boost Software License, Version 1.0. (See accompanying # file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) diff --git a/historic/jam/index.html b/historic/jam/index.html new file mode 100644 index 000000000..a0a0d89d0 --- /dev/null +++ b/historic/jam/index.html @@ -0,0 +1,15 @@ + + + + + + + + + + + Automatic redirection failed, please go to ../../doc/html/jam.html + + diff --git a/historic/jam/src/Jam.html b/historic/jam/src/Jam.html deleted file mode 100644 index d06af934a..000000000 --- a/historic/jam/src/Jam.html +++ /dev/null @@ -1,1356 +0,0 @@ - - - Jam/MR - Make(1) Redux - - - -
- -

Jam/MR - Make(1) Redux

- -

The Jam/MR Executable - -

- -
- -

USAGE

- -
-jam [ -a ] [ -n ] [ -v ] [ -q ]
-    [ -d debug ] 
-    [ -f jambase ] 
-    [ -j jobs ] 
-    [ -o actionsfile ] 
-    [ -s var=value ] 
-    [ -t target ] 
-    [ target ... ]
-
- -

DESCRIPTION

- -

- - Jam is a program construction tool, like make(1). - -

- - Jam recursively builds target files from source files, - using dependency information and updating actions expressed in - the Jambase file, which is written in jam's own interpreted - language. The default Jambase is compiled into jam and - provides a boilerplate for common use, relying on a user-provide - file "Jamfile" to enumerate actual targets and sources. - -

- - The Jambase is described in the Jambase - Reference and the document Using - Jamfiles and Jambase. - -

OPTIONS

- -

- - If target is provided on the command line, jam - builds target; otherwise jam builds the target - 'all'. - -

- - Jam may be invoked with the following options: - -

- -
-a - Build all targets anyway, even if they are up-to-date. - -
-d n - Enable cummulative debugging levels from 1 to n. - Interesting values are: - -
-
1
Show actions (the default) -
2
Show "quiet" actions and display all action text -
3
Show dependency analysis, and target/source - timestamps/paths -
4
Show shell arguments -
5
Show rule invocations and variable expansions -
6
Show directory/header file/archive scans -
7
Show variable settings -
8
Show variable fetches -
9
Show variable manipulation, scanner tokens -
- -
-d +n - Enable debugging level n. - -
-d 0 - Turn off all debugging levels. Only errors are not suppressed. - -
-f jambase - Read jambase instead of using the built-in Jambase. - Only one -f flag is permitted, but the jambase may - explicitly include other files. - -
-j n - Run up to n shell commands concurrently (UNIX - and NT only). The default is 1. - -
-n - Don't actually execute the updating actions, but do - everything else. This changes the debug level default to -d2. - -
-o file - Write the updating actions to the specified file instead - of running them (or outputting them, as on the Mac). - -
-q - Quit quickly (as if an interrupt was received) - as soon as any target fails. - -
-s var=value - Set the variable var to value, overriding - both internal variables and variables imported from the - environment. - -
-t target - Rebuild target and everything that depends on it, - even if it is up-to-date. - -
-v - Print the version of jam and exit. - -
- -

OPERATION

- -

- - Jam has four phases of operation: start-up, parsing, - binding, and updating. - -

Start-up

- -

- - Upon start-up, jam imports environment variable settings - into jam variables. Environment variables are split at - blanks with each word becoming an element in the variable's list - of values. Environment variables whose names end in PATH are - split at $(SPLITPATH) characters (e.g., ":" for Unix). - -

- - To set a variable's value on the command line, overriding the - variable's environment value, use the -s option. To see variable - assignments made during jam's execution, use the -d+7 - option. - -

Parsing

- -

- - In the parsing phase, jam reads and parses the Jambase - file, by default the built-in one. It is written in the jam - language. See Language below. The - last action of the Jambase is to read (via the "include" rule) - a user-provided file called "Jamfile". - -

- - Collectively, the purpose of the Jambase and the Jamfile is to - name built target and source files, construct the dependency - graph among them, and associate build actions with targets. - The Jambase defines boilerplate rules and variable assignments, - and the Jamfile uses these to specify the actual relationship - among the target and source files. See the Jambase Reference and the document Using Jamfiles and Jambase for information. - - -

Binding

- - -

- -

Binding
- - After parsing, jam recursively descends the dependency - graph and binds every file target with a location in the - filesystem. If jam detects a circular dependency in the - graph, it issues a warning. - -

- - File target names are given as absolute or relative path names - in the filesystem. If the path name is absolute, it is bound - as is. If the path name is relative, it is normally bound as - is, and thus relative to the current directory. This can be - modified by the settings of the $(SEARCH) and $(LOCATE) variables, - which enable jam to find and build targets spread across - a directory tree. See SEARCH and LOCATE - Variables below. - -

Update Determination
- - After binding each target, jam determines whether the - target needs updating, and if so marks the target for the updating - phase. A target is normally so marked if it is missing, it is - older than any of its sources, or any of its sources are marked - for updating. This behavior can be modified by the application - of special built-in rules, ALWAYS, LEAVES, NOCARE, NOTFILE, - NOUPDATE, and TEMPORARY. See Modifying - Binding below. - -

Header File Scanning
- -

- - During the binding phase, jam also performs header file - scanning, where it looks inside source files for the implicit - dependencies on other files caused by C's #include syntax. This - is controlled by the special variables $(HDRSCAN) and $(HDRRULE). - The result of the scan is formed into a rule invocation, with - the scanned file as the target and the found included file names - as the sources. Note that this is the only case where rules - are invoked outside the parsing phase. See HDRSCAN and HDRRULE Variables below. - -

Updating

- -

- - After binding, jam again recursively descends the dependency - graph, this time executing the update actions for each target - marked for update during the binding phase. If a target's - updating actions fail, then all other targets which depend on - that target are skipped. - -

- - The -j flag instructs jam to build more than one target - at a time. If there are multiple actions on a single target, - they are run sequentially. - - -

LANGUAGE

- - -

Overview

- - Jam has an interpreted, procedural language. Statements - in jam are rule (procedure) definitions, rule invocations, - flow-of-control structures, variable assignments, and sundry - language support. - -

Lexical Features

- -

- - Jam treats its input files as whitespace-separated tokens, - with two exceptions: double quotes (") can enclose whitespace - to embed it into a token, and everything between the matching - curly braces ({}) in the definition of a rule action is treated - as a single string. A backslash (\) can escape a double quote, - or any single whitespace character. - -

- - Jam requires whitespace (blanks, tabs, or newlines) to - surround all tokens, including the colon (:) and semicolon - (;) tokens. - -

- - Jam keywords (an mentioned in this document) are reserved - and generally must be quoted with double quotes (") to be used - as arbitrary tokens, such as variable or target names. - -

Targets

- -

- - The essential jam data entity is a target. Built targets - are files to be updated. Source targets are the files used in - updating built targets. Built targets and source targets are - collectively referred to as file targets, and frequently built - targets are source targets for other built targets. Pseudotargets - are symbols which represent dependencies on other targets, but - which are not themselves associated with any real file. - -

- - A file target's identifier is generally the file's name, which - can be absolutely rooted, relative to the directory of jam's - invocation, or simply local (no directory). Most often it is - the last case, and the actual file path is bound using the - $(SEARCH) and $(LOCATE) special variables. See - SEARCH and LOCATE Variables below. A local filename is - optionally qualified with grist, a string value used to assure - uniqueness. A file target with an identifier of the form - file(member) is a library member (usually an ar(1) archive - on UNIX). - -

Rules

- -

- - The basic jam language entity is called a rule. A rule - is defined in two parts: the procedure and the actions. The - procedure is a body of jam statements to be run when the - rule is invoked; the actions are the OS shell commands to execute - when updating the built targets of the rule. - -

- - Rules can return values, which can be expanded into a list with - "[ rule args ... ]". A rule's value is the value - of its last statement, though only the following statements - have values: 'if' (value of the leg chosen), 'switch' (value of the case - chosen), set (value of the resulting variable), and 'return' (value - of its arguments). Note that 'return' doesn't actually cause a - return, i.e., is a no-op unless it is the last statement - of the last block executed within rule body. - -

- - The jam statements for defining and invoking rules are - as follows: - -

- -

- rule rulename { statements } - - -
Define a rule's procedure, replacing any previous - definition. - -

- actions [ modifiers ] rulename { commands } - - -
Define a rule's updating actions, replacing any - previous definition. - -

- rulename field1 : field2 : ... - : fieldN ; - - -
Invoke a rule. - -

- on target rulename field1 : field2 : ... - : fieldN ; - - -
Invoke a rule under the influence of target's specific - variables.. - -

- [ rulename field1 : field2 : ... - : fieldN ]
- [ on target rulename field1 : field2 : ... - : fieldN ]
- - - -
Used as an argument, expands to the return value of the rule invoked. - -
- -

- - A rule is invoked with values in field1 through - fieldN. They may be referenced in the procedure's - statements as $(1) through $(N) (9 max), and the - first two only may be referenced in the action's commands - as $(1) and $(2). $(<) and $(>) are synonymous with $(1) - and $(2). - -

- - Rules fall into two categories: updating rules (with actions), - and pure procedure rules (without actions). Updating rules - treat arguments $(1) and $(2) as built targets and sources, - respectively, while pure procedure rules can take arbitrary - arguments. - -

- - When an updating rule is invoked, its updating actions are added - to those associated with its built targets ($(1)) before the - rule's procedure is run. Later, to build the targets in the - updating phase, commands are passed to the OS command - shell, with $(1) and $(2) replaced by bound versions of the - target names. See Binding above. - -

- - Rule invokation may be indirected through a variable: - -

- -

- $(var) field1 : field2 : ... - : fieldN ; - - -

- on target $(var) field1 : field2 : ... - : fieldN ; - - -

- [ $(var) field1 : field2 : ... - - : fieldN ]
- [ on target $(var) field1 : field2 : ... - : fieldN ]
- - - -
- - The variable's value names the rule (or rules) to be invoked. - A rule is invoked for each element in the list of - $(var)'s values. The fields - field1 : field2 : ... are passed as - arguments for each invokation. For the [ ... ] forms, - the return value is the concatenation of the return values for - all of the invokations. - - -

Action Modifiers

- - -

- - The following action modifiers are understood: - -

- -

actions bind vars -
$(vars) will be replaced with bound values. - -

actions existing -
$(>) includes only source targets currently existing. - -

actions ignore -
The return status of the commands is ignored. - -

actions piecemeal -
commands are repeatedly invoked with a subset - of $(>) small enough to fit in the command buffer on this - OS. - -

actions quietly -
The action is not echoed to the standard output. - -

actions together -
The $(>) from multiple invocations of the same action - on the same built target are glommed together. - -

actions updated -
$(>) includes only source targets themselves marked - for updating. - -
- - -

Built-in Rules

- -

- Jam has eleven built-in rules, all of which are pure - procedure rules without updating actions. They are in - three groups: the first builds the dependency graph; - the second modifies it; and the third are just utility - rules. - -

- -

Dependency Building
- -

- -

- DEPENDS targets1 : targets2 ; - - -
Builds a direct dependency: makes each of targets1 - depend on each of targets2. Generally, targets1 - will be rebuilt if targets2 are themselves rebuilt are - or are newer than targets1. - -

- INCLUDES targets1 : targets2 ; - - -
Builds a sibling dependency: makes any target that depends - on any of targets1 also depend on each of targets2. - This reflects the dependencies that arise when one source file - includes another: the object built from the source file depends - both on the original and included source file, but the two - sources files don't depend on each other. For example: - - -

DEPENDS foo.o : foo.c ; -
INCLUDES foo.c : foo.h ; - - -

- - "foo.o" depends on "foo.c" and "foo.h" in this example. - -

- - -

Modifying Binding
- - -

- - The six rules ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, and - TEMPORARY modify the dependency graph so that jam treats - the targets differently during its target binding phase. See - Binding above. Normally, jam - updates a target if it is missing, if its filesystem modification - time is older than any of its dependencies (recursively), or if - any of its dependencies are being updated. This basic behavior - can be changed by invoking the following rules: - -

- -

- ALWAYS targets ; - - -
Causes targets to be rebuilt regardless of whether - they are up-to-date (they must still be in the dependency graph). - This is used for the clean and uninstall targets, as they have - no dependencies and would otherwise appear never to need building. - It is best applied to targets that are also NOTFILE targets, - but it can also be used to force a real file to be updated as - well. - -

- LEAVES targets ; - - -
Makes each of targets depend only on its leaf sources, - and not on any intermediate targets. This makes it immune to - its dependencies being updated, as the "leaf" dependencies are - those without their own dependencies and without updating actions. - This allows a target to be updated only if original source files - change. - -

- NOCARE targets ; - - -
Causes jam to ignore targets that neither - can be found nor have updating actions to build them. Normally - for such targets jam issues a warning and then skips - other targets that depend on these missing targets. The HdrRule - in Jambase uses NOCARE on the header file names found during - header file scanning, to let jam know that the included - files may not exist. For example, if a #include is within an - #ifdef, the included file may not actually be around. - -

- NOTFILE targets ; - - -
Marks targets as pseudotargets and not real files. - No timestamp is checked, and so the actions on such a target - are only executed if the target's dependencies are updated, or - if the target is also marked with ALWAYS. The default jam - target "all" is a pseudotarget. In Jambase, NOTFILE is used to - define several addition convenient pseudotargets. - -

- NOUPDATE targets ; - - -
Causes the timestamps on targets to be ignored. - This has two effects: first, once the target has been created - it will never be updated; second, manually updating target will - not cause other targets to be updated. In Jambase, for example, - this rule is applied to directories by the MkDir rule, because - MkDir only cares that the target directory exists, not when it - has last been updated. - -

- TEMPORARY targets ; - - -
Marks targets as temporary, allowing them to be - removed after other targets that depend upon them have been - updated. If a TEMPORARY target is missing, jam uses the - timestamp of the target's parent. Jambase uses TEMPORARY to - mark object files that are archived in a library after they are - built, so that they can be deleted after they are archived. - -
- -

Utility Rules
- -

- - The two rules ECHO and EXIT are utility rules, used only in - jam's parsing phase. - -

- -

- ECHO args ; - - -
Blurts out the message args to stdout. - -

- EXIT args ; - - -
Blurts out the message args to stdout and then exits - with a failure status. - -

- - "Echo", "echo", "Exit", and "exit" are accepted as aliases for ECHO - and EXIT, since it is hard to tell that these are built-in - rules and not part of the language, like "include". - -

- -

- - The GLOB rule does filename globbing. - -

- -

- GLOB directories : patterns : downcase-opt - - -
Using the same wildcards as for the patterns in the switch statement). It is invoked by being - used as an argument to a rule invocation inside of `[ ]`. For - example: "FILES = [ GLOB dir1 dir2 : *.c *.h ]" sets - A to the list of C source and header files in dir1 or dir2. - The resulting filenames are the full pathnames, including the - directory, but the pattern is applied only to the file name - without the directory. - -

If downcase-opt is supplied, filenames are converted to - all-lowercase before matching against the pattern; you can use - this to do case-insensitive matching using lowercase patterns. - The paths returned will still have mixed case if the OS supplies - them. On Windows NT and Cygwin, filenames are always downcased - before matching. - -

- -

- - The MATCH rule does pattern matching. - -

- -

- MATCH regexps : list - - -
Matches the egrep(1) style regular expressions - regexps against the strings in list. The result - is the concatenation of matching () subexpressions for - each string in list, and for each regular expression in - regexps. Only useful within the [ ] construct, - to change the result into a list. - -
- -

Flow-of-Control

- -

- - Jam has several simple flow-of-control statements: - -

- -

- - for var in list { statements } - - - -

Executes statements for each element in - list, setting the variable var to the element - value. - - -

- - - if cond { statements } -
[ else statements ] - - - -

Does the obvious; the else clause is optional. - cond is built of: - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
a true if any a element is a non-zero-length - string
a = b list a matches list b - string-for-string
a != b list a does not match list b
a < b a[i] string is less than b[i] - string, where i is first mismatched element - in lists a and b
a <= b every a string is less than or equal to - its b counterpart
a > b a[i] string is greater than b[i] - string, where i is first mismatched element
a >= b every a string is greater than or equal to - its b counterpart
a in b true if all elements of a can be found - in b, or if a has no elements
! cond condition not true
cond && cond conjunction
cond || cond disjunction
( cond ) precedence grouping
- -

- - include file ; - - - -

Causes jam to read the named file. - The file is bound like a regular target (see Binding above) but unlike a regular - target the include file cannot be built. - -

- - The include file is inserted into the input stream during - the parsing phase. The primary input file and all the included - file(s) are treated as a single file; that is, jam - infers no scope boundaries from included files. - -

- - local vars [ = values ] ; - - - -

Creates new vars inside to the enclosing {} - block, obscuring any previous values they might have. The - previous values for vars are restored when the current - block ends. Any rule called or file included will see the - local and not the previous value (this is sometimes called - Dynamic Scoping). The local statement may appear anywhere, - even outside of a block (in which case the previous value - is restored when the input ends). The vars are - initialized to values if present, or left uninitialized - otherwise. - -

- - return values ; - - - -

Within a rule body, the return statement sets the return - value for an invocation of the rule. It does not cause the - rule to return; a rule's value is actually the value of the - last statement executed, so a return should be the - last statement executed before the rule "naturally" returns. - -

- - - switch value - -
{ -
case pattern1 : statements ; -
case pattern2 : statements ; -
... -
} - - - -

The switch statement executes zero or one of the - enclosed statements, depending on which, if any, is - the first case whose pattern matches value. - The pattern values are not variable-expanded. The - pattern values may include the following wildcards: - - - - - - - - - - - - - - -
? match any single character
* match zero or more characters
[chars] match any single character in chars
[^chars] match any single character not in chars
\x match x (escapes the other wildcards)
- -

- - while cond { statements } - - - -

Repeatedly execute statements while cond - remains true upon entry. (See the description of cond - expression syntax under if, above). -
- -

Variables

- -

- - Jam variables are lists of zero or more elements, with - each element being a string value. An undefined variable is - indistinguishable from a variable with an empty list, however, - a defined variable may have one more elements which are null - strings. All variables are referenced as $(variable). - -

- - Variables are either global or target-specific. In the latter - case, the variable takes on the given value only during the - updating of the specific target. - -

- - A variable is defined with: - -

- -
- variable = elements ; -
- variable += elements ; -
- variable on targets = elements ; -
- variable on targets += elements ; -
- variable default = elements ; -
- variable ?= elements ; - -
- -

- - The first two forms set variable globally. The third - and forth forms set a target-specific variable. The = operator - replaces any previous elements of variable with - elements; the += operation adds elements to - variable's list of elements. The final two forms are - synonymous: they set variable globally, but only if it - was previously unset. - -

- - Variables referenced in updating commands will be replaced with - their values; target-specific values take precedence over global - values. Variables passed as arguments ($(1) and $(2)) to actions - are replaced with their bound values; the "bind" modifier can - be used on actions to cause other variables to be replaced with - bound values. See Action Modifiers - above. - -

- - Jam variables are not re-exported to the environment of - the shell that executes the updating actions, but the updating - actions can reference jam variables with $(variable). - -

Variable Expansion

- -

- - During parsing, jam performs variable expansion on each - token that is not a keyword or rule name. Such tokens with - embedded variable references are replaced with zero or more - tokens. Variable references are of the form $(v) or - $(vm), where v is the variable name, and m - are optional modifiers. - -

- - Variable expansion in a rule's actions is similar to variable - expansion in statements, except that the action string is - tokenized at whitespace regardless of quoting. - -

- - The result of a token after variable expansion is the - product of the components of the token, where each - component is a literal substring or a list substituting a variable - reference. For example: - -

- -
$(X) -> a b c -
t$(X) -> ta tb tc -
$(X)z -> az bz cz -
$(X)-$(X) -> a-a a-b a-c b-a b-b b-c c-a c-b c-c - -
- -

- - The variable name and modifiers can themselves contain - a variable reference, and this partakes of the product - as well: - -

- -
$(X) -> a b c -
$(Y) -> 1 2 -
$(Z) -> X Y -
$($(Z)) -> a b c 1 2 - -
- -

- - Because of this product expansion, if any variable reference in - a token is undefined, the result of the expansion is an empty - list. If any variable element is a null string, the result - propagates the non-null elements: - -

- -
$(X) -> a "" -
$(Y) -> "" 1 -
$(Z) -> -
*$(X)$(Y)* -> *a* *a1* ** *1* -
*$(X)$(Z)* -> - -
- -

- - A variable element's string value can be parsed into grist and - filename-related components. Modifiers to a variable are used - to select elements, select components, and replace components. - The modifiers are: - -

- -
[n] - Select element number n (starting at 1). If - the variable contains fewer than n elements, - the result is a zero-element list. - -
[n-m] - Select elements number n through m. - -
[n-] - Select elements number n through the last. - -
:B - Select filename base. - -
:S - Select (last) filename suffix. - -
:M - Select archive member name. - -
:D - Select directory path. - -
:P - Select parent directory. - -
:G - Select grist. - -
:U - Replace lowercase characters with uppercase. - -
:L - Replace uppercase characters with lowercase. - -
:chars - Select the components listed in chars. - -
:G=grist - Replace grist with grist. - -
:D=path - Replace directory with path. - -
:B=base - Replace the base part of file name with base. - -
:S=suf - Replace the suffix of file name with suf. - -
:M=mem - Replace the archive member name with mem. - -
:R=root - Prepend root to the whole file name, if not - already rooted. - -
:E=value - Assign value to the variable if it is unset. - -
:J=joinval - Concatentate list elements into single - element, separated by joinval. - -
- -

- - On VMS, $(var:P) is the parent directory of $(var:D). - -

Built-in Variables

- -

- - This section discusses variables that have special meaning to - jam. - - -

SEARCH and LOCATE Variables

- - -

- - These two variables control the binding of file target names to - locations in the file system. Generally, $(SEARCH) is used to - find existing sources while $(LOCATE) is used to fix the location - for built targets. - -

- - Rooted (absolute path) file targets are bound as is. Unrooted - file target names are also normally bound as is, and thus relative - to the current directory, but the settings of $(LOCATE) and - $(SEARCH) alter this: - -

- -

    - -
  • If $(LOCATE) is set then the target is bound relative to - the first directory in $(LOCATE). Only the first element is - used for binding. - -
  • If $(SEARCH) is set then the target is bound to the first - directory in $(SEARCH) where the target file already exists. - -
  • If the $(SEARCH) search fails, the target is bound relative - to the current directory anyhow. - -
- -

- - Both $(SEARCH) and $(LOCATE) should be set target-specific and - not globally. If they were set globally, jam would use - the same paths for all file binding, which is not likely to - produce sane results. When writing your own rules, especially - ones not built upon those in Jambase, you may need to set - $(SEARCH) or $(LOCATE) directly. Almost all of the rules defined - in Jambase set $(SEARCH) and $(LOCATE) to sensible values for - sources they are looking for and targets they create, respectively. - - -

HDRSCAN and HDRRULE Variables

- - -

- - These two variable control header file scanning. $(HDRSCAN) is - an egrep(1) pattern, with ()'s surrounding the file name, - used to find file inclusion statements in source files. Jambase - uses $(HDRPATTERN) as the pattern for $(HDRSCAN). $(HDRRULE) - is the name of a rule to invoke with the results of the scan: - the scanned file is the target, the found files are the sources. - This is the only place where jam invokes a rule through - a variable setting. - -

- - Both $(HDRSCAN) and $(HDRRULE) must be set for header file - scanning to take place, and they should be set target-specific - and not globally. If they were set globally, all files, including - executables and libraries, would be scanned for header file - include statements. - -

- - The scanning for header file inclusions is not exact, but it is - at least dynamic, so there is no need to run something like - makedepend(GNU) to create a static dependency file. The - scanning mechanism errs on the side of inclusion (i.e., it is - more likely to return filenames that are not actually used by - the compiler than to miss include files) because it can't tell - if #include lines are inside #ifdefs or other conditional logic. - In Jambase, HdrRule applies the NOCARE rule to each header file - found during scanning so that if the file isn't present yet - doesn't cause the compilation to fail, jam won't care. - -

- - Also, scanning for regular expressions only works where the - included file name is literally in the source file. It can't - handle languages that allow including files using variable names - (as the Jam language itself does). - -

Platform Identifier Variables

- -

- - A number of Jam built-in variables can be used to identify - runtime platform: - -

- - - -
OSOS identifier string -
OSPLATUnderlying architecture, when applicable -
MACtrue on MAC platform -
NTtrue on NT platform -
OS2true on OS2 platform -
UNIXtrue on Unix platforms -
VMStrue on VMS platform - -
- -

Jam Version Variables

- -

- - - -
JAMDATETime and date at jam start-up. -
JAMUNAMEOuput of uname(1) command (Unix only) -
JAMVERSIONjam version, currently "2.3" - -
- -

JAMSHELL Variable

- -

- - When jam executes a rule's action block, it forks and - execs a shell, passing the action block as an argument to the - shell. The invocation of the shell can be controlled by - $(JAMSHELL). The default on Unix is, for example: - -

- - JAMSHELL = /bin/sh -c % ; - -

- - The % is replaced with the text of the action block. - -

- - Jam does not directly support building in parallel across - multiple hosts, since that is heavily dependent on the local - environment. To build in parallel across multiple hosts, you - need to write your own shell that provides access to the multiple - hosts. You then reset $(JAMSHELL) to reference it. - -

- - Just as jam expands a % to be the text of the rule's - action block, it expands a ! to be the multi-process slot number. - The slot number varies between 1 and the number of concurrent - jobs permitted by the -j flag given on the command line. Armed - with this, it is possible to write a multiple host shell. For - example: - -

- -
- -
#!/bin/sh -
-
# This sample JAMSHELL uses the SunOS on(1) command to execute a -
# command string with an identical environment on another host. -
-
# Set JAMSHELL = jamshell ! % -
# -
# where jamshell is the name of this shell file. -
# -
# This version handles up to -j6; after that they get executed -
# locally. -
-
case $1 in -
1|4) on winken sh -c "$2";; -
2|5) on blinken sh -c "$2";; -
3|6) on nod sh -c "$2";; -
*) eval "$2";; -
esac - -
- - -

DIAGNOSTICS

- -

- - In addition to generic error messages, jam may emit one of - the following: - -

- -

warning: unknown rule X
- - A rule was invoked that has not been defined with - an "actions" or "rule" statement. - -

using N temp target(s)
- - Targets marked as being temporary (but nonetheless - present) have been found. - -

updating N target(s)
- - Targets are out-of-date and will be updated. - -

can't find N target(s)
- - Source files can't be found and there are no - actions to create them. - -

can't make N target(s)
- - Due to sources not being found, other targets cannot be made. - -

warning: X depends on itself
- - A target depends on itself either directly or - through its sources. - -

don't know how to make X
- - A target is not present and no actions have been - defined to create it. - -

X skipped for lack of Y
- - A source failed to build, and thus a target cannot - be built. - -

warning: using independent target X
- - A target that is not a dependency of any other - target is being referenced with $(<) or $(>). - -

X removed
- - Jam removed a partially built target after being - interrupted. - -
- -

BUGS, LIMITATIONS

- -

- - The -j flag can cause jam to get confused when single - actions update more than one target at a time. jam may - proceed as if the targets were built even though they are still - under construction. - -

- - For parallel building to be successful, the dependencies among - files must be properly spelled out, as targets tend to get built - in a quickest-first ordering. Also, beware of un-parallelizable - commands that drop fixed-named files into the current directory, - like yacc(1) does. - -

- - With the -j flag, errors from failed commands can get staggeringly - mixed up. - -

- - A poorly set $(JAMSHELL) is likely to result in silent failure. - -

SEE ALSO

- -

- -

- -

- - Jam documentation and source are available from the Perforce - Public Depot. - -

AUTHOR

- -

- Jam's author is Christopher Seiwald (seiwald@perforce.com). - Documentation is provided by - Perforce Software, Inc. - -

- -

- -

- - Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc. -
- Comments to info@perforce.com -
- Last updated: April 1, 2002 -
- $Id$ - - - - diff --git a/historic/jam/src/Jambase.html b/historic/jam/src/Jambase.html deleted file mode 100644 index 1037ac38e..000000000 --- a/historic/jam/src/Jambase.html +++ /dev/null @@ -1,931 +0,0 @@ - - -Jambase Reference - - -

- -Jam/MR - -

- -Jambase Reference - -

-
-

- Jambase is a base set of Jam/MR rules which - provide roughly make(1)-like functionality for - jam, the Jam/MR executable program. - This document, which started out as the Jambase(5) man page, - is a reference guide to the - rules, - pseudotargets, - and variables - defined in Jambase for use in Jamfiles. -

- For further information see: -

-

-Jam/MR documentation and source are available from the -Perforce Public Depot. -For detailed information about any of the rules summarized below, -see the -Jambase -file itself. -

-

- -Jambase Rules - -

-

- As obj.o : source.s ; -

- Assemble the file source.s. Called by the Object - rule. -
- Bulk directory : sources ; -
- Copies sources into directory. -
- Cc object : source ; -
- Compile the file source into object, using the C - compiler $(CC), its flags $(CCFLAGS) and $(OPTIM), - and the header file directories $(HDRS). Called by - the Object rule. -
- C++ obj.o : source.cc ; -
- Compile the C++ source file source.cc. Called by - the Object rule. -
- Chmod target ; -
- (Unix and VMS only.) - Change file permissions on target to - target-specific $(MODE) value set by Link, File, - Install*, and Shell rules. -
- - Clean clean : targets ; -
- Removes existing targets when clean is built. - clean is not a dependency of all, and must be built - explicitly for targets to be removed. -
- FDefines defines ;
- Expands a list of definitions into a list of compiler - (or preprocessor) switches (such as - -Dsymbol=val on Unix) - to pass the definitions. -
- File target : source ; -
- Copies source into target. -
- FIncludes dirs ;
- Expands a list of directories into a list of compiler - (or preprocessor) switches (such as -Idir on Unix) - to add the directories to the header inclusion search path. -
- Fortran obj.o : source.f ; -
- Compile the Fortran source file source.f. Called - by the Object rule. -
- FQuote files ;
- Returns each of files suitably quoted so as to hide shell - metacharacters (such as whitespace and filename matching wildcards) - from the shell. -
-

- GenFile target : image sources ; -

- Runs the command "image target sources" - to create target from sources and - image. (where image is an - executable built by the Main rule.) -
- HardLink target : source ; -
- Makes target a hard link to source, if it isn't one - already. (Unix only.) -
- HdrRule source : headers ; -
- Arranges the proper dependencies when the file - source includes the files headers through the - "#include" C preprocessor directive. -

- This rule is not intended to be called explicitly. - It is called automatically during header scanning on - sources handled by the Object rule (e.g., sources in - Main or Library rules). -

- InstallBin dir : sources ;
- Copy sources into dir with mode - $(EXEMODE). -
- InstallLib dir : sources ;
- Copy sources into dir with mode - $(FILEMODE). -
- InstallMan dir : sources ;
- Copy sources into the appropriate subdirectory - of dir with mode $(FILEMODE). The subdirectory - is mans, where s is the suffix of - each of sources. -
- InstallShell dir : sources ;
- Copy sources into dir with mode - $(SHELLMODE). -
- Lex source.c : source.l ;
- Process the lex(1) source file source.l and - rename the lex.yy.c to source.c. Called by - the Object rule. -
- Library library : sources ;
- Compiles sources and archives them into - library. The intermediate objects - are deleted. Calls Objects and LibraryFromObjects. -

- If Library is invoked with no suffix on library, - the $(SUFLIB) suffix is used. -

- LibraryFromObjects library : objects ; -
- Archives objects into library. The - objects are then deleted. -

- If library has no suffix, the $(SUFLIB) suffix is used. -

- Link image : objects ; -
- Links image from objects and sets - permissions on image to $(EXEMODE). - Image must be actual filename; suffix is not - supplied. - Called by Main. - -
- LinkLibraries image : libraries ; -
- Makes image depend on libraries and - includes them during the linking. -

- Image may be referenced without a suffix in this - rule invocation; LinkLibraries supplies the suffix. -

- Main image : sources ; -
- Compiles sources and links them into image. - Calls Objects and MainFromObjects. -

- Image may be referenced without a suffix in this - rule invocation; Main supplies the suffix. -

- MainFromObjects image : objects ; -
- Links objects into image. Dependency - of exe. MainFromObjects supplies the suffix on image - filename. -
- MakeLocate target : dir ; -
- Creates dir and causes target to be built - into dir. -
- MkDir dir ; -
- Creates dir and its parent directories. -
- Object object : source ; -
- Compiles a single source file source into - object. The Main and Library rules use - this rule to compile source files. -

- Causes source to be scanned for "#include" - directives and calls HdrRule to make all included - files dependedencies of object. -

- Calls one of the following rules to do the actual - compiling, depending on the suffix of source: -

-		     *.c:   Cc 
-		     *.cc:  C++ 
-		     *.cpp: C++
-		     *.C:   C++ 
-		     *.l:   Lex 
-		     *.y:   Yacc
-		     *.*:   UserObject
-
-
- ObjectC++Flags source : flags ; -
- ObjectCcFlags source : flags ; -
- Add flags to the source-specific - value of $(CCFLAGS) or $(C++FLAGS) when compiling source. - Any file suffix on source is ignored. -
- ObjectDefines object : defines ;
- Adds preprocessor symbol definitions to the (gristed) - target-specific $(CCDEFS) for the object. -
- ObjectHdrs source : dirs ;
- Add dirs to the source-specific value of - $(HDRS) when scanning and compiling source. - Any file suffix on source is ignored. -
- Objects sources ;
- For each source file in sources, calls - Object to compile the source file into a similarly - named object file. -
- RmTemps targets : sources ;
- Marks sources as temporary with the TEMPORARY - rule, and deletes sources once targets - are built. Must be the last rule invoked on - targets. Used internally by LibraryFromObjects rule. -
- Setuid images ;
- Sets the setuid bit on each of images after - linking. (Unix only.) - -
- SoftLink target : source ; -
- Makes target a symbolic link to source, if it isn't one - already. (Unix only.) -
- SubDir VAR d1 ... dn ; -
- Sets up housekeeping for the source files located - in $(VAR)/d1/.../dn: -
    -
  • Reads in rules file associated with VAR, - if it hasn't already been read. -
  • Initializes variables for search paths, - output directories, compiler - flags, and grist, using d1 ... dn tokens. -
-

- VAR is the name of a variable; - d1 thru dn are elements - of a directory path. -

- SubDirC++Flags flags ; -
- SubDirCcFlags flags ; -
- Adds flags to the compiler flags for source files - in SubDir's directory. -
- SubDirHdrs d1 ... dn ; -
- Adds the path d1/.../dn/ to the header search paths for - source files in SubDir's directory. d1 through dn - are elements of a directory path. -
- SubInclude VAR d1 ... dn ; -
- Reads the Jamfile in $(VAR)/d1/.../dn/. -
- Shell image : source ;
- Copies source into the executable sh(1) - script image. Ensures that the first line of - the script is $(SHELLHEADER) (default #!/bin/sh). -
- Undefines images : symbols ;
- Adds flags to mark symbols as undefined - on link command for images. - Images may be referenced unsuffixed; the - Undefines rule supplies the suffix. -
- UserObject object : source ;
- This rule is called by Object for source - files with unknown suffixes, and should be defined - in Jamrules - with a user-provided rule to handle the source file - types not handled by the Object rule. - The Jambase UserObject rule merely issues a - complaint when it encounters source with - files suffixes it does not recognize. -
- Yacc source.c : source.y ;
- Process the yacc(1) file source.y and renamed - the resulting y.tab.c and y.tab.h to source.c. - Produces a y.tab.h and renames it to source.h. - Called by the Object rule. -
-

-

- -

-Jambase Pseudotargets -

- -

-There are two kinds of Jam targets: file targets and pseudotargets. -File targets are objects that can be found in the filesystem. -Pseudotargets are symbolic, and usually represent other targets. -Most Jambase rules that define file targets also define pseudotargets -which are dependent on types of file targets. The Jambase pseudotargets -are: -

- -
exe - Executables linked by the Main or MainFromObjects rules - -
lib - Libraries created by the Library or LibraryFromObjects rules - -
obj - Compiled objects used to create Main or Library targets - -
dirs - Directories where target files are written - -
file - Files copied by File and Bulk rules - -
shell - Files copied by Shell rule - -
clean - Removal of built targets (except files copied by Install* rules) - -
install - Files copied by Install* rules - -
uninstall - Removal of targets copied by Install* rules - -
-
-

-In addition, Jambase makes the jam default target "all" -depend on "exe", "lib", "obj", "files", and "shell". -

- -

- -

-Jambase Variables -

- -

- Most of the following variables have default values for - each platform; refer to the Jambase file to see what those - defaults are. -

- ALL_LOCATE_TARGET -

- Alternative location of built targets. By default, - Jambase rules locate built targets in the source - tree. By setting $(ALL_LOCATE_TARGET) - in Jamrules, you can cause jam - to write built targets to a location outside - the source tree. -
- - AR - -
- The archive command used to update Library - and LibraryFromObjects targets. -
- AS -
- The assembler for As rule targets. -
- - ASFLAGS - -
- Flags handed to the assembler for As. -
- - AWK - -
- The name of awk interpreter, used when copying a - shell script for the Shell rule. -
- - BCCROOT -
- Selects Borland compile and link actions on NT. -
- - - BINDIR - -
- Not longer used. - (I.e., used only for backward compatibility with the - obsolete INSTALLBIN rule.) -
- - CC - -
- C compiler used for Cc rule targets. -
- - CCFLAGS - -
- Compile flags for Cc rule targets. - The Cc rule sets target-specific $(CCFLAGS) - values on its targets. -
- - C++ - -
- C++ compiler used for C++ rule targets. -
- - C++FLAGS - -
- Compile flags for C++ rule targets. - The C++ rule sets target-specific $(C++FLAGS) - values on its targets. -
- - CHMOD - -
- Program (usually chmod(1)) used to set file - permissions for Chmod rule. -
- - CP - -
- The file copy program, used by File and Install* rules. -
- - CRELIB - -
- If set, causes the Library rule to invoke the CreLib - rule on the target library before attempting to archive - any members, so that the library can be created if - needed. -
- - CW - -
- On Macintosh, the root of the Code Warrior Pro 5 directory. -
- - DEFINES - -
- Preprocessor symbol definitions for Cc and C++ rule targets. - The Cc and C++ rules set target-specific $(CCDEFS) - values on their targets, based on $(DEFINES). (The - "indirection" here is required to support compilers, - like VMS, with baroque command line syntax for - setting symbols). -
- - DOT - -
- The operating system-specific name for the current directory. -
- - DOTDOT - -
- The operating system-specific name for the parent directory. -
- - EXEMODE - -
- Permissions for executables linked with Link, Main, - and MainFromObjects, on platforms with a Chmod action. -
- - FILEMODE - -
- Permissions for files copied by File or Bulk, - on platforms with a Chmod action. -
- - FORTRAN - -
- The Fortran compiler used by Fortran rule. -
- - FORTRANFLAGS - -
- Fortran compiler flags for Fortran rule targets. -
- - GROUP - -
- (Unix only.) - The group owner for Install* rule targets. -
- - HDRGRIST - -
- If set, used by the HdrRule to distinguish header files - with the same name in diffrent directories. -
- - HDRPATTERN - -
- A regular expression pattern that matches - C preprocessor "#include" directives in source files - and returns the name of the included file. -
- - HDRRULE - -
- Name of the rule to invoke with the results of header file - scanning. Default is "HdrRule". -

- This is a jam-special variable. If both HDRRULE and HDRSCAN - are set on a target, - that target will be scanned for lines - matching $(HDRSCAN), and $(HDDRULE) will be - invoked on included files found in the matching $(HDRSCAN) lines. -

- - HDRS - -
- Directories to be searched for header files. - This is used by the Object rule to: -
    -
  • set up search paths for finding files returned - by header scans -
  • add -I flags on compile commands -
- (See STDHDRS.) -
- - HDRSCAN - -
- Regular expression pattern to use for header file - scanning. The Object rule sets this to $(HDRPATTERN). - This is a jam-special variable; see HDRRULE. -
- - HDRSEARCH - -
- Used by the HdrRule to fix the list of directories where - header files can be found for a given source file. -
- - INSTALLGRIST - -
- Used by the Install* rules to grist paths to installed - files; defaults to "installed". -
- - JAMFILE - -
- Default is "Jamfile"; the name of the user-written - rules file found in each source directory. -
- - JAMRULES - -
- Default is "Jamrules"; the name of a rule definition - file to be read in at the first SubDir rule invocation. -
- - KEEPOBJS - -
- If set, tells the LibraryFromObjects rule not to delete - object files once they are archived. -
- - LEX - -
- The lex(1) command and flags. -
- - LIBDIR - -
- Not longer used. - (I.e., used only for backward compatibility with the - obsolete INSTALLLIB rule.) -
- - LINK - -
- The linker. Defaults to $(CC). -
- - LINKFLAGS - -
- Flags handed to the linker. Defaults to $(CCFLAGS). -
- - LINKLIBS - -
- List of external libraries to link with. The target image - does not depend on these libraries. -
- - LN - -
- The hard link command for HardLink rule. -
- - LOCATE_SOURCE -
- Used to set the location of generated source files. - The Yacc, Lex, and GenFile rules set LOCATE on - their targets to $(LOCATE_SOURCE). - $(LOCATE_SOURCE) is initialized by the SubDir rule - to the source directory itself. - (Also, see ALL_LOCATE_TARGET.) -
- - LOCATE_TARGET -
- Used to set the location of built binary targets. - The Object rule, and hence the Main and Library rules, - set LOCATE on their targets to $(LOCATE_TARGET). - $(LOCATE_TARGET) is initialized by the - SubDir rule to the source directory itself. - (See ALL_LOCATE_TARGET.) -
- - - MANDIR - -
- Not longer used. - (I.e., used only for backward compatibility with the - obsolete INSTALLMAN rule.) -
- - MKDIR - -
- The 'create directory' command used for the MkDir - rule. -
- - MODE - -
- The target-specific file mode (permissions) for targets - of the Shell, Setuid, Link, and Install* rules. - Used by the Chmod action; hence relevant to NT and VMS - only. -
- - MSVC -
- Selects Microsoft Visual C 16-bit compile & link - actions on NT. -
- - MSVCNT -
- Selects Microsoft Visual C NT compile & link - actions on NT. -
- - - MV - -
- The file rename command and options. -
- - NEEDLIBS - -
- The list of libraries used when linking an executable. - Used by the Link rule. -
- - NOARSCAN - -
- If set, indicates that library members' timestamps can't - be found, and prevents the individual objects from being - deleted, so that their timestamps can be used instead. -
- - NOARUPDATE - -
- If set, indicates that libraries can't be updated, but only - created whole. -
- - OPTIM - -
- The C compiler flag for optimization, used by Cc and C++ - rules. -
- - OSFULL - -
- The concatenation of $(OS)$(OSVER)$(OSPLAT), used when jam - builds itself to determine the target binary directory. - $(OS) and $(OSPLAT) are determined by jam at its compile - time (in jam.h). $(OSVER) can optionally be set by the user. - -
- - OWNER - -
- The owner of installed files. Used by Install* rules. -
- - RANLIB - -
- The name of the ranlib command. If set, causes - the Ranlib action to be applied after the - Archive action to targets of the Library rule. -
- - RELOCATE - -
- If set, tells the Cc rule to move the output object - file to its target directory because the cc command - has a broken -o option. -
- - RM - -
- The command and options to remove a file. -
- - SEARCH_SOURCE - -
- The directory to find sources listed with Main, - Library, Object, Bulk, File, Shell, InstallBin, - InstallLib, and InstallMan rules. This works by - setting the jam-special variable SEARCH to the - value of $(SEARCH_SOURCE) for each of the rules' - sources. The SubDir rule initializes SEARCH_SOURCE - for each directory. -
- - SHELLHEADER - -
- A string inserted to the first line of every file - created by the Shell rule. -
- - SHELLMODE - -
- Permissions for files installed by Shell rule. -
- - SOURCE_GRIST - -
- Set by the SubDir to a value derived from the - directory name, and used by Objects and related - rules as 'grist' to perturb file names. -
- - STDHDRS - -
- Directories where headers can be found without - resorting to using the flag to the C compiler. - The $(STDHDRS) directories are used to find - headers during scanning, but are not passed to the - compiler commands as -I paths. -
- - SUBDIR - -
- The path from the current directory to the directory - last named by the SubDir rule. -
- - TOP - -
- The path from the current directory to the directory - that has the Jamrules file. Used by the SubDir rule. -
- - SUFEXE - -
- The suffix for executable files, if none provided. - Used by the Main rule. -
- - SUFLIB - -
- The suffix for libraries. Used by the Library and - related rules. -
- - SUFOBJ - -
- The suffix for object files. Used by the Objects - and related rules. -
- - UNDEFFLAG - -
- The flag prefixed to each symbol for the Undefines - rule (i.e., the compiler flag for undefined symbols). -
- - WATCOM -
- Selects Watcom compile and link actions on OS2. -
- - YACC - -
- The yacc(1) command. -
- - YACCFILES - -
- The base filename generated by yacc(1). -
- - YACCFLAGS - -
- The yacc(1) command flags. -
- - YACCGEN - -
- The suffix used on generated yacc(1) output. -
- -

-

-Back to top. -

- Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc. -
- Comments to info@perforce.com -
- Last updated: Dec 31, 2000 -
- $Id$ - - diff --git a/historic/jam/src/Jamfile.html b/historic/jam/src/Jamfile.html deleted file mode 100644 index 2f94ddf9d..000000000 --- a/historic/jam/src/Jamfile.html +++ /dev/null @@ -1,1450 +0,0 @@ - - -Jamfiles and Jambase - - -

- -Jam/MR - - -

-Using Jamfiles and Jambase -

- -
-

-This document describes how to write Jamfiles using the Jam/MR Jambase -rules to build software products. -Related documents of interest are: -

-

-Jam/MR documentation and source are available from the -Perforce Public Depot. -

-

-

-Overview -

-

- jam, the Jam executable program, - recursively builds target files from source files - using dependency and build specifications defined - in Jam rules files. - jam parses the rules files to identify targets - and sources, - examines the filesystem to determine which - targets need updating, and issues OS commands to update - targets. -

- A base rules file called "Jambase" is provided with the - Jam distribution. - The Jambase file defines rules and variables which support - standard software build operations, like compiling, linking, - etc. -

- When the Jambase rules are used, - jam reads Jambase, then reads a file called - "Jamfile" in the current directory. - The Jamfile describes what to do with the source files in - its directory. It may also cause - Jamfiles in other directories to be read. -

- Under certain circumstances, the first Jamfile read - also causes a site-specific "Jamrules" file to be read. - The Jamrules file is an optional set of rule and variable - definitions used to define site-specific processing. -

-

-The Basic Jamfile -

-

-Jamfiles contain rule invocations, which usually look like: -

-	RuleName targets : targets ;
-
-The target(s) to the left of the colon usually indicate -what gets built, and the target(s) to the right of the -colon usually indicate what it is built from. -

-

-A Jamfile can be as simple as this: -

-	Main myprog : main.c util.c ;
-
-This specifies that there is a main.c and util.c file in the same -directory as the Jamfile, and that those source files should be -compiled and linked into an executable called myprog. -If you cd to the directory where this Jamfile lives, -you can see the exactly how jam would -build myprog with: -
-	jam -n
-
-Or, you can actually build myprog with the command: -
-	jam
-
- -

-

-Whitespace -

-Jamfile elements are delimited by whitespace (blanks, tabs, or -newlines). Elements to be delimited include rule names, targets, -colons, and semicolons. A common mistake users make is to forget the -whitespace, e.g., -
-	Main myprog: main.c util.c ; #WRONG!
-
-Jam doesn't distinguish between a typo and a target called "myprog:", -so if you get strange results, the first thing -you should check for in your Jamfile is missing whitespace. -

-

-Filenames, Target Identifiers, and Buildable Targets -

-

-Consider this Jamfile: -

-	Main myprog : main.c util.c ;                   
-	LinkLibraries myprog : libtree ;     
-	Library libtree : treemake.c treetrav.c ;    
-
-

-The Main rule specifies that an executable called myprog will be built. -The compiled main.c and util.c objects will be linked to produce -myprog. -The LinkLibraries rule specifies that libtree will -be linked into myprog as well. -The Library rule specifies which source files will be compiled and -archived into the libtree library. -

-The Jamfile above refers to targets like "myprog" and "libtree". -However, depending on the platform you're building on, the actual -filenames of those targets could be "myprog.exe" and "libtree.lib". -Most Jambase rules supply the actual filenames of targets, -so that Jamfiles themselves need not make any -platform-specific filename references. -

-The jam program builds up a list of unique target identifiers. -Unless you are using the SubDir rules (described later), -the default identifier for a file target is its filename. In the above -example, the target identifiers are the filenames: myprog.exe, -libtree.lib, main.obj, etc. -

-While all Jambase rules refer to "targets", -not all targets are buildable. -There are two kinds of buildable targets: -file targets and pseudotargets. -File targets are objects that can be found in the filesystem. -Pseudotargets are symbolic, and represent other targets. -

-You can use any buildable target on the jam command line to -build a subset of defined targets. For example: -

-        jam libtree.a 
-
-on Unix builds the libtree library and all the compiled objects -that go in it. -

-

-Pseudotargets -

-

-Most Jambase rules that define file targets also define pseudotargets -which are dependent on types of file targets. -For example, Jambase defines a pseudotarget called "lib", which -is dependent on file targets created by the Library rule. So -the command: -

-        jam lib
-
-used with the above example would cause the libtree library to be built. -Also, there is one pseudotarget built into jam itself, called -"all". Jambase sets "all" dependent on (almost) all other targets. -

-In the unfortunate case where you have a buildable target whose name -is the same as one of the Jambase pseudotargets, you'll have problems -with the conflicting target name. -Your workaround choices are: -

-

    -
  1. Change the name of your buildable file or directory that conflicts. -

    -

  2. Modify your Jambase and change the name of the conflicting pseudotarget. -(Pseudotargets are defined in Jambase using the NOTFILE rule.) -

    -

  3. Use grist on the conflicting target name in your Jamfile. E.g., instead - of - 
    -    File lib : libfoo.a ;
-
    - try - 
    -    File <dir>lib : libfoo.a ;
-
    -
-

- -

-Dependencies -

-

-Jambase rules set dependencies on targets, so that if you update a -source file, all the file targets that depend on that source -file, and only the ones that depend on that source file, -will be updated (rebuilt) the next time you run jam. -

-Here are some of the dependencies -that get set when jam runs on NT using the example Jamfile above: -

- - -
Target   Depends on
myprog.exemain.obj, util.obj, libtree.lib -
libtree.libtreemake.obj, treetrav.obj -
treetrav.objtreetrav.c -
-
-

-Furthermore, the Main and Library rules set up recursive -header scanning on their source targets. -So after jam has finished parsing the Jamfile and -setting the rule-driven dependencies, it scans the source -files for "#include" lines. All #include files found during -this scan become dependencies of the compiled object. -E.g., all header files used to compile treetrav.c would -be made dependencies of treetrav.obj. -

-As a result, when you run jam, it will rebuild targets -if either the source files change or the -header files change. You can't tell by looking at a Jamfile -which header files are dependencies, but you can easily -display those dependencies with: -

-	jam -nd+3
-
-

-Rule Ordering -

-

-Rules which specify dependencies, like the Main, Library, and -LinkLibrary rules, can be invoked in any order. jam -figures out the order in which targets are built from -their dependencies. -

-Some rules, however, set variables which are used by subsequent -rule invocations, and their ordering is important. -For example, the SubDir* rules (discussed -later) must be invoked in a particular order. - -

-

-Detailed Jambase Specifications -

-

-This document describes how to use various Jambase rules -from a functional point of view. -You can see the summary of available Jambase rules in the -Jambase Reference. -The detailed specifications for any Jambase rule -can be found by reading the rule definition itself -in the Jambase file. -

- -

-

-Handling Directory Trees -

- The SubDir* rules are used to - define source code directory hierarchies. - With SubDir and SubInclude, you can use jam - to build software from source files and Jamfiles spread - across many directories, as is typical for large projects. - The SubDir* rules unify an entire - source code tree so that jam can read in - all the Jamfiles in one pass and - compute dependencies across the entire project. -

- To use the SubDir* rules, you must: -

-

    -
  1. Preface the Jamfile in each directory with an invocation - of the SubDir rule. -

    -

  2. Place at the root of the tree a file named Jamrules. - This file could be empty, but in - practice it contains user-provided rules and variable - definitions that are shared throughout the - tree. Examples of such definitions are library - names, header directories, install directories, - compiler flags, etc. This file is good candidate - for automatic customizing with autoconf(GNU). -

    -

  3. Optionally, set an environment variable pointing - to the root directory of the srouce tree. The - variable's name is left up to you, but in these - examples, we use TOP. -
-

-

- SubDir Rule -

-

- The SubDir rule must be invoked before any rules that - refer to the contents of the directory - it is best to put - it at the top of each Jamfile. For example: -

-	# Jamfile in $(TOP)/src/util directory.
-
-	SubDir TOP src util ;
-
-	Main myprog : main.c util.c ;                   
-	LinkLibraries myprog : libtree ;     
-	Library libtree : treemake.c treetrav.c ;    
-
- This compiles four files in $(TOP)/src/util, archives - two of the objects into libtree, and links the whole - thing into myprog. - Outputs are placed in the $(TOP)/src/util - directory. -

- This doesn't appear to be any different from - the previous example that didn't have a SubDir rule, - but two things are happening behind the scenes: -

    -
  1. The SubDir rule causes jam to read - in the $(TOP)/Jamrules file. - (The Jamrules file can alternately be named by the - variable $(xxxRULES), where xxx is the name of the - root variable, e.g., $(TOPRULES)). -

    - The Jamrules file can contain variable definitions - and rule definitions specific to your codeline. - It allows you to completely customize your build - environment without having to rewrite Jambase. - Jamrules is only read - in once, at the first SubDir invocation. -

    -

  2. - The SubDir rule initializes a set of variables - that are used by Main and other rules to - uniquely identify the source files in this - directory and assign locations to the targets - built from files in this directory. -

    - When you have set a root variable, e.g., $(TOP), - SubDir constructs path names rooted with $(TOP), - e.g., $(TOP)/src/util. - Otherwise, SubDir constructs relative pathnames - to the root directory, computed from the number - of arguments to the first SubDir rule, e.g., - ../../src/util. In either case, the SubDir - rule constructs the path names that locate source - files. - You'll see how this is useful later. -

    - - -

    - The SubDir rule takes as its first argument the root - variable's name and takes as subsequent arguments the - directory names leading from the root to the directory of - the current Jamfile. Note that the name of the subdirectory - is given as individual elements: the SubDir rule - does not use system-specific directory name syntax. -

    -

    -

    - SubInclude Rule -

    - The SubInclude rule is used in a Jamfile to cause another - Jamfile to be read in. - Its arguments are in the same format as - SubDir's. -

    - The recommended practice is only to include one level of - subdirectories at a time, and let the Jamfile in each subdirectory - include its own subdirectories. This allows a - user to sit in any arbitrary directory of the source tree - and build that subtree. For example: -

    -       # This is $(TOP)/Jamfile, top level Jamfile for mondo project.
-
-       SubInclude TOP src ;
-       SubInclude TOP man ;
-       SubInclude TOP misc ;
-       SubInclude TOP util ;
-
    - If a directory has both subdirectories of its own as well - as files that need building, the SubIncludes should be - either before the SubDir rule or be at the end of the Jamfile - - not between the SubDir and other rule invocations. - For example: -
    -	# This is $(TOP)/src/Jamfile:
-
-	SubDir TOP src ;
-
-	Main mondo : mondo.c ;
-	LinkLibraries mondo : libmisc libutil ;
-	
-	SubInclude TOP src misc ;
-	SubInclude TOP src util ;
-
    -

    - (jam processes all the Jamfiles it reads as if - it were reading one single, large Jamfile. - Build rules like Main and LinkLibraries rely on the - preceding SubDir rule to set up source file and - output file locations, and SubIncludes rules read in - Jamfiles that contain SubDir rules. So if you put - a SubIncludes rule between a SubDir and a Main - rule, jam will try to find the source files - for the Main rule in the wrong directory.) -

    -

    - Variables Used to Handle Directory Trees -

    - The following variables are set by the SubDir rule - and used by the Jambase rules that define file targets: -

    -

    - -
    - SEARCH_SOURCE - The SubDir targets (e.g., "TOP src util") - are used to construct a pathname (e.g., $(TOP)/src/util), - and that pathname is assigned to $(SEARCH_SOURCE). - Rules like Main and Library use $(SEARCH_SOURCE) - to set search paths on source files. -
    - LOCATE_SOURCE - Initialized by the SubDir rule to the same - value as $(SEARCH_SOURCE), unless ALL_LOCATE_TARGET - is set. - $(LOCATE_SOURCE) is used by rules that build - generated source files (e.g., Yacc and Lex) to - set location of output files. - Thus the default location of built source files - is the directory of the Jamfile that defines them. -
    - LOCATE_TARGET - Initalized by the SubDir rule to the same - value as $(SEARCH_SOURCE), unless ALL_LOCATE_TARGET - is set. - $(LOCATE_TARGET) is used by rules that build - binary objects (e.g., Main and Library) to - set location of output files. - Thus the default location of built binaray files - is the directory of the Jamfile that defines them. -
    - ALL_LOCATE_TARGET - - If $(ALL_LOCATE_TARGET) is set, LOCATE_SOURCE - and and LOCATE_TARGET are set to $(ALL_LOCATE_TARGET) - instead of to $(SEARCH_SOURCE). This can be used to - direct built files to be written to a location outside - of the source tree, and enables building from read-only - source trees. -
    - SOURCE_GRIST - The SubDir targets are formed into a string - like "src!util" and that string is assigned to - SOURCE_GRIST. Rules that define file targets - use $(SOURCE_GRIST) to set the "grist" attribute - on targets. This is used to assure uniqueness - of target identifiers where filenames themselves - are not unique. - For example, the target identifiers of - $(TOP)/src/client/main.c and $(TOP)/src/server/main.c - would be <src!client>main.c and <src!server>main.c. -
    -
    -

    - The $(LOCATE_TARGET) and $(SEARCH_SOURCE) variables are used - extensively by rules in Jambase: most rules that generate - targets (like Main, Object, etc.) set $(LOCATE) to - $(LOCATE_TARGET) for the targets they generate, and rules - that use sources (most all of them) set $(SEARCH) to be - $(SEARCH_SOURCE) for the sources they use. -

    - $(LOCATE) and $(SEARCH) are better explained in - The Jam Executable Program - but in brief they tell jam where to create new targets and - where to find existing ones, respectively. -

    - Note that you can reset these variables - after SubDir sets them. For example, this Jamfile builds - a program called gensrc, then runs it to create a source file - called new.c: - 

    -       SubDir TOP src util ;
-       Main gensrc : gensrc.c ;
-       LOCATE_SOURCE = $(NEWSRC) ;
-       GenFile new.c : gensrc ;
-
    - By default, new.c would be written into the - $(TOP)/src/util directory, but resetting LOCATE_SOURCE causes - it to be written to the $(NEWSRC) directory. ($(NEWSRC) is assumed - to have been set elsewhere, e.g., in Jamrules.) -

    -

    - VMS Notes -

    - On VMS, the logical name table is not imported as is the - environment on UNIX. To use the SubDir and related rules, - you must set the value of the variable that names the root - directory. For example: -
    -              TOP = USR_DISK:[JONES.SRC] ;
-
-              SubInclude TOP util ;
-
    - The variable must have a value that looks like a directory - or device. If you choose, you can use a concealed logical. - For example: -
    -              TOP = TOP: ;
-
-              SubInclude TOP util ;
-
    - The : at the end of TOP makes the value of $(TOP) look - like a device name, which jam respects as a directory name - and will use when trying to access files. TOP must then - be defined from DCL: -
    -              $ define/job/translation=concealed TOP DK100:[USERS.JONES.SRC.]
-
    - Note three things: the concealed translation allows the - logical to be used as a device name; the device name in - the logical (here DK100) cannot itself be concealed logical - (VMS rules, man); and the directory component of the - definition must end in a period (more VMS rules). -

    -

    -Building Executables and Libraries -

    -

    -The rules that build executables and libraries are: Main, Library, -and LinkLibraries. -

    - Main Rule -

    - The Main rule compiles source files and links the resulting - objects into an executable. For example: -
    -              Main myprog : main.c util.c ;
-
    - This compiles main.c and util.c and links main.o and - util.o into myprog. The object files and resulting - executable are named appropriately for the platform. -

    - Main can also be used to build shared libraries and/or - dynamic link libraries, since those are also linked - objects. E.g.: - 

    -		Main driver$(SUFSHR) : driver.c ;
-
    - Normally, Main uses $(SUFEXE) to determine the suffix on - the filename of the built target. To override it, - you can supply a suffix explicity. - In this case, - $(SUFSHR) is assumed to be the OS-specific shared library - suffix, defined in Jamrules with something - like: - 
    -		if $(UNIX)      { SUFSHR = .so ; }
-		else if $(NT)   { SUFSHR = .dll ; }
-
    -

    - Main uses the Objects rule to compile source targets. - -

    - Library Rule -

    - The Library rule compiles source files, archives the - resulting object files into a library, and then deletes - the object files. For example: -
    -              Library libstring : strcmp.c strcpy.c strlen.c ;
-              Library libtree : treemake.c treetrav.c ;
-
    - This compiles five source files, archives three of the - object files into libstring and the other two into libtree. - Actual library filenames are formed with the $(SUFLIB) suffix. - Once the objects are safely in the libraries, the - objects are deleted. -

    - Library uses the Objects rule to compile source files. -

    -

    - LinkLibraries Rule -

    - To link executables with built libraries, use - the LinkLibraries rule. For example: -
    -              Main myprog : main.c util.c ;
-              LinkLibraries myprog : libstring libtree ;
-
    - The LinkLibraries rule does two things: it makes the - libraries dependencies of the executable, so that they get - built first; and it makes the libraries show up on the - command line that links the executable. The ordering of - the lines above is not important, because jam builds targets - in the order that they are needed. -

    - You can put multiple libraries on a single invocation of - the LinkLibraries rule, or you can provide them in multiple - invocations. In both cases, the libraries appear on - the link command line in the order in which they were - encountered. You can also provide multiple executables to - the LinkLibraries rule, if they need the same libraries, - e.g.: - 

    -		LinkLibraries prog1 prog2 prog3 : libstring libtree ;
-
    -

    -

    - Variables Used in Building Executables and Libraries -

    -
    - -
    - AR - Archive command, used for Library targets. -
    - SUFEXE - *Suffix on filenames of executables referenced - by Main and LinkLibraries. -
    - LINK - Link command, used for Main targets. -
    - LINKFLAGS - Linker flags. -
    - LINKLIBS - Link libraries that aren't dependencies. (See note - below.) -
    - EXEMODE - *File permissions on Main targets. -
    - MODE - Target-specific file permissions on Main targets - (set from $(EXEMODE)) -
    - RANLIB - Name of ranlib program, if any. -
    -
    - -

    - Variables above marked with "*" are used by the Main, - Library, and LinkLibraries rules. Their values at the - time the rules are invoked are used to set target-specific - variables. -

    - All other variables listed above are globally defined, - and are used in actions that update Main and Library - targets. This means that the global values of those - variables are used, uness target-specific values have - been set. - (For instance, a target-specific MODE value is set by - the Main rule.) - The target-specific values always override - global values. -

    - Note that there are two ways to specify link libraries for - executables: -

      -
    • Use the LinkLibraries rule - to specify built libraries; i.e., libraries - that are built by Library rules. This assures that - these libraries are built first, and that Main targets are - rebuilt when the libraries are updated. -

      -

    • Use the LINKLIBS variable to specify external - libraries; e.g., system libraries or third-party libraries. - The LINKLIBS variable must be set to the the actual - link command flag that specifies the libraries. -

      -

    -

    - For example: -

    -	#In Jamrules:
-              if $(UNIX) { X11LINKLIBS = -lXext -lX11 ; }
-              if $(NT)   { X11LINKLIBS = libext.lib libX11.lib ; }
-
-	#In Jamfile:
-              Main xprog : xprog.c ;
-              LINKLIBS on xprog$(SUFEXE) = $(X11LINKLIBS) ;
-              LinkLibraries xprog : libxutil ;
-              Library libxutil : xtop.c xbottom.c xutil.c ;
-
    - This example uses the Jam syntax "variable on target" to - set a target-specific variable. In this way, only xprog - will be linked with this special $(X11LINKLIBS), - even if other executables were going to be built - by the same Jamfile. Note that when you set a variable - on a target, you have to specify the target identifer - exactly, which in this case is the suffixed filename of - the executable. - The actual link command line on Unix, for example, would - look something like this: -
    -              cc -o xprog xprog.o libxutil.a -lXext -lX11
-
    -

    -Compiling -

    - Compiling of source files occurs normally as a byproduct - of the Main or Library rules, which call the rules - described here. These rules may also be called explicitly - if the Main and Library behavior doesn't satisfy your - requirements. -

    -

    - Objects Rule -

    - The Main and Library rules call the Objects rule on source files. - Compiled object files built by - the Objects rule are a dependency of the obj - pseudotarget, so "jam obj" will build object files used in - Main and Library rules. -

    - Target identifiers created by the Objects rule have grist - set to $(SOURCE_GRIST). So given this Jamfile: - 

    -		SubDir TOP src lock ;
-		Main locker : lock.c ;
-
    - the object file created is lock.o (or lock.obj) and - its target identifier is <src!lock>lock.o - (or <src!lock>lock.obj). - -

    - You can also call Objects directly. For example: -

    -              Objects a.c b.c c.c ;
-
    - This compiles a.c into a.o, b.c into b.o, etc. The object - file suffix is supplied by the Objects rule. -

    -

    - Object Rule -

    - Objects gets its work done by calling the Object rule on - each of the source files. - You could use the Object rule directly. - For example, on Unix, you could use: -
    -              Object foo.o : foo.c ;
-
    - However, the Object rule does not provide suffixes, and - it does not provide the grist needed to construct target - identifiers if you are using the SubDir* rules. - A portable and robust Jamfile would need to invoke Object thus: - 
    -	      Object <src!util>foo$(SUFOBJ) : <src!util>foo.c ;
-
    - which is inelegant and clearly shows why using Objects - is better than using Object. -

    - If there's any advantage to the Object rule, it's - that it doesn't require that the object name bear - any relationship to the source. It is thus possible to - compile the same file into different objects. For example: - -

    -              Object a.o : foo.c ;
-              Object b.o : foo.c ;
-              Object c.o : foo.c ;
-
    - This compiles foo.c (three times) into a.o, b.o, and c.o. - Later examples show how this is useful. -

    - The Object rule looks at the suffix of the source file and - calls the appropriate rules to do the actual preprocessing - (if any) and compiling needed to produce the output object file. - The Object rule is - capable of the generating of an object file from any - type of source. For example: -

    -              Object grammar$(SUFOBJ) : grammar.y ;
-              Object scanner$(SUFOBJ) : scanner.l ;
-              Object fastf$(SUFOBJ) : fastf.f ;
-              Object util$(SUFOBJ) : util.c ;
-
    - An even more elegant way to get the same result is to let the - Objects rule call Object: - 
    -              Objects grammar.y scanner.l fastf.f util.c ;
-
    -

    - In addition to calling the compile rules, Object sets up - a bunch of variables specific to the source and target - files. (See Variables Used in Compiling, below.) -

    -

    - Cc, C++, Yacc, Lex, Fortran, As, etc. Rules -

    -

    - The Object rule calls compile rules specific to the suffix of - the source file. (You can see which suffixes are supported - by looking at the Object rule definition in Jambase.) - Because the extra work done by the - Object rule, it is not always useful to call the compile - rules directly. But the adventurous user might attempt - it. For example: -

    -              Yacc grammar.c : grammar.y ;
-              Lex scan.c : scan.l ;
-              Cc prog.o : prog.c ;
-
    - These examples individually run yacc(1), lex(1), and the C - compiler on their sources. -

    -

    - UserObject Rule -

    - Any files with suffixes not understood by the Object rule - are passed to the UserObject rule. The default definition - of UserObject simply emits a warning that the suffix is - not understood. This Jambase rule definition is intended to be - overridden in Jamrules with one that recognizes the project-specific - source file suffixes. For example: - -
    -	#In Jamrules:
-
-              rule UserObject
-              {
-                  switch $(>)
-                  {
-                  case *.rc   : ResourceCompiler $(<) : $(>) ;
-                  case *      : ECHO "unknown suffix on" $(>) ;
-                  }
-              }
-
-              rule ResourceCompiler
-              {
-                  DEPENDS $(<) : $(>) ;
-		  Clean clean : $(<) ;
-              }
-
-              actions ResourceCompiler
-              {
-                  rc /fo $(<) $(RCFLAGS) $(>)
-              }
-
-
-	#In Jamfile:
-
-              Library liblock : lockmgr.c ;
-	      if $(NT) { Library liblock : lock.rc ; }
-
    -

    - In this example, the UserObject definition in Jamrules - allows *.rc files to be handle as regular Main and Library - sources. The lock.rc file is compiled into lock.obj - by the "rc" command, and lock.obj is archived into a library - with other compiled objects. -

    - LibraryFromObjects Rule -

    - Sometimes the Library rule's straightforward compiling of - source into object modules to be archived isn't flexible - enough. The LibraryFromObjects rule does the archiving - (and deleting) job of the Library rule, but not the compiling. - The user can make use of the Objects or Object - rule for that. For example: -
    -              LibraryFromObjects libfoo.a : max.o min.o ;
-              Object max.o : maxmin.c ;
-              Object min.o : maxmin.c ;
-              ObjectCcFlags max.o : -DUSEMAX ;
-              ObjectCcFlags min.o : -DUSEMIN ;
-
    - This Unix-specific example compiles the same source file into - two different - objects, with different compile flags, and archives them. - (The ObjectCcFlags rule is described shortly.) - Unfortunately, the portable and robust implementation of the - above example is not as pleasant to read: - 
    -	      SubDir TOP foo bar ;
-              LibraryFromObjects libfoo$(SUFLIB) : <foo!bar>max$(SUFOBJ) 
-			                           <foo!bar>min$(SUFOBJ) ;
-              Object <foo!bar>min$(SUFOBJ) : <foo!bar>maxmin.c ;
-              Object <foo!bar>max$(SUFOBJ) : <foo!bar>maxmin.c ;
-	      ObjectCcFlags <foo!bar>min$(SUFOBJ) : -DUSEMIN ;
-	      ObjectCcFlags <foo!bar>max$(SUFOBJ) : -DUSEMAX ;
-
    - Note that, among other things, you must supply the library - file suffix when using the LibraryFromObjects rule. -

    -

    - MainFromObjects Rule -

    - Similar to LibraryFromObjects, MainFromObjects does the - linking part of the Main rule, but not the compiling. - MainFromObjects can be used when there are no - objects at all, and everything is to be loaded from - libraries. For example: -
    -              MainFromObjects testprog ;
-              LinkLibraries testprog : libprog ;
-              Library libprog : main.c util.c ;
-
    - On Unix, say, this generates a link command that looks like: -
    -              cc -o testprog libprog.a
-
    - Linking purely from libraries is something that doesn't - work everywhere: it depends on the symbol "main" being - undefined when the linker encounters the library that contains - the definition of "main". -

    -

    - Variables Used in Compiling -

    - The following variables control the compiling of source - files: -

    -

    - -
    - C++ - The C++ compiler command -
    - CC - The C compiler command -
    - C++FLAGS -
    - CCFLAGS -     		Compile flags, used to - create or update compiled objects -
    - SUBDIRC++FLAGS -
    - SUBDIRCCFLAGS -     		Additonal compile flags - for source files in this directory. -
    - OPTIM - Compiler optimization flag. The Cc and C++ - actions use this as well as C++FLAGS or CCFLAGS. -
    - HDRS - Non-standard header directories; i.e., - the directories the compiler will not look in - by default and which therefore must be supplied - to the compile command. These directories are - also used by jam to scan for include files. -
    - STDHDRS - Standard header directories, i.e., the - directories the compiler searches automatically. - These are not passed to the compiler, but they - are used by jam to scan for include files. -
    - SUBDIRHDRS - Additional paths to add to HDRS for source files - in this directory. -
    - LEX - The lex(1) command -
    - YACC - The yacc(1) command -
    -
    -

    - The Cc rule sets a target-specific $(CCFLAGS) to the current - value of $(CCFLAGS) and $(SUBDIRCCFLAGS). Similarly - for the C++ rule. The Object rule sets a target-specific - $(HDRS) to the current value of $(HDRS) and $(SUBDDIRHDRS). - -

    - $(CC), $(C++), $(CCFLAGS), $(C++FLAGS), $(OPTIM), and - $(HDRS) all affect the compiling of C and C++ files. - $(OPTIM) is separate from $(CCFLAGS) and $(C++FLAGS) so - they can be set independently. -

    - $(HDRS) lists the directories to search for header files, - and it is used in two ways: first, it is passed to the C - compiler (with the flag -I prepended); second, it is used - by HdrRule to locate the header files whose names were - found when scanning source files. $(STDHDRS) lists the - header directories that the C compiler already knows - about. It does not need passing to the C compiler, but is - used by HdrRule. -

    - Note that these variables, if set as target-specific variables, - must be set on the target, not the source file. - The target file in this case is the object file to be generated. - For example: -

    -              Library libximage : xtiff.c xjpeg.c xgif.c ;
-
-              HDRS on xjpeg$(SUFOBJ) = /usr/local/src/jpeg ;
-              CCFLAGS on xtiff$(SUFOBJ) = -DHAVE_TIFF ;
-
    - This can be done more easily with the rules that follow. -

    -

    - ObjectCcFlags, ObjectC++Flags, ObjectHdrs Rules -

    - $(CCFLAGS), $(C++FLAGS) and $(HDRS) can be set on object file - targets - directly, but there are rules that allow these variables - to be set by referring to the original source file name, - rather than to the derived object file name. ObjectCcFlags - adds object-specific flags to the $(CCFLAGS) variable, - ObjectC++Flags adds object-specific flags to the - $(C++FLAGS) variable, and ObjectHdrs add object-specific - directories to the $(HDRS) variable. For example: -
    -	#In Jamrules:
-		if $(NT) { CCFLAGS_X = /DXVERSION ;	
-			   HDRS_X = \\\\SPARKY\\X11\\INCLUDE\\X11 ;
-		         }
-
-	#In Jamfile:
-              Main xviewer : viewer.c ;
-              ObjectCcFlags viewer.c : $(CCFLAGS_X) ;
-              ObjectHdrs viewer.c : $(HDRS_X) ;
-
    - The ObjectCcFlags and ObjectHdrs rules take .c files - as targets, but actually set $(CCFLAGS) and $(HDRS) values - on the .obj (or .o) files. As a result, the action - that updates the target .obj file uses the target-specific - values of $(CCFLAGS) and $(HDRS). -

    -

    - SubDirCcFlags, SubDirC++Flags, SubDirHdrs Rules -

    - These rules set the values of $(SUBDIRCCFLAGS), $(SUBDIRC++FLAGS) - and $(SUBDIRHDRS), which are used by the Cc, - C++, and Object rules when setting the target-specific - values for $(CCFLAGS), $(C++FLAGS) and $(HDRS). The SubDir - rule clears these variables out, and thus they provide - directory-specific values of $(CCFLAGS), $(C++FLAGS) and - $(HDRS). For example: -
    -	#In Jamrules:
-              GZHDRS = $(TOP)/src/gz/include ;
-	      GZFLAG = -DGZ ;
-		
-	#In Jamfile:
-              SubDir TOP src gz utils ;
-
-              SubDirHdrs $(GZHDRS) ;
-              SubDirCcFlags $(GZFLAG) ;
-
-	      Library libgz : gizmo.c ;
-	      Main gizmo : main.c ;
-	      LinkLibraries gizmo : libgz ;
-
    - All .c files in this directory files will be compiled with - $(GZFLAG) as well as the default $(CCFLAG), and the include - paths used on the compile command will be $(GZHDRS) as well - as the default $(HDRS). -

    -Header File Processing -

    - One of the functions of the Object rule is set up - scanning of source - files for (C style) header file inclusions. To do so, it - sets the special variables $(HDRSCAN) and $(HDRRULE) - as target-specific variables on the source file. The - presence of these variables triggers a special mechanism - in jam for scanning a file for header file inclusions and - invoking a rule with the results of the scan. The - $(HDRSCAN) variable is set to an egrep(1) pattern that - matches "#include" statements in C source files, and the - $(HDRRULE) variable is set to the name of the rule that - gets invoked as such: -
    -              $(HDRRULE) source-file : included-files ;
-
    - This rule is supposed to set up the dependencies between - the source file and the included files. The Object rule - uses HdrRule to do the job. HdrRule itself expects - another variable, $(HDRSEARCH), to be set to the list of - directories where the included files can be found. Object - does this as well, setting $(HDRSEARCH) to $(HDRS) and - $(STDHDRS). -

    - The header file scanning occurs during the "file binding" - phase of jam, which means that the target-specific - variables (for the source file) are in effect. To accomodate - nested includes, one of the HdrRule's jobs is to pass - the target-specific values of $(HDRRULE), $(HDRSCAN), and - $(HDRSEARCH) onto the included files, so that they will be - scanned as well. -

    -

    - HdrRule Rule -

    - Normally, HdrRule is not invoked directly; the Object rule - (called by Main and Library) invokes it. -

    - If there are special dependencies that need to be set, - and which are not set by HdrRule itself, you can define - another rule and let it invoke HdrRule. For example: - -

    -	#In Jamrules:
-              rule BuiltHeaders
-              {
-                      DEPENDS $(>) : mkhdr$(SUFEXE) ;
-                      HdrRule $(<) : $(>) ;
-              }
-
-	#In Jamfile:
-              Main mkhdr : mkhdr.c ;
-              Main ugly : ugly.c ;
-
-              HDRRULE on ugly.c = BuiltHeaders ;
-
-
    - This example just says that the files included by "ugly.c" - are generated by the program "mkhdr", which can be built - from "mkhdr.c". During the binding phase, jam will - scan ugly.c, and if it finds an include file, ughdr.h, - for example, it will automatically invoke the rule: - 
    -              BuiltHeaders ugly.c : ughdr.h ;
-
    - By calling HdrRule at the end of BuiltHeaders, - all the gadgetry of HdrRule takes effect and it - doesn't need to be duplicated. -

    -

    - Variables Used for Header Scanning -

    -
    - -
    - HDRPATTERN - Default scan pattern for "include" lines. -
    - HDRSCAN - Scan pattern to use. - This is a special variable: during binding, if - both HDRSCAN and HDRRULE are set, scanning is activated - on the target being bound. - The HdrRule and Object rules sets this - to $(HDRPATTERN) on their source targets. -
    - HDRRULE - Name of rule to invoked on files found in header - scan. The HdrRule and Object rules set this to "HdrRule" - on their source targets. This is also a special variable; - it's the only jam variable that can hold the - name of a rule to be invoked. -
    - HDRSEARCH - Search paths for files found during header scanning. - This is set from $(HDRS) and $(STDHDRS), which are - described in the Compiling section. - jam will search $(HDRSEARCH) directories for - the files found by header scans. -
    -
    -

    - The Object rule sets HDRRULE and HDRSCAN specifically for - the source files to be scanned, rather than globally. If - they were set globally, jam would attempt to scan all - files, even library archives and executables, for header - file inclusions. That would be slow and probably not - yield desirable results. -

    -

    -Copying Files -

    -

    - File Rule -

    - The File rule copies one file to another. The target name - needn't be the same as the source name. For - example: -
    -	switch $(OS)
-	{
-           case NT*  : File config.h : confignt.h ;
-	   case *    : File config.h : configunix.h ;
-	}
-	LOCATE on config.h = $(LOCATE_SOURCE) ;
-
    - This creates a config.h file from either confignt.h or - configunix.h, depending on the current build platform. -

    - The File rule does not - use the LOCATE_SOURCE variable set by the - SubDir rule (although it does use SEARCH_SOURCE), which - means you have to set the copied file's output directory - yourself. That's done by setting the special - LOCATE variable on the target, as shown above, - or with the MakeLocate rule described below. -

    - Bulk Rule -

    - The Bulk rule is a shorthand for many invocations of the - File rule when all files are going to the same directory. - For example: -
    -	#In Jamrules:
-              DISTRIB_GROB = d:\\distrib\\grob ;
-
-	#In Jamfile:
-              Bulk $(DISTRIB_GROB) : grobvals.txt grobvars.txt ;
-
    - This causes gobvals.txt and grobvars.txt to be copied - into the $(DISTRIB_GROB) directory. -

    - HardLink Rule -

    - The Unix-only HardLink rule makes a hard link (using ln(1)) from the - source to the target, if there isn't one already. For - example: -
    -              HardLink config.h : configunix.h ;
-
    -

    - Shell Rule -

    - The Shell rule is like the File rule, except that on Unix it makes - sure the first line of the target is "#!/bin/sh" and sets - the permission to make the file executable. For example: -
    -              Shell /usr/local/bin/add : add.sh ;
-
    -

    - You can also use $(SHELLHEADER) to dictate - what the first line of the copied file will be. - For - example: -

    -              Shell /usr/local/bin/add : add.awk ;
-              SHELLHEADER on /usr/local/bin/add = "#!/bin/awk -f" ;
-
    - This installs an awk(1) script. -

    -

    - Variables Used When Copying Files -

    -
    - -
    - FILEMODE - Default file permissions for copied files -
    - SHELLMODE - Default file permissions for Shell rule targets -
    - MODE - File permissions set on files copied by - File, Bulk, and Shell rules. - File and Shell sets a target-specific MODE to the current - value of $(FILEMODE) or $(SHELLMODE), respectively. -
    - SHELLHEADER - String to write in first line of Shell targets - (default is #!/bin/sh). - -
    -
    -

    - -

    -Installing Files -

    -Jambase provides a set of Install* rules to copy files -into an destination directory and set permissions on them. -On Unix, the install(1) program is used. -If the destination directory does not exist, jam -creates it first. -

    -All files copied with the Install* rules are dependencies -of the install pseudotarget, which means that the -command "jam install" will cause the installed copies to -be updated. Also, "jam uninstall" will cause the installed -copies to be removed. -

    -The Install* rules are: -

    - -
    InstallBin - Copies file and sets its permission to $(EXEMODE). - You must specify the suffixed executable name. E.g.: - 
    InstallBin $(BINDIR) : thing$(SUFEXE) ;
-
    - -
    InstallFile - Copies file and sets its permission to $(FILEMODE). E.g.: - 
    InstallFile $(DESTDIR) : readme.txt ;
-
    - -
    InstallLib - Copies file and sets its permission to $(FILEMODE). - You must specify the suffixed library name. E.g.: - 
    InstallLib $(LIBDIR) : libzoo$(SUFLIB) ;
-
    - -
    InstallMan - Copies file into the mann - subdirectory of the target directory - and sets its permission to $(FILEMODE). E.g., - this copies foo.5 into the $(DESTDIR)/man5 directory: - 
    InstallMan $(DESTDIR) : foo.5 ;
-
    - -
    InstallShell - Copies file and sets its permission to $(SHELLMODE). E.g.: - 
    InstallShell $(DESTDIR) : startup ;
-
    - -
    -
    -

    -

    -

    - Variables -

    - The following variables control the installation rules: -

    -

    - -
    - INSTALL - The install program (Unix only) -
    - FILEMODE - Default file permissions on readable files. -
    - EXEMODE - Default file permission executable files. -
    - SHELLMODE - Default file permission on shell script files. -
    - MODE - Target-specific file permissions -
    -
    -

    -

    - The Install rules set a target-specific MODE to the current - value of $(FILEMODE), $(EXEMODE), or $(SHELLMODE), - depending on which Install rule was invoked. -

    - The directory variables are just defined for convenience: - they must be passed as the target to the appropriate - Install rule. The $(INSTALL) and mode variables must be - set (globally) before calling the Install rules in order - to take effect. -

    -

    -Miscellaneous Rules -

    -

    -Clean Rule -

    -

    -The Clean rule defines files to be removed when you run "jam clean". -Any site-specific build rules defined in your Jamrules should invoke -Clean so that outputs can be removed. E.g., -

    -	rule ResourceCompiler
-	{
-	   DEPENDS $(<) : $(>) ;
-	   Clean clean : $(<) ;
-	}
-
    -

    -

    -Most Jambase rules invoke the Clean rule on their built targets, -so "jam clean" will remove all compiled objects, libraries, -executables, etc. -

    -

    -MakeLocate Rule -

    - MakeLocate is a single convenient rule that creates a directory, - sets LOCATE on a target to that directory, and makes the directory - a dependency of the target. It is used by many Jambase rules, - and can be invoked directly, e.g.: - 
    -		GenFile data.tbl : hxtract data.h ;
-		MakeLocate data.tbl : $(TABLEDIR) ;
-
    - In this example, the File rule creates data.tbl from data.h. - The MakeLocate causes data.tbl to be written into the $(TABLEDIR) - directory; and if the directory doesn't exist, it is created first. -

    - The MakeLocate rule invokes another Jambase rule, MkDir, - to (recursively) create - directories. MkDir uses the $(MKDIR) variable to determine the - platform-specific command that creates directories. -

    -

    -RmTemps Rule -

    - Some intermediate files are meant to be temporary. - The RmTemps rule can be used to cause - jam to delete them after they are used. -

    - RmTemps must be: -

      -
    • - the last rule - invoked on the permanent file that uses - the temporary file(s) -
    • - invoked with the permanent file as the output - target and the temporary file(s) as the input target -
    • - invoked with the exact target identifiers of - the permanent file and the temporary file(s) -
    - For - example: - 
    -		SubDir TOP src big ;
-		GenFile big.y : joinfiles part1.y part2.y part3.y ;
-		Main bigworld : main.c big.y ;
-		RmTemps bigworld$(SUFEXE) : <src!big>big.y ;
-
    - This causes big.y to be deleted after it has been used to create - the bigworld executable. - The exact target identifier of big.y is <src!big>big.y - (the GenFile and Main rules tack on the grist automatically); - the exact target identifier of the bigworld executable - is bigworld$(SUFEXE). -

    -

    -Back to top. -

    - Copyright 1997, 2000 Perforce Software, Inc. -
    - Comments to info@perforce.com -
    - Last updated: Dec 31, 2000 -
    - $Id$ - - diff --git a/historic/jam/src/Porting b/historic/jam/src/Porting deleted file mode 100644 index 750556572..000000000 --- a/historic/jam/src/Porting +++ /dev/null @@ -1,68 +0,0 @@ -Notes on porting Jam - revised 12/31/2000 - -1) Working out system dependencies in the Jam code. - - Jam's OS footprint is fairly small. For OS independent work Jam - liberally uses standard libc functions like stdio, malloc, and - string. The OS dependent interfaces are: - - From filesys.h: - - file_parse() - split a file name into dir/base/suffix/member - file_build() - build a filename given dir/base/suffix/member - file_dirscan() - scan a directory for files - file_archscan() - scan an archive for files - file_time() - get the timestamp of a file, if not already - done by file_dirscan(). - - From execcmd.h: - - execcmd() - execute a shell script - execwait() - wait for any outstanding execcmd()'s. - - The current implementations are: - - filemac.c - mac MPW - filent.c - NT - fileos2.c - OS/2 - fileunix.c - all UNIX - filevms.c - VMS - - execmac.c - mac MPW - execunix.c - UNIX, OS/2, NT - execvms.c - VMS - -2) Defining OSMAJOR, OSMINOR in jam.h - - So that the Jambase and Jamfile know their host, Jam defines $(OS) - to be something useful for each platform. Make sure that there is - code in jam.h to generate a useful value for $(OS), and key it off - the platform specific C-preprocessor symbol. If the C-preprocessor - doesn't itself defines such a symbol, add a define to the Makefile. - - In addition to $(OS), you can also set $(OSPLAT) if the OS runs on - multiple platforms (like Linux or NT). - -3) Working out system dependencies in the Jambase - - With the value of $(OS) available, the Jambase can be extended to - support special variables or rules for new platforms. See the - current support for VMS, NT, and Mac. - -4) Yacc troubles - - The generated files jamgram.h and jamgram.c are distributed for the - poor souls without yacc. - -5) Known problematic systems: - - - Pyramid has no malloc.h, memory.h - - - Encore has no stdlib.h - - - Bull DPX has sys/file.h problems - -6) Send the results back. - - If you do porting work, the result can be integrated into future - releases if you send it back to the author's address in the README. diff --git a/historic/jam/src/README b/historic/jam/src/README deleted file mode 100644 index 7ee7a8e9c..000000000 --- a/historic/jam/src/README +++ /dev/null @@ -1,150 +0,0 @@ -Jam/MR (aka "jam - make(1) redux") - - /+\ - +\ Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc. - \+/ - - This is Release 2.4 of Jam/MR, a make-like program. - - License is hereby granted to use this software and distribute it - freely, as long as this copyright notice is retained and modifications - are clearly marked. - - ALL WARRANTIES ARE HEREBY DISCLAIMED. - -FEATURES - - -> Jam is a make(1) replacement that makes building simple things - simple and building complicated things manageable. - - -> Jam's language is expressive, making Jamfiles (c.f. Makefiles) - compact. Here's a sample: - - Main smail : main.c map.c resolve.c deliver.c - misc.c parser.y alias.c pw.c headers.c - scanner.l getpath.c str.c ; - - This builds "smail" from a dozen source files. Jam handles - header file dependencies automatically and on-the-fly. - - -> Jam is very portable: it runs on UNIX, VMS, Mac, and NT. - Most Jamfiles themselves are portable, like the sample above. - - -> Jam is unintrusive: it is small, it has negligible CPU - overhead, and it doesn't create any of its own funny files - (c.f. Odin, nmake, SunOS make). - - -> Jam can build large projects spread across many directories - in one pass, without recursing, tracking the relationships - among all files. Jam can do this with multiple, concurrent - processes. - - -> Jam isn't under the blinkin GNU copyright, so you can - incorporate it into commercial products. - - -INFORMATION GUIDE - - Jam.html jam and language reference. - - Jambase.html Reference for the Jambase boilerplate file. - - Jamfile.html Easy reading on creating a Jamfile and using jam. - - RELNOTES Release 2.3 release notes. - - Porting Notes on porting jam to wildcat platforms. - - README This file. Includes installation instructions. - - jam.c Contains the jam command's main() as well as an - introduction to the code, for serious hackers. - - -INSTALLING - - The Makefile (UNIX, NT), build.com (VMS), Build.mpw (Mac MPW) are - for bootstrapping. Once jam is built, it can rebuild itself. - - UNIX - - Build jam with make(1) on: - - Platform $(OS) - ------------------------- - AIX AIX * - BSD/386 1.0 BSDI - COHERENT/386 COHERENT - DGUX 5.4 DGUX - FreeBSD FREEBSD - HPUX 9.0 HPUX - IRIX 5.0 IRIX - Linux LINUX - NEXTSTEP 3.2 NEXT - OSF/1 OSF - PTX V2.1.0 PTX - Solaris 2 SOLARIS * - SunOS4.1 SUNOS - Ultrix 4.2 ULTRIX - BeOS BEOS * - GNU/kFreeBSD KFREEBSD - - * requires editing Makefile - - Windows - - Build jam with nmake on: - - Platform $(OS) - ------------------------- - NT NT * - OS/2 OS2 * - - The NT MAXLINE (command line length) is still set in jam.h to - 996, which was apparently the NT 3.5 limit. On 4.0, the limit - is somewhere around 10K. For now, you can increase MAXLINE in - jam.h so that a jam running on 4.0 will use the full command - line length, but that jam.exe will fail miserably on the older OS. - - On NT, a variable must be set before invoking jam to tell - it where the C compiler lives. The name of this variable - depends on which compiler you are using: - - BCCROOT: The Borland C compiler - MSVCNT: The Microsoft Compiler 5.0 (for NT) - MSVC: The Microsoft Compiler 1.5 (for Windows) - - Only MSVCNT has really been tested and is known to work. - - Macintosh - - Build jam with Build.mpw on: - - Platform $(OS) - ------------------------- - Macintosh MAC - - You'll need to edit Build.mpw to set CW. - - VMS - - Build jam with @build.com on: - - Platform $(OS) - ------------------------- - VMS 5.4 VMS - OPENVMS OPENVMS - -Comments to the author! - -November, 1993 - release 1.0 -March, 1995 - release 2.0 -February, 1996 - release 2.1 -November, 1997 - release 2.2 -December, 2000 - release 2.3 -March, 2002 - release 2.4 - - -Christopher Seiwald - -seiwald@perforce.com diff --git a/historic/jam/src/RELNOTES b/historic/jam/src/RELNOTES deleted file mode 100644 index d142a11ed..000000000 --- a/historic/jam/src/RELNOTES +++ /dev/null @@ -1,941 +0,0 @@ -Release notes for Jam/MR 2.4 -(aka Jam - make(1) redux) - -0. Changes between 2.4rc1 and 2.4rc2: - - THESE NOTES WILL BE REMOVED WITH THE FINAL 2.4 RELEASE, SINCE THEY - REFER EXCLUSIVELY TO ADJUSTMENTS IN BEHAVIORS NEW BETWEEN 2.3 and - 2.4: - - Make MATCH generate empty strings for () subexpressions that - match nothing, rather than generating nothing at all. - Thanks to David Abrahams. - - GLOB now applies the pattern to the directory-less filename, - rather than the whole path. Thanks to Niklaus Giger. - - Make Match rule do productized results, rather than - using just $(1[1]) as pattern and $(2[1]) as the string. - -1. Release info: - - Jam/MR 2.4 - March, 21, 2002 - VERSION 2.4 - -2. Compatibility - - Jam 2.4 is upward compatible with Jam 2.3 - - The Jam 2.4 language is a superset of the 2.3 language; - Jamfiles, Jambase, and other rulesets used in 2.3 can be used - with the 2.4 language support. - -3. Changes since 2.3. - -3.1. Changes to Jam Language - - The mechanism for calling rules that return values - "[ rule - args ...]", (and 'return' in the rule body), is now a - documented part of the language. - - Add "on ..." syntax, to invoke a - rule under the influence of a target's specific variables. - - Add "[ on targ rule ... ]" to call a rule returning a value, - under the influence of a target's specific variables. - - New 'Glob' builtin that returns a list of files in a list of - directories, given a list of patterns. - - New 'while expr { block }' construct. - - New :E=value modifier provides default value if variable unset. - - New :J=joinval modifier concatenates list elements into single - element, separated by joinval. - - \ can now be used to escape a space (or any single whitespace - character), so that you don't have to resort to quotes. - - New 'Match regexp : string' rule matches regexp against string - and returns list of results. - - Rules can now be invoked indirectly, through variable names. - If the variable expands to an empty list, no rule is run. - If the variable expands to multiple entries, each rule is - run with the same arguments. The result of the rule invocation - is the concatenation of the results of the rules invoked. - - 'Echo' and 'Exit' now have aliases 'echo' and 'exit', since it - is really hard to tell that these are built-in rules and not - part of the language, like 'include'. Real rules continue to - start with a capital. - -3.2. Jambase Changes - - Support for YACCGEN, the suffix used on generated yacc output. - - Fix ups to have jam and p4 build with borland C 5.5, - and minor win98 jam support for jam clean - - SubDirHdrs now takes directory names in the same format as - SubInclude : one directory element per word. - - More portable support for specifying includes and #defines: - New ASHDRS, CCHDRS, CCDEFS, DEFINES, ObjectDefines, FQuote, - FIncludes, FDefines. Ordering of cc and c++ flags grossly - rearranged. - - Jambase has been compacted by applying the new E: and J: - expansion modifiers. - - New SoftLink rule, courtesy of David Lindes. It currently - assumes you can pass a -s flag to $(LN). - -3.3 'jam' Changes (See Jam.html) - - Added '-q' (quit quick) option; jam will exit promptly (as if it - received an interrupt), as soon as any target fails. - - Added experimental '-g' (build newest sources first) option: - all things being equal, normally targets are simply built in - the order they appear in the Jamfiles. With this flag, targets - with the newest sources are built first. From an idea by Arnt - Gulbrandsen. Undocumented (outside this note). - -3.4. Jam internal code changes - - jamgram.yy now defines YYMAXDEPTH to 10000, what it is on - FreeBSD, for older yaccs that left it at 150 or so. This is - needed for the right-recursion now used in the grammar. - - Optimize rule compilation, with right-recursion instead of left. - - Split jam's built-in rules out to builtins.c from compile.c, - so that compile.c only deals with the language. - - Split jam's pathsys.h from filesys.h, since they are really - two different pieces. - - evaluate_if(), which evaluated the condition tree for 'if' and - returned an int, has been replaced with compile_eval(), which does - essentially the same but returns a LIST. - -4. Fixed bugs - - Missing TEMPORARY targets with multiple parents no longer spoil one - parent's time with another. The parents' time is used for comparison - with dependents, but no longer taken on as the target's own time. - - 'actions updated', not 'actions together', now protects targets - from being deleted on failed/interrupted updates. - - Fixed broken $(v[1-]), which always returned an empty expansion. - Thanks to Ian Godin . - - Defining a rule within another rule, and invoking the enclosing - rule more than once, would result in giving the first rule a - null definition. Fixed. - - $(d:P) now works properly on the mac, climbing up directories. - Thanks to Miklos Fazekas . - - No longer (sometimes) treat \ as a directory separator on - UNIX. It isn't supposed to be, but was due to bungled ifdefs. - - Applying just :U or :D (or :E, :J) mods no longer causes the - variable value to be treated as a filename (parsed and rebuilt - using the OS specific pathsys routines). Previously, if _any_ - mods were present then the value was parsed and rebuilt as if - a filename, and that could in certain cases munge the value. - Only the file modifiers (:GDBSM) treat the value as a - filename. - - Four rules makeCommon, makeGrist, makeString, makeSubDir from - jam 2.2 missing in 2.3 have been re-added, with apologies to - dtb@cisco.com. - - Return status more likely to be correct when using -d0, now that - targets are could as being built even with no debugging output. - Thanks to Miklos Fazekas . - - yyacc now suffixes all terminals it defines with _t, so that they - don't conflict with other symbols (like RULE with the typedef - in rules.h). Thanks to Michael Allard. - - InstallInto now handles multiple sources properly, rather than - acting as if each installed target depended on all sources to - be installed. $(INSTALLGRIST) is now the default grist for - installed targets, rather than the hardcoded 'installed'. Thanks - to Stephen Goodson. - -5. Porting - - [MACINTOSH] Paths are now downshifted (internally) so as to - handle its case insensitivity. Thanks to Miklos Fazekas - . - - [NT] MS changed the macro for the IA64 Windows NT 64bit - compiler. - - [CYGWIN] Cygwin jam porting: dance around bison and yyacc. - Use bison's -y flag to use yacc's output file naming - conventions, and don't use yyacc on systems whose SUFEXE is - set. - - [VMS] The Jambase itself was not formatting the CCHDRS and - CCDEFS properly: on VMS they can't be appended to, because - multiple /define or /include directives don't work. Instead - now CCHDRS and CCDEFS is reformatted from HDRS and DEFINES - anytime those latter two change. This requires the recent - change to jam to allow access to target-specific variables - when setting other variables. - - [VMS] Remove exception call when file_dirscan() can't, for - some reason, scan a directory. Use a better set of #ifdefs to - determine if we're on a vax, rather than relying on the C - compiler being a specific version: we're able to build with - the C++ compiler now. - - [VMS] Port new jam to run with just cxx compiler. - (The C compiler being a extra-cost item). - - [NT] Add entry for DevStudio when the settings are already in the - system environment. - - [NT] default $(MV) to "move /y" in Jambase. - - [MINGW] Mingw port by Max Blagai. - -=============================================================================== -=============================================================================== - - -======= end -Release notes for Jam/MR 2.3 -(aka Jam - make(1) redux) - -0. Bugs fixed since 2.3.1 - - PATCHLEVEL 2 - 3/12/2001 - - NOCARE changed back: it once again does not applies to targets - with sources and/or actions. In 2.3 it was changed to apply to - such targets, but that broke header file builds: files that are - #included get marked with NOCARE, but if they have source or - actions, they still should get built. - -1. Release info: - - Jam/MR 2.3 - November 16, 2000 - VERSION 2.3 - PATCHLEVEL 1 - -2. Compatibility - - Jam 2.3 is upward compatible with Jam 2.2. - - The Jam 2.3 language is a superset of the 2.2 language; - Jamfiles, Jambase, and other rulesets used in 2.2 can be used - with the 2.3 language support. - -3. Changes since 2.2 - -3.1. Changes to Jam Language - - Rules now can have values, which can expanded into a list with - the new "[ rule args ... ]" syntax. A rule's value is the value - of its last statement, though only the following statements have - values: if (value of the leg chosen), switch (ditto), set (value - of the resulting variable), return (its arguments). Note that - 'return' doesn't actually return. This support is EXPERIEMENTAL - and otherwise undocumented. (2.3.1) - - Because of the new way lists are processed, if a rule has no - targets a warning message is no longer issued. - - NOCARE now applies to targets with sources and/or actions, - rather than just those without. - -3.2. Jambase Changes - - The HDRPATTERN variable now allows for leading blanks before - the #include, to keep up with ANSI. By john@nanaon-sha.co.jp - (John Belmonte) (2.2.3). - - HDRPATTERN has been adjusted to avoid mistaking cases like: - - # include /* could be */ - - MkDir now NOUPDATE's $(DOT), so that there are no dependencies - on the current directory's timestamp. By john@nanaon-sha.co.jp - (John Belmonte). - - The old mock functions like makeDirName, which assigned their - results to the variable named as their first argument, have - been replaced with real functions using the new [] synxtax. - E.g. "makeDirName foo : bar ola" is now "foo = [ fDirName bar ]" - - Install now always does a cp/chmod/etc, rather than using - the system's install(1), which invariably seems broken. - -3.3. Jam internal code changes - - $JAMUNAME is set on UNIX. (2.2.4). - - Jam ANSI-fied (2.3.0). - - jam.h now defines a bunch of symbols used by the other source - files, so as minimize compiler- and platform-specific ifdefs. - - OSVER is no longer set by jam.h (it was only set for AIX). - Jam does not depend on this variable at all, except to set - $(OSFULL), which is used to determine jam's build directory. - If the user needs to distinguish between various revs of - OSs, he must set OSVER in the environment. - -4. Fixed bugs - - Redefining a rule while it was executing could cause jam to - crash. Reference counts are now used to prevent that, thanks - to Matt Armstrong. - - Logic for computing chunk size when executing PIECEMEAL rules - has been reworked to be a little more accurate, without danger - of overflow, at the cost of being a little more compute intensive. - Instead of computing an estimate chunksize in the (now gone) - make1chunk(), make1cmds() now just goes full bore and tries to - use all args. When that fails, it backs off by 10% of the source - args until the command fits. It takes a little bit more compute - time compared to the old logic, but when you're executing actions - to build all of Shinola it's still pretty small in the scheme - of things. - - The NT handle leak in execunix.c has been fixed, thanks to - Gurusamy Sarathy. (2.2.1). - -5. Porting - - Platforms newly supported or updated: - - AmigaOS (with gcc), courtesy of Alain Penders (2.2.2). - - Beos - - CYGWIN 1.1.4, courtesy of John Belmonte . - - IBM AS400 via Visual Age on NT (primitive) - - IBM OS/390 Unix System Services - - Linux SuSE on OS390 - - Linux Mips, ARM - - Lynx - - HPUX 11, IA64 - - Mac OS X Server, courtesy of Jeff_Sickel@sickel.com (2.2.5). - - Mac Rhapsody - - MPE IX 6.0 - - NetBSD - - QNX RTP (QNX 6.0) - - Siemens Sinix - - UNICOS - - VMS 6.2, 7.1 - - Windows NT IA64 - -5.1. NT Porting Notes - - Always create tmp .bat file for actions if JAMSHELL is set. - That way, if JAMSHELL is a .bat file itself, it can handle - single-command actions with more than 9 cmd line args. - - COMSPEC is no longer examined: cmd.exe is always used - instead. Only cmd.exe can execute the Jambase rules anyhow. - - Jam can be built with Borland C++ 5.5. - - OS2 fixes: InstallBin now works. Filenames are now downshifted, - so mixed case works better there, too. file_dirscan() can now scan - the root ("c:\" or "\") directory, which it couldn't handle before. - - var_defines now ignores OS=Windows_NT, because it conflicts - with Jam's setting of OS (to NT). - -5.2. Mac OS 8/9 Notes - - The support for Mac is curious at best. It runs under MPW. - - It requires CodeWarrior Pro 5, but no longer requires GUSI. - - Use Build.mpw to bootstrap the build. - - The Mac specific definitions in the Jambase are not intended - to be of general purpose, but are sufficient to have Jam build - itself. - -=============================================================================== -=============================================================================== - - -Release Notes for Jam 2.2 - -1. Release info: - - Jam 2.2 - October 22, 1997 - VERSION 2.2 - PATCHLEVEL 1 - -2. Compatibility - - Jam 2.2 is a roll-up of 'Jam - make(1) redux' release 2.1+. - Most of the changes described below were available before this, - in the jam.2.1.plus.tar ball. - - The Jam 2.2 language is a superset of the 2.1 language; - Jamfiles, Jambase, and other rulesets used in 2.1 can be used - with the 2.2 language support. - - See 'Jambase Changes', below, to see if your Jamfiles need any - changes to work with the 2.2 Jambase. - - -3. Changes Since 2.1 - - New product name: Jam. (Executable program is still named 'jam'.) - - Documentation rewritten; HTML versions supplied. - - -3.1 Changes to Jam Language - - Rules may now have more fields than just $(<) and $(>). - - Local variables are now supported. - - The expression 'if $(A) in $(B)' is now supported. - - New variable modifiers :U and :L result in uppercased or lowercased - values. - - New variable modifier :P reliably results in parent directory - of either a file or directory. (Previously, :D was used, but on VMS - :D of a directory name is just the directory name.) - - The :S variable modifier now results in the _last_ suffix if a - filename has more than one dot (.) in it. - - New predefined $(JAMDATE) variable is initialized at runtime for - simple date stamping. - - New predefined variables $(OSVER) and $(OSPLAT) are used to - distinguish among operating system versions and hardware platforms, - when possible. - - New 'bind' qualifier on action definitions allows variables - other than $(<) and $(>) to be bound with SEARCH and LOCATE paths. - - Action buffer size is no longer limited by MAXCMD. Instead, each - line in an action is limited by MAXLINE, defined for each OS, and - the entire action size is limited by CMDBUF. - - -3.2 Jambase Changes (See Jamfile.html) - - Jambase has been reworked to incorporate new language features. - - A handful of new utility rules has been added: makeString, - makeDirName, etc. - - New HDRGRIST variable in Jambase allows for headers with the same - name to be distinguished. - - LOCATE_TARGET now has a new flavor, LOCATE_SOURCE, that is used by - rules that generate source files (e.g., Yacc and Lex). - - Header file includes now happen in the proper order. The limit of - 10 include files has been eliminated. - - The old "Install" rule is no longer available. Use InstallBin, - InstallFile, InstallLib, InstallMan, or InstallShell instead. - - -3.3 'jam' Changes (See Jam.html) - - 'jam' can now be built as a stand-alone program, with Jambase - compiled into the executable. An external or alternate Jambase can - still be referenced explicitly with -f. - - On command failure, 'jam' now emits the text of the command that - failed. This is a compromise between the normal -d1 behavior (where - commands were never seen) and -d2 (where commands are always seen). - - 'jam' now exits non-zero if it doesn't have a total success. A parse - error, sources that can't be found, and targets that can't be built - all generate non-zero exit status. - - The debugging levels (-d flags) have been slightly redefined. - - The supplied Jamfile now builds 'jam' into a platform specific - subdirectory. This lets you use the same source directory to - build 'jam' for more than one platform. - - The supplied Jamfile does not rebuild generated source files by - default. (They are supplied with the distribution.) See Jamfile - for more information. - - -4. Fixed Bugs - - The 'include' bug has finally been fixed, so that include - statements take effect exactly when they are executed, - rather than after the current statement block. This also - corrects the problem where an 'include' within an 'if' - block would wind up including the file one token after the - 'if' block's closing brace. Credit goes to Thomas Woods - for suggesting that the parse tree generation and parse - tree execution be paired in their own loop, rather than - having the parser execute the tree directly. - - The setting and extracting of grist has been regularized: - normally, if you set a component of a filename (using the - :DBSMG= modifiers), you are supposed to include the delimiters - that set off the component: that is, you say "$(x:S=.suffix)", - including the ".". But with grist it was inconsistent - between setting and getting: setting grist required no - <>'s, while getting grist included them. Getting grist - continues to return the <>'s, but now setting grist can - either include them (the new way) or not (the old way). - - 'actions together' now suppresses duplicate sources from - showing up in $(>). - - Accessing variables whose names contained ['s (as happens with - MkDir on VMS) wasn't working, because it treated the [ as an - array subscript. Now [ and ] are, like :, handled specially so - that they can appear in variable values. - - The 'if' statement now compares all elements in expressions; - previously, it only compared the first element of each list. - - If a command line in an action is longer than MAXLINE (formerly - MAXCMD), 'jam' now issues an error and exits rather than dumping - core. - - If a Jamfile ended without a trailing newline, jam dumped core. - This has been fixed. - - -5. Porting - - See jam.h for the definitive list of supported platforms. - Since 2.1, support has been added for: - - Macintosh MPW - Alpha VMS - Alpha NT - NT PowerPC - BeOS - MVS OE - UNIXWARE - QNX - SINIX (Nixdorf) - OS/2 - Interactive UNIX (ISC), courtesy of Matthew Newhook - - -5.1 NT Support Fixes - - The NT command executor now handles multiple line actions, by writing - multi-line actions to a batch file and executing that. - - Targets are universally lowercased on NT. (Matthew Newhook) - - Concurrent process support is fully enabled for NT. - (Gurusamy Sarathy ) - - Path handling: Jam now knows that the directory component of "D:\" - is "D:\", just as on unix it knows that the directory component of - "/" is "/". It also now successfully gets the timestamp for "D:\" - or just plain "\". - - -5.2 VMS Support Fixes - - VMS support is much, much better now. The path name manipulation - routines (in pathvms.c) were more or less rewritten, and they now - handle the vagaries of combining directory and file names properly. - - Targets are universally lowercased on VMS. - - Multi-line command blocks on VMS are now executed in a single system() - call rather than separate ones for each line, so that actions can - be DCL scripts. - -=============================================================================== -=============================================================================== - - -Release notes for Jam 2.1. - -1. Release info: - Jam 2.1 - February 1, 1996 - VERSION 2.1 - PATCHLEVEL 0 - -2. Porting - - Linux is now supported. - - FREEBSD is now supported. - - SCO ("M_XENIX") now supported. - - NCR now supported. - - NEXT support from karthy@dannug.dk (Karsten Thygesen) - - DECC support from zinser@axp614.gsi.de (Martin P.J. Zinser) - - I have changes for OS/2, but no way to test them. Volunteers? - I have VMS multiprocess support, but no way to test it. Volunteers? - -2.1. NT Support fixes. - - The NT support is considerably more real than it was in 2.0. - Filent.c had its syntax error corrected, it no longer skips the - first entry when scanning directories, and it handles string - tables in archives (for long object file names). - - The Jambase was changed a bit to support the various C/C++ - compilers on NT, although it has only been thorougly tested - with MSVC20. - - You still need to set MSVCNT or BCCROOT to the root of the - the compiler's directory tree, and you'll get an error if you - don't set it (rather than getting a pile of mysterious errors). - -2.2. Other porting fixes. - - SPLITPATH now set up for UNIX (:), NT (;), VMS (,) - - Jambase support for Solaris works better now: the location of - AR is hardwired to /usr/ccs/bin/ar and it knowns "install" - doesn't take -c. Solaris -- how the mighty have fallen. - - To handle Linux's wacko yacc, jamgram.h is now included after - scan.h so that YYSTYPE is define. - -3. Jambase Changes (see Jamfile.html) - - SubDir now computes the root directory for the source tree, if - the variable naming the root directory isn't set in the environment. - It counts the number of directory elements leading from the root - to the current directory (as passed to SubDir) and uses that many - "../"'s to identify the root. This means that to use SubDir you - no longer have to have anything special set in the environment. - - InstallFile is now an alias for InstallLib. - - 'first' is now dependency of all pseudo-targets (all, files, - exe, lib, shell), so that jamming any of these pseudo-targets - also builds any dependencies of 'first'. - - The File rule definition in the Jambase was missing an &. - - The File rule now calls the Clean rule, so that installed files - get cleaned. - -4. Jam changes (see Jam.html) - - Variables may now be set on the command line with -svar=value. - - Targets marked with NOUPDATE are now immune to the -a (anyhow) - flag. Previously, the MkDir rule would try to recreate directories - that already exist when jam was invoked with -a. - - A new variable, $(JAMVERSION), joins the small list of built-in - variables. It it set to the release of jam, currently "2.1". - - If an actions fails, jam now deletes the target(s). It won't - delete libraries or other targets that are composites. This is - now consistent with jam's behavior on interrupts (it deletes the - targets). - - Jam had a nasty bug when setting multiple variables to the same - value: if the first two variable names were the same, the variable - value got trashed. This also affected "on target" variables if - the first two targets were the same. For example: - - FOO on bar.c bar.c foo.c = a b c ; - - This would mangle the value of FOO for bar.c and foo.c. This has - been fixed. - - Jam would generate bogus numbers when reporting the number of - targets updated after an interrupt. It now is more careful about - counting. - - The debugging flag -d has been extended. In addition to supporting - -dx (turn on debugging for all levels up to x) there is also now - -d+x (turn on debugging at only level x). The default output - level is -d1 (-or d2 if -n is given); this can be turned off with - -d0. The debug levels are listed in jam.1 and jam.h. - - The parsing debug output now uses indenting to indicate when - one rule invokes another. - -=============================================================================== -=============================================================================== - - -Release notes for Jam 2.0. - -1. Release info: - Jam 2.0 - March 10, 1994 - VERSION 2.0 - PATCHLEVEL 5 - -2. Porting - - Windows/NT is now (crudely) supported, courtesy of Brett Taylor - and Laura Wingerd. - - COHERENT/386 is now supported, courtesy of Fred Smith. - - Solaris archive string table for long archive names is now - supported, thanks to Mike Matrigali. - -3. Compatibility - - Jam 2.0 syntax is a superset of Jam 1.0 syntax, and thus it can - interpret a Jam 1.0 Jambase. - - The Jam 2.0 Jambase is a superset of the Jam 1.0 Jambase, and - thus it can include a Jamfile written for Jam 1.0. - -4. Changes from Jam 1.0 to Jam 2.0 - -4.1. Documentation changes - - New Jamfile.5 manual page, with lots of examples and easy - reading. It replaces both the old "Examples" file as well as - the old Jambase.5 manual page. - - jam.1 edited by Stephen W. Liddle and Diane Holt. - -4.2. Jambase Changes (see Jamfile.5) - -4.2.1. New rules: - - There are new rules to make handling subdirectories easier: - SubDir, SubInclude, SubDirCcFlags, SubDirHdrs. - - There are new rules to handle file-specific CCFLAGS and HDRS: - ObjectCcFlags and ObjectHdrs. - - Misc new rules: HardLink, InstallShell, MkDir. - - New rule "clean" that deletes exactly what jam has built, and - "uninstall" that deletes exactly what was installed. - - New rules for handling suffixes .s, .f, .cc, .cpp, .C. - -4.2.2. Old rules: - - The InstallBin, Lib, Man, and the new Shell rules now take the - destination directory as the target and the files to be copied - as sources. These rules formerly took the files to be copied - as targets, and used built-in destination directories of - $(BINDIR), $(LIBDIR), $(MANDIR), and $(BINDIR). - - The InstallBin, Lib, Man, and Shell rules use the install(1) - program now, instead of doing their own copying. - - The Cc rule now uses -o when possible, rather than moving the - result. Some platforms (Pyramid?) have a broken -o. - - Jambase rules taking libraries, objects, and executables now - all ignore the suffixes provided and use the one defined in the - Jambase for the platform. - - Stupid yyacc support moved out of Jambase, as jam is its only - likely user. - - Jambase now purturbs library sources with a "grist" of - SOURCE_GRIST. - -4.2.3. Misc: - - The names of the default rules defined in Jambase have been - lowercased and un-abbreviated, to be more imake(1) like. - - The Jambase has been reorganized and sorted, with VMS and NT - support moved in from their own files. - - The Jambase has been relocated on UNIX from /usr/local/lib/jam - to /usr/local/lib. - -4.3. Jam changes (see jam.1) - -4.3.1. Flags: - - New -a (anyhow) flag: means build everything. - - New -j flag: run jobs in parallel. - - Old -t now rebuilds the touched target, rather that just the - target's parents. - - -n now implies -d2, so that you see what's happening. The - debug level can be subsequently overridden. - - New -v to dump version. - -4.3.2. Rules: - - New ALWAYS rule behaves like -t: always builds target. - - New EXIT rule makes it possible to raise a fatal error. - - New LEAVES rule which say target depends only on the update - times of the leaf sources. - - New NOUPDATE rule says built targets only if they don't exist. - - NOTIME has been renamed NOTFILE, to more accurately reflect its - meaning (it says a target is not to be bound to a file). - -4.3.3. Variables: - - New special variable JAMSHELL: argv template for command execution - shell. - - Variables, both normal and target-specific, can have their - value appended with the syntax "var += value" or "var on target - += value". - - "?=" is now synonymous with "default =". - - Imported enviroment variable values are now split at blanks - (:'s if the variable name ends in PATH), so that they become - proper list values. - -4.3.4. Misc: - - Files to be sourced with "include" are now bound first, so - $(SEARCH) and $(LOCATE) affect them. They still can't be - built, though. - - New modifier on "actions": "existing" causes $(>) to expand - only those files that currently exist. - -4.3.5. Bug fixes: - - When scanning tokens known to be argument lists (such as the - arguments to rule invocations and variable assignment), the - parser now tells the scanner to ignore alphabetic keywords, as - all such lists terminate with punctuation keywords (like : or - ;). This way, alphabetic keywords don't need to be quoted when - they appear as arguments. - - The scanner has been fixed to handle oversized tokens, - unterminated quotes, unterminated action blocks, and tokens - abutting EOF (i.e. a token with no white space before EOF). - - The progress report "...on xth target..." used to count all - targets, rather than just those with updating actions. Since - the original pronouncement of targets to be udpated included - only those with updating actions, the progress report has been - changed to match. - - 'If' conditionals now must be single arguments. Previously, - they could be zero or more arguments, which didn't make much - sense, and made things like 'foo == bar' true. The comparison - operator is '=', and '==' just looked like the second of three - arguments in the unary "non-empty argument list" conditional. - - Header files indirectly including themselves were mistakenly - reported as being dependent on themselves. Recursing through - header file dependencies is now done after determining the fate - of the target. - - The variable expansion support was expanding $(X)$(UNDEF) as if - it were $(X). It now expands to an empty list, like it - should. - - The UNIX version of file_build() didn't handle "dir/.suffix" - right. Now it does. - - The VMS command buffer was assumed to be as large as 1024 bytes, - which isn't the case everywhere as it is related to some weird - quota. It has been lowered to 256. - - $(>) and $(<) wouldn't expand in action blocks if the targets - were marked with NOTIME. Now they expand properly. - - Malloc() return values are now checked. - - The variable expansion routine var_expand() is now a little - faster, by taking a few often needed shortcuts. - - The VMS version of file_build() used the wrong length when - re-rooting file names that already had directory compoents. - This was fixed. - - Various tracing adjustments were made. - -5. Limitations/Known Bugs - - The new Windows/NT support has only been marginally tested. It - is dependent on certain variables being set depending on which - compiler you are using. You'll need to look in the file - Jambase and see what variables are expected to be set. - - The VMS support has been tested, courtesy of the DEC guest - machine, but has not been hammered fully in release 2.0. It - was used quite a bit in Jam 1.0. - - Jam clean when there is nothing to clean claims it is updating - a target. - - Because the include statement works by pushing a new file in - the input stream of the scanner rather than recursively - invoking the parser on the new file, multiple include - statements in a rule's procedure causes the files to be - included in reverse order. - - If the include statement appears inside an if block, the - parser's attempt to find the else will cause the text of the - included file to appear after the first token following the - statement block. This is rarely what is intended. - - In a rule's actions, only $(<) and $(>) refer to the bound file - names: all other variable references get the unbound names. - This is a pain for $(NEEDLIBS), because it means that library - path can't be bound using $(SEARCH) and $(LOCATE). - - With the -j flag, errors from failed commands can get - staggeringly mixed up. Also, because targets tend to get built - in a quickest-first ordering, dependency information must be - quite exact. Finally, beware of parallelizing commands that - drop fixed-named files into the current directory, like yacc(1) - does. - - A poorly set $(JAMSHELL) is likely to result in silent - failure. diff --git a/historic/jam/src/build.jam b/historic/jam/src/build.jam index 821ed22d6..8698efe57 100644 --- a/historic/jam/src/build.jam +++ b/historic/jam/src/build.jam @@ -16,7 +16,7 @@ _VERSION_ = 3 1 12 ; NAME = boost-jam ; VERSION = $(_VERSION_:J=$(.)) ; RELEASE = 1 ; -LICENSE = 1_0 ; +LICENSE = LICENSE_1_0 ; # Generate development debug binaries? if --debug in $(ARGV) @@ -713,22 +713,28 @@ rule .hdr.scan } .scan [ GLOB . : *.c ] ; -# Distribution making from here on out. +# Distribution making from here on out. Assumes that +# the docs are already built as html at ../doc/html. If +# they aren't, then the docs are not included in the dist +# archive. dist.license = - #~ [ GLOB . : LICENSE_$(LICENSE).txt ] [ GLOB [ .path .. .. .. ] : LICENSE_$(LICENSE).txt ] ; - [ GLOB . : LICENSE_$(LICENSE).txt ] - [ GLOB [ .path .. .. .. ] : LICENSE_$(LICENSE).txt ] - [ GLOB [ .path .. boost ] : LICENSE_$(LICENSE).txt ] ; + [ GLOB . : $(LICENSE).txt ] + ; +dist.license = $(dist.license:D=) + [ GLOB [ .path .. .. .. ] : $(LICENSE).txt ] + [ GLOB [ .path .. boost ] : $(LICENSE).txt ] ; dist.docs = - $(dist.license[1]) - index.html - Porting - Jam.html + [ GLOB . : *.png *.css *.html ] + ; +dist.docs = $(dist.docs:D=) + [ GLOB [ .path images ] : *.png ] + [ GLOB [ .path jam ] : *.html ] ; dist.source = [ GLOB . : *.c *.h ] ; dist.source = $(dist.source:D=) + $(dist.license[1]) $(dist.docs) build.jam build.bat build.sh build_vms.com Jambase diff --git a/historic/jam/src/index.html b/historic/jam/src/index.html deleted file mode 100644 index 417f9d6f5..000000000 --- a/historic/jam/src/index.html +++ /dev/null @@ -1,1263 +0,0 @@ - - - - - - - - - Boost.Jam - - - - - - - - - - - - - -
    -

    -

    -     		-

    Boost.Jam

    - -

    -
    -

    - -
    -
    Introduction
    - -
    Features
    - -
    Contents
    - -
    Building Boost.Jam
    - -
    Core Jam Extensions
    - -
    -
    -
    Command-line and Environment Variable - Quoting
    - -
    Startup Behavior
    - -
    Rule Indirection
    - -
    Argument Lists
    - -
    Module Support
    - -
    -
    -
    Declaration
    - -
    Variable Scope
    - -
    Local Rules
    - -
    The RULENAMES - rule
    - -
    The VARNAMES rule
    - -
    The IMPORT rule
    - -
    The EXPORT rule
    - -
    The - CALLER_MODULE
    - -
    The DELETE_MODULE - rule
    -
    -
    - -
    Local for Loop Variables
    - -
    Negative Indexing
    - -
    Support for Cygwin
    - -
    Target Binding Detection
    - -
    Return Code Inversion
    - -
    Ignoring Return Codes
    - -
    Removing outdated targets
    - -
    The SUBST Rule
    - -
    The JAM_VERSION global - variable
    - -
    Debugging Support
    - -
    -
    -
    The BACKTRACE rule
    - -
    Profiling
    - -
    Parser Debugging
    - -
    Dependency Graph Output
    -
    -
    - -
    The UPDATE rule and changes to command - line handling
    - -
    Semaphores
    - -
    The W32_GETREG rule
    - -
    The ISFILE rule
    - -
    The SHELL rule
    -
    -
    - -
    Jam Fundamentals
    -
    - -

    Introduction

    - -

    Boost.Jam (BJam)  is a build tool based on FTJam, which in turn is - based on Perforce Jam. It contains significant improvements made to - facilitate its use in the Boost Build System, but should be backward - compatible with Perforce Jam.

    - -

    This is version 3.1.12 of BJam and is based on version 2.4 of - Jam/MR:

    - 
    -/+\
-+\  Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc.
-\+/
-This is Release 2.4 of Jam/MR, a make-like program.
-License is hereby granted to use this software and distribute it
-freely, as long as this copyright notice is retained and modifications
-are clearly marked.
-ALL WARRANTIES ARE HEREBY DISCLAIMED.
-
    - -

    Features

    - -

    Jam is a make(1) replacement that makes building simple things simple - and building complicated things manageable.

    - -

    Jam's language is expressive, making Jamfiles (c.f. Makefiles) compact. - Here's a sample:

    - 
    -Main smail : main.c map.c resolve.c deliver.c
-     misc.c parser.y alias.c pw.c headers.c
-     scanner.l getpath.c str.c ;
-
    - -

    This builds "smail" from a dozen source files. Jam handles header file - dependencies automatically and on-the-fly.

    - -

    Jam is very portable: it runs on UNIX, VMS, Mac, and NT. Most Jamfiles - themselves are portable, like the sample above.

    - -

    Jam is unintrusive: it is small, it has negligible CPU overhead, and it - doesn't create any of its own funny files (c.f. Odin, nmake, SunOS - make).

    - -

    Jam can build large projects spread across many directories in one pass, - without recursing, tracking the relationships among all files. Jam can do - this with multiple, concurrent processes.

    - -

    Jam isn't under the blinkin GNU copyright, so you can incorporate it - into commercial products.

    - -

    Contents

    - - - - - - - - - - - - - -
    Jam.htmlJam and language reference.
    PortingNotes on porting jam to wildcat platforms.
    - -

    Building Boost.Jam

    - -

    Installing BJam after building it is simply a matter of copying the - generated executables someplace in your PATH. For building the - executables there are a set of build bootstrap scripts to - accomodate particular environments. The scripts take one optional argument, - the name of the toolset to build with. When the toolset is not given an - attempt is made to detect an available toolset and use that. The build - scripts accept these areguments:

    - 
    -<build script name> [toolset]
-
    - -

    Running the scripts without arguments will give you the best chance of - success. On Windows platforms from a command console do:

    - 
    -cd <jam source location>
-.\build.bat
-
    - -

    On Unix type platforms do:

    - 
    -cd <jam source location>
-sh ./build.sh
-
    - -

    For the Boost.Jam source included with the Boost distribution the - <jam source location> is - BOOST_ROOT/tools/build/jam_src.

    - -

    If the scripts fail to detect an appropriate toolset to build with your - particular toolset may not be auto-detectable. In that case, you can - specify the toolset as the first argument, this assumes that the toolset is - readily available in the PATH. NOTE: The toolset used to build - Boost.Jam is independent of the toolsets used for Boost.Build. Only one - version of Boost.Jam is needed to use Boost.Build. The supported toolsets, - and wether they are auto-detected, are:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ScriptPlatformsToolsetsDetection
    build.batWindows NT, 2000, and XPcomo, Comeau.Computing - C/C++
    borland, - Borland C++Builder (BCC 5.5)* Common install location: - "C:\Borland\BCC55"
    - * BCC32.EXE in PATH
    gcc, GNU GCC
    gcc-nocygwin, GNU - GCC
    intel-win32, - Intel C++ Compiler for Windows* ICL.EXE in PATH
    metrowerks, MetroWerks - CodeWarrior C/C++ 7.x, 8.x* CWFolder variable configured
    - * MWCC.EXE in PATH
    mingw, GNU GCC as the MinGW configuration* Common install location: "C:\MinGW"
    msvc, - Microsoft Visual C++ 6.x* VCVARS32.BAT already configured
    - * Common install locations: "C:\Program Files\Microsoft Visual - Studio", "C:\Program Files\Microsoft Visual C++"
     * - CL.EXE in PATH
    vc7, - Microsoft Visual C++ 7.x* VCVARS32.BAT or VSVARS32.BAT - already configured
    - * Common install location: "C:\Program Files\Microsoft Visual - Studio .NET"
    - * Common install location: "C:\Program Files\Microsoft Visual - Studio .NET 2003"
    build.shUnix, Linux, Cygwin, - etc.acc, HP-UX - aCC* aCC in PATH
    - * uname is "HP-UX"
    como, - Comeau.Computing C/C++* como in PATH
    gcc, GNU GCC* gcc in PATH
    intel-linux, - Intel C++ for Linux* icc in PATH
    - * Common install locations: "/opt/intel/compiler70", - "/opt/intel/compiler60", "/opt/intel/compiler50"
    kcc, Intel KAI - C++* KCC in PATH
    kylix, - Borland C++Builder* bc++ in PATH
    mipspro, - SGI MIPSpro C
    sunpro, Sun Workshop 6 C++* Standard install location: - "/opt/SUNWspro"
    true64cxx, Compaq C++ - Compiler for True64 UNIX
    vacpp, IBM VisualAge - C++* xlc in PATH
    MacOS X
    		darwin, Apple - MacOS X GCC* uname is "Darwin"
    - -

    The built executables are placed in a subdirectory specific to your - platform. For example, in Linux running on an Intel x86 compatible chip, - the executables are placed in: "bin.linuxx86". - The bjam[.exe] executable can be used to invoke Boost.Build.

    - -

    The build scripts support additional invocation arguments for - use by developers of Boost.Jam. The extra arguments come after the toolset, - and can take the form of "--option" or targets for the - build.jam script:

    - 
    -<build script name> [toolset] [--option+ target*]
-
    - -

    There is current only one available option, "--debug", which - builds debugging versions of the executable. When built they are placed in - their own directory "bin.<platform>.debug". To specify - targets without options, one can suply a special ignore option - "---".

    - -

    Currently there are two targets supported: dist, and - clean. Respectively they: generate packages (compressed archives) - as appropriate for distribution in the platform, or remove all the built - executables and objects.

    - -

    Core Jam - Extensions

    - -

    A number of enhancements have been made to the core language of Classic - Jam. These changes were aimed primarily at making it easier to manage the - complexity of a large system such as Boost.Build.

    - -

    Command-line and - Environment Variable Quoting

    - -

    Classic Jam had an odd behavior with - respect to command-line variable ( -s...) and environment variable - settings which made it impossible to define an arbitrary variable with - spaces in the value. Boost Jam remedies that by treating all such settings - as a single string if they are surrounded by double-quotes. Uses of this - feature can look interesting, since shells require quotes to keep - characters separated by whitespace from being treated as separate - arguments:

    - 
    -jam -sMSVCNT="\"\"C:\Program Files\Microsoft Visual C++\VC98\"\"" ...
-
    - -

    The outer quote is for the shell. The middle quote is for Jam, to tell - it to take everything within those quotes literally, and the inner quotes - are for the shell again when paths are passed as arguments to build - actions. Under NT, it looks a lot more sane to use environment variables - before invoking jam when you have to do this sort of quoting:

    - 
    -set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""
-
    - -

    Startup - Behavior

    - -

    The Boost.Build v2 initialization behavior has been implemented. This - behavior only applies when the executable being invoked is called - "bjam" or, for backward-compatibility, when the - BOOST_ROOT variable is set.

    - -
      -
    1. We attempt to load "boost-build.jam" by searching from the current - invocation directory up to the root of the file-system. This file is - expected to invoke the boost-build rule to indicate where the - Boost.Build system files are, and to load them.
      2. - -
    2. If boost-build.jam is not found we error and exit, giving brief - instructions on possible errors. - -
      - As a backward-compatibility measure for older versions of - Boost.Build, when the BOOST_ROOT variable is set, we - first search for boost-build.jam in - $(BOOST_ROOT)/tools/build and - $(BOOST_BUILD_PATH). If found, it is loaded and - initialization is complete. -
      -
      3. - -
    3. The boost-build rule adds its (optional) argument to the - front of BOOST_BUILD_PATH, and attempts to load - bootstrap.jam from those directories. If a relative path is - specified as an argument, it is treated as though it was relative to the - boost-build.jam file.
      4. - -
    4. If the bootstrap.jam file was not found, we print a likely error - message and exit.
      5. -
    - -

    Rule - Indirection

    - -

    Boost Jam allows you to call a rule whose name is held in a variable or - computed as the result of an expression:

    - 
    -x = foo ;
-rule foobar { ECHO foobar ; }   # a trivial rule
-$(x)bar ;                       # invokes foobar
-
    - -

    Furthermore, if the first expression expands to more than one list item, - everything after the first item becomes part of the first argument. This - allows a crude form of argument binding:

    - 
    -# return the elements of sequence for which predicate returns non-nil
-rule filter ( sequence * : predicate + )
-{
-    local result ;
-    for local x in $(sequence)
-    {
-        if [ $(predicate) $(x) ] { result += $(x); }
-    }
-    return $(result);
-}
-# true iff x == y
-rule equal ( x y )
-{
-    if $(x) = $(y) { return true; }
-}
-# bind 3 to the first argument of equal
-ECHO [ filter 1 2 3 4 5 4 3 : equal 3 ] ; # prints "3 3"
-
    - -

    Argument lists

    - -

    You can now describe the arguments accepted by a rule, and refer to them - by name within the rule. For example, the following prints ``I'm sorry, - Dave'' to the console:

    - 
    -rule report ( pronoun index ? : state : names + )
-{
-    local he.suffix she.suffix it.suffix = s ;
-    local I.suffix = m ;
-    local they.suffix you.suffix = re ;
-    ECHO $(pronoun)'$($(pronoun).suffix) $(state), $(names[$(index)]) ;
-}
-report I 2 : sorry : Joe Dave Pete ;
-
    - -

    Each name in a list of formal arguments (separated by ``:'' in - the rule declaration) is bound to a single element of the corresponding - actual argument unless followed by one of these modifiers:

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    SymbolSemantics of preceding symbol
    ?optional
    *Bind to zero or more unbound elements of the actual argument. When - ``*'' appears where an argument name is expected, any number - of additional arguments are accepted. This feature can be used to - implement "varargs" rules.
    +Bind to one or more unbound elements of the actual argument.
    - -

    The actual and formal arguments are checked for inconsistencies, which - cause Jam to exit with an error code:

    - 
    -### argument error
-# rule report ( pronoun index ?  : state  : names + )
-# called with: ( I 2 foo  : sorry  : Joe Dave Pete )
-# extra argument foo
-### argument error
-# rule report ( pronoun index ?  : state  : names + )
-# called with: ( I 2  : sorry )
-# missing argument names
-
    - -

    If you omit the list of formal arguments, all checking is bypassed as in - ``classic'' Jam. Argument lists drastically improve the reliability and - readability of your rules, however, and are strongly recommended for - any new Jam code you write.

    - -

    Module Support

    - -

    Boost Jam introduces support for modules, which provide some rudimentary - namespace protection for rules and variables. A new keyword, - ``module'' was also introduced. The features described in this - section are primitives, meaning that they are meant to provide the - operations needed to write Jam rules which provide a more elegant module - interface.

    - -

    Declaration

    - 
    -module expression { ... }
-
    - -

    Code within the { ... } executes within the module - named by evaluating expression. Rule definitions can be found in the - module's own namespace, and in the namespace of the global module as - module-name.rule-name, so within a module, other - rules in that module may always be invoked without qualification:

    - 
    -module my_module
-{
-    rule salute ( x ) { ECHO $(x), world ; }
-    rule greet ( ) { salute hello ; }
-    greet ;
-}
-my_module.salute goodbye ;
-
    - -

    When an invoked rule is not found in the current module's namespace, it - is looked up in the namespace of the global module, so qualified calls work - across modules:

    - 
    -module your_module
-{
-    rule bedtime ( ) { my_module.salute goodnight ; }
-}
-
    - -

    Variable Scope

    - -

    Each module has its own set of dynamically nested variable scopes. When - execution passes from module A to module B, all the variable bindings from - A become unavailable, and are replaced by the bindings that belong to B. - This applies equally to local and global variables:

    - 
    -module A
-{
-    x = 1 ;
-    rule f ( )
-    {
-        local y = 999 ; # becomes visible again when B.f calls A.g
-        B.f ;
-    }
-    rule g ( )
-    {
-        ECHO $(y) ;     # prints "999"
-    }
-}
-module B
-{
-    y = 2 ;
-    rule f ( )
-    {
-        ECHO $(y) ; # always prints "2"
-        A.g ;
-    }
-}
-
    - -

    The only way to access another module's variables is by entering that - module:

    - 
    -rule peek ( module-name ? : variables + )
-{
-    module $(module-name)
-    {
-        return $($(>)) ;
-    }
-}
-
    Note that because existing variable bindings change whenever a new -module scope is entered, argument bindings become unavailable. That explains -the use of "$(>)" in the peek rule above. - -

    Local Rules

    - 
    -local rule rulename...
-
    - -

    The rule is declared locally to the current module. It is not entered in - the global module with qualification, and its name will not appear in the - result of:

    - 
    -[ RULENAMES module-name ]
-
    - -

    The RULENAMES - Rule

    - 
    -rule RULENAMES ( module ? )
-
    - -

    Returns a list of the names of all non-local rules in the given module. - If module is omitted, the names of all non-local rules in the - global module are returned.

    - -

    The VARNAMES - Rule

    - 
    -rule VARNAMES ( module ? )
-
    - -

    Returns a list of the names of all variable bindings in the given - module. If module is omitted, the names of all variable bindings - in the global module are returned. Note:this includes any local - variables in rules from the call stack which have not returned at the time - of the VARNAMES invocation.

    - -

    The IMPORT - Rule

    - -

    IMPORT allows rule name aliasing across modules:

    - 
    -rule IMPORT ( source_module ? : source_rules *
-            : target_module ? : target_rules * )
-
    - -

    The IMPORT rule copies rules from the source_module - into the target_module as local rules. If either - source_module or target_module is not supplied, it refers - to the global module. source_rules specifies which rules from the - source_module to import; TARGET_RULES specifies the names - to give those rules in target_module. If source_rules - contains a name which doesn't correspond to a rule in - source_module, or if it contains a different number of items than - target_rules, an error is issued. For example,

    - 
    -# import m1.rule1 into m2 as local rule m1-rule1.
-IMPORT m1 : rule1 : m2 : m1-rule1 ;
-# import all non-local rules from m1 into m2
-IMPORT m1 : [ RULENAMES m1 ] : m2 : [ RULENAMES m1 ] ;
-
    - -

    The EXPORT - Rule

    - -

    EXPORT allows rule name aliasing across modules:

    - 
    -rule EXPORT ( module ? : rules * )
-
    - -

    The EXPORT rule marks rules from the - source_module as non-local (and thus exportable). If an element of - rules does not name a rule in module, an error is issued. - For example,

    - 
    -module X {
-  local rule r { ECHO X.r ; }
-}
-IMPORT X : r : : r ; # error - r is local in X
-EXPORT X : r ;
-IMPORT X : r : : r ; # OK.
-
    - -

    The - CALLER_MODULE Rule

    - 
    -rule CALLER_MODULE ( levels ? )
-
    - -

    CALLER_MODULE returns the name of the module scope enclosing - the call to its caller (if levels is supplied, it is interpreted as an - integer number of additional levels of call stack to traverse to locate the - module). If the scope belongs to the global module, or if no such module - exists, returns the empty list. For example, the following prints "{Y} - {X}":

    - 
    -module X {
-    rule get-caller { return [ CALLER_MODULE ] ; }
-    rule get-caller's-caller { return [ CALLER_MODULE 1 ] ; }
-    rule call-Y { return Y.call-X2 ; }
-}
-module Y {
-    rule call-X { return X.get-caller ; }
-    rule call-X2 { return X.get-caller's-caller ; }
-}
-callers = [ X.get-caller ] [ Y.call-X ] [ X.call-Y ] ;
-ECHO {$(callers)} ;
-
    - -

    The - DELETE_MODULE Rule

    - 
    -rule DELETE_MODULE ( module ? )
-
    - -

    DELETE_MODULE removes all of the variable bindings and - otherwise-unreferenced rules from the given module (or the global module, - if no module is supplied), and returns their memory to the system. - Note: though it won't affect rules that are currently executing - until they complete, DELETE_MODULE should be used with extreme - care because it will wipe out any others and all variable (including locals - in that module) immediately. Because of the way dynamic binding works, - variables which are shadowed by locals will not be destroyed, so the - results can be really unpredictable.

    - -

    Local For Loop - Variables

    - -

    Boost Jam allows you to declare a local for loop control - variable right in the loop:

    - 
    -x = 1 2 3 ;
-y = 4 5 6 ;
-for local y in $(x)
-{
-    ECHO $(y) ; # prints "1", "2", or "3"
-}
-ECHO $(y) ;     # prints "4 5 6"
-
    - -

    Negative - Indexing

    - -

    Classic Jam supplies 1-based list indexing, and slicing on a closed - (inclusive) range:

    - 
    -x = 1 2 3 4 5 ;
-ECHO $(x[3]) ;   # prints "3"
-ECHO $(x[2-4]) ; # prints "2 3 4"
-ECHO $(x[2-]) ;  # prints "2 3 4 5"
-
    - -

    Boost Jam adds Python-style negative indexing to access locations - relative to the end of the list.

    - 
    -ECHO $(x[-1]) $(x[-3]) ; # prints "5 3"
-ECHO $(x[-3--1]) ;       # prints "3 4 5"
-ECHO $(x[-3-4]) ;        # prints "3 4"
-ECHO $(x[2--2]) ;        # prints "2 3 4"       
-
    - -

    Consistency with the 1-based, inclusive indexing of Classic Jam and the - use of ``-'' as the range separator make this feature a bit - clumsier than it would otherwise need to be, but it does work.

    - -

    Support for - Cygwin

    - -

    When invoking Windows-based tools from Cygwin it can be important to pass them true - windows-style paths. Boost.Jam supplies the :W modifier which, - under Cygwin only, turns a cygwin path into a Win32 path using the - - cygwin_conv_to_win32_path function. On other platforms, the - string is unchanged.

    - 
    -x = /cygdrive/c/Program Files/Borland ;
-ECHO $(x:W) ; # prints "c:\Program Files\Borland" on Cygwin
-
    - -

    Target Binding Detection

    - -

    Whenever a target is bound to a location in the - filesystem, Boost Jam will look for a variable called BINDRULE - (first ``on'' the target being bound, then in the global module). - If non-empty, $(BINDRULE[1]) names a rule which is called with the - name of the target and the path it is being bound to. The signature of the - rule named by $(BINDRULE[1]) should match the following:

    - 
    -rule bind-rule ( target : path )
-
    - -

    This facility is useful for correct header file scanning, since many - compilers will search for #included files first in the directory - containing the file doing the #include directive. - $(BINDRULE) can be used to make a record of that directory.

    - -

    Return Code - Inversion

    - -

    For handling targets whose build actions are expected to fail (e.g. when - testing that assertions or compile-time type checkin work properly), Boost - Jam supplies a FAIL_EXPECTED rule in the same style as - NOCARE, et. al. During target updating, the return code of the - build actions for arguments to FAIL_EXPECTED is inverted: if it - fails, building of dependent targets continues as though it succeeded. If - it succeeds, dependent targets are skipped.

    - -

    Ignoring Return Codes

    - -

    Perforce Jam supplied a NOCARE rule which is typically used for - header files to indicate that if they are not found, the dependent targets - should be built anyway. Boost Jam extends NOCARE to apply to - targets with build actions: if their build actions exit with a nonzero - return code, dependent targets will still be built.

    - -

    Removing Outdated Targets

    - 
    -rule RMOLD ( targets * )
-
    - -

    Perforce Jam removes any target files that may exist on disk when the - rule used to build those targets fails. However, targets whose dependencies - fail to build are not removed by default. The RMOLD rule - causes its arguments to be removed if any of their dependencies fail to - build.

    - -

    The SUBST Rule

    - -

    Note: the SUBST rule is deprecated in favor of - Perforce Jam's built-in MATCH rule, which has been rolled into - Boost.Jam.

    - -

    The behavior of the SUBST rule for regular-expression matching - and replacement (originally added in FTJam) has been - modified:

    - -
      -
    • One or more replacement patterns may be supplied. The new signature - for SUBST is: - 
      -SUBST ( source pattern replacements + )
-
      The return value is the concatenated results of applying each element -of replacements in turn. For example, the following will print -``[x] (y) {z}'': - 
      -ECHO [ SUBST xyz (.)(.)(.) [$1] ($2) {$3} ] ;
-
      -
      • - -
    • If there is no match, SUBST now returns an empty list. In - FTJam, the original source string was returned, making it - awkward to check whether a pattern was matched.
      • - -
    • Compiled regular expressions are now internally cached, making it - much faster to use SUBST multiple times with the same - string.
      • -
    - -

    The JAM_VERSION global - variable

    - -

    A predefined global variable with two elements indicates the version - number of Boost Jam. Boost Jam versions start at "03" "00". - Earlier versions of Jam do not automatically define - JAM_VERSION.

    - -

    Debugging - Support

    - -

    The BACKTRACE - rule

    - 
    -rule BACKTRACE ( )
-
    - -

    Returns a list of quadruples: filename line module rulename..., - describing each shallower level of the call stack. This rule can be used to - generate useful diagnostic messages from Jam rules.

    - -

    The -d command-line option admits new arguments:

    - -
      -
    • -d+10 - enables profiling of rule invocations. When Jam exits, it - dumps all rules invoked, their gross and net times in platform-dependent - units, and the number of times the rule was invoked.
      • - -
    • -d+11 - enables parser debugging, if Jam has been compiled - with the "--debug" option to the parser generator named by $(YACC).
      • - -
    • -d+12 - enables dependency graph output . This feature was - ``stolen'' from a version of Jam modified by Craig McPheeters.
      • -
    - -

    The UPDATE rule and changes to - command line handling

    - -

    Classic jam treats any non-option element of command line as a name of - target to be updated. This prevented more sophisticated handling of command - line. This is now enabled again but with additional changes to the - UPDATE> rule to allow for the flexibility of changing the list - of targets to update. The UPDATE builtin rule is:

    - 
    -rule UPDATE ( targets * )
-
    - -

    The rule has two effects: 1. it clears the list of targets to update, - and 2. causes the specified targets to be updated. If no target was - specified with the UPDATE rule, no targets will be updated. To - support changing of the update list in more usefull ways, the rule also - returns the targets previously in the update list. This makes it possible - to add targets as such:

    - 
    -local previous-updates = [ UPDATE ] ;
-UPDATE $(previous-updates) a-new-target ;
-
    - -

    Semaphores

    - -

    It is sometimes desirable to disallow parallel execution of some - actions. For example:

    - -
      -
    • Old versions of yacc use files with fixed names. So, running - two yacc actions is dangerous.
      • - -
    • One might want to perform parallel compiling, but not do parallel - linking, because linking is i/o bound and only gets slower.
      • -
    Craig McPeeters has extended Perforce Jam to solve such problems, and - that extension was integrated in Boost.Jam. - -

    Any target can be assigned a semaphore, by setting a variable - called SEMAPHORE on that target. The value of the variable is the - semaphore name. It must be different from names of any declared target, but - is arbitrary otherwise.

    - -

    The semantic of semaphores is that in a group of targets which have the - same semaphore, only one can be updated at the moment, regardless of "-j" - option.

    - -

    The W32_GETREG rule

    - 
    -    rule W32_GETREG ( path : data ? )
-
    - -

    Defined only for win32 platform. It reads the registry of Windows. - 'path' is the location of the information, and 'data' is the name of the - value which we want to get. If 'data' is omitted, the default value of - 'path' will be returned. The 'path' value must conform to MS key path - format and must be prefixed with one of the predefined root keys. As - usual,

    - -
      -
    • 'HKLM' is equivalent to 'HKEY_LOCAL_MACHINE'.
      • - -
    • 'HKCU' is equivalent to 'HKEY_CURRENT_USER'.
      • - -
    • 'HKCR' is equivalent to 'HKEY_CLASSES_ROOT'.
      • -
    - -

    Other predefined root keys are not supported.

    - -

    Currently supported data types : 'REG_DWORD', 'REG_SZ', 'REG_EXPAND_SZ', - 'REG_MULTI_SZ'. The data with 'REG_DWORD' type will be turned into a - string, 'REG_MULTI_SZ' into a list of strings, and for those with - 'REG_EXPAND_SZ' type environment variables in it will be replaced with - their defined values. The data with 'REG_SZ' type and other unsupported - types will be put into a string without modification. If it can't receive - the value of the data, it just return an empty list. For example,

    - 
    -    local PSDK-location =
-    [ PROFILE HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\MicrosoftSDK\\Directories : "Install Dir" ] ;
-
    - -

    The ISFILE - Rule

    - 
    -rule ISFILE ( targets * )
-
    - -

    ISFILE marks targets as required to be files. This changes the - way jam searches for the target such that it ignores mathes for file - system items that are not file, like directories. This makes it possible to - avoid #include "exception" matching if one happens to have a - directory named exception in the header search path.

    - -

    The SHELL - Rule

    - 
    -rule SHELL ( command )
-
    - -

    SHELL executes command, and then returns the standard - output of command. SHELL only works on platforms with a popen() function - in the C library. On platforms without a working popen() function, - SHELL is implemented as a no-op. SHELL works on Unix, MacOS X, - and most Windows compilers. SHELL is a no-op on Metrowerks compilers - under Windows.

    . - -

    Jam - Fundamentals

    - -

    This section is derived from the official Jam documentation and from my - experience using it and reading the Jambase rules. I repeat the information - here mostly because it is essential to understanding and using Jam, but is - not consolidated in a single place. Some of it is missing from the official - documentation altogether. I hope it will be useful to anyone wishing to - become familiar with Jam and the Boost build system.

    - -

    · Jam ``rules'' are actually simple procedural entities. - Think of them as functions. Arguments are separated by colons.

    - -

    · A Jam target is an abstract entity identified by an - arbitrary string. The build-in DEPENDS rule creates a link in the - dependency graph between the named targets.

    - -

    · Note that the documentation for the built-in INCLUDES - rule is incorrect: INCLUDES targets1 : targets2 causes everything - that depends on a member of targets1 to depend on all members of - targets2. It does this in an odd way, by tacking targets2 - onto a special tail section in the dependency list of everything in - targets1. It seems to be OK to create circular dependencies this - way; in fact, it appears to be the ``right thing to do'' when a single - build action produces both targets1 and targets2.

    - -

    · When a rule is invoked, if there are actions - declared with the same name as the rule, the actions are added to - the updating actions for the target identified by the rule's first - argument. It is actually possible to invoke an undeclared rule if - corresponding actions are declared: the rule is treated as empty.

    - -

    · Targets (other than - NOTFILE targets) are associated with paths in the file system - through a process called binding. Binding - is a process of searching for a file with the same name as the target (sans - grist), based on the settings of the target-specific SEARCH and LOCATE - variables.

    - -

    · In addition - to local and global variables, jam allows you to set a variable - on a target. Target-specific variable values can usually - not be read, and take effect only in the following contexts:

    - -
      -
    • In updating actions, variable values are first looked up - on the target named by the first argument (the target - being updated). Because Jam builds its entire dependency tree before - executing actions, Jam rules make target-specific variable - settings as a way of supplying parameters to the corresponding - actions.
      • - -
    • Binding is controlled entirely by the target-specific setting - of the SEARCH and LOCATE variables, as described - here.
      • - -
    • In the special rule used for header file - scanning, variable values are first looked up on the - target named by the rule's first argument (the source file being - scanned).
      • -
    - -

    · The ``bound value'' of a variable is the path associated - with the target named by the variable. In build actions, the first - two arguments are automatically replaced with their bound values. - Target-specific variables can be selectively replaced by their bound values - using the bind action modifier.

    - -

    · Note that the term ``binding'' as used in the Jam documentation - indicates a phase of processing that includes three sub-phases: - binding (yes!), update determination, and header file scanning. The - repetition of the term ``binding'' can lead to some confusion. In - particular, the Modifying Binding - section in the Jam documentation should probably be titled ``Modifying - Update Determination''.

    - -

    · ``Grist'' is just a string prefix of the form - <characters>. It is used in Jam to create - unique target names based on simpler names. For example, the file name - ``test.exe'' may be used by targets in separate subprojects, or - for the debug and release variants of the ``same'' abstract target. Each - distinct target bound to a file called ``test.exe'' has its own - unique grist prefix. The Boost build system also takes full advantage of - Jam's ability to divide strings on grist boundaries, sometimes - concatenating multiple gristed elements at the beginning of a string. Grist - is used instead of identifying targets with absolute paths for two - reasons:

    - -
      -
    1. The location of targets cannot always be derived solely from what the - user puts in a Jamfile, but sometimes depends also on the binding process. Some mechanism to distinctly identify - targets with the same name is still needed.
      2. - -
    2. Grist allows us to use a uniform abstract identifier for each built - target, regardless of target file location (as allowed by setting - ALL_LOCATE_TARGET.
      3. -
    - -

    When grist is extracted from a name with - $(var:G), the result includes the leading and - trailing angle brackets. When grist is added to a name with - $(var:G=expr), existing grist is - first stripped. Then, if expr is non-empty, leading <s - and trailing >s are added if necessary to form an expression of - the form <expr2>; - <expr2> is then prepended.

    - -

    · When - Jam is invoked it imports all environment variable settings into - corresponding Jam variables, followed by all command-line (-s...) - variable settings. Variables whose name ends in PATH, - Path, or path are split into string lists on OS-specific - path-list separator boundaries (e.g. ":" for UNIX and ";" - for Windows). All other variables are split on space (" ") boundaries. - Boost Jam modifies that behavior by allowing variables to be quoted.

    - -

    · A variable whose value is an empty list or which - consists entirely of empty strings has a negative logical value. Thus, for - example, code like the following allows a sensible non-empty default which - can easily be overridden by the user:

    - 
    -MESSAGE ?= starting jam... ;
-if $(MESSAGE) { ECHO The message is: $(MESSAGE) ; }
-
    - -

    If the user wants a specific message, he invokes jam with - "-sMESSAGE=message text". If he wants no message, - he invokes jam with -sMESSAGE= and nothing at all is printed.

    - -

    · The parsing of command line options in Jam can be rather - unintuitive, with regards to how other Unix programs accept options. There - are two variants accepted as valid for an option:

    - -
      -
    1. -xvalue, and
      2. - -
    2. -x value.
      3. -
    - -

    Please also read The Jam language reference for - the additional details.

    -
    - -

    Revised - - 18 November, 2004 -

    - -

    Copyright 2003-2005 Rene Rivera, David Abrahams, Vladimir Prus.

    - -

    Distributed under the Boost Software License, Version 1.0. (See - accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)

    - -