diff --git a/doc/jamfile.jam b/doc/jamfile.jam index 1dfc0735dd..cb6dd180a0 100644 --- a/doc/jamfile.jam +++ b/doc/jamfile.jam @@ -11,7 +11,7 @@ Doc generation works in two modes: standalone embedded and website. For the standalone we just generate the local html for inclusion in a release archive. This is the default when no arguments are given. -For the website we clone the website branch locally, generatate the docs in +For the website we clone the website branch locally, generate the docs in the website tree, commit, and push. The default for those arguments is to build as if we are doing "develop" branch docs. diff --git a/doc/src/abstract-target.adoc b/doc/src/abstract-target.adoc index 0ef0ffb978..c769a18f1b 100644 --- a/doc/src/abstract-target.adoc +++ b/doc/src/abstract-target.adoc @@ -23,7 +23,7 @@ link:#b2.reference.class.abstract-target[abstract-target]: * basic-target -- -1. `rule __init__ ( name : project )` +1. `rule \\__init__ ( name : project )` + `name`:: The name of the target in the Jamfile. @@ -62,4 +62,4 @@ On success, returns: + If `property-set` is empty, performs the default build of this target, in a way specific to the derived class. --- \ No newline at end of file +-- diff --git a/doc/src/basic-target.adoc b/doc/src/basic-target.adoc index 7789ff2283..558b32f7bd 100644 --- a/doc/src/basic-target.adoc +++ b/doc/src/basic-target.adoc @@ -21,7 +21,7 @@ from sources. Allows sources to be either files or other main targets and handles generation of those dependency targets. -- -1. `rule __init__ ( name : project : sources * : requirements * : default-build * : usage-requirements * )` +1. `rule \\__init__ ( name : project : sources * : requirements * : default-build * : usage-requirements * )` + `name`:: The name of the target diff --git a/doc/src/bjam.adoc b/doc/src/bjam.adoc index 3ff4a96abf..5b453b70aa 100644 --- a/doc/src/bjam.adoc +++ b/doc/src/bjam.adoc @@ -270,7 +270,7 @@ targets. Pseudo-targets are symbols representing 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 `b2`s invocation, or +absolutely rooted, relative to the directory of ``b2``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 @@ -381,7 +381,7 @@ 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 +invoked for each element in the list of ``$(var)``s values. The fields `field1 : field2 : ...` are passed as arguments for each invocation For the [ ... ] forms, the return value is the concatenation of the return values for all of the invocations. @@ -663,7 +663,7 @@ WARNING: This is currently not fully implemented. [[jam.language.rules.builtins.utility]] ==== Utility -The two rules `ECHO` and `EXIT` are utility rules, used only in `b2`s +The two rules `ECHO` and `EXIT` are utility rules, used only in ``b2``s parsing phase. [[jam.language.rules.builtins.utility._echo__]] @@ -756,7 +756,7 @@ The `MATCH` rule does pattern matching. [source] ---- -rule MATCH ( regexps + : list * ) +rule MATCH ( regexps * : list * ) ---- Matches the `egrep`(1) style regular expressions _regexps_ against the @@ -768,12 +768,13 @@ for each string in _list_, and for each regular expression in _regexps_. [source] ---- -rule BACKTRACE ( ) +rule BACKTRACE ( levels ? ) ---- 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. +describing each shallower level of the call stack, or only last _levels_ +when the argument is provided. This rule can be used to generate useful +diagnostic messages from Jam rules. [[jam.language.rules.builtins.utility._update__]] ===== `UPDATE` diff --git a/doc/src/history.adoc b/doc/src/history.adoc index 7997a0ca56..976b322633 100644 --- a/doc/src/history.adoc +++ b/doc/src/history.adoc @@ -6,6 +6,9 @@ * Fix jam/{CPP} bind definitions of 4 or more values in a single declared argument not actually adding all the definitions. -- _Paolo Pastori_ +* *New*: Argument lists description provided for all built-in rules, + HDRMACRO and NOTIME discontinued. + -- _Paolo Pastori_ == Version 5.4.2 diff --git a/doc/src/reference.adoc b/doc/src/reference.adoc index 76fb92ee32..32f1ce399a 100644 --- a/doc/src/reference.adoc +++ b/doc/src/reference.adoc @@ -64,7 +64,7 @@ rule check-target-builds ( target message ? : true-properties * : false-properti + This function can only be used when passing requirements or usage requirements to a metatarget rule. For example, to make an application -link to a library if it's available, one has use the following: +link to a library if it's available, one has to use the following: + ---- exe app : app.cpp : [ check-target-builds has_foo "System has foo" : foo : FOO_MISSING=1 ] ; diff --git a/doc/src/typed-target.adoc b/doc/src/typed-target.adoc index d62b2199f4..9bbe4fc2a2 100644 --- a/doc/src/typed-target.adoc +++ b/doc/src/typed-target.adoc @@ -24,7 +24,7 @@ kind of target alternative. Rules for creating typed targets are defined automatically for each type. -- -1. `rule __init__ ( name : project : type : sources * : requirements * : default-build * : usage-requirements * )` +1. `rule \\__init__ ( name : project : type : sources * : requirements * : default-build * : usage-requirements * )` + `name`:: The name of the target diff --git a/src/engine/build.bat b/src/engine/build.bat index e57d25c7b0..92e9d8386a 100644 --- a/src/engine/build.bat +++ b/src/engine/build.bat @@ -172,7 +172,7 @@ set B2_SOURCES=%B2_SOURCES% command.cpp compile.cpp constants.cpp cwd.cpp set B2_SOURCES=%B2_SOURCES% debug.cpp debugger.cpp set B2_SOURCES=%B2_SOURCES% events.cpp set B2_SOURCES=%B2_SOURCES% execcmd.cpp execnt.cpp execunix.cpp filent.cpp filesys.cpp fileunix.cpp frames.cpp function.cpp -set B2_SOURCES=%B2_SOURCES% glob.cpp hash.cpp hcache.cpp hdrmacro.cpp headers.cpp jam.cpp +set B2_SOURCES=%B2_SOURCES% glob.cpp hash.cpp hcache.cpp headers.cpp jam.cpp set B2_SOURCES=%B2_SOURCES% jamgram.cpp lists.cpp make.cpp make1.cpp md5.cpp mem.cpp modules.cpp set B2_SOURCES=%B2_SOURCES% native.cpp output.cpp parse.cpp pathnt.cpp set B2_SOURCES=%B2_SOURCES% pathsys.cpp pathunix.cpp regexp.cpp rules.cpp scan.cpp search.cpp jam_strings.cpp diff --git a/src/engine/build.sh b/src/engine/build.sh index 1938704a25..46d0984e1e 100755 --- a/src/engine/build.sh +++ b/src/engine/build.sh @@ -443,7 +443,6 @@ function.cpp \ glob.cpp \ hash.cpp \ hcache.cpp \ -hdrmacro.cpp \ headers.cpp \ jam_strings.cpp \ jam.cpp \ diff --git a/src/engine/builtins.cpp b/src/engine/builtins.cpp index 29f1efc578..469ab2f841 100644 --- a/src/engine/builtins.cpp +++ b/src/engine/builtins.cpp @@ -14,7 +14,7 @@ #include "filesys.h" #include "frames.h" #include "hash.h" -#include "hdrmacro.h" +//#include "hdrmacro.h" // NOTE: Faulty feature HDRMACRO, discontinued. #include "lists.h" #include "make.h" #include "md5.h" @@ -54,7 +54,7 @@ # define FSCTL_GET_REPARSE_POINT 0x000900a8 #endif #ifndef IO_REPARSE_TAG_SYMLINK -# define IO_REPARSE_TAG_SYMLINK (0xA000000CL) +# define IO_REPARSE_TAG_SYMLINK (0xA000000CL) #endif #include @@ -97,10 +97,11 @@ * builtin_echo() - ECHO rule * builtin_exit() - EXIT rule * builtin_export() - EXPORT ( MODULE ? : RULES * ) - * builtin_flags() - NOCARE, NOTFILE, TEMPORARY rule + * builtin_flags() - ALWAYS/LEAVES/NOCARE/NOTIME/NOTFILE/NOUPDATE + * TEMPORARY/ISFILE/FAIL_EXPECTED/RMOLD rule * builtin_glob() - GLOB rule - * builtin_glob_recursive() - ??? - * builtin_hdrmacro() - ??? + * builtin_glob_recursive() - GLOB-RECURSIVELY rule + * builtin_hdrmacro() - HDRMACRO rule, faulty, discontinued * builtin_import() - IMPORT rule * builtin_match() - MATCH rule, regexp matching * builtin_rebuilds() - REBUILDS rule @@ -165,18 +166,27 @@ RULE * duplicate_rule( char const * name_, RULE * other ) void load_builtins() { - duplicate_rule( "Always", - bind_builtin( "ALWAYS", - builtin_flags, T_FLAG_TOUCHED, 0 ) ); + { + char const * args[] = { "targets", "*", 0 }; + duplicate_rule( "Always", + bind_builtin( "ALWAYS", + builtin_flags, T_FLAG_TOUCHED, args ) ); + } - duplicate_rule( "Depends", - bind_builtin( "DEPENDS", - builtin_depends, 0, 0 ) ); + { + char const * args[] = { "targets1", "*", ":", "targets2", "*", 0 }; + duplicate_rule( "Depends", + bind_builtin( "DEPENDS", + builtin_depends, 0, args ) ); + } - duplicate_rule( "echo", - duplicate_rule( "Echo", - bind_builtin( "ECHO", - builtin_echo, 0, 0 ) ) ); + { + char const * args[] = { "args", "*", 0 }; + duplicate_rule( "echo", + duplicate_rule( "Echo", + bind_builtin( "ECHO", + builtin_echo, 0, args ) ) ); + } { char const * args[] = { "message", "*", ":", "result-value", "?", 0 }; @@ -190,7 +200,7 @@ void load_builtins() char const * args[] = { "directories", "*", ":", "patterns", "*", ":", "case-insensitive", "?", 0 }; duplicate_rule( "Glob", - bind_builtin( "GLOB", builtin_glob, 0, args ) ); + bind_builtin( "GLOB", builtin_glob, 0, args ) ); } { @@ -199,9 +209,12 @@ void load_builtins() builtin_glob_recursive, 0, args ); } - duplicate_rule( "Includes", - bind_builtin( "INCLUDES", - builtin_depends, 1, 0 ) ); + { + char const * args[] = { "targets1", "*", ":", "targets2", "*", 0 }; + duplicate_rule( "Includes", + bind_builtin( "INCLUDES", + builtin_depends, 1, args ) ); + } { char const * args[] = { "targets", "*", ":", "targets-to-rebuild", "*", @@ -210,13 +223,19 @@ void load_builtins() builtin_rebuilds, 0, args ); } - duplicate_rule( "Leaves", - bind_builtin( "LEAVES", - builtin_flags, T_FLAG_LEAVES, 0 ) ); + { + char const * args[] = { "targets", "*", 0 }; + duplicate_rule( "Leaves", + bind_builtin( "LEAVES", + builtin_flags, T_FLAG_LEAVES, args ) ); + } - duplicate_rule( "Match", - bind_builtin( "MATCH", - builtin_match, 0, 0 ) ); + { + char const * args[] = { "regexps", "*", ":", "list", "*", 0 }; + duplicate_rule( "Match", + bind_builtin( "MATCH", + builtin_match, 0, args ) ); + } { char const * args[] = { "string", ":", "delimiters", 0 }; @@ -224,39 +243,61 @@ void load_builtins() builtin_split_by_characters, 0, args ); } - duplicate_rule( "NoCare", - bind_builtin( "NOCARE", - builtin_flags, T_FLAG_NOCARE, 0 ) ); + { + char const * args[] = { "targets", "*", 0 }; + duplicate_rule( "NoCare", + bind_builtin( "NOCARE", + builtin_flags, T_FLAG_NOCARE, args ) ); + } - duplicate_rule( "NOTIME", - duplicate_rule( "NotFile", - bind_builtin( "NOTFILE", - builtin_flags, T_FLAG_NOTFILE, 0 ) ) ); + { + char const * args[] = { "targets", "*", 0 }; + /*duplicate_rule( "NOTIME", // Bad alias, discontinued. */ + duplicate_rule( "NotFile", + bind_builtin( "NOTFILE", + builtin_flags, T_FLAG_NOTFILE, args ) ); + } - duplicate_rule( "NoUpdate", - bind_builtin( "NOUPDATE", - builtin_flags, T_FLAG_NOUPDATE, 0 ) ); + { + char const * args[] = { "targets", "*", 0 }; + duplicate_rule( "NoUpdate", + bind_builtin( "NOUPDATE", + builtin_flags, T_FLAG_NOUPDATE, args ) ); + } - duplicate_rule( "Temporary", - bind_builtin( "TEMPORARY", - builtin_flags, T_FLAG_TEMP, 0 ) ); + { + char const * args[] = { "targets", "*", 0 }; + duplicate_rule( "Temporary", + bind_builtin( "TEMPORARY", + builtin_flags, T_FLAG_TEMP, args ) ); + } - bind_builtin( "ISFILE", - builtin_flags, T_FLAG_ISFILE, 0 ); + { + char const * args[] = { "targets", "*", 0 }; + bind_builtin( "ISFILE", + builtin_flags, T_FLAG_ISFILE, args ); + } + /* NOTE: Faulty feature HDRMACRO, discontinued. duplicate_rule( "HdrMacro", bind_builtin( "HDRMACRO", - builtin_hdrmacro, 0, 0 ) ); + builtin_hdrmacro, 0, 0 ) ); */ - /* FAIL_EXPECTED is used to indicate that the result of a target build - * action should be inverted (ok <=> fail) this can be useful when - * performing test runs from Jamfiles. - */ - bind_builtin( "FAIL_EXPECTED", - builtin_flags, T_FLAG_FAIL_EXPECTED, 0 ); + { + /* FAIL_EXPECTED is used to indicate that the result of a target build + * action should be inverted (ok <=> fail) this can be useful when + * performing test runs from Jamfiles. + */ + char const * args[] = { "targets", "*", 0 }; + bind_builtin( "FAIL_EXPECTED", + builtin_flags, T_FLAG_FAIL_EXPECTED, args ); + } - bind_builtin( "RMOLD", - builtin_flags, T_FLAG_RMOLD, 0 ); + { + char const * args[] = { "targets", "*", 0 }; + bind_builtin( "RMOLD", + builtin_flags, T_FLAG_RMOLD, args ); + } { char const * args[] = { "targets", "*", 0 }; @@ -463,10 +504,10 @@ void load_builtins() #ifdef JAM_DEBUGGER - { - const char * args[] = { "list", "*", 0 }; - bind_builtin("__DEBUG_PRINT_HELPER__", builtin_debug_print_helper, 0, args); - } + { + const char * args[] = { "list", "*", 0 }; + bind_builtin("__DEBUG_PRINT_HELPER__", builtin_debug_print_helper, 0, args); + } #endif @@ -927,9 +968,13 @@ LIST * glob_recursive( char const * pattern ) } -/* - * builtin_glob_recursive() - ??? - */ +// +// builtin_glob_recursive() - GLOB-RECURSIVELY rule +// +// Recursively expands each of the provided patterns (GLOBs) into a list +// of paths. Each pattern can have different components for each directory +// e.g., */*.test +// LIST * builtin_glob_recursive( FRAME * frame, int flags ) { @@ -1078,9 +1123,9 @@ LIST * builtin_split_by_characters( FRAME * frame, int flags ) /* - * builtin_hdrmacro() - ??? - */ - + * builtin_hdrmacro() - HDRMACRO rule, faulty, discontinued + * + * LIST * builtin_hdrmacro( FRAME * frame, int flags ) { LIST * const l = lol_get( frame->args, 0 ); @@ -1091,7 +1136,7 @@ LIST * builtin_hdrmacro( FRAME * frame, int flags ) { TARGET * const t = bindtarget( list_item( iter ) ); - /* Scan file for header filename macro definitions. */ + // Scan file for header filename macro definitions. if ( is_debug_header() ) out_printf( "scanning '%s' for header file macro definitions\n", object_str( list_item( iter ) ) ); @@ -1100,7 +1145,7 @@ LIST * builtin_hdrmacro( FRAME * frame, int flags ) } return L0; -} +} */ /* diff --git a/src/engine/compile.cpp b/src/engine/compile.cpp index 921da42767..b835ea9d2a 100644 --- a/src/engine/compile.cpp +++ b/src/engine/compile.cpp @@ -28,7 +28,6 @@ #include "class.h" #include "constants.h" #include "hash.h" -#include "hdrmacro.h" #include "make.h" #include "modules.h" #include "parse.h" diff --git a/src/engine/hdrmacro.cpp b/src/engine/hdrmacro.cpp index 926424b93e..0811a5ffce 100644 --- a/src/engine/hdrmacro.cpp +++ b/src/engine/hdrmacro.cpp @@ -119,6 +119,11 @@ void macro_headers( TARGET * t ) object_free( symbol ); /* XXXX: FOR NOW, WE IGNORE MULTIPLE MACRO DEFINITIONS !! */ /* WE MIGHT AS WELL USE A LIST TO STORE THEM.. */ + /* + * NO, YOU CANNOT IGNORE A SYMBOL REDEFINITION, SINCE YOU STORE + * THE FIRST VERSION YOU SAW, WHILE PREPROCESSORS TYPICALLY + * OVERRIDE AND USE THE LATEST VERSION. + */ } } diff --git a/src/engine/hdrmacro.h b/src/engine/hdrmacro.h index 1489aef9cd..3862e6cb58 100644 --- a/src/engine/hdrmacro.h +++ b/src/engine/hdrmacro.h @@ -1,4 +1,6 @@ /* + * NOTE: faulty feature, discontinued. + * * Copyright 1993, 1995 Christopher Seiwald. * * This file is part of Jam - see jam.c for Copyright information. diff --git a/src/engine/headers.cpp b/src/engine/headers.cpp index 54b2da4a94..bc582d0bc6 100644 --- a/src/engine/headers.cpp +++ b/src/engine/headers.cpp @@ -27,7 +27,7 @@ #include "headers.h" #include "compile.h" -#include "hdrmacro.h" +//#include "hdrmacro.h" // NOTE: Faulty feature HDRMACRO, discontinued. #include "lists.h" #include "modules.h" #include "object.h" @@ -84,7 +84,7 @@ void headers( TARGET * t ) } /* Doctor up call to HDRRULE rule */ - /* Call headers1() to get LIST of included files. */ + /* Get LIST of included files. */ { FRAME frame[ 1 ]; frame_init( frame ); @@ -164,7 +164,9 @@ LIST * headers1( LIST * l, OBJECT * file, int rec, b2::regex::program re[] ) } } - /* Special treatment for #include MACRO. */ + /* NOTE: Faulty feature HDRMACRO, discontinued. + * + // Special treatment for #include MACRO. auto re_macros_i = re_macros.search( buf ); if ( re_macros_i && re_macros_i[ 1 ].end() != nullptr ) { @@ -187,7 +189,7 @@ LIST * headers1( LIST * l, OBJECT * file, int rec, b2::regex::program re[] ) if ( is_debug_header() ) out_printf( " ignored !!\n" ); } - } + } */ } fclose( f ); diff --git a/src/engine/mod_jam_class.h b/src/engine/mod_jam_class.h index f1fa2a7e14..3f3e05652e 100644 --- a/src/engine/mod_jam_class.h +++ b/src/engine/mod_jam_class.h @@ -35,7 +35,7 @@ Jam:: `rule new ( class args * : * )` & rest, bind::context_ref_ context_ref)` ==== -Instantiates a new instance of the given class and calls the `__init__` with +Instantiates a new instance of the given class and calls the `\\__init__` with the given arguments. Returns the instance ID. end::reference[] */ diff --git a/src/engine/mod_jam_modules.h b/src/engine/mod_jam_modules.h index 194b046d85..a20f7f538b 100644 --- a/src/engine/mod_jam_modules.h +++ b/src/engine/mod_jam_modules.h @@ -37,11 +37,11 @@ modules A and B both use a variable named X, each one gets its own copy of X. They won't interfere with each other in any way. Similarly, importing rules into one module has no effect on any other module. -Every module has two special variables. `$(__file__)` contains the name -of the file that the module was loaded from and `$(__name__)` contains +Every module has two special variables. `$(\\__file__)` contains the name +of the file that the module was loaded from and `$(\\__name__)` contains the name of the module. -NOTE: `$(__file__)` does not contain the full path to the file. If you need +NOTE: `$(\\__file__)` does not contain the full path to the file. If you need this, use `modules.binding`. end::reference[] */ @@ -229,7 +229,7 @@ Jam:: `rule run-tests ( m )` ==== Runs internal B2 unit tests for the specified module. The module's -`__test__` rule is executed in its own module to eliminate any inadvertent +`\\__test__` rule is executed in its own module to eliminate any inadvertent effects of testing module dependencies (such as assert) on the module itself. end::reference[] */ diff --git a/src/tools/python.jam b/src/tools/python.jam index dceeed5303..bd472b9d32 100644 --- a/src/tools/python.jam +++ b/src/tools/python.jam @@ -174,7 +174,7 @@ local rule is-cygwin-symlink ( path ) local base-pat = [ regex.escape $(path:D=) : "].[()*+?|\\$^" : \\ ] ; # Extract the file's size from the directory listing. - local size-of-system-file = [ MATCH "([0-9]+) "$(base-pat) : $(dir-listing) : 1 ] ; + local size-of-system-file = [ MATCH "([0-9]+) "$(base-pat) : $(dir-listing) ] ; # If the file has a reasonably small size, look for the special symlink # identification text. @@ -186,7 +186,7 @@ local rule is-cygwin-symlink ( path ) local nl = " " ; - is-symlink = [ MATCH ".*!([^"$(nl)"]*)" : $(link[1]) : 1 ] ; + is-symlink = [ MATCH ".*!([^"$(nl)"]*)" : $(link[1]) ] ; if $(is-symlink) { is-symlink = [ *nix-path-to-native $(is-symlink) ] ; @@ -396,7 +396,7 @@ local rule path-to-native ( paths * ) # local rule split-version ( version ) { - local major-minor = [ MATCH "^([0-9]+)\.([0-9]+)(.*)$" : $(version) : 1 2 3 ] ; + local major-minor = [ MATCH "^([0-9]+)\.([0-9]+)(.*)$" : $(version) ] ; if ! $(major-minor[2]) || $(major-minor[3]) { ECHO "Warning: \"using python\" expects a two part (major, minor) version number; got" $(version) instead ;