[cmake-developers] [PATCH] Discussion needed: FindBISON: refine VERBOSE feature of BISON_TARGET

정언 eonikupy at gmail.com
Sun Jun 21 09:06:18 EDT 2015

Please look over description of BISON_TARGET macro of FindBISON. It's
availabie in <http://www.cmake.org/cmake/help/v3.3/module/FindBISON.html>
for 3.3(currently 3.3.0-rc2).

It says:
BISON_TARGET(<Name> <YaccInput> <CodeOutput> [VERBOSE <file>]
[COMPILE_FLAGS <string>])
Specifying `VERBOSE <file>` makes a report (description) file on
parser is generated.

In fact, current BISON_TARGET does not. VERBOSE adds the bison command
line option `-v`(--verbose). As this option has no extra space for the
file name, bison generates a report file of default name. Instead, the
internal macro defines a custom command that makes a copy of the
default named report file to the specified <file> path. The custom
command is not invoked until any other command requires the <file>,
for example, from its dependencies. The <file> is aliased
BISON_${Name}_VERBOSE_FILE. This is nowhere documented behavior and
should be fixed.

It is possible to specify a non-default report file path in command
line. The bison command line option `--report-file` is used to do
that. For use of this, these are what should be considered:
- (C1) `--report-file` does not generate a report file; it specifies
path of the report file if it is generated. `--report` or `--verbose`
does generate a report file. Considering this means that the main
internal custom command of BISON_TARGET no more recognizes the report
file as one of its outputs. If some <file> is passed for
`--report-file` but never generated, the main command would run again
and again because it would fail to generate the nonexistent report
- (C2) `--report-file` is added to bison in 2007. (See GNU bison
upstream commit 1bb2bd75
Another patch I submitted was one using `--defines` to specify a
non-default header name, which is available in bison since 2001. (See
commit 6526f6d <http://git.savannah.gnu.org/cgit/bison.git/commit/?id=6526f6d>.)
As GNU bison is widely used since the late 1980's, `--report-file` can
be unavailable for a large amount of systems. For these systems, the
current copying way is appropriate.
(C1) is a consideration which includes (C2), as (C1) implies including
`--report-file` usage.

Any adjustment on BISON_TARGET would harm backward compatibility. Here
are some possible solutions.
- (S1) Updating the documentation only, leaving current behavior unchanged.
- (S2) Changing `[VERBOSE <file>]` to `[VERBOSE [<file>]]`. `VERBOSE`
would add `--verbose`, and specifying `<file>` would add additional
`--report-file`. I think this is the best solution. However, FindBISON
uses CMAKE_PARSE_ARGUMENTS, which does not support formatting
parameters in this way. It means that it is required to remove
CMAKE_PARSE_ARGUMENTS to implement this solution. (Consider
BISON_TARGET recently moved to CMAKE_PARSE_ARGUMENTS. See thread
for details.)
- (S2+) `[VERBOSE [REPORT_FILE <file>]]` to tell user `<file>` is path
for the report file output. Also impossible with
CMAKE_PARSE_ARGUMENTS. (C2) should be considered.
- (S3) Changing `[VERBOSE <file>]` to `[VERBOSE]` so it matches the
bison option `--verbose`.
- (S3+) `[VERBOSE] [REPORT_FILE <file>]`. Each would add its
corresponding command line option described above. `<file>` is
non-default name for report file if generated ever. (C1) should be
- (S4) Let `[VERBOSE <string>]` as is, and no more internal custom
command using <file>. This is only for the syntactic backward
compatibility of BISON_TARGET.
- (S4+) `[VERBOSE <string>] [REPORT_FILE <file>]`. `VERBOSE` will
generate `<string>` is ignored, and `<file>` is non-default name for
report file if generated ever. (C1) should be considered.
- (S5) Remove `VERBOSE` and leave only `[REPORT_FILE <file>]`.
`<file>` is non-default name for report file if generated ever. To
generate report file, `--verbose` or `--report` should be specified
via `COMPILE_FLAGS`. (C1) should be considered.

I'm not certain which solution is better than the others, so I wrote
patches for almost all possible solutions. Five patches are attached
in total:
- (current)->(S3).
- (S3)->(S3+). 0002-FindBISON-Add-REPORT_FILE-option-to-pass-report-file.patch.1
- (current)->(S4).
- (S4)->(S4+). 0002-FindBISON-Add-REPORT_FILE-option-to-pass-report-file.patch.2
- (current)->->(S5). 0001-FindBISON-Remove-VERBOSE-option.patch,
Note that all patches are experimental proof-of-concepts. After a
right solution is chosen, I will write a patch (or more) again for
that, including documentation update.


More information about the cmake-developers mailing list