Brief introduction of BJAM - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - BJAM is a project management tool similar to Make. It is specifically customized to Boost, which is based on ftjam, Ftjam is developed from Perforce Jam. Bjam is compatible with Perforce Jam.
The BJAM tool is maintained by the Boost.jam project.
The latest version of BJAM is: 3.1.9 (released with Boost-1.31.0). It is based on 2.4 of JAM / MR. Its authorization is: / / / 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 itfreely, as long as this copyright notice is retained and modificationsare clearly marked.ALL WARRANTIES ARE HEREBY dISCLAIMED.
BJAM execution process - == - == - == - == - == - == - == - == - == - == - == - == - == - = = - == - == - == - == - == - == - == -
BJAM consists of bjam.exe and some project profiles (written by JAM).
The BJAM execution process is divided into four processes:
Startup BJAM introduces all environment variables into the JAM execution environment. At the same time, the command line is also introduced into the execution environment.
Parsing (Analysis) BJAM Reads Jambase File. If you don't exist, you will read into built-in Jambase. The last instruction of the built-in Jambase is an include (included) Jamfile file. This is a file provided by the user, its effect is equivalent to Makefile Jambase and Jamfile functions (1) Define targets and source files, and their dependencies Jambase files define basic Rule (rules) and variables. Jamfile uses these rule to specify dependencies.
Binding is divided into three steps:
Binding JAM loops traverses the dependence tree, associates the file target with real files. If there is a ring-dependent dependency, it will be reported. The file target is represented by an absolute path or relative path, which is generally bound to the corresponding file, but by modifying $ ( Search and $ (locate) can modify the way the file target is associated with the real file. See the Rule reference.
Update Determination After completing binding, Jam will decide which file targets need to be updated. The file does not exist, one of the files than one of the files or its source file is marked as being updated, and the target will be marked as needed. You can pass Always, Leaves, Nocare, NotFile, NOUPDATE, and TEMPORARYRULE modify the update rule.
Header File Scanning JAM also scans the file to discover the C style header file reference. This line is controlled by $ (HDRSCAN) and $ (HDRrule) variable. Scan results are relying on the dependencies. Updating ( Update) After completing the binding process, JAM will loop the dependency tree, which will execute each marked as an update process associated with the update target. If -j is specified, JAM will execute it sequentially .jam language definition - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == -
The lexical JAM believes that all markers are separated by blank characters (BLANKS, TABS, OR NEWLINES). Including symbols (:) and (;) must also be separated by blank character.
Exception: In the marker surrounded by quotation marks ("), blank symbols can be used. Symbol (/) can escape quotation marks and blank characters.
The string surrounded by {} can use blank symbols and considered just a string.
Keywords, when doing a marker, you must use quotation marks to surround.
Built-in rule semantics - == - == - == - == - == - == - == - == - == - == - == - == - == - = = - == - == - == - == - == - == - == -
Content dependency
Depends Targets1: Targets2; use Target1 depends on Targets2, if Targets2 is new than Targets1, Targets1 will be rebuilt. Includes targets1: targets2; constructs the same dependency, making the target dependent on targets2 also dependen on targets1.
2. Modify dependency
Always targets;
Leaves Targets;
Nocare targets;
NOTFILE TARGETS;
Noupdate Targets;
Temporary Targets;
3. Tool Echo args; display parameters
Exit args; display parameters, and exit.
Glob Director: Patterns: DownCase-OPT Takes the file name that meets Patterns in Directories.
Match Regexps: List Takes out symbols that meet the regexps from the list.
Process control - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == -
------------------------------- for var in list {statements} ----------- ---------------------
Perform a Statements in each of the LIST, VAR is designed to be a value of a list element.
------------------------------------------------------------------------------------------------------------------------------------------------------- ----------------------- Obviously, the ELSE part is optional.
The condition can be: a When a non-empty string is at least a non-empty string; a = b list element is true when Truea! = B list elements are not exactly the same time, TRUEA = b A Each element is larger than the element large or equal A IN B A all elements can be found in B. Or a is a holiday! COND logic is non-COND && COND logic and COND || COND logic or (COND) priority operation
----------------------------------------- -----------------
Use JAM to read file and process it. This process occurs during the parsing phase, so FILE will not be built, no file range.
-------------------------------- Local Vars [= VALUES]; ----------- ---------------------
Define a local variable, and return to the value of the original variable outside {}.
----------------------------------------- -----------------
Set the return value, Note In the Rule, Return does not jump out of the execution of the rule.
------------------------------- Switch value {copy pattern1: statements; case pattern2: statements; ...} ------------------------------ Performed once or zero based on Value. Pattern can be the following symbolic wildcard
• Match an arbitrary character * Match zero or more characters [Chars] Match any of Chars [^ chars] matching any character / x matching X (escape other wildcard)
------------------------------------------------------- -------------------
When the conditions are true, STATEMENT is executed repeatedly.
Variable control and built-in variable - == - == - == - == - == - == - == - == - == - == - == - == - == - - == - == - == - == - == - == - == - == -
The JAM variable is a string list, which may be 0, or multiple strings. An undefined variable is not distinguished, but a variable can be defined as a number of Empty string.
Variables can be valued by $ (variable)
The variable has two "global" or "dedicated dedicated". The target-specific variable is only valued when the target is constructed.
The variable definitions have the following ways. Variable = Elements; variable = Elements; variable on targets = Elements; variable on targets = Elements; variable default = elements; variable? = Elements; first two ways define global variables, Three and fourth methods define target-specific variables. = I can override the contents of the variables. = Connect the original content and new content. The last two effects are consistent: When the variable is not defined, a global variable is defined.
Command line option - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == - == -
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 PERGET-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 remodes.
FDefines defines; Expands a list of definitions Into a list of compiler (Such as -dsymbol = val on) 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 source;
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 is not 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 (EG, 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 I The Suffix of Each of Sources. Installshell Dir: Sources; Copy 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 Reference WITHOUT A SUFFIX IN This Rule Invocation
Main image: Sources; Compiles Sources and links the...............................
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) SUBDI R Var D1 ... DN; Sets Up Housekeeping for the Source Files Located in $ (VAR) / D1 / Man 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 D1 THROUGH DN. 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 SUFFIX ES 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. Products 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 * rulesIn addition, Jambase makes the jam default target "all" depend on "exe", "lib", "OBJ", "files", and "shell".
-------------------------------------------------- ------------------------------
.
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. (Ie, 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 per missions for Chmod rule. CP The file copy program, used by File and Install * rules. CRELIB If set, causes the Library rule invoke the CreLib rule on the target library before attempting to archive any members, so that the library can be created to 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 $ ( (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 include file. HDRRULE Name of the rule to invoke with the results of header file scanning. Default is "hdrrule". this is a jam-special vari Able. 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 . (Ie, 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. (Ie, 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 not 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 not be updated, but only created whole. OPTIM The C compiler flag for optimization, used by Cc and C rules. OSFULL The concatenation 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 map orthit get 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 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'
