Build and install Guidedog
==========================

Install on macOS with Homebrew
----------------------------------------

Use the official ``insanai/homebrew-guidedog`` tap on Apple silicon or Intel Macs:

.. code-block:: sh

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

Homebrew selects the release archive for your processor and checks its SHA-256.
The package includes Typst, Graphviz, and tree-sitter. You do not need an Odin
compiler, a Python environment, or a separate Typst installation to build HTML
and PDF. The release requires macOS 12 or later.

Create your first project with :doc:`../tutorial/first-project`.
To update an installed release:

.. code-block:: sh

   brew update
   brew upgrade insanai/guidedog/guidedog

Run ``brew test insanai/guidedog/guidedog`` to check the installed package by
creating a project and building HTML and PDF.

Build from source
-----------------

Use the Odin toolchain pinned in ``tools/odin-release.txt``.
The release uses Odin ``dev-2026-10`` and Typst 0.15.1.
Graphviz development libraries are needed for the shared-library build.

Development build
-----------------

From the repository root:

.. code-block:: sh

   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

The tree-sitter build supplies the pinned Python grammar for source-based autodoc.
Install Graphviz's development files through your system package manager.
A build without the Typst bridge uses an installed ``typst`` program for PDF.
Use ``--typst=/absolute/path/to/typst`` to select it explicitly.

Embedded compiler
-----------------

Build the native dependencies once, then link them into the Odin executable:

.. code-block:: sh

   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

The Typst bridge is Rust code outside Guidedoc's allocation-free boundary.
An embedded build removes the need to launch a separate Typst executable.
It does not remove the compiler's own memory costs.

On Windows, name the output ``build/guidedog.exe``.
Put the executable on your ``PATH`` if you want to use ``guidedog`` without its path.