Debugging harness

[zaimoni]

This needs significant buildout/rethinking.

What is currently present is:

• debugmsg (defined in output.cpp) is an printf format-string based utility that simply spams the user screen with messages. It provides no logging facility currently. It typically is not locked down under an #ifndef NDEBUG block (i.e., its usage was meant for release mode builds for C:Whales)

• The Zaimoni.STL support library provides an assert re-implementation. The *.sln file uses an option to switch parts of this re-implementation over to throwing std::logic_error (which, when testing in Visual Studio, triggers a debugger with a browsable stack and object data.) The Makefile builds are currently going through C stdio for this (stdout and stderr).

• We have a few places where throwing std::logic_error is within an #ifndef NDEBUG block .

Context:

• the current C stdio-based re-implementation, uses return code 3 to simulate the Microsoft compiler's assert. This is used by two of Zaimoni's projects (Z.C++ and Franci) to enable distinguishing between expected failure, and assertion failure, in test driver shell scripts.

• Franci already uses log file support (see contradictable points enumeration), but not specifically as a debugging log. (She records automated symbolic calculations to the logfile, to enable manual review.)

I Zaimoni am fine with evaluating relevant third-party libraries for use, whose licenses are compatible with the Creative Commons license inherited from C:Whales. I Am Not A Lawyer; my understanding is that fully permissive licenses (such as Boost or MIT) are compatible, while copyleft licenses (such as the GPL) are incompatible. (There is a gap in the project documentation; the GitHub hosted wiki needs updating.)

Points intended to be precise enough to be contradictable:

"We" (referring to all currently active developers) immediately could use:

• a debugging log present even in release mode builds. (E.g., something like Battle of Wesnoth's stderr.txt .)

** The assert re-implementation should also leave a trace here in debug builds, when not intentionally landing in the debugger.

** The debugging log should not spam the user interface (this could cause file loading to freeze when debugging file format changes); thus, extending debugmsg is not sufficient for this purpose (and it is reasonable that many current debugmsg calls should be changed to this new silent mode).

** It would be reasonable, to hook debugmsg calls into this debugging log.

** There should be some indication in the game that the debugging log has triggered, but it should not itself interfere with gameplay. This indication may depend on how the game is built.

** the current debugmsg calls would be fine when interrupting gameplay is reasonable.

• a documented procedure for how to set up a Linux environment to allow a debug build to land in a full debugger. The assert re-implementation should acquire a build option that triggers this, if it does not already exist.

[zaimoni]

Many current usages of the legacy debugmsg function will have to be adjusted as well. Generally speaking (this is a restatement and/or amplification of points of initial summary):

• release mode build: log to stderr.txt; unobtrusively adjust UI to indicate that stderr.txt actually has content. (option: hijack the player status UI?). runtime assert to no-op out. Most current debugmsg calls violate the respecified release-mode behavior.

• debug mode build: per-call-site decisions needed re current in-game messaging (debugmsg) vs. stderr.txt logging vs land-in-debugger.

One of the more popular third-party C++ libraries is https://github.com/gabime/spdlog (MIT license)

[zaimoni]

spdlog dependency: https://github.com/fmtlib/fmt . License "weak MIT" (should just be Boost).

[zaimoni]

I don't think we need the hard-to-replicate features of spdlog at this time. (Unusual logging destinations: Windows or *NIX system error logging.) It should suffice to create the error log on first use.

[zaimoni]

Further buildout of this is stalling (most remaining changes have to do with call invariants which ideally would be compile-time errors, but most of those have been caught).

It is unfortunate that C++ contracts was half-baked and had to be removed. (The proposal as voted in initially, was not that useful -- it was "advisory" rather than enabling hard syntax errors.)