项目结构

理解 Toka 的项目结构有助于你有效地组织代码。

单文件程序

对于快速原型开发或简单的脚本，一个单独的 .tk 文件就足够了。正如我们在 Hello, Toka！一节中所见，您可以将所有代码编写在一个文件（如 hello.tk）中，并通过以下命令立即执行它：

toka run hello.tk

多文件项目

对于大型项目，使用 toka init 初始化一个项目。这会创建一个 package.tk 文件：

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

目录结构：

my-project/
├── package.tk      # 项目配置和依赖管理
├── src/
│   ├── main.tk     # 入口文件
│   ├── utils.tk    # 工具函数
│   └── models.tk   # 数据模型
└── lib/
    ├── config.tk   # 库配置
    └── helpers.tk  # 辅助函数

添加依赖

你可以通过 toka add 命令轻松添加第三方包到项目中：

toka add regex

该命令会查询默认 Toka Registry，解析不可变发布归档并校验目录记录的 SHA-256，同时更新 package.tk 与 package.lock：

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

执行 toka build 时，解析器会把经校验的依赖拉取到 .toka/packages。不要手改 package.lock；它记录已解析归档与内容摘要。

库项目

对于可复用的库项目，toka new my-lib --lib 会生成一个不含 main.tk 可执行入口点的库结构。package.tk 的配置格式保持一致。

导入系统

// 从标准库导入
import std/io::println

// 从项目源码导入
import src/utils::{helper_fn}

// 从本地库导入
import lib/config::{Config}

// 使用别名导入
import std/time as time_lib

构建输出

运行 toka run 或 toka build 会生成：

my-project/
└── target/
    ├── debug/
    │   └── my-project    # 调试版二进制
    └── release/
        └── my-project    # 发布版二进制（添加 --release 参数）

🛠️ 增量构建与 Forge 引擎

toka CLI 内置 Forge 并行增量构建模式。它读取 build.tk 中声明的依赖拓扑，协调并行任务，并在 .toka/build 中保存构建来源记录。

1. 声明构建配置 `build.tk`

在项目的根目录下创建一个 build.tk 文件，使用内置的 build 工具链来定义你的可执行文件或库：

import build::{Executable, run_build}

fn main() -> i32 {
    // 实例化一个构建工程，Executable::make(二进制名称, 入口源文件)
    // 由于 Executable::make 底层是对 C-FFI 的高层封装，我们需要显式传递 FFI 裸指针。
    auto proj# = Executable::make("my-project".as_cstr().raw_ptr(), "src/main.tk".as_cstr().raw_ptr())
    return run_build(proj)
}

2. 使用 Forge 开启增量并发构建

通过 toka CLI 启用 Forge：

# 使用并行增量引擎构建当前项目
toka build --forge

forge 引擎将自动：

扫描并解析 src/main.tk 及其所有 import 子模块的静态依赖拓扑 DAG。
在 .toka/build 下记录当前构建 manifest。
智能增量跳过：对没有发生代码变更的源文件，利用增量缓存技术瞬时绕过，从而将大型多模块项目的自举编译耗时压缩到毫秒级别！

Toka 编程语言指南