Getting Started

This guide will walk you through installing the Home compiler and writing your first program.

Prerequisites

Home is written in Zig and is built with the Pantry-pinned Zig 0.17 dev toolchain.

Installing the Toolchain

pantry install

Verify your installation:

./pantry/ziglang.org/v0.17.0-dev.263+0add2dfc4/zig version
# Should output: 0.17.0-dev.263+0add2dfc4

Building the Compiler

Clone the Home repository and build the compiler:

git clone https://github.com/home-lang/home.git
cd home
pantry install
./pantry/ziglang.org/v0.17.0-dev.263+0add2dfc4/zig build

This will create the Home compiler at ./zig-out/bin/home.

Verify Installation

./zig-out/bin/home --version

Hello World

Create a new file called hello.home:

// hello.home
fn main() {
  print("Hello, Home!")
}

Build and run your program:

./zig-out/bin/home build hello.home
./hello

You should see:

Hello, Home!

Your First Real Program

Let's write something more interesting - a Fibonacci calculator:

// fibonacci.home

fn fib(n: int): int {
  if (n <= 1) {
    return n
  }
  return fib(n - 1) + fib(n - 2)
}

fn main() {
  let result = fib(10)
  print("Fibonacci(10) = {result}")
}

Build and run:

./zig-out/bin/home build fibonacci.home
./fibonacci

Output:

Fibonacci(10) = 55

Project Structure

A typical Home project looks like this:

my-project/
├── src/
│   ├── main.home       # Entry point
│   ├── lib.home        # Library code
│   └── utils/
│       └── helpers.home
├── tests/
│   └── test_lib.home
├── examples/
│   └── demo.home
└── pantry.json         # Package manifest (optional)

The Home Compiler Structure

The Home compiler itself follows this structure:

home/
├── src/main.zig           # CLI entry point
├── packages/
│   ├── lexer/             # Tokenization
│   ├── parser/            # AST generation
│   ├── ast/               # Syntax tree types
│   ├── types/             # Type system
│   ├── codegen/           # Native code generation (x64)
│   ├── interpreter/       # Direct execution
│   ├── diagnostics/       # Error reporting
│   └── ...
├── examples/              # Example programs
├── tests/                 # Integration tests
└── stdlib/                # Standard library

Running Programs

There are two ways to run Home programs:

Compiled Execution (Recommended)

Build to a native executable:

./zig-out/bin/home build myprogram.home
./myprogram

Interpreted Execution

Run directly without compilation (useful for development):

./zig-out/bin/home run myprogram.home

File Extensions

Home supports two file extensions:

• .home - Standard source file extension (recommended)
• .hm - Short alternative

Build Commands

# Build a program
./zig-out/bin/home build program.home

# Run without building
./zig-out/bin/home run program.home

# Run tests
./zig-out/bin/home test tests/

# Format code
./zig-out/bin/home fmt src/

Next Steps

Now that you have Home installed, explore these topics:

• Variables and Types - Learn about Home's type system
• Functions - Define and call functions
• Control Flow - Conditionals and loops
• Error Handling - Work with Result types

Troubleshooting

Common Issues

Pantry Zig not found

Install the pinned toolchain through Pantry:

pantry install
./pantry/.bin/zig version

Build fails with memory error

Try increasing stack size or check for infinite recursion in your code.

Permission denied

Make sure the built executable has execute permissions:

chmod +x ./myprogram

Getting Help

• Check the examples directory
• Read the architecture documentation
• Open an issue on GitHub