Clone wiki

dbg / building

building dbg

To build dbg, I use my own build system, doozer, which is distributed as a single python file. While I don't expect that everyone will want to use this system, I hope the description in dbg's will be easy enough to read an understand in order to adapt it to another build system.

The fungo library is a dependency of doozer, required for exception capture and storage. The test-o-matic library is also needed. If you are building dbg with your own build system and do not require that the tests be built or run, test-o-matic will not be needed.


On Windows, dbg will use Microsoft's dbghelp.dll in order to perform symbol lookup. Older versions of Windows (XP and before) are distributed with somewhat buggy versions dbghelp.dll, which can impede the ability of dbg to find function symbols.

To get a later version search MSDN for "debugging tools". Redistributables can be found should you wish to supply an up-to-date dbghelp.dll with your application.

Building with doozer

First you should get doozer and write a config file to describe where your toolchain resides, which platform SDK to use (where applicable) and which build options and optimizations you want to apply.

Some additional configuration variables should be added for the sake of doozer:

  • fungo.root the root of the fungo source tree.
  • test_o_matic.root the root of the test-o-matic source tree.
  • dbg.platform should be set to 'windows' or 'osx' depending on the target platform.
  • dbg.dbghelp_dll_path can be set to point to the location of an up-to-date version of Microsoft's dbghelp.dll. This configuration option is ignored on non-Windows platforms. This path will be hard-coded in to the dbg library and is only really intended for situations where dbg is used only for internal development, and release/retail/customer builds do not require symbol lookup functionality. If omitted, dbghelp.dll will be sought inside the default Windows DLL search paths.
  • dbg.optimize_out can be set to True if the dbg.staticlib target should only return public header paths and not the dbg static library itself. This is useful for release/retail/customer builds where the no-op definitions of dbg macros are needed (assertions etc) in order for successful compilation, but a static library is not needed to fulfil their definitions. This option is only needed if you are using doozer to build an application or library that links against dbg.

Once the configuration file has been created, the dbg library, its tests and examples can be built with the following command:

> python doozer/ variant=your_config.cfg

The tests should be run automatically as part of the build.

Tips for building with another build system

Public includes (for clients of dbg) reside under the include directory. When building dbg, this should also be included in the compiler's header search paths.

The source code for the library can be found under the src directory.

The code under src/osx is only needed when targeting OS X. It is also the starting point for porting to other UNIX systems.

The code immediately inside src/windows is needed when building both MinGW and MSVC targets. The code inside src/windows/msvc and src/windows/mingw is additionally needed for those toolchains, respectively.

If a hard-coded path to Windows' dbghelp.dll should be used (for internal development), the DBG_RECENT_DBGHELP_DLL preprocessor macro should be defined to point to it. For example:


> cl "/DDBG_RECENT_DBGHELP_DLL=C:/Program Files/Windows Kits/8.0/Debuggers/x86/dbghelp.dll" ...


> g++ "-DDBG_RECENT_DBGHELP_DLL=C:/Program Files/Windows Kits/8.0/Debuggers/x86/dbghelp.dll" ...