This is a collection of scripts to support maintenance of -O gen-C++
(and friends).  They're oriented around running against the BTest test
suite, and are currently tailored for the lead maintainer's own environment.
The scripts all assume you're running them from build/ .

If you make changes to the scripts, format them using

	shfmt -w -i 4 -ci *.sh

(or set up "pre-commit" and use "pre-commit run -a")

The maintenance workflow:

1.  Update this timestamp, so this file will be changed and you'll remember
    to check in updates to the list of how the compiler currently fares
    on various btests (see end of this doc):

	Fri Sep 16 16:13:49 PDT 2022

2.  Run "find-test-files.sh" to generate a list (to stdout) of all of the
    possible Zeek source files found in the test suite.

3.  For each such Zeek file, run "check-zeek.sh" to see whether Zeek can
    parse it.  This helps remove from further consideration difficult
    tests (like those that have embedded input files, or multiple separate
    scripts).

4.  "mkdir CPP-test" - a directory for holding results relating to C++ testing

5.  Run "check-CPP-gen.sh" for each Zeek file that passed "check-zeek.sh".
    This will generate a corresponding file in CPP-test/out* indicating whether
    "-O gen-C++" can successfully run on the input.  Presently, it should
    be able to do so for all of them, other than some exceptions noted below.

6.  Copy ./src/zeek to ./zeek.HOLD.  This is used to speed up recompilation used
    in the next step.  However, it's also a headache to do development to
    fix a bug and then forget to update zeek.HOLD, which means you wind up
    running the old version.  You can combat that by removing ./zeek.HOLD
    every time you start working on fixing a bug.

7.  Use the appended database to remove inputs that have known issues.

8.  For every input that survives that pruning, run "do-CPP-btest.sh".
    This will generate C++ for the BTest, compile it, and run the result
    to see if it succeeds.  It populates CPP-test/diag* with the Btest
    diagnostic output (empty means success).  For non-empty output,
    either fix the problem, add 

	# @TEST-REQUIRES: test "${ZEEK_USE_CPP}" != "1"

    if the test isn't appropriate, or update the database if it's not
    readily fixable, along with the reason why.

    Note that do-CPP-btest.sh takes the same -d and -U arguments as
    does btest, for displaying differences or updating the baseline
    (which is Baseline.cpp).

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

These BTests won't successfully run due to the indicated issue:

	bad-constructor - uses a complex old-style constructor that
		should be updated
	bad-when - deliberately has old-style "when" without captures
	deprecated - uses deprecated features not support for -O gen-C++
	test-glitch - fails because of how we do testing: the first -O gen-C++
		pass leaves httpd running, which causes the second -O use-C++
		pass to fail when it tries to start up a new httpd
	opaque - needs a global whose value is (or contains) an opaque value,
		not currently supported
	skipped - test can be skipped due to environmental reasons (e.g.,
		whether we have a certain Kerberos setup)

Database Of Known Issues (keep sorted)

../testing/btest/bifs/table_values.zeek bad-constructor
../testing/btest/core/global_opaque_val.zeek opaque
../testing/btest/language/alternate-event-hook-prototypes.zeek deprecated
../testing/btest/language/global-init-calls-bif.zeek opaque
../testing/btest/language/redef-same-prefixtable-idx.zeek deprecated
../testing/btest/language/table-redef.zeek deprecated
../testing/btest/language/when-aggregates.zeek bad-when
../testing/btest/scripts/base/protocols/krb/smb2_krb.test skipped
../testing/btest/scripts/base/protocols/krb/smb2_krb_nokeytab.test skipped
../testing/btest/scripts/base/utils/active-http.test test-glitch
../testing/btest/scripts/policy/frameworks/telemetry/log-prefixes.zeek opaque
../testing/btest/scripts/policy/frameworks/telemetry/log.zeek opaque
../testing/btest/scripts/policy/misc/dump-events.zeek skipped
../testing/btest/telemetry/counter.zeek opaque
../testing/btest/telemetry/gauge.zeek opaque
../testing/btest/telemetry/histogram.zeek opaque
