ajhahn.de
← all chapters

Flash tutorial · 2 / 12

2. Getting Started

Setting up the Flash environment requires a few commands. Since the Flash compiler compiles to Zig, you need the Zig toolchain installed on your machine.

1. Prerequisites

Flash has a strict dependency requirement:

  • Zig 0.16.0 is hard-pinned. The build configuration enforces this major/minor/patch exactly and will fail on any other version.

Ensure Zig is installed and runs properly:

zig version   # Expected output: 0.16.0

2. Building the Compiler

To build the Flash compiler (flashc):

  1. Clone the repository and navigate into it:

    git clone https://github.com/ajhahnde/Flash.git
cd Flash

  2. Build the project using Zig:

    zig build

    The compiled compiler binary is placed in: zig-out/bin/flashc

  3. Verify the installation:

    zig-out/bin/flashc --version

3. Running the Compiler

The flashc CLI offers several commands and flags:

Transpilation (Default)

To transpile a Flash source file into Zig:

zig-out/bin/flashc path/to/file.flash

This prints the lowered Zig source directly to stdout. You can redirect this to a file:

zig-out/bin/flashc path/to/file.flash > output.zig

Inspecting Tokens

To dump the lexer token stream of a source file:

zig-out/bin/flashc --dump-tokens path/to/file.flash

Formatting

To reformat a Flash source file in place to the canonical style:

zig-out/bin/flashc fmt path/to/file.flash

Add --check to verify formatting without rewriting the file. It exits non-zero when the file is not already canonical, which makes it convenient in CI:

zig-out/bin/flashc fmt --check path/to/file.flash

Compilation Run (via Zig Build)

You can transpile directly in one step using the build script:

zig build run -- examples/hello.flash

4. Run the Host Tests

Before building, it is highly recommended to run the host unit suite to ensure the environment is fully verified:

zig build test

This runs the unit tests for all pipeline modules (lexer, parser, sema, lower) alongside the integration checks, the .flash test suite (test-flash), and the self-hosted compiler's own test blocks (test-selfhost).