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.