Hypotenuse Compiler CLI Reference: Commands and Flags

Full reference for the hypotenuse command-line compiler: flags for output format, architecture, debug output, assembly, and library management.

The hypotenuse command compiles C△ source files (.ctri) and library files (.plib) into native binaries. You can control output format, target architecture, debug output, and library management through flags. Without the -c flag, the compiler prints the generated C code to stdout instead of producing an executable — useful for inspecting or piping the intermediate output.

Basic Usage

hypotenuse [options] <file.ctri>

Quick Examples

These examples cover the most common workflows:

# Compile a file and produce a native executable
hypotenuse -c hello.ctri

# Compile with a custom output path
hypotenuse -c -o build/hello hello.ctri

# Debug: print lexical tokens and exit
hypotenuse -t hello.ctri

# Debug: print the structure/scope graph
hypotenuse -p hello.ctri

# Compile with extra gcc flags (e.g., SDL2)
hypotenuse -c -C "$(sdl2-config --cflags --libs)" graphics.ctri

# Show generated assembly
hypotenuse -a hello.ctri

# Install a library to PLIBS
hypotenuse -i mylib.plib

# Remove a library from PLIBS
hypotenuse -r mylib

All Flags

-c / --compile · flag

Compile with GCC to produce an executable. Without this flag, the compiler prints the generated C code to stdout instead of writing an output file.

-o / --output · PATH

Write compiled output to PATH. When used with -c, this sets the name of the output executable.

-C / --cflags · FLAGS

Pass extra flags directly to GCC. Use this to link external libraries or set compiler options.

hypotenuse -c -C "$(sdl2-config --cflags --libs)" graphics.ctri

-t / --tokens · flag

Print the lexed token stream, then exit without compiling. Use this flag to debug parser issues or inspect how the lexer tokenizes your source.

-p / --print · flag

Print the structure/scope graph instead of compiling. Shows all Callee, Caller, and scope nodes with their relationships and parent scopes.

-a / --asm · flag

Show the generated assembly output for asm blocks. Work in progress — output may be incomplete for some targets.

-T / --target · ARCH

Target architecture for asm blocks. Accepted values: x86_64 or arm64. Defaults to auto-detection from the host platform when omitted.

-F / --format · FORMAT

Object file format for assembled output. Accepted values: macho (ARM64 macOS) or elf (Linux). Overrides auto-detection.

NASM does not support ARM64 Mach-O directly. On Apple Silicon, omit this flag and let the compiler auto-detect the format.

-i / --install · PATH

Install a .plib file to the PLIBS folder. The compiler tries the system location (/usr/lib/PLIBS/) first, then falls back to your user location (~/.local/lib/PLIBS/).

-r / --remove · NAME

Remove a .plib file from PLIBS by name. You can omit the .plib extension — the compiler adds it automatically if missing.

Compiler Pipeline

When you run hypotenuse -c, your source file passes through seven stages before the final binary is produced:

.ctri source
     │
     ▼
  1. Lexer          ──▶  token stream
     │
     ▼
  2. Parser         ──▶  AST
     │
     ▼
  3. Structurer     ──▶  Callee/Caller/Scope graph
     │
     ▼
  4. Simulation Pass ──▶  constant folding, last-use analysis
     │
     ▼
  5. Code Generation ──▶  .c file + .asm files
     │
     ▼
  6. GCC + NASM     ──▶  object files
     │
     ▼
  7. Linker         ──▶  native binary

What does each stage do?

Lexer — Tokenizes your .ctri source into a flat stream of (type, value) tokens, handling all C△ keywords, operators, literals, and comments.

Parser — Builds an abstract syntax tree (AST) from the token stream using a recursive-descent parser with full operator precedence. Covers expressions, statements, declarations, functions, structs, and all loop and branch forms.

Structurer — Walks the AST and builds a Callee/Caller/Scope graph, the compiler’s internal representation of every variable, function, and scope relationship. Use -p to inspect this graph directly.

Simulation Pass — Performs static analysis: constant folding, last-use analysis for autoremove pointers, and robbery validation.

Code Generation — Emits a .c file from the AST and one or more .asm files from asm blocks in your source.

GCC + NASM — GCC compiles the generated .c file; NASM assembles each .asm block into an object file.

Linker — GCC links all object files into the final native binary.

Target Platforms

The Hypotenuse Compiler supports two target platforms. Architecture and output format are auto-detected from your host system unless you override them with -T and -F.

Architecture	Platform	Output Format	Backend
x86_64	Linux	ELF64	GCC + NASM
ARM64	macOS	Mach-O64	GCC + NASM