The RAD Debugger Project

NOTE: This README does not document usage instructions and tips for the debugger itself, and is intended as a technical overview of the project. The debugger's README, which includes usage instructions and tips, can be found packaged along with debugger releases, or within the build folder after a local copy has been built. You can find pre-built release binaries here (https://github.com/EpicGamesExt/raddebugger/releases).

The RAD Debugger is a native, user-mode, multi-process, graphical debugger. It currently only supports local-machine Windows x64 debugging with PDBs, with plans to expand and port in the future. In the future we'll expand to also support native Linux debugging and DWARF debug info.

The debugger is currently in ALPHA. In order to get the debugger bullet-proof, it'd greatly help out if you submitted the issues you find here (https://github.com/EpicGamesExt/raddebugger/issues), along with any information you can gather, like dump files (along with the build you used), instructions to reproduce, test executables, and so on.

In addition to the debugger, we aim to further improve the toolchain with two additional related technologies: (1) the RAD Debug Info (RDI) format, and (2) the RAD Linker.

The RAD Debug Info (RDI) Format

The RAD Debug Info (RDI) format is our custom debug information format, which the debugger parses and uses, rather than the debug information natively produced by toolchains, like PDB or DWARF. To work with these existing toolchains, we convert PDB (and eventually PE/ELF files with embedded DWARF) into the RDI format on-demand.

The RDI format is currently specified in code, in the files within the src/lib_rdi folder. In rdi.h and rdi.c, the types and functions which define the format itself are specified. In rdi_parse.h and rdi_parse.c, helpers for parsing the format are included.

We also have an in-progress library for constructing and serializing RDI data, located within the src/lib_rdi_make folder.

Our radbin utility (accessible through the debugger too, via the --bin command line argument) is capable of converting native debug information formats to RDI, and of producing textual dumps of contents stored within RDI files.

The RAD Linker

The RAD Linker is a new performance linker for generating x64 PE/COFF binaries. It is designed to be very fast when creating gigantic executables. It generates standard PDB files for debugging, but it can also (optionally) natively create RAD Debug Info too, which is useful both to eliminate on-demand conversion time when debugging, but also for huge executables that otherwise create broken PDBs that overflow internal 32-bit tables.

The RAD Linker is primarily optimized to handle huge linking projects. In our test cases (where debug info is multiple gigabytes), we see 50% faster link times.

The command line syntax is fully compatible with MSVC; you can get a full list of implemented switches from /help.

Our current designed-for use case for the linker is to help with the compile-debug cycle of huge projects. We don't yet have support for link-time-optimizations, but this feature is on the road map.

By default, the linker spawns as many threads as there are cores, so if you plan to run multiple linkers in parallel, you can limit the number of thread workers via /rad_workers.

We also have support for large memory pages, which, when enabled, reduce link time by another 25%. To link with large pages, you need to explicitly request them via /rad_large_pages. Large pages are off by default, since Windows support for large pages is a bit buggy; we recommend they only be used in Docker or VM images where the environment is reset after each link. In a standard Windows environment, using large pages otherwise will fragment memory quickly, forcing a reboot. We are working on a Linux port of the linker that will be able to build with large pages robustly.