Skip to content

documentation maintanence #560

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
paolopas wants to merge 4 commits into
base: main
Choose a base branch
from
Open

documentation maintanence #560

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5b94428
documentation maintanence
paolopas Feb 16, 2026
fcf82e6
minor "function" -> "rule" substitutuins in
paolopas Feb 21, 2026
2fcaf75
fixed regex in example in §8.4 Scanners
paolopas Feb 21, 2026
8b3e344
fixed example in §8.7 Main target rules
paolopas Feb 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
226 changes: 112 additions & 114 deletions doc/src/bjam.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -471,7 +471,8 @@ any new Jam code you write.
`B2` 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.
are just utility rules. A fourth set of rules relating to modules are
described in link:#jam.language.modules[Modules].

[[jam.language.rules.builtins.dependency_building]]
==== Dependency Building
Expand Down Expand Up @@ -663,8 +664,18 @@ 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
parsing phase.
[[jam.language.rules.builtins.utility._backtrace__]]
===== `BACKTRACE`

[source]
----
rule BACKTRACE ( levels ? )
----

Returns a list of quadruples: _filename_ _line_ _module_ _rulename_...,
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._echo__]]
===== `ECHO`
Expand Down Expand Up @@ -692,6 +703,20 @@ _result-value_.
`ECHO` and `EXIT`, since it is hard to tell that these are built-in
rules and not part of the language, like `include`.

[[jam.language.rules.builtins.utility._file_open__]]
===== `FILE_OPEN`

[source]
----
rule FILE_OPEN ( filename : mode )
----

The `FILE_OPEN` rule opens the specified file and returns a file
descriptor if the _mode_ parameter is either "w" or "r". Note that at
present, only the `UPDATE_NOW` rule can use the resulting file
descriptor number. If the _mode_ parameter is "t" this opens the file as a
text file and returns the contents as a single string.

[[jam.language.rules.builtins.utility._glob__]]
===== `GLOB`

Expand Down Expand Up @@ -787,18 +812,80 @@ Matches the `egrep`(1) style regular expressions _regexps_ against the
strings in _list_. The result is a list of matching `()` subexpressions
for each string in _list_, and for each regular expression in _regexps_.

[[jam.language.rules.builtins.utility._backtrace__]]
===== `BACKTRACE`
[[jam.language.rules.builtins.utility._md5__]]
===== `MD5`

[source]
----
rule BACKTRACE ( levels ? )
rule MD5 ( string )
----

Returns a list of quadruples: _filename_ _line_ _module_ _rulename_...,
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.
`MD5` computes the MD5 hash of the string passed as parameter and
returns it.

[[jam.language.rules.builtins.utility._pad__]]
===== `PAD`

[source]
----
rule PAD ( string : width )
----

If _string_ is shorter than _width_ characters, pads it with whitespace
characters on the right, and returns the result. Otherwise, returns
_string_ unmodified.

[[jam.language.rules.builtins.utility._precious__]]
===== `PRECIOUS`

[source]
----
rule PRECIOUS ( targets * )
----

The `PRECIOUS` rule specifies that each of the targets passed as the
arguments should not be removed even if the command updating that target
fails.

[[jam.language.rules.builtins.utility._shell__]]
===== `SHELL`

[source]
----
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. There is a variable set of allowed options as additional
arguments:

`exit-status`::
In addition to the output the result status of the executed command is
returned as a second element of the result.
`no-output`::
Don't capture the output of the command. Instead an empty ("") string
value is returned in place of the output.
`strip-eol`::
Remove trailing end-of-line character from output, if any.

Because the Perforce/Jambase defines a `SHELL` rule which hides the
builtin rule, `COMMAND` can be used as an alias for `SHELL` in such a
case.

[[jam.language.rules.builtins.utility._split_by_characters__]]
===== `SPLIT_BY_CHARACTERS`

[source]
----
rule SPLIT_BY_CHARACTERS ( string : delimiters )
----

`SPLIT_BY_CHARACTERS` splits the specified _string_ on any delimiter
character present in _delimiters_ and returns the resulting list.

[[jam.language.rules.builtins.utility._update__]]
===== `UPDATE`
Expand Down Expand Up @@ -828,6 +915,21 @@ local previous-updates = [ UPDATE ] ;
UPDATE $(previous-updates) a-new-target ;
----

[[jam.language.rules.builtins.utility._update_now__]]
===== `UPDATE_NOW`

[source]
----
rule UPDATE_NOW ( targets * : log ? : ignore-minus-n ? )
----

The `UPDATE_NOW` caused the specified targets to be updated immediately.
If update was successful, non-empty string is returned. The _log_
parameter, if present, specifies a descriptor of a file where all output
from building is redirected. If the _ignore-minus-n_ parameter is
specified, the targets are updated even if the `-n` parameter is
specified on the command line.

[[jam.language.rules.builtins.utility._w32_getreg__]]
===== `W32_GETREG`

Expand Down Expand Up @@ -904,110 +1006,6 @@ for local subkey in $(subkeys)
}
----

[[jam.language.rules.builtins.utility._shell__]]
===== `SHELL`

[source]
----
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. There is a variable set of allowed options as additional
arguments:

