CLI Option Parsing

This page documents the command-line option parsing infrastructure in nvlink v13.0.88: the parser framework, option entry struct layout, registration sequence, post-extraction validation, mutual-exclusion enforcement, and global variable mappings. For the complete alphabetically-sorted quick-reference table of all flags, see CLI Flags Reference.

Parser Infrastructure

Option parsing is a self-contained subsystem at addresses 0x42C510--0x42F640. The parser is a generic, reusable framework (shared with cicc and ptxas) that handles option registration, argv scanning, value extraction, help formatting, and validation. nvlink creates one parser instance at the start of nvlink_parse_options (0x427AE0) and destroys it implicitly when the function returns.

Core Functions

Parser Object Layout (56 bytes)

The parser object (sub_42DFE0 return value) is allocated from the "nvlink option parser" memory arena:

Option Entry Layout (120 bytes)

Each option registered by option_register occupies 120 bytes:

Type Codes

Flag Bits

The flags field at offset 24 controls parser behavior:

Registration and Extraction Flow

The nvlink_parse_options function (0x427AE0, 30272 bytes, 1299 lines) follows a strict sequence:

1. parser = option_parser_create(0)                    // 0x42DFE0
2. For each of ~65 options:
     option_register(parser, long, short, type,        // 0x42F130
                     mult, flags, keywords, reserved,
                     default, default_kw, placeholder, help)
3. option_parse_argv(parser, argc, argv)               // 0x42E5A0
4. Handle immediate-exit options:
     if option_was_specified("trap-into-debugger"):     // 0x42E580
         install_trap_handler()                         // 0x42FA60
     if option_was_specified("help"):
         print_help_and_exit()                          // 0x42F560 + 0x44A420
     if option_was_specified("version"):
         print_version_and_exit()                       // 0x44A420
5. For each option:
     option_get_value(parser, name, &global_var, size)  // 0x42E390
6. Post-extraction validation:
     - Architecture range checks (sm > 19)
     - Mercury mode detection (sm > 99)
     - LTO consistency checks
     - Mutual-exclusion enforcement
     - CUDA API version parsing
7. tkinfo = option_generate_tkinfo(parser, ...)         // 0x42F640

Option Catalog

For the complete alphabetically-sorted flag table (all 68 entries with types, defaults, and one-line descriptions), see CLI Flags Reference.

The remainder of this page documents the implementation-level details: how each option is registered, what global variable it maps to, validation logic, and inter-option dependencies. Options are grouped by functional category below.

Output Options

Global variable mappings:

The gen-host-linker-script option accepts keywords lcs-aug and lcs-abs (default: lcs-abs). The value lcs-aug sets dword_2A77DC0 = 1 (standalone SECTIONS fragment, 130 bytes, written to file or stdout), while lcs-abs sets it to 2 (full augmented script: ld --verbose pipeline + append SECTIONS + ld -T validation). The mapping is computed by a byte-by-byte compare against the literal "lcs-aug" at sub_427AE0 lines 1012-1027 (see Mode Dispatch).

Debug Options

Global variable mappings:

When --suppress-debug-info is specified with --debug, the effect is to clear byte_2A5F310 (debug flag) to 0, effectively disabling debug output. If specified without --debug, a warning is emitted: "-suppress-debug-info" conflicts with "no -g".

Architecture Options

Global variable mappings:

The arch option is registered with an allowed-keywords callback (sub_486EC0(1)) that validates the architecture name against the supported SM table. The machine option defaults to "64" and only accepts value 64; specifying 32 on SM > 72 produces a fatal error.

The cpu-arch option accepts keywords: unknown, X86, X86_64, ARMv7, AARCH64, PPC64LE (default: unknown).

Architecture validation logic (post-extraction):

sm = parse_sm_number(arch_string)         // sub_44E3E0
if sm <= 19:
    fatal_error("unsupported arch")
