enabling runtime argument checking for free (part 2) #487

paolopas · 2025-12-30T16:56:30Z

Note

Note this PR ends the work of #486, the code is branched from there, so this one accumulate all the changes.

fbf6f04 argument description provide for ECHO and MATCH builtins; for the latter I do not use the documented signature (regexps + : list *) but the safer (regexps * : list *). This is the way the code has always worked and to no risk to break compatibility with expression like MATCH "$(foo)" : ... in case foo var is empty or undefined. Cannot find original documentation ("Perforce Software") about MATCH signature. The documentation has other problems as well.

ECHO [ MATCH "$(foo)" : b : c ] ;

# b2
jamfile.jam:1: in modules.load
*** argument error
* rule MATCH ( regexps * : list * )
* called with: (  : b : c )
* extra argument c
(builtin):see definition of rule 'MATCH' being called
/home/pax/.local/share/b2/src/build/project.jam:586: in load-jamfile
/home/pax/.local/share/b2/src/build/project.jam:84: in load
/home/pax/.local/share/b2/src/build/project.jam:241: in project.find
/home/pax/.local/share/b2/src/build-system.jam:639: in module scope

328ddb7 provided code documentation for GLOB-RECURSIVELY builtin rule; this might be handy to have on hand.

of HDRMACRO which is the only one left we would do well to forget about, since it will never work reliably even if we remove OPT_HEADER_CACHE_EXT from config.h.

The documentation (bjam.adoc) for BACKTRACE and MATCH still needs to be updated, while GLOB-RECURSIVELY, REBUILDS and NOTIME are not even mentioned.

now available, this when provided is used by the functions function_bind_variables, function_run, argument_error allowing the checking of arguments that otherwise cannot happen

ALWAYS, LEAVES, NOCARE, NOTIME, NOTFILE, NOUPDATE, TEMPORARY, ISFILE, FAIL_EXPECTED, RMOLD

now available, notice that documented signature of MATCH differs form the actual one, the function allows for 0 regexps (first arg), beacuse that is the way the function has always worked and to not break compatibility.

grafikrobot · 2025-12-31T01:41:41Z

Note this PR ends the work of #486, the code is branched from there, so this one accumulate all the changes.

So.. #486 should be closed?

grafikrobot · 2025-12-31T01:43:11Z

The documentation (bjam.adoc) for BACKTRACE and MATCH still needs to be updated, while GLOB-RECURSIVELY, REBUILDS and NOTIME are not even mentioned.

Would be great to include such a documentation change in this PR. :-)

Also would be great to update the history.adoc to note the change.

grafikrobot · 2025-12-31T01:48:57Z

I see the changes caught some "problems" in python.jam.

The MATCH never, or no longer, takes the match indices to return.

paolopas · 2025-12-31T05:50:49Z

I'm sure these changes will expose more cases like the python.jam one (if the tests have sufficient coverage).
HDRMACRO suffers from a serious design flaw because it does not address the problem of redefined symbols (I won't go into detail). But HDRMACRO also shows that you can waste a lot of time when your code contains dead bodies, not only that it requires a configuration that has been abandoned (OPT_HEADER_CACHE_EXT), but also in hdrmacro.cpp there are untrue things said about the usage of HDRRULE. In headers.cpp the headers1 function is only used to make the HDRMACRO work and will NEVER be used, So I would eliminate these traps by throwing HDRMACRO, hdrmacro.*, headers1(). And only then I would try to understand how OPT_HEADER_CACHE_EXT is actually involved.
NOTIME is a truly unfortunate alias for NOTFILE, and I would also get rid of that one without further ado.
If you give me time to get familiar with asciidoctor, I can try updating the BACKTRACE and MATCH documentation, and maybe add GLOB-RECURSIVELY and REBUILDS. I make no promises about history.adoc.

So I'd say it's not time to close this PR yet, to be absolutely clear point 4 is the only one that will be performed.

fixed typo in jamfile.jam, updated MATCH and BACKTRACE in §12.2.4 Built-in Ryles, fixed formatting in §12.2.2 Targets, fixed syntax in §6.2 Builtin rules

…tins-2

paolopas · 2025-12-31T13:09:07Z

I fixed some things in the documentation, but

I didn't add the GLOB-RECURSIVELY rule to the documentation, and I think I now understand why it wasn't published before. The problem is in the naming convention: currently, rules never use the minus sign, only the underscore. GLOB-RECURSIVELY is only used internally but you can also find it in boost's tools/build/src/kernel/bootstrap.jam (I looked in an old 1.77 release). We might release an alias while we wait for the deprecated one to be gone.

Should we change the name before publishing it?

I didn't even add REBUILDS because it has a different convention for the order of arguments; in fact, it's now

# Appends each of the targets-to-rebuild to the rebuilds list
# for each of the targets.
rule REBUILDS ( targets * : targets-to-rebuild * )

and even if unlike the DEPENDS/INCLUDE (which modify the depends list) the REBUILDS acts on the rebuilds list, the order of the params seems reversed compared to the custom of having the targets first and then the dependencies (sources).

Maybe that's why it wasn't published. REBUILDS is only used internally, but instead of exchanging params it is better to introduce a new builtin, but what do we call it?

Should we reverse the params before publishing it?

Finally:

NOTIME doesn't seem to be used anywhere and I think it should be eliminated.
HDRMACRO may be disabled

or I could update history.adoc, let's close this PR and address the outstanding issues in subsequent PRs.

fixed formatting in §12.2.3 Rules fixed formatting in §12.2.4 Built-in Rules fixed escaping of __XYZ__ in §6.5.1 modules fixed escaping of __XYZ__ in §6.5.2 class fixed escaping of __XYZ__ in §6.6.1 Class abstract-target fixed escaping of __XYZ__ in §6.6.4 Class basic-target fixed escaping of __XYZ__ in §6.6.5 Class typed-target

NOTIME can be quickly restored, removed hdrmacro.cpp from compiled sources.

paolopas · 2026-01-01T16:46:40Z

Ok René, I think there are more pressing things right now than thinking about GLOB-RECURSIVELY and REBUILDS, we will deal with them separately, for now I would say we can stop here with this PR, consider that with the latest changes I have decommissioned both HDRMACRO and NOTIME, the latter can be quickly restored if necessary.

grafikrobot

@paolopas you mentioned ignoring the errors withe older Boost version for the MATCH.. Unfortunately it's not an impossible use case to build the old Boost version with the current B2. It can happen in the Conan packages if one builds from source. As that package is written to use the B2 recipe for all versions. My suggestion would be to change the signature to: rule MATCH ( regexps * : list * : unused * ). And then in the implementation print a warning if the unused argument is used instead of a hard error.

I can work on doing that change if you don't feel like spending more time on this. :-)

src/engine/builtins.cpp

src/engine/hdrmacro.cpp

src/engine/hdrmacro.h

src/engine/headers.cpp

grafikrobot · 2026-01-06T18:31:58Z

src/engine/headers.cpp

        }

