Project Structure

Understanding Toka's project structure helps you organize your code effectively.

Single-File Programs

For quick prototyping or simple scripts, a single .tk file is perfectly sufficient. As we saw in the Hello, Toka! section, you can write all your code in one file (like hello.tk) and execute it instantly with:

toka run hello.tk

Multi-File Projects

For larger projects, initialize a project using toka init. This creates a package.tk file:

// package.tk
pub const PACKAGE = (
    name = "my_project",
    version = "0.1.0",
    dependencies = ()
)

Directory layout:

my-project/
├── package.tk      # Project configuration and dependencies
├── src/
│   ├── main.tk     # Entry point
│   ├── utils.tk    # Utility functions
│   └── models.tk   # Data models
└── lib/
    ├── config.tk   # Library config
    └── helpers.tk  # Helper functions

Adding Dependencies

You can easily add third-party packages to your project using the toka add command:

toka add regex

This queries the default Toka Registry, resolves an immutable release archive, verifies its catalog-recorded SHA-256, and updates package.tk plus package.lock:

// package.tk
pub const PACKAGE = (
    name = "my_project",
    version = "0.1.0",
    dependencies = (
        regex = "regex:0.1.1",
    )
)

During toka build, the resolver fetches verified dependencies into .toka/packages. Do not edit package.lock by hand; it records the resolved archive and content digests.

Library Projects

For reusable libraries, toka new my-lib --lib generates a library structure without a main.tk executable entry point. The configuration format remains the same in package.tk.

Import System

// Import from standard library
import std/io::println

// Import from project source
import src/utils::{helper_fn}

// Import from local library
import lib/config::{Config}

// Import with alias
import std/time as time_lib

Build Output

Running toka run or toka build produces:

my-project/
└── target/
    ├── debug/
    │   └── my-project    # Debug binary
    └── release/
        └── my-project    # Release binary (with --release)

🛠️ Incremental Builds with the Forge Engine

The toka CLI includes the Forge parallel incremental build mode. It reads the dependency topology declared by build.tk, coordinates workers, and records build provenance under .toka/build.

1. Declaring Build Configuration build.tk

Create a build.tk file in the root directory of your project, utilizing the standard build toolchain to declare your executable or library:

import build::{Executable, run_build}

fn main() -> i32 {
    // Instantiate a build project, Executable::make(binary_name, entry_source)
    // Since Executable::make is a high-level wrapper around low-level C-FFI, we pass raw FFI pointers.
    auto proj# = Executable::make("my-project".as_cstr().raw_ptr(), "src/main.tk".as_cstr().raw_ptr())
    return run_build(proj)
}

2. Running Forge for Parallel Incremental Builds

Enable Forge through the toka CLI:

# Compile the current project with the parallel incremental engine
toka build --forge

The forge engine will automatically:

• Parse the entry point src/main.tk and map its static dependency DAG recursively.
• Record the current build manifest under .toka/build.
• Smart Incremental Skip: Instantly bypass compilation for unchanged files, shrinking multi-module project compilation times down to milliseconds!