[DOC] improve description of CPPDEFINES

[mwichmann]

The CPPDEFINES entry and the Append method entry has some additional clarification added, about ways cpp macros can be specified. Added a couple more examples to illustrate.

Doc-only change.

Signed-off-by: Mats Wichmann mats@linux.com

Contributor Checklist:

• I have created a new test or updated the unit tests to cover the new/changed functionality.
• I have updated CHANGES.txt (and read the README.rst)
• I have updated the appropriate documentation

[mwichmann]

As part of this work, I added another example, intending to show the use of a (list, tuple) of tuples and/or a dictionary to pass multiple values to CPPDEFINES. This blows up the doc build, with an unhelpful error (the message is "string", it's something in lxml). Since we're not worse off by doing so - the example was not included before - I've commented it out in the latest commit, maybe can revisit some time to try to find out why this kills it.

[bdbaddog]

Is that the current functionality? Hmm. not what I'd expect.

[mwichmann]

Revisited this. At the core, this is not an SCons limitation (although it becomes one because we always invoke a shell to run the compile command), but the fact that the definition is already in a Python string makes it really hard to get right. Here's what the cpp manpage says:

If you are invoking the preprocessor from a shell or shell-like program you may need to use the shell's quoting syntax to protect characters such as spaces that have a meaning in the shell syntax.

As additional fun, GCC's cpp supports function-like macros on the command line, MSVC does not. They have the extra problem of using parens, which matter to the shell also.

On the whole, we'd need to emit options this way:

gcc -D"FOO=thing with strings"

That is, quoting the whole definition rather than the right-hand-side, which I think there is no way to do with current syntax - we'd have to hack on _defines I assume. Open to suggestions on how to describe this, if we should at all. I'm pushing a new revision which removes the example, because the example (just invented by me, not tested at the time) doesn't actually work - take a look at whether that wording covers the case or if we should just "remain silent" on this topic and figure people will only use simple replacement in CPPDEFINES.

[mwichmann]

adding MSVC's manpage on the function-like macro topic for completeness:

The /D option doesn't support function-like macro definitions. To insert definitions that can't be defined on the command line, consider the /FI (Name forced include file) compiler option.

and cpp's:

If you wish to define a function-like macro on the command line, write its argument list with surrounding parentheses before the equals sign (if any). Parentheses are meaningful to most shells, so you should quote the option. With sh and csh, -D'name(args...)=definition' works.

[jcbrill]

@mwichmann When working on #4174, I ran into docbook issues that were related to a internal lxml global limit that resulted in docbook failures without particularly helpful messages. The root cause took more time that it should have to figure out what was going awry.

That particular issue was solved by added the ability to increase the global limit and hard-coding a new constant.

As part of #4174, the following snippet was added to SCons\Tool\docbook\__init__.py:

#
# lxml etree XSLT global max traversal depth
#

lmxl_xslt_global_max_depth = 3100

if has_lxml and lmxl_xslt_global_max_depth:
    def __lxml_xslt_set_global_max_depth(max_depth):
        from lxml import etree
        etree.XSLT.set_global_max_depth(max_depth)
    __lxml_xslt_set_global_max_depth(lmxl_xslt_global_max_depth)

At the time, the hard-coded constant 3100 was larger than what was necessary to build the documentation. Perhaps not so anymore.

Could be worth a try to bump up the global max depth to see if that is the problem. For all I know, there may be more limits hard-coded into lxml as well.

EDIT ADDITION:

https://lxml.de/api/lxml.etree.XSLT-class.html

set_global_max_depth(max_depth)
Static Method

The maximum traversal depth that the stylesheet engine will allow. This does not only count the template recursion
depth but also takes the number of variables/parameters into account. The required setting for a run depends on
both the stylesheet and the input data.

Example:

XSLT.set_global_max_depth(5000)
Note that this is currently a global, module-wide setting because libxslt does not support it at a per-stylesheet
level.

[mwichmann]

Thanks! I remember reading about this in your PR now you mention it, and it clearly didn't sink in because I in no way made the connection. Your guess is probably on target - bumping the limit made one build work out, but then something else blew up (in Sphinx, so it's past the phase where lxml is involved).

[mwichmann]

Closed in favor of #4263