`exit-status`::
In addition to the output the result status of the executed command is
returned as a second element of the result.
`no-output`::
Don't capture the output of the command. Instead an empty ("") string
value is returned in place of the output.
`strip-eol`::
Remove trailing end-of-line character from output, if any.

Because the Perforce/Jambase defines a `SHELL` rule which hides the
builtin rule, `COMMAND` can be used as an alias for `SHELL` in such a
case.

[[jam.language.rules.builtins.utility._md5__]]
===== `MD5`

[source]
----
rule MD5 ( string )
----

`MD5` computes the MD5 hash of the string passed as parameter and
returns it.

[[jam.language.rules.builtins.utility._split_by_characters__]]
===== `SPLIT_BY_CHARACTERS`

[source]
----
rule SPLIT_BY_CHARACTERS ( string : delimiters )
----

`SPLIT_BY_CHARACTERS` splits the specified _string_ on any delimiter
character present in _delimiters_ and returns the resulting list.

[[jam.language.rules.builtins.utility._precious__]]
===== `PRECIOUS`

[source]
----
rule PRECIOUS ( targets * )
----

The `PRECIOUS` rule specifies that each of the targets passed as the
arguments should not be removed even if the command updating that target
fails.

[[jam.language.rules.builtins.utility._pad__]]
===== `PAD`

[source]
----
rule PAD ( string : width )
----

If _string_ is shorter than _width_ characters, pads it with whitespace
characters on the right, and returns the result. Otherwise, returns
_string_ unmodified.

[[jam.language.rules.builtins.utility._file_open__]]
===== `FILE_OPEN`

[source]
----
rule FILE_OPEN ( filename : mode )
----

The `FILE_OPEN` rule opens the specified file and returns a file
descriptor if the _mode_ parameter is either "w" or "r". Note that at
present, only the `UPDATE_NOW` rule can use the resulting file
descriptor number. If the _mode_ parameter is "t" this opens the file as a
text file and returns the contents as a single string.

[[jam.language.rules.builtins.utility._update_now__]]
===== `UPDATE_NOW`

[source]
----
rule UPDATE_NOW ( targets * : log ? : ignore-minus-n ? )
----

The `UPDATE_NOW` caused the specified targets to be updated immediately.
If update was successful, non-empty string is returned. The _log_
parameter, if present, specifies a descriptor of a file where all output
from building is redirected. If the _ignore-minus-n_ parameter is
specified, the targets are updated even if the `-n` parameter is
specified on the command line.

[[jam.language.flow_of_control]]
=== Flow-of-Control

Expand Down
19 changes: 12 additions & 7 deletions doc/src/extending.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ process that creates concrete targets from metatargets. Extending
metatarget level is rarely required. The jam targets are typically only
used inside the command line patterns.

WARNING: All of the Boost.Jam target-related builtin functions, like
WARNING: All of the Boost.Jam target-related builtin rules, like
`DEPENDS` or `ALWAYS` operate on jam targets. Applying them to metatargets or
concrete targets has no effect.

Expand All @@ -54,8 +54,8 @@ instance of link:#b2.reference.class.property-set[property-set])
`virtual-target` class.)

It's possible to lookup a metatarget by target-id using the
`targets.resolve-reference` function, and the
`targets.generate-from-reference` function can both lookup and generate
`targets.resolve-reference` rule, and the
`targets.generate-from-reference` rule can both lookup and generate
a metatarget.

The link:#b2.reference.class.abstract-target[abstract-target] class
Expand Down Expand Up @@ -137,7 +137,7 @@ In some cases, code that creates concrete targets may be invoked more
than once with the same properties. Returning two different instances of
`file-target` that correspond to the same file clearly will result in
problems. Therefore, whenever returning targets you should pass them via
the `virtual-target.register` function, besides allowing B2 to
the `virtual-target.register` rule, besides allowing B2 to
track which virtual targets got created for each metatarget, this will
also replace targets with previously created identical ones, as
necessary.footnote:[This create-then-register pattern is caused by
Expand Down Expand Up @@ -329,7 +329,7 @@ class verbatim-scanner : common-scanner
{
rule pattern ( )
{
return "//###include[ ]*\"([^\"]*)\"" ;
return "[ \t]*#[ \t]*include[ \t]*\"([^\"]+)\"" ;
}
}
----
Expand Down Expand Up @@ -423,12 +423,12 @@ target type. For example, the first generator invoked when building an
`exe` target is a composing generator corresponding to the proper
linker.

You should also know about two specific functions for registering
You should also know about two specific rules for registering
generators: `generators.register-c-compiler` and
`generators.register-linker`. The first sets up header dependency
scanning for C files, and the seconds handles various complexities like
searched libraries. For that reason, you should always use those
functions when adding support for compilers and linkers.
rules when adding support for compilers and linkers.

(Need a note about UNIX)

Expand Down Expand Up @@ -762,6 +762,11 @@ type.register OBFUSCATED_CPP : ocpp ;

import generators ;
generators.register-standard obfuscate.file : CPP : OBFUSCATED_CPP ;

actions file
{
# command(s) to obfuscate $(>) and build $(<)
}
----

and import that module, you'll be able to use the rule "obfuscated-cpp"
Expand Down