> ## Documentation Index
> Fetch the complete documentation index at: https://hypotenuse.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
hypotenuse [options] <file.ctri>
```

## Quick Examples

These examples cover the most common workflows:

```bash theme={null}
# 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

<ParamField path="-c / --compile" type="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.
</ParamField>

<ParamField path="-o / --output" type="PATH">
  Write compiled output to `PATH`. When used with `-c`, this sets the name of the output executable.
</ParamField>

<ParamField path="-C / --cflags" type="FLAGS">
  Pass extra flags directly to GCC. Use this to link external libraries or set compiler options.

  ```bash theme={null}
  hypotenuse -c -C "$(sdl2-config --cflags --libs)" graphics.ctri
  ```
</ParamField>

<ParamField path="-t / --tokens" type="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.
</ParamField>

<ParamField path="-p / --print" type="flag">
  Print the structure/scope graph instead of compiling. Shows all `Callee`, `Caller`, and scope nodes with their relationships and parent scopes.
</ParamField>

<ParamField path="-a / --asm" type="flag">
  Show the generated assembly output for `asm` blocks. Work in progress — output may be incomplete for some targets.
</ParamField>

<ParamField path="-T / --target" type="ARCH">
  Target architecture for `asm` blocks. Accepted values: `x86_64` or `arm64`. Defaults to auto-detection from the host platform when omitted.
</ParamField>

<ParamField path="-F / --format" type="FORMAT">
  Object file format for assembled output. Accepted values: `macho` (ARM64 macOS) or `elf` (Linux). Overrides auto-detection.

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

<ParamField path="-i / --install" type="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/`).
</ParamField>

<ParamField path="-r / --remove" type="NAME">
  Remove a `.plib` file from PLIBS by name. You can omit the `.plib` extension — the compiler adds it automatically if missing.
</ParamField>

## 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
```

<Accordion title="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.
</Accordion>

## 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 |