Logging

From K-3D

All error, information, and debugging messages must be logged to the k3d::log() stream using the K-3D logging interface ... no exceptions! You must also specify the log level of every message, using the iostream-compatible manipulators defined in <k3dsdk/log.h>:

#include <k3dsdk/log.h>

k3d::log() << debug << "This is an internal debugging message" << std::endl;
k3d::log() << info << "This is an informational message" << std::endl;
k3d::log() << warning << "Recoverable unexpected input or behavior has occurred" << std::endl;
k3d::log() << error << "Current operation cannot complete due to unexpected input or behavior" << std::endl;
k3d::log() << critical << "Application will shut down due to an unrecoverable condition" << std::endl;

This is a new (as of this writing) requirement, so there are many error messages left in the code that don't specify the log level yet ... feel free to send a patch if you run across something. Each message should be written to a single line of output, and you should terminate messages with std::endl instead of "\n" to ensure that they are flushed immediately.

By default for users, K-3D outputs warning messages and above. To print information and debug messages too, use the "--log-level debug" command-line option. For developers, the "make test" target sets "--log-level debug" by default.

Users can customize log output using a variety of runtime arguments. See <k3dsdk/logbufs.h> for the custom streambuf objects we use to tailor the output.

You are encouraged to use the macros defined in <k3dsdk/result.h> to test for preconditions and other runtime problems in your code:

#include <k3dsdk/result.h>

assert_not_implemented(); // This code hasn't been implemented yet
assert_not_reached(); // This code should never be executed.
assert_warning(Expression); // Generates a warning message if Expression evaluates false.
return_if_fail(Expression); // Generates an error message and returns from the enclosing function if Expression evaluates false.
return_val_if_fail(Expression, Val); // Generates an error message and returns Val from the enclosing function if Expression evaluates false.

Note that these macros are not "debug" macros ... they will always be compiled into every build, so you may use them with expressions that have side effects (more than that - we want you to use them).