byte_2A5F224 = (sm > 72)                  // "new-style" ELF flag
if sm > 72 && machine == 32:
    fatal_error("sm > 72 requires 64-bit")
    byte_2A5F224 = 0
if sm > 99:                               // Mercury (Blackwell+)
    byte_2A5F222 = 1                      // mercury mode
    byte_2A5F225 = 1                      // SASS output mode
    byte_2A5B510 = 0
elif sm > 89:                             // sm_90+ needs SASS mode
    if sm <= 89:
        fatal_error("SASS mode requires sm >= 90")

Library Options

Global variable mappings:

Both library and library-path have multiplicity 2 (multi-value), so repeated -l / -L flags accumulate into linked lists. host-linker-options is accepted and stored but ignored by the device linker.

Linking Behavior Options

Global variable mappings:

The null-pointer reservation logic computes byte_2A5F2CD = reserve-null-pointer AND NOT dont-reserve-null-pointer. The dont-reserve-null-pointer flag always wins if both are specified.

The disable-smem-reservation and enable-extended-smem options accept true/false as values (boolean with multiplicity 1), with default "false".

no-opt and optimize-data-layout are mutually exclusive; specifying both produces a fatal error.

Dead Code Elimination Options

Global variable mappings:

use-host-info and ignore-host-info are mutually exclusive. If neither is specified, use-host-info defaults to true (byte_2A5F213 = 1, byte_2A5F214 = 1). If --relocatable-link is specified, ignore-host-info is forced on. If --kernels-used or --variables-used is specified, use-host-info is forced off with a warning.

LTO Options

Global variable mappings:

When --dlto is specified, byte_2A5F288 (the LTO master flag) is set to 1. The LTO options have extensive mutual-exclusion and dependency validation:

• --nvvmpath is required with -lto; omitting it produces: "-nvvmpath should be specified with -lto"
• --force-partial-lto and --force-whole-lto are mutually exclusive
• --emit-ptx requires -lto
• --Ofast-compile requires -lto
• --force-partial-lto without -dlto is an error
• --force-whole-lto without -dlto is an error
• --relocatable-link forces partial LTO mode

Both split-compile and split-compile-extended default to 1 (single-threaded). When --emit-ptx is specified with multi-threaded split-compile, the threads are forced to 1 with a warning.

LTO Forwarding Options

Global variable mappings:

The Ofast-compile option accepts: "0", "min", "mid", "max" (default: "0"). Any other value produces a fatal error referencing "--Ofast-compile". The values control optimization aggressiveness during LTO compilation:

• "max": Focus only on the fastest compilation speed, disabling many optimizations
• "mid": Balance compile time and runtime, disabling expensive optimizations
• "min": More minimal impact on both compile time and runtime
• "0": Disables fast-compile (full optimization)

Warning and Diagnostic Options

Global variable mappings:

After extraction, warning-as-error and disable-warnings/disable-infos are applied immediately:

sub_468420(byte_2A5F2C3);   // configure warning-as-error in diagnostics subsystem
sub_468430(byte_2A5F2C4);   // configure disable-warnings
sub_468430(byte_2A5F2C5);   // configure disable-infos

Verbose and Debug Output Options

Global variable mappings:

dump-callgraph and dump-callgraph-no-demangle are mutually exclusive.

When --debug is specified and --verbose-tkinfo was not explicitly given, byte_2A5F223 is forced to 1 (tkinfo is always verbose in debug builds).

CUDA API and Compatibility Options

Global variable mappings:

The cuda-api-version value is parsed with sscanf("%u.%u"). The major version must equal the toolkit version (dword_2A5B50C); the minor version is clamped to the minimum of the specified value and the built-in default (dword_2A5B508).

Security Options

Global variable mappings:

Both options have their "was specified" flags stored separately (byte_2A5F1FF for device-stack-protector, byte_2A5F1FC for device-stack-protector-frame-size-threshold), retrieved via option_was_specified.

Internal / Undocumented Options

Global variable mappings:

