formalize codebase's library exports; document in README

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
+`src/lib_raddbgi_format` folder. The other relevant folders for working with
-format are:
+the format are:
 
-- `raddbgi_cons`: The RADDBGI construction layer, for making RADDBGI debug
+- `lib_raddbgi_cons`: The RADDBGI construction library, for making RADDBGI
-info.
+debug info.
-- `raddbgi_convert`: Our implementation of PDB-to-RADDBGI (and an in-progress
+- `raddbgi_convert`: Our legacy-debug-info-to-RADDBGI converters. Right now
-implementation of a DWARF-to-RADDBGI) conversion.
+this includes a working PDB-to-RADDBGI converter, and an in-progress DWARF-to-
-- `raddbgi_stringize`: Code for converting binary RADDBGI info into text.
+RADDBGI converter. These converters can be built both as helper codebase layers
-- `raddbgi_dump`: Code for textually dumping information from RADDBGI files.
+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
+- `raddbgi_convert` (`PDBCONV_`): Our implementation of PDB-to-RADDBGI and
-  programs to work with various features in the `raddbg` debugger. Does not
+  DWARF-to-RADDBGI conversion.
-  depend on `base`.
-- `raddbgi_cons` (`RADDBGIC_`): Implements an API for constructing files of the
-  RADDBGI debug info file format.
 - `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.

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_cons_local/raddbgi_cons_local.h"
-#include "raddbgi_format/raddbgi_format_parse.h"
-#include "raddbgi_cons/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_cons_local/raddbgi_cons_local.c"
-#include "raddbgi_format/raddbgi_format_parse.c"
-#include "raddbgi_cons/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"

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"

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

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_local/raddbgi_cons_local.h"
-#include "raddbgi_cons/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_local/raddbgi_cons_local.c"
-#include "raddbgi_cons/raddbgi_cons_local.c"
 
 #include "raddbgi_msf.c"
 #include "raddbgi_codeview.c"

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