NDRC CLI reference

NDRC (Next DAAD Reborn Compiler) is a from-scratch C port of DRC, Uto's DAAD Reborn Compiler, verified byte-identical against DRC's own drf+drb pipeline (the reference implementation: https://github.com/Utodev/DRC). DRC ships as two programs (a drf front end and a drb back end) joined by a JSON file on disk; ndrc runs both stages in one process by default, and also exposes each stage on its own for tooling that wants the JSON intermediate directly.

Every command prints one banner line (NDRC 0.2.2 or NDRC 0.2.2 --to-json/--from-json) before anything else; that line is omitted from the examples below.

Join invocation (the normal case)

ndrc TARGET [SUBTARGET] LANG file.dsf [output.ddb] [symbols] [options]

Compiles a .DSF straight to a .DDB in one process: the drf stage reads and checks the source, the drb stage emits the database. Example:

ndrc NEXTDAAD EN game.DSF

writes game.DDB beside game.DSF. With no output name, the DDB name is the input's own name with its extension replaced by DDB (upper-case).

Targets and subtargets

14 targets. Four take a mandatory subtarget (given immediately after the target); the rest take none.

Target Subtarget required Subtarget values
NEXTDAAD no -
ZX yes 48K, 128K, PLUS3, ESXDOS, NEXT, UNO
ZX81 yes 16K, SD81B
PC yes VGA256, VGA, EGA, CGA, TEXT
MSX2 yes 5_6, 5_8, 6_6, 6_8, 7_6, 7_8, 8_6, 8_8, 10_6, 10_8, 12_6, 12_8
CPC no -
C64 no -
CP4 no -
CPM no -
MSX no -
PCW no -
AMIGA no -
ST no -
HTML no -

Target and subtarget names are case-insensitive. The target name itself is not validated by the source-reading stage - an unrecognised target compiles the source anyway and is only rejected once the database-writing stage sees it.

For any of the four subtargeted targets, the database-writing stage always prints a stray Debug: Checking subtarget <sub> for target <target> line before its own Target: line, win or lose - this is ported output, not something to act on.

Language

One of: EN, ES, DE, PT, FR. Case-insensitive.

Grammar after the input file

The argument immediately after the input file is claimed as the output name if it contains a dot anywhere; otherwise it is left for the options loop below, where a dotless argument becomes the additional-symbols list (see below). A --json=<path> argument is the one exception - it always contains a dot but is never claimed as the output name.

ndrc NEXTDAAD EN game.DSF out.ddb          out.ddb is the output
ndrc NEXTDAAD EN game.DSF EXTRA1,EXTRA2    both become #define symbols
ndrc NEXTDAAD EN game.DSF out.ddb EXTRA1   both output name and symbols

Only the last dotless argument survives as the symbol list; symbols are comma-separated and each becomes a defined constant, numbered by its position in the list (1, 2, 3...).

Options (source-reading stage)

Case-sensitive, dash-prefixed, recognised in any position after the input file.

Option Meaning
-verbose Print extra progress detail (target/subtarget line, stage confirmations).
-no-semantic Skip semantic analysis (only syntax is checked). Cannot combine with -semantic-warnings.
-semantic-warnings Report semantic problems as warnings rather than errors, so compilation still completes. Cannot combine with -no-semantic.
-force-normal-messages Force normal (non-extended) message handling. Cannot combine with -force-x-messages.
-force-x-messages Force extended-message (XMessage) handling. Cannot combine with -force-normal-messages.
-check-maluva-disabled Disable the MALUVA extension check.
-v3 Generate a DAAD V3 database. Default is V2.
-7 Generate a 7-bit ASCII database.
-replace-xcondacts Replace extended condacts with their standard equivalents.
-cols=40, -cols=80 Override the exported COLS symbol (NEXTDAAD 40-column text mode). Case-sensitive, NDRC extension. Any other value is an "Invalid option" error.

Options are matched left to right in one pass; an option's own confirmation line (when -verbose is on) reflects verbose's setting at that point in the argument list, not its final value - so option order can change what gets printed, though never what gets compiled.

Options (database-writing stage)

Case-insensitive (upper-cased before matching), dash-prefixed.

Option Meaning
-v Verbose output: per-section memory-map addresses, classic/debug mode and endianness status lines, and an "Adventure Totals" + created-file summary at the end. The size-per-block breakdown and final database size/address lines print regardless of -v.
-c Force classic mode (pre-DRC compatible output). Refused on NEXTDAAD - see below.
-ch Prepend a C64 header. Valid only for the C64 and CP4 targets.
-3h Prepend a +3DOS header. Valid only for the ZX target.
-d Force debug mode (extra debug information for the ZEsarUX debugger). On a target that does not support it, prints Debug mode active, but target is not ZX. Debug mode deactivated. and turns debug mode back off - the message says "not ZX" even on a target other than ZX that also lacks debug support (e.g. CP4); this is the printed text verbatim, not a target-name bug in ndrc.
-np Force no padding. Cannot combine with -p. WARNING: this flag writes whatever bytes have been emitted so far and stops immediately at the very first padding decision - the database is truncated mid-emission, well short of complete, and the run still reports success (exit 0) with no error. Reproduced from the reference implementation. Do not use.
-p Force padding. Cannot combine with -np.
-x Dump TX (text) sections to a separate 0.XMB file instead of embedding them in the database.
-b=<addr> Override the target's default base address. Decimal, or hex with a 0x/0X prefix. Must resolve to 1-0xFFFF.
-auto-tokens Select compression tokens from the game's own text instead of the builtin language table. Case-sensitive, NDRC extension. Accepted on the join and --from-json. Wins over an implicit .tok beside the input (a notice names the bypassed file). Encodes text with an optimal parse (smaller output than the sequential encoder); output DDBs remain format-identical and decode on every DAAD interpreter. Also compresses object texts and emits each duplicate text once (shared lookup entries); both stay format-identical.
--tok[=path] Write the selected token table as a standard .tok file (bare form: <input>.tok, where the normal override lookup finds it on the next run). Implies -auto-tokens. Like --json=, a --tok= argument is never claimed as the output name.
-no-object-tokens Keep object texts uncompressed under -auto-tokens or a marked .tok; duplicate sharing and the per-game table stay on, and under -auto-tokens the table is selected without object texts (a marked .tok keeps its table). For interpreters the object-text compression was not verified on. Case-sensitive, NDRC extension. Accepted on the join and --from-json. Without -auto-tokens or a marked .tok it is an error (-no-object-tokens requires -auto-tokens, exit 2).
-nxtext Emit NextDAAD text format 2 (Huffman-coded text with an indexed token dictionary); see "Text format 2" below. Implies -auto-tokens. NEXTDAAD target only. Case-sensitive, NDRC extension. Accepted on the join and --from-json.
-srcmap=<path> Write a DSM v2 source map to <path>: one record per emitted condact, entry and process (DSF file, line, column, DDB offset), plus the #define symbols. Used by the NextDAAD CSpect debugger. Case-sensitive, NDRC extension. Join only: --from-json refuses it (-srcmap needs a .DSF source input, exit 2, nothing written), because source positions exist only when the front end ran in-process. The DDB is byte-identical with or without it. File paths in the map are relative to the map's own directory. An empty path is an option error. With -np no map is written. A map that cannot be created is an error.

An unrecognised option, in either set, stops compilation immediately with an error naming it. A stray extra positional argument is not an error here: the join and --to-json absorb every dotless positional into the additional-symbols slot silently (only the last one is kept - see above), and a second dotted/dashed positional is likewise just whatever the grammar above already assigns it to. The database-writing stage's own standalone CLI (--from-json) is the one place a second stray positional is rejected outright - see below.

Per-game token selection

-auto-tokens replaces the builtin language token table with up to 128 tokens chosen from the compiling game's own text, then encodes the text with an optimal parse over that table. On real English games this measured 7.8% to 14.4% off compressed text+table against the builtin table. Selection is deterministic: the same source always produces the same table.

Object texts are compressed along with the other text tables, and identical texts within a table are emitted once, with every duplicate's lookup entry pointing at the one copy. The DDB format is unchanged.

Without the flag, output is byte-identical to DRC, as always. A compile with the flag self-checks: every compressed message is decoded back and compared against the source text, and the emitted DDB is verified by decoding every text through its lookup table, before the DDB is written.

The freeze workflow: compile once with -auto-tokens --tok, then drop both flags - the written .tok sits beside the input where the normal override lookup picks it up. The tee records "encoder": "optimal" and the reload honours it, so the frozen build is byte-identical to the flagged one. A marked .tok compiles with object compression and duplicate sharing on reload; unmarked and hand-written .tok files compile exactly as DRC would. Stock DRC accepts a marked .tok and simply ignores the field. A tee written under -no-object-tokens also carries "objects": false, and the reload honours it: object texts stay uncompressed and the frozen build is byte-identical to the flagged one.

On targets other than NEXTDAAD, selected tokens never contain _ or @ (object-name and print placeholders): on the original ZX Spectrum interpreter a _ arriving from inside a token prints literally instead of substituting the object name, so such tokens would silently change the game's output. NEXTDAAD expands tokens byte-transparently and has no such restriction.

On targets other than NEXTDAAD, each object text keeps its first word, the run of spaces after it and every . uncompressed; a text with no space stays wholly uncompressed, and tokens containing . are never used in object texts. The original ZX Spectrum, CPC and MSX interpreters strip an object's article by scanning the stored bytes for the first space, before any token is expanded, so a token over that span would change the printed name. NEXTDAAD strips the article from the decoded text and has no such restriction.

On the optimal rows (-auto-tokens or a marked .tok) the token table is emitted most-referenced first: interpreters scan the table from its first entry on every reference, so common tokens are found sooner. The format is unchanged.

Under -v a selecting build prints Auto-tokens: <n> candidates, <n> selected., then Compression tokens used: <n>. (the table length, counting the empty entry 0) and Token table ordered by use.. A marked .tok reload prints only the last two. Every table whose duplicates were shared adds Shared <n> duplicate texts in <table> (<n> bytes)., where the table is objects, sysmess, messages or locations and the bytes are the saving.

Text format 2

-nxtext lets the compiler emit NextDAAD text format 2, a NEXTDAAD-only text encoding: every text (objects, system messages, messages, locations and XMESSAGEs) is one canonical Huffman bit stream ending in its own end-of-message code, over a per-game dictionary of up to 383 tokens, each reachable through a 2-byte index. Only a NextDAAD that reads the region layout can open such a DDB: the version byte carries bit 7 (0x82, or 0x83 under -v3), which every other interpreter and every older NextDAAD refuses.

The file is part A followed by the text region. Part A holds the header, tables, vocabulary and processes; header offset 32 holds its length. The text region holds the format 2 text block (magic "H2") at region offset 0, then the coded texts, and header offset 8 is 0. Every text lookup word is an offset into the region, not a memory address. Part A and the region are each limited to 65535 bytes, so a file can reach 131070.

The compiler builds format 1 as -auto-tokens does and format 2 from the same texts, and emits format 2 whenever the selection found a token: the indexed dictionary is what makes printing faster, so a small game gets it even when format 2 comes out larger (the text block costs at least 135 bytes before any token). Under -v such a build prints Text format 2 is <n> bytes larger than format 1. (texts, text block and XMB, each duplicate text counted once in both formats). Only a game with no repeated text at all is emitted as the format 1 build, with or without -v:

Text format 2 has no tokens; format 1 emitted.
 

Under -v a format 2 build prints Text format 2: <n> tokens, <bits> bits per symbol, <bytes> text bytes. and the "Compression Tokens" line of the size report gives the text block size. Format 2 texts are stored as is (no XOR) and duplicate texts are still emitted once. -no-object-tokens does not apply when format 2 is emitted: object texts are coded like every other text.

A format 2 build adds Part A is <n> bytes, text region is <n> bytes. to the size report after the total, and -v adds a Text region line to the address map; its value is part A's length (the region's file offset), not a memory address. The Database ends at address line is the end of part A. Part A over 65535 is the usual DDB file goes <n> bytes over the 65535 memory address boundary; a region over 65535 is Text region goes <n> bytes over the 65535 limit (exit 2, no DDB written).

