In the previous lesson (3.4 -- Basic debugging tactics), we started exploring how to manually debug problems. In that lesson, we offered some criticisms of using statements to print debug text:
- Debug statements clutter your code.
- Debug statements clutter the output of your program.
- Debug statements require modification of your code to both add and to remove, which can introduce new bugs.
- Debug statements must be removed after you’re done with them, which makes them non-reusable.
We can mitigate some of these issues. In this lesson, we’ll explore some basic techniques for doing so.
Conditionalizing your debugging code
Consider the following program that contains some debug statements:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
#include <iostream> int getUserInput() { std::cerr << "getUserInput() called\n"; std::cout << "Enter a number: "; int x; std::cin >> x; return x; } int main() { std::cerr << "main() called\n"; int x = getUserInput(); std::cout << "You entered: " << x; return 0; } |
When you’re done with the debugging statement, you’ll either need to remove them, or comment them out. Then if you want them again later, you’ll have to add them back, or uncomment them.
One way to make it easier to disable and enable debugging throughout your program is to make your debugging statements conditional using preprocessor directives:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
#include <iostream> #define ENABLE_DEBUG // comment out to disable debugging int getUserInput() { #ifdef ENABLE_DEBUG std::cerr << "getUserInput() called\n"; #endif std::cout << "Enter a number: "; int x; std::cin >> x; return x; } int main() { #ifdef ENABLE_DEBUG std::cerr << "main() called\n"; #endif int x = getUserInput(); std::cout << "You entered: " << x; return 0; } |
Now we can enable debugging simply by commenting / uncommenting #define ENABLE_DEBUG. This allows us to reuse previously added debug statements and then just disable them when we’re done with them, rather than having to actually remove them from the code. If this were a multi-file program, the #define ENABLE_DEBUG would go in a header file that’s included into all code files so we can comment / uncomment the #define in a single location and have it propagate to all code files.
This addresses the issue with having to remove debug statements and the risk in doing so, but at the cost of even more code clutter. Another downside of this approach is that if you make a typo (e.g. misspell “DEBUG”) or forget to include the header into a code file, some or all of the debugging for that file may not be enabled. So although this is better than the unconditionalized version, there’s still room to improve.
Using a logger
An alternative approach to conditionalized debugging via the preprocessor is to send your debugging information to a log file. A log file is a file (normally stored on disk) that records events that occur in software. The process of writing information to a log file is called logging. Most applications and operating systems write log files that can be used to help diagnose issues that occur.
Log files have a few advantages. Because the information written to a log file is separated from your program’s output, you can avoid the clutter caused by mingling your normal output and debug output. Log files can also be easily sent to other people for diagnosis -- so if someone using your software has an issue, you can ask them to send you the log file, and it might help give you a clue where the issue is.
While you can write your own code to create log file and send output to them, you’re better off using one of the many existing third-party logging tools available. Which one you use is up to you.
For illustrative purposes, we’ll show what outputting to a logger looks like using the plog logger. Plog is implemented as a set of header files, so it’s easy to include anywhere you need it, and it’s lightweight and easy to use.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
#include <iostream> #include "plog/Log.h" // Step 1: include the logger header int getUserInput() { LOGD << "getUserInput() called"; // LOGD is defined by the plog library std::cout << "Enter a number: "; int x; std::cin >> x; return x; } int main() { plog::init(plog::debug, "Logfile.txt"); // Step 2: initialize the logger LOGD << "main() called"; // Step 3: Output to the log as if you were writing to the console int x = getUserInput(); std::cout << "You entered: " << x; return 0; } |
Here’s output from the above logger:
2018-12-26 20:03:33.295 DEBUG [4752] [main@22] main() called 2018-12-26 20:03:33.296 DEBUG [4752] [getUserInput@10] getUserInput() called
How you include, initialize, and use a logger will vary depending on the specific logger you select.
Note that conditional compilation directives are also not required using this method, as most loggers have a method to reduce/eliminate writing output to the log. This makes the code a lot easier to read, as the conditional compilation lines add a lot of clutter. With plog, logging can be temporarily disabled by changing the init statement to the following:
|
1 |
plog::init(plog::none , "Logfile.txt"); // plog::none eliminates writing of most messages, essentially turning logging off |
We won’t use plog in any future lessons, so you don’t need to worry about learning it.
If you want to compile the above example yourself, you’ll need to grab the Log.h file from the plog repo, and do one of the following:
- Save it to <your project root>/plog/Log.h (easy, but only works for one project).
- Save it <anywhere>/plog/Log.h, and then set the <anywhere> directory as an include directory inside your IDE (less easy, but can share across multiple projects). There are instructions on how to do this for Visual Studio here: A.2 -- Using libraries with Visual Studio and Code::Blocks here: A.3 -- Using libraries with Code::Blocks.
 3.6 -- Using an integrated debugger: Stepping |
 Index |
 3.4 -- Basic debugging tactics |
Hi Alex,
As you have mentioned, in a multi-file program #define ENABLE_DEBUG can go into a header file.
Can you please write code for that header file?
someheader.h:
Thank you very much for help
In visual studio 2019 you need to include the "plog" directory by Project-> Properties -> C\C++ -> General -> Additional Include directories -> <path to "plog" not including itself>.
This is because the code references the "plog" directory
"Log files can also easily sent to other people for diagnosis"
Syntax error: missing "be".
Got this working in Atom no worries.
I am running MinGW to compile.
Steps:
1. Download zip from https://github.com/SergiusTheBest/plog
2. Extract files and copy plog folder (~\plog-master\include) to folder (~MinGW\include).
3. Follow instructions in readme from github.
plog library didn't work in MacOSx.
In file included from CPlusPlusTutorial.cpp:3:
./plog/Log.h:7:10: fatal error: 'plog/Logger.h' file not found
#include <plog/Logger.h>
^~~~~~~~~~~~~~~
1 error generated.
Angle brackets cause a problem. I think so it should be double quotes.
I agree. You should report this to the library maintainer. :)
In the "Plog strategy" example, I type this code and run it in Visual Studio 2013 and DevC++. Both of them makes error about this code.
- In Dev C++, [Error] plog/Log.h: No such file or directory.
- In Visual Studio, first error is the same. The second error is: name followed by '::' must be a class or namespace name. It the same error in Dev C++. I donot know where "plog/Log.h". Thanks for your help.
You need to get the Log.h file and place it appropriately on your system. I added some instruction to the lesson about how to do this.
Since there are no comments on this lesson, I just wanted to take a second to say thanks for making these. This is a decent example, since you haven't really touched on utilizing third-party resources much yet.