The `fj` command-line tool¶

fj is the FlipJump assembler and interpreter in one command. By default it does both: it assembles your .fj source files into a .fjm memory image and immediately runs it.

fj a.fj b.fj          # assemble a.fj + b.fj (+ the STL) and run the result

The command is installed as the fj console-script when you pip install flipjump — see Installation.

Usage¶

fj [--asm | --run] [arguments] files [files ...]

files is one or more .fj source files (or, with --run, a single .fjm file). When you pass several .fj files they are concatenated in order, after the standard library.

A few real invocations (from fj’s own help text):

fj  a.fj b.fj                                    # assemble and run
fj  a.fj b.fj  -o out.fjm                        # assemble, save out.fjm, and run
fj  code.fj  -d  -B swap_start exit_label         # assemble and debug

fj --asm  -o o.fjm a.fj  -d dir/debug.fjd         # assemble + save debug info
fj --asm  -o out.fjm a.fj b.fj  --no_stl  -w 32   # assemble, no STL, 32-bit memory

fj --run  prog.fjm                               # just run a prebuilt image
fj --run  o.fjm  -d dir/debug.fjd  -B label       # run and debug

Choosing a phase¶

By default fj assembles and runs. These two mutually-exclusive flags pick a single phase:

Flag	Effect
`-a`, `--asm`	Assemble only. Run-time arguments are ignored. Pair with `-o` to keep the output.
`-r`, `--run`	Run only. The positional argument is a `.fjm` file; assemble-time arguments are ignored.

Universal options¶

These apply in every mode:

Option	Meaning
`files`	The `.fj` files to assemble — or, with `--run`, the `.fjm` file to run.
`-s`, `--silent`	Don’t print assemble/run times or run statistics.
`-d`, `--debug [PATH]`	Debug-file path, used for breakpoints. When you both assemble and run you may pass `-d` with no path and a temporary file is used.
`-V`, `--flipjump_version`	Print the installed flipjump version (e.g. `flipjump 1.5.0`) and exit. New in 1.5.0 — note lowercase `-v`/`--version` is the unrelated `.fjm` format version below.

Assemble options¶

Ignored when --run is given.

Option	Meaning
`-o`, `--outfile PATH`	Write the assembled `.fjm` to `PATH`. Without it, assembly is held in memory and (unless `--asm`) run directly.
`-w`, `--width WIDTH`	Memory width in bits — one of `8`, `16`, `32`, `64`. Default `64`.
`-v`, `--version VERSION`	`.fjm` format version (see The `.fjm` binary format). Defaults to 3 (Compressed) when `--outfile` is given, 1 (Normal) otherwise.
`-f`, `--flags FLAGS`	Default `.fjm` unpacking & running flags (integer). Default `0`.
`--lzma_preset N`	LZMA2 compression preset `0`–`9` (default `6`), used when `version=3`.
`--werror`	Treat all assemble warnings as errors.
`--max_recursion_depth N`	Maximum macro-recursion depth the compiler allows.
`--no_stl`	Don’t assemble/link the standard library. You’re then on your own for startup, I/O and everything else.
`--stats`	Show macro code-size statistics.

Run options¶

Ignored when --asm is given.

Option	Meaning
`-t`, `--trace`	Print every opcode as it executes. Verbose — for the smallest programs only. Forces the featured (slower) engine.
`--profile`	Collect the full per-op statistics (flips/jumps percentages). Uses the slower featured run-loop.
`--io MODE`	Pick the IO device — `standard` (terminal, the default) or `pc` (interactive window). See Choosing an IO device.
`--debug-ops-list LENGTH`	On a run that ends abnormally, show the last `LENGTH` executed opcodes. Off by default (tracking them slows the engine); auto-enabled when debugging, tracing, or profiling.
`--flat-max-words N`	The native engine’s flat-storage window, in words (`2^23` by default). Memory below the window runs in the fast flat array; raising it costs startup time and memory (8 bytes per word of window), never per-op speed.
`-b`, `--breakpoint NAME [NAME ...]`	Pause when execution reaches a label named exactly `NAME`.
`-B`, `--breakpoint_contains NAME [NAME ...]`	Pause when reaching any label whose name contains `NAME`.

Interpreter engines¶

Since 1.5.0 the interpreter has three engines, picked automatically:

Native engine (~300M fj-ops/s) — a C extension prebuilt in the official wheels (Linux glibc/musl, macOS, Windows; every CPython ≥ 3.10). Used automatically whenever present. Set FLIPJUMP_NO_NATIVE=1 to disable it, or FLIPJUMP_FLAT_MAX_WORDS to set the same limit as --flat-max-words.
Fast loop (~4M fj-ops/s) — pure Python, the fallback when the native engine isn’t built.
Featured loop — used automatically for --trace, breakpoints, and --profile; collects the full per-op statistics.

Choosing an IO device¶

--io MODE selects one complete IO device that owns all of the program’s input and output:

Mode	Behaviour
`standard` (default)	Input/output over the terminal.
`pc`	An interactive window: live keyboard input and a scaled 256-color screen, in one window the device owns. `F11` toggles fullscreen; closing the window stops the run. Needs pygame — `pip install "flipjump[io]"`. Works on Windows, Linux, and macOS.

fj --run prog.fjm --io pc       # run with the keyboard+screen window

The language-level IO opcode is unchanged; the device just decides where those bits go (the pc screen even reads pixel data straight from program memory). See Input / Output for the language side.

Debugging¶

The -d/-b/-B options drive FlipJump’s interactive CLI debugger. Breakpoints are matched against label names, so they need debug information: when you assemble and run in one go, -d (no path) keeps it in a temporary file for you; when you split the phases, write the debug file at assemble time (--asm -o out.fjm -d dir/debug.fjd) and feed it back at run time (--run out.fjm -d dir/debug.fjd -B label).

At a breakpoint the debugger prints the current address (with its macro-stack label) and waits for a command. The commands are case-insensitive:

Command	Does
`h` / `help` / `?`	Show the help, including every `read` target format.
`r` / `read TARGET`	Read a memory word or a FlipJump variable — by address, by label, or as a typed `:type:` variable (bit/hex/byte and their vectors).
`s` / `step`	Execute one op.
`s` / `skip N`	Execute `N` more ops, then stop (`N` decimal or `0x`-hex). `s` with an argument means skip; without one it means step.
`c` / `cont` / `continue`	Run to the next breakpoint.
`c*` / `ca` / `continue all`	Run to the end, ignoring all remaining breakpoints.
`q` / `quit` / `exit`	Stop the run (also Ctrl+C / EOF).