EpicGames / raddebugger

本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。

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.

RAD Debugger 项目说明：本 README 文档不包含调试器本身的使用说明和技巧，仅作为该项目的技术概览。包含使用说明和技巧的调试器 README 文件随调试器发布包一同提供，或者在本地构建完成后位于构建文件夹内。您可以在此处找到预构建的发布二进制文件。

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.

RAD Debugger 是一款原生的、用户模式的、多进程图形化调试器。目前仅支持本地 Windows x64 环境下的 PDB 调试，未来计划进行扩展和移植。未来我们将扩展支持原生 Linux 调试和 DWARF 调试信息。该调试器目前处于 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.

为了使调试器更加稳健，如果您能在此提交发现的问题，并附上收集到的任何信息（如转储文件及其对应的构建版本、复现步骤、测试可执行文件等），将对我们有很大帮助。除了调试器之外，我们还旨在通过另外两项相关技术进一步改进工具链：(1) RAD 调试信息 (RDI) 格式，以及 (2) RAD 链接器。

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.

RAD 调试信息 (RDI) 格式：RAD 调试信息 (RDI) 格式是我们自定义的调试信息格式，调试器会解析并使用它，而不是使用 PDB 或 DWARF 等工具链原生生成的调试信息。为了兼容这些现有工具链，我们会按需将 PDB（以及最终将包含嵌入式 DWARF 的 PE/ELF 文件）转换为 RDI 格式。

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.

RDI 格式目前在代码中定义，位于 src/lib_rdi 文件夹内的文件中。rdi.h 和 rdi.c 中指定了定义该格式本身的类型和函数。rdi_parse.h 和 rdi_parse.c 中包含了用于解析该格式的辅助程序。我们还有一个正在开发中的用于构建和序列化 RDI 数据的库，位于 src/lib_rdi_make 文件夹内。

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.

我们的 radbin 工具（也可以通过调试器的 —bin 命令行参数访问）能够将原生调试信息格式转换为 RDI，并能生成存储在 RDI 文件中内容的文本转储。

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.

RAD 链接器：RAD 链接器是一款用于生成 x64 PE/COFF 二进制文件的新型高性能链接器。它旨在创建超大型可执行文件时保持极高的速度。它生成标准的 PDB 文件用于调试，但也可以（可选地）原生创建 RAD 调试信息，这不仅有助于消除调试时的按需转换时间，对于那些因内部 32 位表溢出而导致 PDB 损坏的超大型可执行文件也很有用。

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.

RAD 链接器主要针对处理大型链接项目进行了优化。在我们的测试案例中（调试信息达到数 GB），链接速度提升了 50%。其命令行语法与 MSVC 完全兼容；您可以从 /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.

我们目前为该链接器设计的用例是辅助大型项目的编译-调试周期。我们尚未支持链接时优化 (LTO)，但该功能已在路线图中。默认情况下，链接器会根据核心数开启相应数量的线程，因此如果您计划并行运行多个链接器，可以通过 /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.

我们还支持大内存页，启用后可进一步缩短 25% 的链接时间。要使用大内存页进行链接，您需要通过 /rad_large_pages 显式请求。大内存页默认处于关闭状态，因为 Windows 对大内存页的支持存在一些缺陷；我们建议仅在每次链接后都会重置环境的 Docker 或虚拟机镜像中使用。

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. A benchmark of the linker’s performance is below:

在标准 Windows 环境中，使用大内存页会迅速导致内存碎片化，从而强制重启。我们正在开发该链接器的 Linux 移植版本，它将能够稳健地支持大内存页构建。以下是链接器的性能基准测试：

Project Development Setup / Local Build Instructions The project is actively developed both on Windows x64 and Linux x64 development machines. Click on whichever you’d like to use. 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.

项目开发设置 / 本地构建说明：该项目在 Windows x64 和 Linux x64 开发机器上均处于活跃开发状态。点击您想要使用的平台。Windows x64 1. 安装所需工具 (MSVC & Windows SDK)：首先，您需要 Microsoft C/C++ Build Tools v15 (2017) 或更高版本，以获取 Windows SDK 以及 MSVC 编译器和链接器。如果已安装 Windows SDK（例如通过安装 Microsoft C/C++ Build Tools），您也可以使用 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 variant of the vanilla cmd.exe.

3. 构建环境设置：构建代码库可以在具备从命令行调用 MSVC 或 Clang 能力的终端中完成。这通常通过调用 Microsoft C/C++ Build Tools 中包含的 vcvarsall.bat x64 来实现。该脚本由 VS <年份> 版本的 x64 原生工具命令提示符自动调用。

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 If everything is set up correctly, you should have output very similar to the following: Microsoft (R) C/C++ Optimizing Compiler Version 19.29.30151 for x64 Copyright (C) Microsoft Corporation. All rights reserved. usage: cl [ option… ] filename… [ /link linkoption… ]

如果您已安装构建工具，可以通过在 Windows 开始菜单搜索中查找“Native”轻松找到此命令提示符。您可以通过运行 cl 来确保 MSVC 编译器可从命令行访问。如果设置正确，您应该会看到类似以下的输出：Microsoft (R) C/C++ Optimizing Compiler Version 19.29.30151 for x64 Copyright (C) Microsoft Corporation. All rights reserved. usage: cl [ option… ] filename… [ /link linkoption… ]

3. Building Within this terminal, cd to the root directory of the codebase, and just run the build.bat script: build You should see the following output: [debug mode] [msvc compile] [default mode, assuming raddbg build] metagen_main.c searching C:\devel\raddebugger/src… 458 files found parsing metadesk… 16 metadesk files parsed gathering tables… 97 tables found generating layer code… raddbg_main.c

4. 构建：在此终端内，cd 进入代码库的根目录，然后直接运行 build.bat 脚本：build。您应该会看到以下输出：[debug mode] [msvc compile] [default mode, assuming raddbg build] metagen_main.c searching C:\devel\raddebugger/src… 458 files found parsing metadesk… 16 metadesk files parsed gathering tables… 97 tables found generating layer code… raddbg_main.c

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. This raddbg.exe will have been built in debug mode, which is not built with optimizations, and may perform worse. To produce a release mode executable, run build.bat with a release argument: build release T

如果一切正常，代码库根目录下会出现一个 build 文件夹，其中包含刚构建好的 raddbg.exe。此 raddbg.exe 是在调试模式下构建的，未经过优化，性能可能较差。要生成发布模式的可执行文件，请使用 release 参数运行 build.bat：build release T