Defaults and Config-File Model

All symbols and addresses on this page apply to neuronx_cc 2.24.5133.0+58f8de22 (cp310 Cython modules under neuronxcc/). The cp311 and cp312 wheels carry the byte-identical module layout (same three .so files at the same paths) and the same negative result. Treat every address as version-pinned.

Abstract

This page documents a negative result, and the negative is the whole point: neuronx_cc has no config-file mechanism. There is no argparse response-file (fromfile_prefix_chars / @file), no .cfg / .ini / .rc / .json / .toml / .yaml settings reader, no configparser, and no getenv read in the option layer. Every option the compiler honors arrives through one channel — sys.argv — and every default is bound at the moment the flag is registered, by the ordinary argparse default= keyword on the add_argument call. A reader who goes looking for a neuronx-cc.conf, a ~/.neuronxccrc, or an @options.txt response file will not find one because the code to read it was never written. This page proves that, so nobody hunts for a file that does not exist.

The proof rests on an exhaustive string-pool and symbol scan of the three modules that own the option machinery — penguin/Options.so (the Penguin backend's CommandLineParser), driver/Arguments.so (the top-level InterceptingArgumentParser), and driver/CommandDriver.so (the dispatcher that owns sys.argv) — widened to the whole neuronxcc wheel. None of them link argparse's fromfile internals; none import configparser; none call getenv. The single environ interned name that survives the scan lives in CommandDriver alongside multiprocessing / Process and is the child-process environment handed to the fork, not an option source. The familiar trap — ELF section names .init / .init_array matching a naive .ini grep — is called out below so it does not masquerade as a config reader.

The positive half is short. Defaults are distributed, not centralized: there is no monolithic "defaults dataclass." Each flag's default is the default= argument on its add_argument call; argparse seeds the result Namespace with those defaults before parsing; sys.argv overrides only the flags the user actually passed. RecordUsedAction (in driver/Actions.so) exists precisely to distinguish a user-supplied value from a pre-seeded default. That is the entire model.

For reimplementation, the contract is:

• The only inbound option channel is sys.argv — passed to CommandDriver.main → InterceptingArgumentParser.parse_known_args. Reproduce nothing else; there is nothing else.
• Defaults are registration-time — bound by add_argument(..., default=…) and mirrored into _ArgumentRegistry.arguments_by_context for help/introspection. There is no second resolution pass and no override file.
• The absences are load-free — a faithful reimplementation must omit fromfile_prefix_chars, omit any config reader, and omit env reads in the option path. Adding any of them is a divergence from the binary.

The only option source is sys.argv

There is exactly one door. CommandDriver.main (@0x17a90) builds the top InterceptingArgumentParser and calls parse_known_args on the process argument vector — the interned names argv, parse_known_args, known_args, and delegated_args are all present in CommandDriver.so's pool. parse_known_args splits the vector into the driver-level Namespace and the leftover delegated_args, which become the sub-command's argv. Nothing in this path consults a file or the environment.

sys.argv
   │
   ▼
CommandDriver.main  (0x17a90)
   │  builds InterceptingArgumentParser (Arguments.so)
   ▼
parse_known_args(argv)        ── 'argv','known_args','delegated_args' in pool
   │
   ├─► driver Namespace        (global flags; defaults pre-seeded, argv overrides)
   └─► delegated_args ────────► CompileCommand consumes (subcommand argv)

NOTE — NEURON_CC_FLAGS is not an exception. The well-known NEURON_CC_FLAGS environment variable is read by the framework integration (PyTorch-XLA / JAX glue) outside the wheel; that code prepends its tokens to argv before neuronx-cc ever runs. By the time CommandDriver.main sees them they are ordinary argv tokens. The wheel itself performs no getenv for options — see 3.11 Env-Var Catalog. This is why a string scan of the option modules finds no env read even though the compiler "respects" an env var.

Defaults are bound at registration, not resolved from a file

A default is not looked up; it is seeded. When a flag is registered with add_argument(name, default=X, …), argparse stores X on the action and writes it into the Namespace before parsing begins; parse_known_args then overwrites only the entries whose flags appeared on the command line. Arguments.so's pool confirms the registration-time API — add_argument, default, get_default, parse_known_args — and notably lacks any set_defaults-from-file or second-pass override. The custom layer adds bookkeeping (kind, job) but changes none of this.

// The defaults-resolution flow — models InterceptingArgumentParser
//   (driver/Arguments.so) over stock argparse. No file is ever consulted.

function register_flag(parser, name, default, kind, job, **kw):     // add_argument @0x11320 / 0x19210
    action = super_add_argument(name, default=default, **kw)        // argparse binds default onto the action
    captured = action.default                                       // == get_default(name); the registration-time value
    registry.storeArgument(context, action, kind, job, captured)    // mirror into arguments_by_context (B.2)
    return action                                                   // NO config/env consulted anywhere here

function resolve_options(argv):                                     // CommandDriver.main @0x17a90
    ns = Namespace()
    for action in parser._actions:                                  // argparse pre-seeds every default
        setattr(ns, action.dest, action.default)                   // <-- this IS the default mechanism
    driver_ns, delegated = parser.parse_known_args(argv, ns)        // argv overrides only the flags the user passed
    return driver_ns, delegated                                    // sole inputs: argv + the seeded defaults

QUIRK — defaults are distributed, not a dataclass. The AF-strand brief hypothesised a single "Options defaults object." There is none. Each flag carries its own default=; the only aggregate view is _ArgumentRegistry.arguments_by_context (an OrderedDict, literal arguments_by_context confirmed in Arguments.so), which mirrors each (argument, kind, job, default) record purely for help/introspection — it is a read model for print_help_hidden, not the resolution mechanism. RecordUsedAction (driver/Actions.so) exists only because defaults are pre-seeded: it marks a flag as explicitly-set so downstream code can tell a real user value from a seeded default. See 3.2 Two-Parser Architecture.

The exhaustive absence scan

A negative result is only as strong as the scan behind it. The method: strings -a over each .so's full string pool plus objdump -T over its dynamic symbol/PLT table, then widened to a wheel-wide grep -rIl over every *.so. Counts below are literal rg -c hits in the pool; 0 means the token does not appear anywhere in the module — neither as a Python identifier (__pyx_n_s_*), a literal, nor a docstring.

¹ CommandDriver.so carries one environ interned name (__pyx_n_s_environ, __pyx_k_environ). It co-occurs in the pool with multiprocessing, Process, and argv and lives in run_subcommand_in_process (@0x19110) — it is the environment dict propagated to the forked child (C.3), not a read of any option key. No getenv appears in the PLT, so there is no C-level environment read at all.

² CommandDriver.so contains shlex paired only with quote (never split) — that is shlex.quote for the diagnostic command echo (getReplayCommandLine, 3.5 Sub-Tool Argv), not option parsing. Options.so's parseOptions uses a bare str.split() (interned split, no shlex anywhere) to whitespace-tokenize its flat backend string — still not a file or env read.

GOTCHA — .init is not .ini. A naive rg -i '\.ini' over any of these .so files returns two hits: .init and .init_array. Those are ELF section names, not an INI config reference — every shared object has them. The scan above excludes them by matching the literal token configparser / .cfg / read_config rather than the substring ini. A reimplementer auditing for config support must apply the same exclusion or they will "find" a config reader that is just the constructor section table.

Where the brief expected a config and what is there instead

Three plausible config surfaces were checked explicitly, each resolving to an argv- or in-memory mechanism:

• @-response files (argparse's built-in): would require fromfile_prefix_chars='@' on a parser constructor and pull in _read_args_from_files. Both are absent in all three modules and wheel-wide. neuronx-cc -O2 @opts.txt would treat @opts.txt as a literal positional, not expand it.
• A backend options file: penguin/Options.so's CommandLineParser.parseOptions (@0xbf40) does take a string of flags — but it is a string passed in memory (e.g. the value of a backend-options flag), split with str.split() and fed to parse_args. There is no open() of a settings file; Options.so is pure in-memory argparse over a passed-in string.
• An env-driven defaults override: would need getenv / os.environ.get(KEY) in the option path. The PLT has no getenv in any of the three; the one environ name is the fork env. The compiler's env-sensitivity is entirely upstream of the wheel (3.11).

Adversarial self-verification

Each strongest claim below is an absence; the verification challenges it by trying to find a counter-example in the binary. Where a counter-example cannot be exhaustively ruled out, the claim is tagged INFERRED rather than CONFIRMED.

1. "No fromfile_prefix_chars / @-response file anywhere." Challenge: argparse's fromfile is opt-in via the constructor and via the _read_args_from_files method — either token would betray it. Both return 0 across Options.so, Arguments.so, CommandDriver.so, and a wheel-wide grep -rIl '_read_args_from_files' --include='*.so' (0 files). The InterceptingArgumentParser.__init__ (@0x146a0) does not pass fromfile_prefix_chars. CONFIRMED.

2. "No configparser / .cfg / .ini / .rc config reader." Challenge: a config reader could hide behind a renamed helper. Scanned for the parser (configparser), the file extensions, and the verbs (read_config / load_config); all 0. The only ini substring hits are the ELF .init / .init_array sections (excluded by token-exact matching). Wheel-wide configparser grep: 0 files. CONFIRMED.

3. "No getenv / env read in the option path." Challenge: env reads can be C-level (getenv@plt) or Python-level (os.environ). The PLT carries no getenv import in any of the three modules. The single Python environ name is in CommandDriver's run_subcommand_in_process, paired with multiprocessing/Process/argv — the child-fork environment, not an option key. I could not trace the exact opcode that touches environ, only its pool co-residence and the absence of any option-key string near it; the option-source claim is therefore STRONG, the broader "no env read at all in CommandDriver" is INFERRED (the name exists; its use as fork-env is the best-supported reading, but the precise call was not disassembled).

4. "The only inbound option source is sys.argv." Challenge: a second source would surface as a file-read or env-read feeding the parser; both ruled out by (1)–(3). Positive evidence: argv, parse_known_args, known_args, delegated_args are all present and form the documented inbound chain. CONFIRMED for the option vector itself. (Input model files — the .hlo/.pb the compiler reads — are positional argv values, not an option config; out of scope.)

5. "Defaults are bound at registration, with no override file." Challenge: a defaults file would need set_defaults-from-file or a post-parse merge. Arguments.so exposes add_argument, default, get_default (registration-time) and arguments_by_context (the mirror), but no file-backed set_defaults and no second resolution pass. The registration-time binding is CONFIRMED; that no downstream code re-reads or overrides a default from a file is STRONG (proven for the option modules; a defaults override buried in an unrelated module cannot be exhaustively excluded, though the wheel-wide config/fromfile scans returning zero make it very unlikely).

CORRECTION (AF05) — an earlier framing of this strand expected penguin/Options.so to be the resolved top-level "defaults object" holding the -O{0..3} map. It is not. Options.so is a separate backend lane — the Penguin CommandLineParser singleton — with per-flag defaults supplied at addOption time and no opt-level table. The top-level CLI and its defaults live in driver/Arguments.so. The two parsers are independent; see 3.2 Two-Parser Architecture.

Related Components

Cross-References

• Two-Parser Architecture — 3.2; the top-level InterceptingArgumentParser vs. the Penguin CommandLineParser, and where each flag's default lives
• Sub-Tool Argv Construction — 3.5; how the resolved Namespace is marshalled back into per-Job sub-tool argv (the only place shlex.quote appears)
• Env-Var Catalog — 3.11; NEURON_CC_FLAGS and friends are consumed by the framework integration outside the wheel, then prepended to argv