Under format 2, 0.XMB is written after coding, with a 4-byte header: "X2" and the 16-bit fingerprint (CRC-16 of the text block's code lengths) the text block also carries, so a stale XMB is detected. XMESSAGE offsets count from the start of the file, so the first is 4. An XMESSAGE whose coded stream exceeds 8K is an error (XMESSAGE <n> exceeds 8K coded, exit 2).

Refused combinations, each exit 2:

  • any target other than NEXTDAAD: -nxtext requires the NEXTDAAD target
  • -x: -X is not available with -nxtext (NextDAAD does not read messages, system messages or locations from the XMB)
  • --tok: --tok is not available with -nxtext (a format 2 dictionary cannot be written as a .tok)

Without -nxtext every build is byte-identical to before.

--json[=path]

Available only on the join invocation. Tees the JSON the source-reading stage produces to a file, without changing the compile in any other way:

ndrc NEXTDAAD EN game.DSF --json              writes game.json
ndrc NEXTDAAD EN game.DSF --json=dump.json     writes dump.json
 

Bare --json writes <input>.json (the same default name the flow would use internally) beside the input file. The tee is written as soon as the source-reading stage finishes, so it is still produced even if the database-writing stage later refuses the input.

--to-json (source-reading stage only)

ndrc --to-json TARGET [SUBTARGET] file.dsf [output.json] [symbols] [options]

Runs only the drf-equivalent stage: reads and checks a .DSF and writes DRC's JSON intermediate format, without producing a database. This is DRC's own front-end/back-end interchange format - other tools in the DAAD ecosystem may read or write it directly. Grammar, target list, language rules (there is no language argument in this mode - language is a database-writing-stage concern) and the source-reading options table above all apply unchanged. With no output name, the JSON is written as <input>.json.

--from-json (database-writing stage only)

ndrc --from-json TARGET [SUBTARGET] LANG input.json [output.ddb] [options]

Runs only the drb-equivalent stage: reads a JSON document in DRC's intermediate format and writes a .DDB. The target/subtarget/language rules and the database-writing options table above apply unchanged. With no output name, the DDB is written as <input>.DDB (extension replaced, upper-case).

Unlike the join and --to-json, a missing required argument here (target, subtarget, language or input file) is reported as Error: usage: ndrc --from-json ... and exits 2, not 1 - see Exit codes below.

The first non-option argument after the input file is the output name; a second one is rejected outright with Error: Bad parameter: <argument>., exit 2 - unlike the join and --to-json, where an extra dotless positional is just silently absorbed as the (last-wins) symbol list.

The NEXTDAAD / #classic refusal

A source file's #classic directive (or the -c option) asks for classic, pre-DRC-compatible output. This is refused for the NEXTDAAD target specifically, because the original pre-DRC interpreters cannot read a NEXTDAAD database at all - the machine byte and pointer base both differ. The database-writing stage reports:

Error: #classic is not supported on NEXTDAAD: the original pre-DRC
interpreters cannot read a NEXTDAAD database at all, since the
machine byte and pointer base both differ.

and exits with code 2. -c cannot override this refusal.

Exit codes

Code Meaning
0 Success.
1 The join's or --to-json's own too-few-arguments usage message, or a compile-time syntax/semantic error in the source.
2 A parameter error (bad option, bad file, bad grammar), --from-json's own too-few-arguments usage message, or a database-writing-stage error (invalid target/subtarget/language, refused input, I/O failure).

The usage message is not a fixed exit class: the join and --to-json print their own text directly and exit 1 when too few positional arguments are given; --from-json instead reaches its usage text through the database-writing stage's own error path (Error: prefix, trailing period) and exits 2. A completely bare ndrc invocation (no arguments at all) falls back to --from-json's usage path and so also exits 2.