diff --git a/historic/jam/doc/bjam.qbk b/historic/jam/doc/bjam.qbk index 971899c20..c770cc422 100644 --- a/historic/jam/doc/bjam.qbk +++ b/historic/jam/doc/bjam.qbk @@ -25,10 +25,10 @@ [/ Images ] -[def :note: [$images/note.png]] -[def :alert: [$images/caution.png]] -[def :detail: [$images/note.png]] -[def :tip: [$images/tip.png]] +[def :NOTE: [$images/note.png]] +[def :ALERT: [$images/caution.png]] +[def :DETAIL: [$images/note.png]] +[def :TIP: [$images/tip.png]] [/ Links ] @@ -73,6 +73,189 @@ Jam isn't under the blinkin GNU copyright, so you can incorporate it into commer [endsect] [section:building Building BJam] + +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: + +[pre +/build/ \[/toolset/\] +] + +Running the scripts without arguments will give you the best chance of success. On Windows platforms from a command console do: + +[pre +cd /jam source location/ +.\\build.bat +] + +On Unix type platforms do: + +[pre +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: + +[table Supported Toolsets + +[[Script] [Platform] [Toolset] [Detection]] + +[ [=build.bat=] [Windows NT, 2000, and XP] + [ [@http://www.comeaucomputing.com/ =como=]\n + Comeau Computing C/C++] + [ +] ] + +[ [] [] + [ [@http://www.borland.com/bcppbuilder/freecompiler =borland=]\n + [@http://www.borland.com/ Borland] C++Builder (BCC 5.5)] + [ * Common install location: "=C:\\Borland\\BCC55="\n + * =BCC32.EXE= in =PATH= +] ] + +[ [] [] + [ [@http://gcc.gnu.org/ =gcc=]\n + GNU GCC] + [ +] ] + +[ [] [] + [ [@http://gcc.gnu.org/ =gcc-nocygwin=]\n + GNU GCC] + [ +] ] + +[ [] [] + [ [@http://www.intel.com/software/products/compilers/c60 =intel-win32=]\n + Intel C++ Compiler for Windows] + [ * =ICL.EXE= in =PATH= +] ] + +[ [] [] + [ [@http://www.metrowerks.com/ =metrowerks=]\n + MetroWerks CodeWarrior C/C++ 7.x, 8.x, 9.x] + [ * =CWFolder= variable configured + * =MWCC.EXE= in =PATH= +] ] + +[ [] [] + [ [@http://www.mingw.org/ =mingw=]\n + GNU [@http://gcc.gnu.org/ GCC] as the [@http://www.mingw.org/ MinGW] configuration] + [ * Common install location: "=C:\MinGW=" +] ] + +[ [] [] + [ [@http://msdn.microsoft.com/visualc/ =msvc=]\n + 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= +] ] + +[ [] [] + [ [@http://msdn.microsoft.com/visualc/ =msvc=]\n + 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=" +] ] + +[ [] [] + [ [@http://msdn.microsoft.com/visualc/ =msvc=]\n + Microsoft Visual C++ 8.x] + [ +] ] + +[ [=build.sh=] [Unix, Linux, Cygwin, etc.] + [ [@http://www.hp.com/go/c++ =acc=]\n + HP-UX aCC] + [ * =aCC= in =PATH=\n + * =uname= is "HP-UX" +] ] + +[ [] [] + [ [@http://www.comeaucomputing.com/ =como=]\n + Comeau Computing C/C++] + [ * como in =PATH= +] ] + +[ [] [] + [ [@http://gcc.gnu.org/ =gcc=]\n + GNU GCC] + [ * gcc in =PATH= +] ] + +[ [] [] + [ [@http://www.intel.com/software/products/compilers/c60l/ =intel-linux=]\n + Intel C++ for Linux] + [ * =icc= in =PATH= + * Common install locations: "=/opt/intel/compiler70=", "=/opt/intel/compiler60=", "=/opt/intel/compiler50=" +] ] + +[ [] [] + [ =kcc=\n + Intel KAI C++] + [ * =KCC= in =PATH= +] ] + +[ [] [] + [ [@http://www.borland.com/bcppbuilder/freecompiler =kylix=]\n + [@http://www.borland.com/ Borland] C++Builder] + [ * bc++ in PATH +] ] + +[ [] [] + [ [@http://www.sgi.com/developers/devtools/languages/mipspro.html =mipspro=]\n + SGI MIPSpro C] + [ +] ] + +[ [] [] + [ =sunpro=\n + Sun Workshop 6 C++] + [ * Standard install location: "=/opt/SUNWspro=" +] ] + +[ [] [] + [ [@http://www.tru64unix.compaq.com/cplus/ =true64cxx=]\n + Compaq C++ Compiler for True64 UNIX] + [ +] ] + +[ [] [] + [ [@http://www-3.ibm.com/software/ad/vacpp/ =vacpp=]\n + IBM VisualAge C++] + [ * =xlc= in =PATH= +] ] + +[ [] [MacOS X] + [ [@http://developer.apple.com/tools/compilers.html =darwin=]\n + 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: + +[pre +/build/ \[/toolset/\] \[--/option/+ /target/*\] +] + +There is currently 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. + [endsect] [section:usage Using BJam] @@ -87,9 +270,7 @@ bjam ( -option \[value\] | target ) * Options are either singular or have an accompanying value. When a value is allowed, or required, it can be either given as an argument following the option argument, or it can be given immediately after the option as part of the option argument. The allowed options are: -[table - - [] +[variablelist [ [[^-a]] [Build all targets anyway, even if they are up-to-date.] ] @@ -150,6 +331,22 @@ Options are either singular or have an accompanying value. When a value is allow [Print the version of =bjam= and exit.] ] ] +[section 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: + +[pre +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: + +[pre +set MSVCNT=""C:\\Program Files\\Microsoft Visual C++\\VC98\\"" +] + +[endsect] + [endsect] [section:operation Operation] @@ -162,6 +359,16 @@ Upon start-up, =bjam= imports environment variable settings into =bjam= variable 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 bjam's execution, use the =-d+7= option. +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. + +# 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. + +# 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. + +# 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. + +# If the =bootstrap.jam= file was not found, we print a likely error message and exit. + [endsect] [section:parsing Parsing] @@ -224,6 +431,18 @@ The essential =bjam= data entity is a target. Built targets are files to be upda A file target's identifier is generally the file's name, which can be absolutely rooted, relative to the directory of =bjam='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 [link jam.language.variables.builtins.search 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). +[section 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: + +[pre +rule /bind-rule/ ( /target/ : /path/ ) +] + +This facility is useful for correct header file scanning, since many compilers will search for `#include` files first in the directory containing the file doing the `#include` directive. =$(BINDRULE)= can be used to make a record of that directory. + +[endsect] + [endsect] [section:rules Rules] @@ -288,9 +507,7 @@ The variable's value names the rule (or rules) to be invoked. A rule is invoked The following action modifiers are understood: -[table - -[] +[variablelist [[[^actions bind /vars/]] [[^$(/vars/)] will be replaced with bound values.]] @@ -317,6 +534,47 @@ The following action modifiers are understood: [endsect] +[section Argument lists] + +You can 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: + +[pre +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: + +[table +[[Symbol] [Semantics 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: + +[pre +### 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. + +[endsect] + [section:builtins Built-in Rules] =BJam= has a growing set of 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. @@ -366,6 +624,8 @@ NOCARE /targets/ ; Causes =bjam= to ignore /targets/ that neither can be found nor have updating actions to build them. Normally for such targets =bjam= 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 =bjam= know that the included files may not exist. For example, if an `#include` is within an `#ifdef`, the included file may not actually be around. +[warning For targets with build actions: if their build actions exit with a nonzero return code, dependent targets will still be built.] + [pre NOTFILE /targets/ ; ] @@ -382,7 +642,27 @@ Causes the timestamps on /targets/ to be ignored. This has two effects: first, o 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, =bjam= 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. +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, =bjam= 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. + +[pre +FAIL_EXPECTED /targets/ ; +] + +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 the =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. + +[pre +RMOLD /targets/ ; +] + +=BJam= 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. + +[pre +rule ISFILE ( /targets/ * ) +] + +=ISFILE= marks targets as required to be files. This changes the way =bjam= 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. + +[warning This is currently not fully implemented.] [endsect] @@ -422,6 +702,53 @@ 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. +[pre +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. + +[pre +rule UPDATE ( /targets/ * ) +] + +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 rule has two effects: + +# It clears the list of targets to update, and +# 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: + +[pre +local previous-updates = \[ UPDATE \] ; +UPDATE $(previous-updates) a-new-target ; +] + +[pre +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, + +[pre +local PSDK-location = + \[ PROFILE HKEY_LOCAL_MACHINE\\\\SOFTWARE\\\\Microsoft\\\\MicrosoftSDK\\\\Directories : "Install Dir" \] ; +] + +[pre +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. + [endsect] [endsect] @@ -445,11 +772,9 @@ if /cond/ { /statements/ } Does the obvious; the =else= clause is optional. /cond/ is built of: -[table +[variablelist -[] - -[[[^['a']]] +[[[^['a]]] [true if any ['a] element is a non-zero-length string]] [[[^['a] = ['b]]] @@ -518,9 +843,7 @@ switch /value/ 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: -[table - -[] +[variablelist [[[^?]] [match any single character]] @@ -606,18 +929,16 @@ $(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: -[table - -[] +[variablelist [[[^\[['n]\]]] - [Select element number ['n] (starting at 1). If the variable contains fewer than ['n] elements, the result is a zero-element list.]] + [Select element number ['n] (starting at 1). If the variable contains fewer than ['n] elements, the result is a zero-element list. ['n] can be negative in which case the element number ['n] from the last leftward is returned]] [[[^\[['n]-['m]\]]] - [Select elements number ['n] through ['m].]] + [Select elements number ['n] through ['m]. ['n] and ['m] can be negative in which case they refer to elements counting from the last leftward.]] [[[^\[['n]-\]]] - [Select elements number ['n] through the last.]] + [Select elements number ['n] through the last. ['n] can be negative in which case it refers to the element counting from the last leftward.]] [[[^:B]] [Select filename base.]] @@ -643,6 +964,9 @@ A variable element's string value can be parsed into grist and filename-related [[[^:L]] [Replace uppercase characters with lowercase.]] +[[[^:W]] + [When invoking Windows-based tools from [@http://www.cygwin.com/ Cygwin] it can be important to pass them true windows-style paths. Tthe =:W= modifier which, *under Cygwin only*, turns a cygwin path into a Win32 path using the [@http://www.cygwin.com/cygwin-api/func-cygwin-conv-to-win32-path.html =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]]] + [[[^:['chars]]] [Select the components listed in ['chars].]] @@ -676,25 +1000,430 @@ On VMS, [^$(var:P)] is the parent directory of [^$(var:D)]. [endsect] +[section Local For Loop Variables] + +Boost Jam allows you to declare a local for loop control variable right in the loop: + +[pre +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" +] + +[endsect] + [section:builtins Built-in Variables] +This section discusses variables that have special meaning to =bjam=. + [section:search SEARCH and LOCATE] + +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, =bjam= 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. + [endsect] [section:hdrscan HDRSCAN and HDRRULE] + +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 =bjam= 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, =bjam= 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). + +[endsect] + +[section 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. + [endsect] [section Platform Identifier] + +A number of Jam built-in variables can be used to identify runtime platform: + +[variablelist +[[=OS=] [OS identifier string]] +[[=OSPLAT=] [Underlying architecture, when applicable]] +[[=MAC=] [true on MAC platform]] +[[=NT=] [true on NT platform]] +[[=OS2=] [true on OS2 platform]] +[[=UNIX=] [true on Unix platforms]] +[[=VMS=] [true on VMS platform]] +] + [endsect] [section Jam Version] + +[variablelist +[[=JAMDATE=] [Time and date at =bjam= start-up.]] +[[=JAMUNAME=] [Ouput of uname(1) command (Unix only)]] +[[=JAMVERSION=] [=bjam= version, currently ":version:"]] +[[=JAM_VERSION=] [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=.]] +] + [endsect] [section JAMSHELL] -[endsect] + +When =bjam= 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: + +[pre +JAMSHELL = /bin/sh -c % ; +] + +The =%= is replaced with the text of the action block. + +=BJam= 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 =bjam= 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: + +[pre +#!/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 +] [endsect] [endsect] [endsect] + +[section Modules] + +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. + +[section Declaration] + +[pre +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: + +[pre +*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: + +[pre +module your_module +{ + rule bedtime ( ) { *my_module.salute* goodnight ; } +} +] + +[endsect] + +[section 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: + +[pre +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: + +[pre +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. + +[endsect] + +[section Local Rules] + +[pre +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: + +[pre +\[ RULENAMES /module-name/ \] +] + +[endsect] + +[section The =RULENAMES= Rule] + +[pre +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. + +[endsect] + +[section The =VARNAMES= Rule] + +[pre +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.] + +[endsect] + +[section The =IMPORT= Rule] + +=IMPORT= allows rule name aliasing across modules: + +[pre +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, + +[pre +# 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 \] ; +] + +[endsect] + +[section The =EXPORT= Rule] + +=EXPORT= allows rule name aliasing across modules: + +[pre +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, + +[pre +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. +] + +[endsect] + +[section The =CALLER_MODULE= Rule] + +[pre +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}": + +[pre +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)} ; +] + +[endsect] + +[section The =DELETE_MODULE= Rule] + +[pre +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.] + +[endsect] + +[endsect] + +[endsect] + +[section Miscellaneous] + +[section Diagnostics] + +In addition to generic error messages, =bjam= may emit one of the following: + +[pre warning: unknown rule X] + +A rule was invoked that has not been defined with an "=actions=" or "=rule=" statement. + +[pre using N temp target(s)] + +Targets marked as being temporary (but nonetheless present) have been found. + +[pre updating N target(s)] + +Targets are out-of-date and will be updated. + +[pre can't find N target(s)] + +Source files can't be found and there are no actions to create them. + +[pre can't make N target(s)] + +Due to sources not being found, other targets cannot be made. + +[pre warning: X depends on itself] + +A target depends on itself either directly or through its sources. + +[pre don't know how to make X] + +A target is not present and no actions have been defined to create it. + +[pre X skipped for lack of Y] + +A source failed to build, and thus a target cannot be built. + +[pre warning: using independent target X] + +A target that is not a dependency of any other target is being referenced with =$(<)= or =$(>)=. + +[pre X removed] + +=BJam= removed a partially built target after being interrupted. + +[endsect] + +[section Bugs, Limitations] + +The =-j= flag can cause =bjam= to get confused when single actions update more than one target at a time. =bjam= 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. + +[endsect] + +[section Fundamentals] + +This section is derived from the official Jam documentation and from experience using it and reading the Jambase rules. We 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. We 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 . 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: + + # 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. + # 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. + +* 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 are added if necessary to form an expression of the form ; 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: + + # =-xvalue=, and + # =-x value=. + +[endsect] + +[endsect]