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.

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, 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.

Project Development Setup / Local Build Instructions

The project is actively developed both on Windows x64 and Linux x64 development machines.

Windows x64

1. Installing the Required Tools (MSVC & Windows SDK)

First, you'll need the Microsoft C/C++ Build Tools v15 (2017) or later, for the Windows SDK, and the MSVC compiler and linker.

If the Windows SDK is installed (e.g. via installation of the Microsoft C/C++ Build Tools), you may also build with Clang.

2. Build Environment Setup

Building the codebase can be done in a terminal which is equipped with the ability to call either MSVC or Clang from command line.

This is generally done by calling vcvarsall.bat x64, which is included in the Microsoft C/C++ Build Tools. This script is automatically called by the x64 Native Tools Command Prompt for VS <year> variant of the vanilla cmd.exe. If you've installed the build tools, this command prompt may be easily located by searching for Native from the Windows Start Menu search.

You can ensure that the MSVC compiler is accessible from your command line by running:

cl

3. Building

Within this terminal, cd to the root directory of the codebase, and just run the build.bat script:

build

If everything worked correctly, there will be a build folder in the root level of the codebase, and it will contain a freshly-built raddbg.exe.

To produce a release mode executable, run build.bat with a release argument:

build release

Linux x64

1. Installing the Required Tools (GCC or Clang, Libraries)

First, you'll need either GCC or Clang. They can be obtained by running one of the following commands, depending on your toolchain of choice and distribution:

GCC on Ubuntu / Debian / Mint

sudo apt update && sudo apt install build-essential

Clang on Ubuntu / Debian / Mint

sudo apt update && sudo apt install clang llvm

GCC on Arch / Manjaro

sudo pacman -S base-devel

Clang on Arch / Manjaro

sudo pacman -S clang llvm

2. Installing Dependencies

The debugger project relies on a few dynamically linked libraries being present on the system:

• libfreetype
• libx11
• libxext
• libxfixes
• libxrandr
• libgl
• libegl

3. Building

To build, cd to the root directory of the codebase, and run the build.sh script:

./build.sh

Project Roadmap

The Initial Alpha Battle-Testing Phase

The first priority for the project is to ensure that the most crucial components are functioning extremely reliably for local, x64, Windows development.

Local x64 Linux Debugging Phase

The next priority for the project is to take the rock solid x64 Windows debugging experience, and port all of the relevant pieces to support local x64 Linux debugging also.

And Beyond!

There are several directions we might take after these two major phases, like remote debugging, porting to different architectures, further improving the debugger's features, and so on.

Codebase Introduction

Top-Level Directory Descriptions

• data: Small binary files which are used when building.
• src: All source code.

Layer Descriptions

The codebase is organized into layers. Layers are separated either to isolate certain problems, and to allow inclusion into various builds without needing to pull everything in the codebase into a build.

• artifact_cache (AC_): Asynchronously-filled cache of computation artifacts.
• base: Universal, codebase-wide constructs.
• codeview (CV_): Parsing and writing the CodeView format.
• coff (COFF_): Parsing and writing the COFF format.
• content (C_): Cache for general data blobs.
• ctrl (CTRL_): Asynchronous process control, stepping, and breakpoints.
• dbg_engine (D_): Core debugger system without graphical components.
• dbg_info (DI_): Asynchronous debug info conversion and loading.
• demon (DMN_): Abstraction layer for low-level process control.
• disasm (DASM_): Disassembly generation.
• draw (DR_): High-level graphics drawing API.
• dwarf (DW_): Parsing the DWARF format.
• eh (EH_): Parsing the EH frame format.
• elf (ELF_): Parsing the ELF format.
• eval (E_): Compiler for expression language evaluation.
• eval_visualization (EV_): Non-graphical evaluation visualization engine.
• file_stream (FS_): Asynchronous file streaming.
• font_cache (FNT_): Cache of rasterized font data.
• font_provider (FP_): Abstraction layer for font rasterization.
• lib_raddbg_markup (RADDBG_): Standalone library for marking up user programs.
• lib_rdi (RDI_): Core RDI types and helpers.
• lib_rdi_make (RDIM_): Constructing RDI debug info.
• linker (LNK_): RAD Linker implementation.
• mdesk (MD_): Parsing Metadesk files.
• metagen (MG_): Metaprogram for generating code and data tables.
• msf (MSF_): Parsing and writing the MSF format.
• msvc_crt (MSCRT_): MSVC CRT specific parsing.
• mule: Test executables for battle testing.
• mutable_text (MTX_): Cache for mutable text buffers.
• natvis: Type visualization for other debuggers.
• os/core (OS_): Core OS abstraction.
• os/gfx (OS_): Graphical OS abstraction.
• pdb (PDB_): Parsing and writing the PDB format.
• pe (PE_): Parsing and writing the PE format.
• radbin (RB_): radbin binary utility.
• raddbg (RD_): Graphical debugger frontend.
• regs (REGS_): Register metadata and helpers.
• render (R_): Abstract rendering API.
• text (TXT_): Text processing functions.
• third_party: External code.
• ui (UI_): GUI building machinery.