enabling runtime argument checking for free (part 2)

[paolopas]

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.

[grafikrobot]

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]

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]

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

[paolopas]

1. I'm sure these changes will expose more cases like the python.jam one (if the tests have sufficient coverage).
2. 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.
3. NOTIME is a truly unfortunate alias for NOTFILE, and I would also get rid of that one without further ado.
4. 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.

[paolopas]

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.

[paolopas]

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.