Guidedog / 文档 0.2.0

typst¶

Package typst adapts the Typst toolchain for the host. The development backend runs an installed, pinned typst executable with an argument vector, never a shell; the embedded backend links the compiler in (bridge.odin). It is outside Guidedoc’s allocation-free core.

Typst is not a sandbox of its own; what it may do is what the caller gives it:

- Files: Typst reads only paths below the root it is given, and refuses a path that
  leaves it; a link below the root is followed. Fonts come from font_paths and,
  unless embedded_fonts_only is set, from the system.
- Packages: an @preview import downloads the package, unless offline is set (the
  embedded backend only; the typst program has no such switch).
- Memory and time: Typst's own, in the process (embedded) or in the typst program;
  no budget of the host bounds them. Only the output the embedded backend copies
  back is counted, through reserve.

So Typst code reaches everything below its root: a caller that compiles Typst it does not trust gives a root holding only what that code may read. Guidedog’s builds do (project/typst_root.odin), and an –untrusted build compiles only Typst it generated.

Types

typst.Backend :: struct¶

Backend is the compiler a compile runs: an installed typst program, or the embedded one. locate makes it; its strings are the caller’s.

program: string¶

version: string¶

embedded: bool¶: the statically linked compiler; no external program runs.

typst.Diagnostic :: struct¶

Diagnostic is one problem Typst reported.

file: string¶

line: int¶: 1-based; 0 when the compiler gave no position.

column: int¶

severity: string¶

message: string¶

stdin: bool¶: the position is in the generated source fed on stdin.

typst.Options :: struct¶

Options mirror the typst CLI. Zero values mean: download missing packages into the system cache, and use system fonts before the embedded ones.

offline: bool¶: use only packages already on disk.

package_cache: string¶: package cache directory; “” is the system cache.

embedded_fonts_only: bool¶: ignore system fonts, for reproducible output.

font_paths: []string¶: extra font directories, searched first.

reserve: Reserve ¶: When set, the embedded compiler’s output is counted before it is copied into host memory; a refusal fails the compile. The typst program writes its output itself.

typst.Outcome :: struct¶

Outcome is what a compile did. Its diagnostics and text are allocated in context.allocator and owned by the caller; launch_error is set when Typst could not run.

ok: bool¶

exit_code: int¶

diagnostics: []Diagnostic ¶

detail: string¶: unparsed compiler output, bounded.

launch_error: string¶

typst.Reserve :: struct¶

Reserve asks the caller whether bytes may be allocated, before the embedded compiler’s output is copied into host memory; false refuses the compile.

procedure: proc(user: rawptr, bytes: int) -> bool¶

user: rawptr¶

typst.Target :: enum u8¶

Target is the artifact a compile writes.

Pdf¶

Html¶

Procedures

typst.compile_file :: proc(b: Backend, source, root, output: string, target: Target, options := Options{}) -> Outcome ¶: compile_file compiles a native Typst source file into output; paths resolve against root, and Typst reads nothing outside it. The Outcome is allocated in context.allocator and owned by the caller. Write to a staged path and rename it on success when a failed compile must not disturb an earlier artifact.

typst.compile_text :: proc(b: Backend, text, root, output: string, target: Target, options := Options{}) -> Outcome ¶: compile_text compiles generated Typst fed on stdin, so no file is written beside the user’s sources. Relative paths in the text resolve against root. The Outcome is allocated in context.allocator and owned by the caller.

typst.find_program :: proc(name: string) -> (string, bool)¶: find_program looks a program up on PATH, handling Windows’ “;” and “.exe”. The path is allocated in context.allocator and owned by the caller; false when none is found.

typst.locate :: proc(program: string) -> (Backend, bool)¶: locate returns the embedded compiler when this build links one and the caller did not name another program; otherwise it finds the program and asks for its version. The backend’s strings are allocated in context.allocator and owned by the caller; false when no program is found. A program that cannot tell its version has version “”.

typst.offset_of :: proc(text: string, line, column: int) -> int¶: offset_of converts a 1-based line and column (in characters) into a byte offset of text, clamped to its end; it allocates nothing.

typst.pinned :: proc(b: Backend) -> bool¶: pinned reports whether the backend is the Typst release Guidedog is tested with.

Constants

typst.EMBEDDED :: #config(GUIDEDOG_TYPST_BRIDGE, false)¶

EMBEDDED selects the statically linked Typst compiler. Build the bridge first:

cargo build --release --offline --manifest-path native/typst_bridge/Cargo.toml
odin build cmd/guidedog -define:GUIDEDOG_TYPST_BRIDGE=true -out:build/guidedog

Without it, Guidedog uses the development backend: an installed typst program.

typst.PINNED_VERSION :: "0.15.1"¶: PINNED_VERSION is the Typst release Guidedog is built and tested with.

Foreign imports

foreign import typst.bridge {"../../native/typst_bridge/target/release/guidedog_typst_bridge.lib", "system:ws2_32.lib", "system:userenv.lib", "system:ntdll.lib", "system:bcrypt.lib", "system:advapi32.lib", "system:kernel32.lib"}¶: 可用平台: Windows.

foreign import typst.bridge {"../../native/typst_bridge/target/release/libguidedog_typst_bridge.a", "system:Security.framework", "system:CoreFoundation.framework", "system:System", "system:iconv"}: 可用平台: Darwin.

foreign import typst.bridge {"../../native/typst_bridge/target/release/libguidedog_typst_bridge.a", "system:gcc_s", "system:util", "system:rt", "system:pthread", "system:m", "system:dl", "system:c"}: 可用平台: Linux, FreeBSD, OpenBSD, NetBSD, WASI, JS, Orca, Freestanding.