From 21744bd256f66fa31bd6f84dd58292d88b4b0746 Mon Sep 17 00:00:00 2001 From: Joshua Watt Date: Mon, 6 Jul 2026 09:18:07 -0600 Subject: [PATCH] doc: add documentation for --debug-prefix-map option Document the --debug-prefix-map command-line option in doc/running.src, including its BASE=DEST argument format, use cases (cross-directory builds and reproducible builds), example usage with ELF64/DWARF, and behavior when multiple mappings are specified. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- doc/running.src | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/running.src b/doc/running.src index 5aeefc6b2..58a25588c 100644 --- a/doc/running.src +++ b/doc/running.src @@ -289,6 +289,29 @@ If no debug information is currently implemented in the selected output format, \c{-g} is \e{silently ignored}. +\S{opt-debug-prefix-map} The \i\c{--debug-prefix-map} Option: Remapping \i{Source File Paths} in Debug Info + +This option remaps source file path prefixes when encoding filenames in +the output object file's debug information. It takes a single argument +of the form \c{BASE=DEST}: any source path that begins with \c{BASE} has +that prefix replaced with \c{DEST} before the path is written into the +output. This is useful when building in a different directory from the +one referenced in the source, or when producing \i{reproducible builds} +by stripping machine-specific path components. + +For example: + +\c nasm -f elf64 -g -F dwarf --debug-prefix-map /home/user/src=/usr/src myfile.asm + +causes paths beginning with \c{/home/user/src} to appear as \c{/usr/src} +in the generated DWARF debug information. Multiple \c{--debug-prefix-map} +options may be given; they are applied in the order specified and the +first matching prefix wins. + +The option requires an argument of the form \c{BASE=DEST}; omitting the +\c{=} separator is a fatal usage error. + + \S{opt-X} The \i\c{-X} Option: Selecting an \i{Error Reporting Format} This option can be used to select an error reporting format for any @@ -575,6 +598,8 @@ For command-line compatibility with Yasm, the form \i\c{--v} is also accepted for this option starting in NASM version 2.11.05. +\IR{--debug-prefix-map} \c{--debug-prefix-map} option + \IR{--prefix} \c{--prefix} option \IC{--prefix}{--gprefix} \c{--gprefix} option \IC{--prefix}{--lprefix} \c{--lprefix} option