# Chapter 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:
```sh
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:
   ```sh
   git clone https://github.com/ajhahnde/Flash.git
   cd Flash
   ```
2. Build the project using Zig:
   ```sh
   zig build
   ```
   The compiled compiler binary is placed in:
   `zig-out/bin/flashc`

3. Verify the installation:
   ```sh
   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:
```sh
zig-out/bin/flashc path/to/file.flash
```
This prints the lowered Zig source directly to `stdout`. You can redirect this to a file:
```sh
zig-out/bin/flashc path/to/file.flash > output.zig
```

### Inspecting Tokens
To dump the lexer token stream of a source file:
```sh
zig-out/bin/flashc --dump-tokens path/to/file.flash
```

### Formatting
To reformat a Flash source file in place to the canonical style:
```sh
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:
```sh
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:
```sh
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:
```sh
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`).