# Zig Compiler as a Toolchain

### Zig Compiler as a Toolchain

When beginners hear the word “compiler,” they often think of one job:

```text
source code -> executable program
```

That is true, but Zig is more than a compiler in the narrow sense.

The `zig` command is a toolchain.

A toolchain is a collection of tools used to build, test, format, and manage programs. In many languages, these tools are separate. In Zig, many of them are available through one command.

```bash
zig
```

This single command can compile Zig code, run tests, format source files, build full projects, compile C code, cross-compile programs, and inspect targets.

#### The Main Idea

Zig tries to reduce the number of separate tools you need.

In a typical C or C++ project, you may see tools such as:

| Tool | Purpose |
|---|---|
| C compiler | Compiles source code |
| Linker | Combines object files and libraries |
| Make or CMake | Controls the build |
| Formatter | Formats code |
| Test runner | Runs tests |
| Cross compiler | Builds for other platforms |
| Package manager | Fetches dependencies |

Zig does not remove every tool in the world, but it puts many common tasks under one command.

That gives beginners a simpler starting point.

#### Common Zig Commands

Here are the commands you will use most often:

| Command | Meaning |
|---|---|
| `zig run file.zig` | Compile and run a Zig file |
| `zig build-exe file.zig` | Build an executable |
| `zig test file.zig` | Run tests in a file |
| `zig fmt file.zig` | Format source code |
| `zig build` | Run the project build script |
| `zig cc` | Use Zig as a C compiler |
| `zig c++` | Use Zig as a C++ compiler |
| `zig targets` | Show supported compilation targets |

You do not need all of these immediately.

At the beginning, focus on:

```bash
zig run
zig build-exe
zig test
zig fmt
```

These four commands cover most beginner work.

#### `zig run`

The command:

```bash
zig run hello.zig
```

means:

```text
Compile this file, then run the result immediately.
```

This is useful for small examples.

You write code, run it, see the output, edit it, and run again.

Example:

```zig
const std = @import("std");

pub fn main() void {
    std.debug.print("Learning Zig\n", .{});
}
```

Run:

```bash
zig run main.zig
```

Output:

```text
Learning Zig
```

#### `zig build-exe`

The command:

```bash
zig build-exe main.zig
```

means:

```text
Compile this file and leave an executable on disk.
```

Use this when you want a program file you can run later.

On Linux and macOS:

```bash
./main
```

On Windows:

```powershell
.\main.exe
```

This is a direct build command. It works well for single-file programs.

#### `zig test`

Zig has built-in support for tests.

A test is code that checks whether other code behaves correctly.

Create a file:

```zig
const std = @import("std");

fn add(a: i32, b: i32) i32 {
    return a + b;
}

test "add two numbers" {
    try std.testing.expect(add(2, 3) == 5);
}
```

Run:

```bash
zig test main.zig
```

Zig compiles the file, finds the `test` blocks, and runs them.

If the test passes, Zig exits successfully.

If the test fails, Zig reports the problem.

Testing is part of normal Zig development. You do not need a separate test framework to begin.

#### `zig fmt`

Zig includes an official formatter.

Run:

```bash
zig fmt main.zig
```

This rewrites the file using Zig’s standard formatting style.

This is useful because it removes many style arguments. Zig code is expected to have a consistent shape.

For example, if you write messy spacing:

```zig
pub fn main(  ) void{
}
```

`zig fmt` rewrites it into normal Zig style:

```zig
pub fn main() void {}
```

Formatting is not only about appearance. Consistent formatting makes code easier to read and review.

#### `zig build`

Small examples can use `zig run` or `zig build-exe`.

Larger projects usually use:

```bash
zig build
```

This command looks for a file named:

```text
build.zig
```

The `build.zig` file describes how to build the project.

A project may have several outputs:

| Output | Example |
|---|---|
| Executable | Command-line program |
| Library | Code used by other programs |
| Tests | Test binaries |
| Generated files | Code or assets created during build |

The build file is written in Zig itself. That means you use Zig as the build language too.

You will learn `build.zig` later. For now, remember:

```text
zig build-exe is for simple files.
zig build is for projects.
```

#### `zig cc`

Zig can act as a C compiler.

For example:

```bash
zig cc hello.c -o hello
```

This compiles a C program.

This is useful because Zig ships with much of the machinery needed for C compilation and cross compilation.

Many programmers use `zig cc` even in C projects, because it can simplify building for different platforms.

For this book, we focus on Zig code first. C interop comes later.

#### Cross Compilation

One of Zig’s major strengths is cross compilation.

Cross compilation means building a program for a different target than your current machine.

For example, you may be using macOS but want to build a Linux executable:

```bash
zig build-exe main.zig -target x86_64-linux
```

Or build a Windows executable:

```bash
zig build-exe main.zig -target x86_64-windows
```

A target describes the machine and operating system the program is built for.

It usually includes:

| Target part | Example |
|---|---|
| CPU architecture | `x86_64`, `aarch64` |
| Operating system | `linux`, `windows`, `macos` |
| ABI or environment | `gnu`, `musl`, `msvc` |

You do not need to memorize targets now. The important point is that Zig treats cross compilation as a normal toolchain feature.

#### The Compiler Checks Your Code

The Zig compiler does more than translate code.

It also checks your program.

It checks syntax:

```zig
pub fn main() void {
```

If braces or punctuation are wrong, Zig reports an error.

It checks types:

```zig
const age: u32 = "hello";
```

This is invalid because `"hello"` is a string, not an unsigned integer.

It checks many compile-time rules:

```zig
const x: u8 = 300;
```

A `u8` can hold only values from `0` to `255`, so this does not fit.

These checks may feel strict, but they protect you from many mistakes.

#### Debug Information and Safety

When Zig builds in debug mode, it includes more safety checks and debugging information.

This helps you find problems while developing.

Later, you can build optimized release versions.

Example:

```bash
zig build-exe main.zig -O ReleaseFast
```

This asks Zig to optimize for speed.

But while learning, debug mode is better. It gives clearer failures and safer behavior.

#### Why This Matters

The Zig toolchain is designed to make the basic workflow simple.

You can write:

```bash
zig run main.zig
```

for a quick experiment.

You can write:

```bash
zig test main.zig
```

to check behavior.

You can write:

```bash
zig fmt main.zig
```

to clean up formatting.

You can write:

```bash
zig build
```

to build a full project.

The same command family handles all of these jobs.

#### What You Should Remember

Zig is not only a language. It is also a toolchain.

The `zig` command can compile, run, test, format, build projects, compile C code, and cross-compile to other platforms.

For now, remember these commands:

```bash
zig run main.zig
zig build-exe main.zig
zig test main.zig
zig fmt main.zig
```

They are enough to start writing real Zig programs.