Support -g debug info generation

[rmac] / docs / rmac.rst

diff --git a/docs/rmac.rst b/docs/rmac.rst
index 78e2d34cb8fae27ae7f615745a65084666415479..36dc5e0ade2a63e047efd01898483c644560dfe0 100644 (file)
--- a/docs/rmac.rst
+++ b/docs/rmac.rst
@@ -125,6 +125,7 @@ Switch               Description
 -fe                  ELF output object file format.
 -fr                  Absolute address. Source code is required to have one .org statement.
 -fx                  Atari 800 com/exe/xex output object file format.
+-g                   Generate source level debug info. Requires BSD COFF object file format.
 -i\ *path*           Set include-file directory search path.
 -l\ *[file[prn]]*    Construct and direct assembly listing to the specified file.
 -l\ *\*[filename]*   Create an output listing file without pagination.
@@ -235,6 +236,19 @@ the table.
  file is created. Beware! If an assembly produces no errors, any error file from
  a previous assembly is not removed.
 
+**-g**
+ The **-g** switch causes RMAC to generate source-level debug symbols using the
+ stabs format. When linked with a compatible linker such as RLN, these symbols
+ can be used by source-level debuggers such as rdbjag, wdb, or gdb to step
+ through assembly code line-by-line with all the additional context of labels,
+ macros, constants, register equates, etc. available in the original assembly
+ listings rather than relying on the simple disassembly or raw machine code
+ available when stepping through instruction-by-instruction. This option only
+ works with the BSD COFF object file format, as the others do not use the
+ a.out-style symbol tables required by stabs, and RMAC does not currently
+ support placing stabs debug symbols in their own dedicated section in ELF
+ format object files.
+
 **-i**
  The **-i** switch allows automatic directory searching for include files. A list of
  semi-colon seperated directory search paths may be mentioned immediately