diff --git a/README.md b/README.md index 64d8dbb0..48f71017 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,11 @@ # 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._ + 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 @@ -24,15 +30,16 @@ simply deserialize the PDBs). It is much slower for much larger projects at the moment, but we expect this will vastly improve overtime. The RADDBGI format is currently specified in code, in the files within the -`src/raddbgi_format` folder. The other relevant folders for working with the -format are: +`src/lib_raddbgi_format` folder. The other relevant folders for working with +the format are: -- `raddbgi_cons`: The RADDBGI construction layer, for making RADDBGI debug -info. -- `raddbgi_convert`: Our implementation of PDB-to-RADDBGI (and an in-progress -implementation of a DWARF-to-RADDBGI) conversion. -- `raddbgi_stringize`: Code for converting binary RADDBGI info into text. -- `raddbgi_dump`: Code for textually dumping information from RADDBGI files. +- `lib_raddbgi_cons`: The RADDBGI construction library, for making RADDBGI +debug info. +- `raddbgi_convert`: Our legacy-debug-info-to-RADDBGI converters. Right now +this includes a working PDB-to-RADDBGI converter, and an in-progress DWARF-to- +RADDBGI converter. These converters can be built both as helper codebase layers +or with a command line interface frontend. +- `raddbgi_dump`: Our RADDBGI textual dumping utility. ## Development Setup Instructions @@ -208,6 +215,11 @@ Layers depend on other layers, but circular dependencies would break the separability and isolation utility of layers (in effect, forming one big layer), so in other words, layers are arranged into a directed acyclic graph. +A few layers are built to be used completely independently from the rest of the +codebase, as libraries in other codebases and projects. As such, these layers do +not depend on any other layers in the codebase. The folders which contain these +layers are prefixed with `lib_`, like `lib_raddbgi_format`. + A list of the layers in the codebase and their associated namespaces is below: - `base` (no namespace): Universal, codebase-wide constructs. Strings, math, memory allocators, helper macros, command-line parsing, and so on. Depends @@ -258,6 +270,16 @@ A list of the layers in the codebase and their associated namespaces is below: for asynchronously preparing data for memory visualization in the debugger. - `hash_store` (`HS_`): Implements a cache for general data blobs, keyed by a 128-bit hash of the data. Used as a general data store by other layers. +- `lib_raddbg_markup` (`RADDBG_`): Standalone library for marking up user + programs to work with various features in the `raddbg` debugger. Does not + depend on `base`, and can be independently relocated to other codebases. +- `lib_raddbgi_cons` (`RADDBGIC_`): Standalone library for constructing RADDBGI + debug info data. Does not depend on `base`, and can be independently relocated + to other codebases. +- `lib_raddbgi_format` (`RADDBGI_`): Standalone library for defining the core + RADDBGI types and helper functions for reading and writing the RADDBGI debug + info file format. Does not depend on `base`, and can be independently + relocated to other codebases. - `metagen` (`MG_`): A metaprogram which is used to generate primarily code and data tables. Consumes Metadesk files, stored with the extension `.mdesk`, and generates C code which is then included by hand-written C code. Currently, it @@ -290,18 +312,10 @@ A list of the layers in the codebase and their associated namespaces is below: - `raddbg` (no namespace): The layer which ties everything together for the main graphical debugger. Not much "meat", just drives `df`, implements command line options, and so on. -- `raddbg_markup` (`RADDBG_`): Standalone header file for marking up user - programs to work with various features in the `raddbg` debugger. Does not - depend on `base`. -- `raddbgi_cons` (`RADDBGIC_`): Implements an API for constructing files of the - RADDBGI debug info file format. +- `raddbgi_convert` (`PDBCONV_`): Our implementation of PDB-to-RADDBGI and + DWARF-to-RADDBGI conversion. - `raddbgi_dump` (`RADDBGIDUMP_`): A dumper utility program for dumping textualizations of RADDBGI debug info files. -- `raddbgi_format` (`RADDBGI_`): Standalone types and helper functions for the - RADDBGI debug info file format. Does not depend on `base`. -- `raddbgi_stringize` (`RADDBGI_`): Code to stringify binary RADDBGI info, for - visualizing textualizations of RADDBGI debug info. Used in `raddbgi_dump`, - and depends on `base`. - `regs` (`REGS_`): Types, helper functions, and metadata for registers on supported architectures. Used in reading/writing registers in `demon`, or in looking up register metadata. diff --git a/src/raddbg_markup/raddbg_markup.h b/src/lib_raddbg_markup/raddbg_markup.h similarity index 100% rename from src/raddbg_markup/raddbg_markup.h rename to src/lib_raddbg_markup/raddbg_markup.h diff --git a/src/raddbgi_cons/raddbgi_cons.c b/src/lib_raddbgi_cons/raddbgi_cons.c similarity index 100% rename from src/raddbgi_cons/raddbgi_cons.c rename to src/lib_raddbgi_cons/raddbgi_cons.c diff --git a/src/raddbgi_cons/raddbgi_cons.h b/src/lib_raddbgi_cons/raddbgi_cons.h similarity index 100% rename from src/raddbgi_cons/raddbgi_cons.h rename to src/lib_raddbgi_cons/raddbgi_cons.h diff --git a/src/raddbgi_format/raddbgi_format.c b/src/lib_raddbgi_format/raddbgi_format.c similarity index 100% rename from src/raddbgi_format/raddbgi_format.c rename to src/lib_raddbgi_format/raddbgi_format.c diff --git a/src/raddbgi_format/raddbgi_format.h b/src/lib_raddbgi_format/raddbgi_format.h similarity index 100% rename from src/raddbgi_format/raddbgi_format.h rename to src/lib_raddbgi_format/raddbgi_format.h diff --git a/src/raddbgi_format/raddbgi_format_parse.c b/src/lib_raddbgi_format/raddbgi_format_parse.c similarity index 100% rename from src/raddbgi_format/raddbgi_format_parse.c rename to src/lib_raddbgi_format/raddbgi_format_parse.c diff --git a/src/raddbgi_format/raddbgi_format_parse.h b/src/lib_raddbgi_format/raddbgi_format_parse.h similarity index 100% rename from src/raddbgi_format/raddbgi_format_parse.h rename to src/lib_raddbgi_format/raddbgi_format_parse.h diff --git a/src/raddbg/raddbg_main.cpp b/src/raddbg/raddbg_main.cpp index 49300df1..681c22c5 100644 --- a/src/raddbg/raddbg_main.cpp +++ b/src/raddbg/raddbg_main.cpp @@ -5,6 +5,8 @@ //~ rjf: Includes //- rjf: [h] +#include "lib_raddbgi_format/raddbgi_format.h" +#include "lib_raddbgi_format/raddbgi_format_parse.h" #include "base/base_inc.h" #include "os/os_inc.h" #include "mdesk/mdesk.h" @@ -15,9 +17,7 @@ #include "txti/txti.h" #include "coff/coff.h" #include "pe/pe.h" -#include "raddbgi_format/raddbgi_format.h" -#include "raddbgi_format/raddbgi_format_parse.h" -#include "raddbgi_cons/raddbgi_cons_local.h" +#include "raddbgi_cons_local/raddbgi_cons_local.h" #include "raddbgi_convert/pdb/raddbgi_coff.h" #include "raddbgi_convert/pdb/raddbgi_codeview.h" #include "raddbgi_convert/pdb/raddbgi_msf.h" @@ -47,6 +47,8 @@ #include "raddbg.h" //- rjf: [c] +#include "lib_raddbgi_format/raddbgi_format.c" +#include "lib_raddbgi_format/raddbgi_format_parse.c" #include "base/base_inc.c" #include "os/os_inc.c" #include "mdesk/mdesk.c" @@ -57,9 +59,7 @@ #include "txti/txti.c" #include "coff/coff.c" #include "pe/pe.c" -#include "raddbgi_format/raddbgi_format.c" -#include "raddbgi_format/raddbgi_format_parse.c" -#include "raddbgi_cons/raddbgi_cons_local.c" +#include "raddbgi_cons_local/raddbgi_cons_local.c" #include "raddbgi_convert/pdb/raddbgi_msf.c" #include "raddbgi_convert/pdb/raddbgi_codeview.c" #include "raddbgi_convert/pdb/raddbgi_pdb.c" diff --git a/src/raddbgi_cons/raddbgi_cons_local.c b/src/raddbgi_cons_local/raddbgi_cons_local.c similarity index 72% rename from src/raddbgi_cons/raddbgi_cons_local.c rename to src/raddbgi_cons_local/raddbgi_cons_local.c index 18e07f38..59334e1d 100644 --- a/src/raddbgi_cons/raddbgi_cons_local.c +++ b/src/raddbgi_cons_local/raddbgi_cons_local.c @@ -1,4 +1,4 @@ // Copyright (c) 2024 Epic Games Tools // Licensed under the MIT license (https://opensource.org/license/mit/) -#include "raddbgi_cons.c" +#include "lib_raddbgi_cons/raddbgi_cons.c" diff --git a/src/raddbgi_cons/raddbgi_cons_local.h b/src/raddbgi_cons_local/raddbgi_cons_local.h similarity index 97% rename from src/raddbgi_cons/raddbgi_cons_local.h rename to src/raddbgi_cons_local/raddbgi_cons_local.h index ad8971a4..3b37a7b7 100644 --- a/src/raddbgi_cons/raddbgi_cons_local.h +++ b/src/raddbgi_cons_local/raddbgi_cons_local.h @@ -41,6 +41,6 @@ #define raddbgic_scratch_begin scratch_begin #define raddbgic_scratch_end scratch_end -#include "raddbgi_cons.h" +#include "lib_raddbgi_cons/raddbgi_cons.h" #endif // RADDBGI_CONS_LOCAL_H diff --git a/src/raddbgi_convert/pdb/raddbgi_from_pdb_main.c b/src/raddbgi_convert/pdb/raddbgi_from_pdb_main.c index 54dca6b7..e0a3db0c 100644 --- a/src/raddbgi_convert/pdb/raddbgi_from_pdb_main.c +++ b/src/raddbgi_convert/pdb/raddbgi_from_pdb_main.c @@ -1,11 +1,11 @@ // Copyright (c) 2024 Epic Games Tools // Licensed under the MIT license (https://opensource.org/license/mit/) +#include "lib_raddbgi_format/raddbgi_format.h" #include "base/base_inc.h" #include "os/os_inc.h" #include "coff/coff.h" -#include "raddbgi_format/raddbgi_format.h" -#include "raddbgi_cons/raddbgi_cons_local.h" +#include "raddbgi_cons_local/raddbgi_cons_local.h" #include "raddbgi_coff.h" #include "raddbgi_codeview.h" @@ -19,11 +19,11 @@ #include "raddbgi_from_pdb.h" +#include "lib_raddbgi_format/raddbgi_format.c" #include "base/base_inc.c" #include "coff/coff.c" #include "os/os_inc.c" -#include "raddbgi_format/raddbgi_format.c" -#include "raddbgi_cons/raddbgi_cons_local.c" +#include "raddbgi_cons_local/raddbgi_cons_local.c" #include "raddbgi_msf.c" #include "raddbgi_codeview.c" diff --git a/src/raddbgi_stringize/raddbgi_stringize.c b/src/raddbgi_dump/raddbgi_stringize.c similarity index 100% rename from src/raddbgi_stringize/raddbgi_stringize.c rename to src/raddbgi_dump/raddbgi_stringize.c diff --git a/src/raddbgi_stringize/raddbgi_stringize.h b/src/raddbgi_dump/raddbgi_stringize.h similarity index 92% rename from src/raddbgi_stringize/raddbgi_stringize.h rename to src/raddbgi_dump/raddbgi_stringize.h index f1064c6e..e74d3a86 100644 --- a/src/raddbgi_stringize/raddbgi_stringize.h +++ b/src/raddbgi_dump/raddbgi_stringize.h @@ -4,12 +4,6 @@ #ifndef RADDBGI_STRINGIZE_H #define RADDBGI_STRINGIZE_H -// TODO(allen): this depends on types from our base layer. -// we need to decide if we want this to be included in the "format" layer -// and therefore lifted off of the base layer, or if we want to put it in -// "base" or "dump" layers or something like that so that it can -// rely on Arena, String8, and String8List from the "base" layer. - //////////////////////////////// //~ RADDBG Stringize Helper Types