Guidedog / 文档 0.2.0

构建并安装 Guidedog¶

在 macOS 上用 Homebrew 安装¶

在 Apple 芯片或 Intel 芯片的 Mac 上，使用官方 tap insanai/homebrew-guidedog 安装：

brew tap insanai/guidedog
brew install insanai/guidedog/guidedog
guidedog --version

Homebrew 会选择适合处理器的发行包，并校验 SHA-256。安装包已包含 Typst、Graphviz 和 tree-sitter。生成 HTML 和 PDF 无需 Odin 编译器、Python 环境或单独安装 Typst。此版本要求 macOS 12 或更高版本。

按照第一个项目创建第一个项目。更新已安装的版本：

brew update
brew upgrade insanai/guidedog/guidedog

运行 brew test insanai/guidedog/guidedog 检查已安装的包。测试会创建项目并生成 HTML 和 PDF。

从源码构建¶

使用 tools/odin-release.txt 指定的 Odin 工具链。发行版使用 Odin dev-2026-10 和 Typst 0.15.1。动态链接版本需要 Graphviz 开发库。

开发版构建¶

在仓库根目录运行：

mkdir -p build
native/tree-sitter/build.sh
odin build cmd/guidedog -out:build/guidedog -o:speed -vet -strict-style
build/guidedog --version
build/guidedog formats

tree-sitter 构建提供固定版本的 Python 语法，用于基于源代码的 autodoc。通过系统包管理器安装 Graphviz 开发文件。没有 Typst 桥接的构建使用已安装的 typst 程序生成 PDF。可用 --typst=/absolute/path/to/typst 显式选择。

内嵌编译器¶

先构建原生依赖，再将其链接至 Odin 可执行程序：

cargo build --release --manifest-path native/typst_bridge/Cargo.toml
native/graphviz/build.sh
odin build cmd/guidedog -out:build/guidedog -o:speed \
    -define:GUIDEDOG_TYPST_BRIDGE=true -define:GRAPHDOG_STATIC=true

Typst 桥接是 Rust 代码，位于 Guidedoc 的无分配边界之外。嵌入式构建无需启动单独的 Typst 可执行文件，但不会消除编译器自身的内存开销。

在 Windows 上，将输出命名为 build/guidedog.exe。若希望直接输入 guidedog，无需路径，将可执行文件加入 PATH。