[[logging]]
= Logging =

All error, information, and debugging messages must be logged to the k3d::log() stream using the K-3D logging interface, without exception - 'printf()' and other mechanisms for logging must not be used.  This ensures that log messages can be displayed and controlled by end-users via the mechanisms that K-3D provides for that purpose.  You should 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;
-------------------------

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, K-3D normally outputs warning messages and above.  To print information and debug messages too, use the '--log-level debug' command-line option.  For developers, the 'make run' target sets 'log-level debug' by default.

Users can customize log output using a variety of runtime arguments.  See 'k3dsdk/log_control.h' and 'k3dsdk/log.cpp' for details on how we tailor console output.

You are strongly encouraged to use the macros defined in <k3dsdk/result.h> to test for preconditions and other runtime problems in your code.  Note that these are not ``debug'' macros ... they are always compiled into every build, so you may use them with expressions that have side effects:

-------------------------
#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.
-------------------------


