dbg(…)
A macro for printf-style debugging fans.
Debuggers are great. But sometimes you just don't have the time or patience to set
up everything correctly and just want a quick way to inspect some values at runtime.
This projects provides a single header file with a dbg(…)
macro that can be used in all circumstances where you would typically write
printf("…", …) or std::cout << …. But it comes with a few extras.
Examples
#include <vector>
#include <dbg.h>
// You can use "dbg(..)" in expressions:
int factorial(int n) {
if (dbg(n <= 1)) {
return dbg(1);
} else {
return dbg(n * factorial(n - 1));
}
}
int main() {
std::string message = "hello";
dbg(message); // [example.cpp:15 (main)] message = "hello" (std::string)
const int a = 2;
const int b = dbg(3 * a) + 1; // [example.cpp:18 (main)] 3 * a = 6 (int)
std::vector<int> numbers{b, 13, 42};
dbg(numbers); // [example.cpp:21 (main)] numbers = {7, 13, 42} (size: 3) (std::vector<int>)
dbg("this line is executed"); // [example.cpp:23 (main)] this line is executed
factorial(4);
return 0;
}
The code above produces this output (try it yourself):
Features
- Easy to read, colorized output (colors auto-disable when the output is not an interactive terminal)
- Prints file name, line number, function name and the original expression
- Adds type information for the printed-out value
- Specialized pretty-printers for containers, pointers, string literals, enums,
std::optional, etc. - Can be used inside expressions (passing through the original value)
- The
dbg.hheader issues a compiler warning when included (so you don't forget to remove it). - Compatible and tested with C++11, C++14 and C++17.
Installation
To make this practical, the dbg.h header should to be readily available from all kinds of different
places and in all kinds of environments. The quick & dirty way is to actually copy the header file
to /usr/include or to clone the repository and symlink dbg.h to /usr/include/dbg.h.
git clone https://github.com/sharkdp/dbg-macro
sudo ln -s $(readlink -f dbg-macro/dbg.h) /usr/include/dbg.h
If you don't want to make untracked changes to your filesystem, check below if there is a package for
your operating system or package manager.
On Arch Linux
You can install dbg-macro from the AUR:
yay -S dbg-macro
With vcpkg
You can install the dbg-macro port via:
vcpkg install dbg-macro
Configuration
- Set the
DBG_MACRO_DISABLEflag to disable thedbg(…)macro (i.e. to make it a no-op). - Set the
DBG_MACRO_NO_WARNINGflag to disable the "'dbg.h' header is included in your code base" warnings.
Advanced features
Hexadecimal, octal and binary format
If you want to format integers in hexadecimal, octal or binary representation, you can
simply wrap them in dbg::hex(…), dbg::oct(…) or dbg::bin(…):
const uint32_t secret = 12648430;
dbg(dbg::hex(secret));
Printing type names
dbg(…) already prints the type for each value in parenthesis (see screenshot above). But
sometimes you just want to print a type (maybe because you don't have a value for that type).
In this case, you can use the dbg::type<T>() helper to pretty-print a given type T.
For example:
template <typename T>
void my_function_template() {
using MyDependentType = typename std::remove_reference<T>::type&&;
dbg(dbg::type<MyDependentType>());
}
Customization
If you want dbg(…) to work for your custom datatype, you can simply overload operator<< for
std::ostream&:
std::ostream& operator<<(std::ostream& out, const user_defined_type& v) {
out << "…";
return out;
}
If you want to modify the type name that is printed by dbg(…), you can add a custom
get_type_name overload:
// Customization point for type information
namespace dbg {
std::string get_type_name(type_tag<bool>) {
return "truth value";
}
}
Development
If you want to contribute to dbg-macro, here is how you can build the tests and demos:
Make sure that the submodule(s) are up to date:
git submodule update --init
Then, use the typical cmake workflow. Usage of -DCMAKE_CXX_STANDARD=17 is optional,
but recommended in order to have the largest set of features enabled:
mkdir build
cd build
cmake .. -DCMAKE_CXX_STANDARD=17
make
To run the tests, simply call:
make test
You can find the unit tests in tests/basic.cpp.
Acknowledgement
This project is inspired by Rusts dbg!(…) macro.