fdcmpt is a forward-compatibility flag. It is validated post-extraction: if fdcmpt is set but uumn is not set, a warning is emitted ("-fdcmpt"). If both are set but SM <= 69, a fatal error is produced. The flag controls data-model compatibility across architectures (exact semantics not fully determined from decompilation).

uumn is a companion to fdcmpt and has no help text.

The time option enables CSV timing output (used by NVIDIA's build infrastructure for performance tracking). When the file argument is "-", timing data goes to stdout.

Meta Options

Global variable mappings:

--help output format:

Usage  : nvlink [options] <objects>

followed by formatted help for all non-hidden options.

--version output format:

nvlink: NVIDIA (R) Cuda linker
Copyright (c) 2005-2025 NVIDIA Corporation
Built on Wed_Aug_20_01:58:59_PM_PDT_2025
Cuda compilation tools, release 13.0, V13.0.88
Build cuda_13.0.r13.0/compiler.36424714_0

--options-file (type 0 = file-list) is handled by the parser itself during option_parse_argv: response files are expanded in-place before option matching.

--trap-into-debugger installs signal handlers (via sub_42FA60) that trap into a debugger on assertion failure, then continues normal option parsing.

Post-Extraction Validation

After extracting all option values into global variables, nvlink_parse_options performs extensive cross-validation. The mutual-exclusion conflicts all use sub_467460 (the error/warning/fatal dispatcher) with format string unk_2A5B650 for fatal conflicts:

Compilation Mode Determination

The extracted options determine the overall compilation mode stored in dword_2A5B528:

Global Variable Map

Complete mapping from option name to BSS global variable address, sorted by address:

Response File Expansion

The option_parse_argv function (0x42E5A0) handles response files (also called options files) through the --options-file / -optf mechanism and the @file prefix. When the parser encounters an argument beginning with @, it reads the referenced file and expands its contents as additional command-line arguments in-place. This is recursive: a response file can reference other response files.

The --options-file option (type 0 = file-list, multiplicity 2) achieves the same effect through the parser's file-list processing infrastructure.

Interaction with Main

The nvlink_parse_options function is called exactly once from main (0x409800):

// In main():
arena = arena_create_named("nvlink option parser");     // sub_432020
// ... also creates "nvlink memory space" arena ...
nvlink_parse_options(argc, argv);                        // sub_427AE0
// All global variables are now populated.
// main() reads them directly for all subsequent pipeline decisions.

After nvlink_parse_options returns, the parser object itself is no longer referenced. All option values have been extracted into the global variables listed above, and the rest of the linker pipeline accesses those globals directly.

Cross-References

• CLI Flags Reference -- complete alphabetically-sorted quick-reference table of all 68 flags with types, defaults, and visibility
• Pipeline Overview -- how parsed flags drive mode dispatch and the 14-phase pipeline
• Entry Point & Main -- main() calling context for nvlink_parse_options
• Mode Dispatch -- how dword_2A77DC0 (set during option parsing) selects the code path
• ptxas Option Forwarding -- how --Xptxas options are forwarded to the embedded ptxas compiler
• LTO Option Forwarding -- how --Xptxas, --Xnvvm, --maxrregcount, and --Ofast-compile are forwarded to cicc/ptxas during LTO
• Dead Code Elimination -- how --kernels-used, --variables-used, --use-host-info, and --ignore-host-info drive DCE
• Debug Options -- detailed semantics of --debug, --suppress-debug-info, --edbg
• Environment Variables -- environment variables that supplement CLI options (e.g., LIBRARY_PATH)
• Architecture Profiles -- how --arch maps to the per-architecture vtable used throughout the pipeline
• Compatibility -- cross-architecture matching rules gated by the parsed SM number
• cicc wiki: CLI Flags -- cicc compiler CLI flags. The parser framework (option entry struct, hash table lookup, argv scanning) is shared infrastructure between nvlink, cicc, and ptxas
• ptxas wiki: CLI Options -- ptxas CLI options, using the same shared parser framework

Confidence Assessment