commit 17f3105cecf6f5774fa1c1f3526112013104bff8
parent 0bd65c26d9b8dfc87fb9969ceae5efdc5e7b3922
Author: Ryan Sepassi <rsepassi@gmail.com>
Date: Thu, 16 Jul 2026 11:02:52 -0700
docs: align linker help with release contracts
Diffstat:
2 files changed, 34 insertions(+), 9 deletions(-)
diff --git a/driver/cmd/ld.c b/driver/cmd/ld.c
@@ -150,12 +150,13 @@ void driver_help_ld(void) {
"\n"
"INPUTS AND FORMATS\n"
" Relocatable ELF, Mach-O, and COFF objects and POSIX ar archives\n"
- " are accepted. The first object selects the target/output format;\n"
- " all following inputs must match it. This release does not\n"
- " reliably diagnose every mixed-architecture input, so validate\n"
- " each object's target before linking. ELF supports executable,\n"
- " shared, and partial-link output. Mach-O and PE/COFF support the\n"
- " executable and partial-link shapes; -shared is ELF-only.\n"
+ " are accepted. An explicit -target is authoritative; otherwise\n"
+ " the first target-bearing input selects the output target. The\n"
+ " public link boundary validates raw objects, builders, every\n"
+ " archive member, and dynamic/import inputs before creating output.\n"
+ " ELF supports executable, shared, and partial-link output. Mach-O\n"
+ " and PE/COFF support executable and partial-link shapes; -shared\n"
+ " is ELF-only.\n"
"\n"
"OUTPUT\n"
" -o PATH Output path (required, exactly one)\n"
@@ -172,13 +173,17 @@ void driver_help_ld(void) {
" -static Non-PIC, non-PIE\n"
" -pie Position-independent executable\n"
" -no-pie Disable PIE\n"
+ " -target TRIPLE Authoritative output target\n"
" --support-dir DIR kit support root for compiler "
"runtime\n"
" --sysroot DIR hosted C runtime/sysroot root\n"
" (target is otherwise auto-detected from the first object input)\n"
- " A relocated release currently needs an explicit --support-dir.\n"
- " Hosted links need an explicit --sysroot and -l c unless the\n"
- " caller supplies its own startup objects and system libraries.\n"
+ " Support is resolved from the canonical executable path; a\n"
+ " relocated release discovers its sibling support automatically.\n"
+ " --support-dir remains an authoritative override. -l c engages\n"
+ " hosted resolution; native macOS discovers its SDK automatically.\n"
+ " Other cross-hosted links need --sysroot unless the caller supplies\n"
+ " its own startup objects and system libraries.\n"
"\n"
"LIBRARY RESOLUTION\n"
" -L DIR Add library search path\n"
diff --git a/test/driver/run.sh b/test/driver/run.sh
@@ -1555,6 +1555,26 @@ else
not_ok "kit-help-elf-shared-scope" "$work/kit-help.out"
fi
+if "$KIT" ld --help > "$work/ld-help.out" 2> "$work/ld-help.err" &&
+ grep -Fq "relocated release discovers its sibling support automatically" \
+ "$work/ld-help.out" &&
+ grep -Fq -- "--support-dir remains an authoritative override" \
+ "$work/ld-help.out" &&
+ ! grep -Fq "currently needs an explicit --support-dir" \
+ "$work/ld-help.out"; then
+ ok "ld-help-canonical-support"
+else
+ not_ok "ld-help-canonical-support" "$work/ld-help.out"
+fi
+
+if grep -Fq "public link boundary validates raw objects" "$work/ld-help.out" &&
+ grep -Fq "archive member" "$work/ld-help.out" &&
+ grep -Fq -- "-target is authoritative" "$work/ld-help.out"; then
+ ok "ld-help-central-compatibility"
+else
+ not_ok "ld-help-central-compatibility" "$work/ld-help.out"
+fi
+
if "$KIT" dbg --help > "$work/dbg-help.out" 2> "$work/dbg-help.err" &&
! grep -q "toy" "$work/dbg-help.out"; then
ok "dbg-help-hides-toy"