-        /* Special treatment for #include MACRO. */
+        /* NOTE: Faulty feature HDRMACRO, discontinued.


Lets remove the dead code entirely.

Ok, I agree, I'll proceed with the changes you proposed so we can close this PR, then we'll decide what to do with GLOB-RECURSIVELY and REBUILDS.

now available; notice that documented signature of MATCH differs form the actual one for two reasons: 1. the rule allows for 0 regexps (first param), beacuse that is the way the rule has always worked and to not break compatibility; 2. a new "unused *" param was added at the end to emit a warning and skip extra arguments, this also to not break compatibility (see bfgroup#487)

grafikrobot · 2026-01-07T15:21:54Z

Replaced by #492

paolopas added 4 commits December 29, 2025 21:22

argument description for DEPENDS/INCLUDES builtins

d4a576d

now available, this when provided is used by the functions function_bind_variables, function_run, argument_error allowing the checking of arguments that otherwise cannot happen

argument description provided for builtin rules

f65f30a

ALWAYS, LEAVES, NOCARE, NOTIME, NOTFILE, NOUPDATE, TEMPORARY, ISFILE, FAIL_EXPECTED, RMOLD

argument description for ECHO and MATCH builtins

fbf6f04

now available, notice that documented signature of MATCH differs form the actual one, the function allows for 0 regexps (first arg), beacuse that is the way the function has always worked and to not break compatibility.

some comments for builtin GLOB-RECURSIVELY rule

328ddb7

grafikrobot added the enhancement New feature or request label Dec 31, 2025

grafikrobot added this to BFG Tasks Dec 31, 2025

grafikrobot moved this to 👀 In review in BFG Tasks Dec 31, 2025

Fix extra MATCH args in python.jam.

6ec26ef

The MATCH never, or no longer, takes the match indices to return.

grafikrobot moved this from 👀 In review to 🏗 In progress in BFG Tasks Dec 31, 2025

paolopas added 2 commits December 31, 2025 13:42

documentation maintenance

176070c

fixed typo in jamfile.jam, updated MATCH and BACKTRACE in §12.2.4 Built-in Ryles, fixed formatting in §12.2.2 Targets, fixed syntax in §6.2 Builtin rules

Merge branch 'builtins-2' of https://github.com/paolopas/b2 into buil…

cafa26a

…tins-2

paolopas added 2 commits January 1, 2026 08:19

HDRMACRO and NOTIME built-in rules disontinued,

4c48f94

NOTIME can be quickly restored, removed hdrmacro.cpp from compiled sources.

grafikrobot requested changes Jan 6, 2026

View reviewed changes

paolopas mentioned this pull request Jan 7, 2026

enabling runtime argument checking for free (part 3) #492

Open

grafikrobot closed this Jan 7, 2026

github-project-automation bot moved this from 🏗 In progress to ✅ Done in BFG Tasks Jan 7, 2026

Uh oh!

enabling runtime argument checking for free (part 2) #487

enabling runtime argument checking for free (part 2) #487

Uh oh!

Conversation

paolopas commented Dec 30, 2025

Uh oh!

grafikrobot commented Dec 31, 2025

Uh oh!

grafikrobot commented Dec 31, 2025

Uh oh!

grafikrobot commented Dec 31, 2025

Uh oh!

paolopas commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

paolopas commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

paolopas commented Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

grafikrobot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

grafikrobot Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

paolopas Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

grafikrobot commented Jan 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

paolopas commented Dec 31, 2025 •

edited

Loading

paolopas commented Dec 31, 2025 •

edited

Loading

paolopas commented Jan 1, 2026 •

edited

Loading