libcruft-util/README.adoc

== libcruft

A simple cross-platform C++ utility library.

Supported compilers: >=clang-10.x, >=gcc10.x; specifically, we require cxx17 features such as structured bindings which aren't present in older compilers. No attempt has been made to compile under MSVC.

MinGW must be compiled with PThreads support so that the std threading API is available.

=== Environment Variables

The following variables can be defined at runtime to change the library behaviour.

DEBUG:: whether to initialise basic debugging features at load time. the value is irrelevant; the test is for whether the variable is defined.
DEBUG_WAIT:: whether to wait for a debugger to attach before executing `main`.

LOG_LEVEL:: minimum log level that will render to the logging stream. note that a given level may have been compiled out and may not be present, eg. DEBUG tends to only be present for debug builds.
BREAK_LEVEL:: minimum log level that will trigger a breakpoint

CRUFT_LOG_SINK:: The output driver for logging. One of 'CONSOLE', 'PATH'.
CRUFT_LOG_PATH:: The output path for the 'PATH' logging driver. This path is subject to path expansion and will be interpreted as relative to the current working directory if it is relative.

JOB_THREADS:: default number of threads to spin up for job queues.
JOB_DEPTH:: the default size of the pending work item queue for a job queue.

Ideally one would not resort to using these variables, but they may make debugging a little easier in some circumstances.