README.md
1## QsLog - the simple Qt logger ##
2QsLog is an easy to use logger that is based on Qt's QDebug class. QsLog is released as open source, under the BSD license.
3
4###Contribution policy###
5Bug fixes are welcome, larger changes however are not encouraged at this point due to the lack of time on my side for reviewing and integrating them. Your best bet in this case would be to open a ticket for your change or forking the project and implementing your change there, with the possibility of having it integrated in the future.
6All contributions will be credited, license of the contributions should be 3-clause BSD.
7
8### Features ###
9* Six logging levels (from trace to fatal)
10* Logging level threshold configurable at runtime.
11* Minimum overhead when logging is turned off.
12* Supports multiple destinations, comes with file and debug destinations.
13* Thread-safe
14* Supports logging of common Qt types out of the box.
15* Small dependency: just drop it in your project directly.
16
17### Usage ###
18Directly including the QsLog source code in a project:
19
201. Include QsLog.pri in your pro file
212. Include QsLog.h in your C++ files. Include QsLogDest.h only where you create/add destinations.
223. Get the instance of the logger by calling QsLogging::Logger::instance();
234. Optionally set the logging level. Info is default.
245. Create as many destinations as you want by using the QsLogging::DestinationFactory.
256. Add the destinations to the logger instance by calling addDestination.
267. Start logging!
27
28Linking to QsLog dynamically:
29
301. Build QsLog using the QsLogSharedLibrary.pro.
312. Add the QsLog shared library to your LIBS project dependencies.
323. Follow the steps in "directly including QsLog in your project" starting with step 2.
33
34Note: when you want to use QsLog both from an executable and a shared library you have to
35 link QsLog dynamically due to a limitation with static variables.
36
37### Configuration ###
38QsLog has several configurable parameters in its .pri file:
39
40* defining QS_LOG_LINE_NUMBERS in the .pri file enables writing the file and line number
41 automatically for each logging call
42* defining QS_LOG_SEPARATE_THREAD will route all log messages to a separate thread.
43* defining QS_LOG_WIN_PRINTF_CONSOLE will use fprintf instead of OutputDebugString on Windows
44
45Sometimes it's necessary to turn off logging. This can be done in several ways:
46
47* globally, at compile time, by enabling the QS_LOG_DISABLE macro in the supplied .pri file.
48* globally, at run time, by setting the log level to "OffLevel".
49* per file, at compile time, by including QsLogDisableForThisFile.h in the target file.
50
51### Thread safety ###
52The Qt docs say:
53A **thread-safe** function can be called simultaneously from multiple threads, even when the invocations use shared data, because all references to the shared data are serialized.
54A **reentrant** function can also be called simultaneously from multiple threads, but only if each invocation uses its own data.
55
56Since sending the log message to the destinations is protected by a mutex, the logging macros are thread-safe provided that the log has been initialized - i.e: instance() has been called. Adding and removing destinations and the instance function are likewise thread-safe.
57The setup functions (e.g: setLoggingLevel) are NOT thread-safe and are NOT reentrant, they must be called at program startup.