sekura-js Command-Line Reference

This document describes the implementation at source revision 6dd5716a8f3bcf29d27ae9ca64800bb517601236.

Documentation version: 1.1
Target: Memora8

1. Commands

sekura-js check <file> [--mono]
sekura-js ast <file> [--mono]
sekura-js compile [options] <file> [...]
sekura-js assemble [file.sasm] [...]

The command name is required. There is no default compile command. With no arguments, sekura-js prints usage to standard error and exits with status 1. There is no top-level --help or --version option in the current compiler CLI; an unrecognized first argument is reported as an unknown command.

For all source-reading commands, .sjs is appended when the supplied path does not already end in .sjs. compile accepts multiple input files and processes each separately. check and ast require exactly one input.

2. check

sekura-js check program.sjs
sekura-js check program --mono

Reads and parses the source, then validates types. On success it prints Syntax OK. Without --mono, it loads the input and its SJS libraries using the simple loader. With --mono, it recursively resolves imported SJS source files before validation.

Success returns 0. Invalid arguments, missing files, parse errors, or validation errors return 1.

3. ast

sekura-js ast program.sjs
sekura-js ast program.sjs --mono

Loads and validates one source file, then prints its AST. --mono selects the recursive import loader described under check.

Success returns 0; usage or processing errors return 1. Options such as -O2, --otm, --no-sobj, and --final-only are consumed by the shared argument parser but have no compilation effect for check or ast; only --mono changes their source-loading mode.

4. compile

sekura-js compile [options] program.sjs [other.sjs ...]

Each input is compiled separately for Memora8. In the ordinary non-mono runtime-module path, the compiler generates assembler text, assembles it, links an SOBJ, and writes module metadata. Options may appear before, between, or after input paths; every argument not recognized as an option is treated as an input path.

The default settings are:

Setting Default
Optimization level -O0
Recursive/monolithic loading Off
OTM optimizer option Off
Write .sobj Yes
Retain .sasm and .sdef Yes

Supported options:

Option Implemented behavior
-O0 through -O4 Sets the integer optimization level passed to code generation and the peephole optimizer. Default is -O0; values above 4 are rejected.
--otm, -OTM Enables the OTM boolean passed to the peephole optimizer. It does not select or change the -O level. In the current peephole implementation, OTM applies the same function dead-code elimination pass used at level 2.
--mono Uses the recursive source loader, which follows imported SJS files and flattens imported declarations into one program. It disables ordinary runtime-module metadata handling and .smod output.
--no-sobj Suppresses .sobj; .sasm and .sdef are still written unless --final-only is used.
--final-only Suppresses .sasm and .sdef; .sobj is still written unless --no-sobj is used. For a non-mono runtime module, .smod is still written.

--no-sobj and --final-only cannot be used together. assemble rejects compile-only flags including --mono, --otm, -O*, --no-sobj, and --final-only.

Output files

For an ordinary non-mono runtime module, the compiler normally writes:

program.sasm
program.sdef
program.sobj
program.smod
  • .sasm is generated assembly text.
  • .sdef is the symbol/layout definition used by assemble; it must include text_base and data_base. It can also include entry_point.
  • .sobj is the linked binary object for Memora8.
  • .smod is module metadata written for non-library runtime modules in non-mono mode.

--no-sobj suppresses only .sobj. --final-only suppresses only the standalone .sasm and .sdef files. A library module does not get .smod from this path. Mono mode does not write .smod.

The output basename comes from the input argument with a terminal .sjs removed. If no .sjs suffix was supplied, the compiler reads <argument>.sjs and writes outputs using <argument> as the basename.

Module metadata side effects

In non-mono mode, a runtime module may reuse its existing sibling .smod to obtain module name, RegID, and system-module status. If the source has a named module declaration without a RegID, and the compiler generates one, it attempts to write that RegID back into the .sjs source. Compilation can therefore modify the input source file. The .smod output records the generated or selected module metadata and exports.

Examples

sekura-js compile app.sjs
sekura-js compile -O3 --final-only app.sjs
sekura-js compile --mono app.sjs
sekura-js compile --no-sobj module_a.sjs module_b.sjs
sekura-js compile -O2 --otm app.sjs

A successful invocation prints per-file output notices and a summary with text/data word counts, function count, optimization label, and entry address when present. Diagnostics are written to standard error; summary output is written to standard output.

5. assemble

sekura-js assemble program.sasm
sekura-js assemble module_a module_b.sasm

For each argument, .sasm is appended unless the argument already ends in .sasm. The command requires a sibling .sdef with text_base and data_base, assembles the text, links it, and writes a sibling .sobj. It does not write .sasm, .sdef, or .smod.

Success returns 0. Missing inputs, incomplete .sdef, assembly/link errors, or invalid options return 1. Multiple inputs are processed in order; an error stops the invocation.

6. Exit statuses

For check, ast, compile, and assemble:

Status Meaning
0 Command completed successfully.
1 Missing/invalid arguments, unknown command, input or output error, parse/type/assembly/link error, or other processing failure.

sekura-js also retains legacy SJV commands. Their status values are those of the shared SJV dispatcher and differ from the compiler commands: verification may return 2 when a counterexample or unverified result is reported. See the sekura-sjv CLI reference for those commands and outcomes.

7. Legacy SJV aliases

These commands are still dispatched by sekura-js; use the standalone sekura-sjv executable for the current verification CLI:

sekura-js sjv <subcommand> ...
sekura-js sjv-ast <file.sjv>
sekura-js verify-model <file.sjv>

The sjv dispatcher currently accepts the verification commands implemented by the shared SJV CLI, including parse, resolve, verify-model, verify, build-verify, make-sjv/make-sjp, keygen-ed25519, sign-sjp, and verify-sjp. sjv-ast prints SJV model counts. These are compatibility entry points, not compiler commands; their argument formats and exit statuses are documented in the separate sekura-sjv CLI reference.

8. Current argument-handling details

  • Options are parsed after the command; the compiler does not support -- as an option terminator.
  • An unrecognized option after a valid compiler command is treated as a filename rather than rejected as an unknown option.
  • The top-level CLI does not implement --help or --version after a command. For example, sekura-js compile --help treats --help as an input path.
  • -O5 and larger one-digit optimization levels are rejected. -O values must use the exact -O0 … -O4 spelling.
  • Invalid command shapes produce a specific argument error; processing exceptions are reported as Error: ... and return status 1.

9. Implementation references

Checked against the source revision above:

  • src-js/main.cpp — command dispatch, options, input resolution, output selection, and exit statuses;
  • src-js/peephole_optimizer.cpp and src-js/codegen_memora8.cpp — optimizer flags and level handoff;
  • src-sjv/cli/cli.cpp — legacy SJV dispatcher reached through sekura-js;
  • src-sjv/cli/main.cpp — standalone SJV command summary.

No tests or site build were run while preparing this reference.