Tooling & CLI Reference

title: 'Tooling & CLI Reference'

Tooling & CLI Reference

This reference guide documents spasm, the command-line assembler tool for the Sparsr toolchain.

Assembler CLI (spasm)

spasm is a single-binary command-line interface that compiles Sparsr assembly source files into binary executable kernel files (.spex). It wraps the native assembler engine into a standalone executable tool.

Usage Syntax

spasm <assembly-file>

Positional Arguments

Argument Type Required Description
<assembly-file> Path Yes Path to the Sparsr assembly source file (.asm, .s, etc.) to compile.

Output Behavior & File Naming

When spasm executes, it parses the input source file and writes the compiled binary output according to the following conventions:

  • Output Location: Output .spex files are always written to the current working directory from which spasm is invoked.
  • Output Extension: Output filenames take the base name of the input file and replace its extension with .spex.

  • Example Usage:

    spasm /path/to/my_kernel.asm

    Produces ./my_kernel.spex in the current working directory.

Console Output & Exit Status

spasm reports execution status through standard output streams (stdout and stderr) and standard exit codes.

Exit Status Codes

Exit Code Status Description
0 Success Assembly completed successfully and output binary was written to disk.
1 Failure Invalid arguments, missing source file, or assembly compilation error.

Console Output Messages

Invalid Arguments (stderr)

Usage: spasm <assembly-file>

Missing Input File (stderr)

Assembly file not found: /path/to/file.spasm

Assembly Compilation Error (stderr)

Failed to assemble the input file.

Technical Specifications & Environment

Operating Constraints

  • Maximum Instructions: Supports up to 1024 instructions per assembly file buffer.
  • Text Input Encoding: Supports ASCII and UTF-8 encoded text files (including UTF-8 with BOM).
  • Binary Encoding Format: Produces 32-bit big-endian instruction words terminated with standard execution control markers (0x00000000 and 0xFFFFFFFF).

Shared Library Dependencies

spasm requires the native libsparsr_asm.so shared library at runtime. The CLI binary automatically searches for libsparsr_asm.so in the following locations relative to the spasm executable:

  1. Executive binary directory (./libsparsr_asm.so)
  2. Sibling library directory (../lib/libsparsr_asm.so)