(sigil package)

The central struct defining a Sigil package.

(package
  name: "my-app"
  version: "1.0.0"
  description: "My application"
  entry: '((my-app main) main)
  dependencies: (list
    (from-git url: "https://github.com/example/lib.git" tag: "v1.0")))

Test if a value is a package struct.

Package name as a string. Used for identification and as default bundle name.

Semantic version string. When #f, inherits version from workspace if loaded as a workspace package, or defaults to "0.0.0" when loaded standalone.

Short description of the package.

Project URL (repository, homepage, etc.) or #f.

License identifier string (e.g., "MIT", "Apache-2.0") or #f.

List of author strings in "Name <email>" format.

Entry point as '((library-name ...) proc-name) or #f for library-only packages.

Output executable name for bundles. Defaults to package name if #f.

Runtime composition strategy for bundled executables.

• 'reuse (default): Reuse the CLI runtime if the app's native dependencies are a subset of what CLI provides. Fast bundling, but includes all CLI native packages even if unused.
• 'custom: Build a runtime with exactly the native packages the app needs. Slower build, but precise control over binary contents. Use this for smaller binaries (omit unused packages) or larger ones (add packages not in CLI like sigil-studio).

Can be overridden with sigil build --runtime=custom.

Build configurations as <config> records.

Symbol naming the default config to use. Common values: 'dev, 'release.

Library targets as <library> records.

Executable targets as <executable> records.

Build tasks as <task> records.

Runtime dependencies as <from-git>, <from-path>, or <from-workspace> records.

Development-only dependencies (not bundled in release builds).

Build lifecycle hooks as a <hooks> record, or #f for none.

Capabilities this package provides. A keyword-tagged list, e.g., (list mcp-tools: '(sigil web mcp tools)).

Capabilities this package provides. A keyword-tagged list, e.g., (list mcp-tools: '(sigil web mcp tools)).

Build configuration defining compiler flags, toolchain, and output settings.

(config
  name: 'release
  optimize: 2
  static?: #t
  c-flags: '("-Wall" "-Werror"))

Test if a value is a config struct.

Configuration name as a symbol. Common values: 'dev, 'release, 'static:release.

Base output directory. Config name is appended (e.g., "build/release").

Toolchain selector. Values: 'native, 'emscripten, 'musl, 'zig, or custom symbol.

Cross-compilation target triple for zig toolchain. Examples: "aarch64-linux-musl", "x86_64-windows-gnu", "x86_64-freebsd". Only used when toolchain is 'zig. If #f, builds for native target.

Override C compiler command. Examples: "musl-gcc", "emcc", "clang".

Override archiver command for static libraries.

Additional C compiler flags as a list of strings.

Additional linker flags as a list of strings.

Preprocessor defines as a list of strings or (name . value) pairs.

Feature flags for cond-expand in Sigil source files.

If #t, build a fully static executable (requires musl or similar).

If #t, include debug symbols in output.

Optimization level from 0 (none) to 3 (aggressive).

If #t, create a bundled executable with embedded modules.

Subdirectory for deployable assets (e.g., "www" for web builds).

Subdirectory for deployable assets (e.g., "www" for web builds).

Named build workflow that composes action steps with dependencies.

(task
  name: 'test
  description: "Run all tests"
  depends: '(build)
  steps: (list (shell "make test")))

Test if a value is a task struct.

Task name as a symbol.

Human-readable description of what this task does.

List of task name symbols that must run before this task.

List of config names this task applies to, or #f for all configs.

Action steps to execute in sequence. Each step is an action record.

Action steps to execute in sequence. Each step is an action record.

A library target producing a static archive from C and Sigil sources.

(library
  name: 'sigil-crypto
  c-sources: '("native/crypto.c" "vendor/mbedtls/library/*.c")
  c-include-dirs: '("vendor/mbedtls/include")
  native-init: "sigil__init_sigil_crypto_module")

Test if a value is a library struct.

Library name as a symbol.

C source files as a list of paths or glob patterns.

C include directories as a list of paths.

Additional C compiler flags for this library. Use (cond-expand ...) for platform-dependent flags. Example: '("-DFOO=1" "-Wno-deprecated") for defines/warnings.

Sigil source files as a list of paths or glob patterns.

Output filename. Defaults to lib<name>.a if #f.

Native init function name (C symbol) called at VM startup. Used for packages with native code that register Scheme primitives.

Platform-specific linker flags for this library. Use (cond-expand ...) for platform-dependent flags. Example: '("-lX11" "-lGL") for graphics libraries.

Platform-specific linker flags for this library. Use (cond-expand ...) for platform-dependent flags. Example: '("-lX11" "-lGL") for graphics libraries.

An executable target that links libraries into a runnable program.

(executable
  name: 'my-app
  entry: '((my-app main) run)
  libraries: '(core utils))

Test if a value is a executable struct.

Executable name as a symbol.

Entry point as '((library-name ...) proc-name), or #f for pure C executables.

List of library name symbols to link.

List of library name symbols to link.

Build lifecycle hooks for customizing build and test phases.

(hooks
  before-build: (lambda (config) (display "Building...\n"))
  after-build: (lambda (config output) (display "Done!\n")))

Test if a value is a hooks struct.

Called before build starts. Receives (config).

Called after build completes. Receives (config output-path).

Called before tests run. Receives (config).

Called after tests complete. Receives (config results).

Called after tests complete. Receives (config results).

A workspace containing multiple packages with shared configuration and tasks.

(workspace
  name: "my-project"
  packages: (list "packages/pkg1" "packages/pkg2")
  configs: (list
    (config name: 'dev debug?: #t)
    (config name: 'release optimize: 2)))

Test if a value is a workspace struct.

Workspace name as a string.

Semantic version string.

Short description of the workspace.

Project URL or #f.

License identifier or #f.

List of author strings in "Name <email>" format.

Package directories as paths or glob patterns.

Shared build configurations as <config> records.

Default config name symbol.

Workspace-level tasks as <task> records.

Workspace-level tasks as <task> records.

A git dependency referencing a remote repository. Supports forge shorthand URLs: codeberg:user/repo, github:user/repo.

(from-git
  url: "codeberg:sigil/sigil"
  subpath: "packages/sigil-json"
  tag: "v1.0.0")

Test if a value is a from-git struct.

Repository URL (HTTPS, SSH, or forge shorthand).

Override package name inferred from URL. If #f, uses repo name.

Path within repo to package directory (for monorepos).

Package name to find in workspace (alternative to subpath). When set, the resolver clones the repo, reads its workspace definition, and locates the package by name. Mutually exclusive with subpath.

Semver version range constraint. When set, the resolver fetches available tags from the remote and selects the highest matching version. Supports Cargo-style ranges: "^0.9.0" → >=0.9.0, <0.10.0 "~0.9.0" → >=0.9.0, <0.9.1 "*" → any version (latest tag) When #f, uses tag/branch/commit or HEAD.

Checkout a specific git tag.

Track a branch (pulls latest on update).

Pin to an exact commit hash.

Pin to an exact commit hash.

A local path dependency for development or monorepo setups.

If package is specified, dir points to a workspace root and the named package is resolved within it. If omitted, dir is the package directory itself.

(from-path dir: "../my-local-lib")
(from-path dir: "../workspace" package: "specific-pkg")

Test if a value is a from-path struct.

Filesystem path to the package directory or workspace root.

Package name to find in workspace (if dir is a workspace).

Override inferred package name. If #f, uses directory name.

Override inferred package name. If #f, uses directory name.

A workspace dependency referencing a sibling package. Used by monorepo packages to declare dependencies on other packages in the same repository. When fetched externally, resolves to the same worktree/ref as the parent package.

(from-workspace name: "sigil-stdlib")

Test if a value is a from-workspace struct.

Package name within the workspace.

Helper to get value from alist

Look up a value from a package's provides list by keyword.

Returns the value following the keyword, or #f if not found.

(package-provides-ref pkg mcp-tools:)
;; => (sigil web mcp tools)

Find package.sgl in current directory or ancestors

Load and evaluate a package.sgl file Returns the <package> record

Automatically imports (sigil package) and (sigil build) so that package files don't need explicit import statements.

Note: All expressions are wrapped in a single (begin ...) form and evaluated together.

Load and evaluate a package.sgl file, returning either package or workspace Returns the <package> or <workspace> record

Wrap a standalone package in a workspace This normalizes the API so all code can work with workspaces

Read all expressions from a port

Get output directory for a config

Resolve a config by name from a package

Resolve a config by name from a workspace

Get absolute paths to all packages in a workspace workspace-dir: directory containing the workspace package.sgl

Load all packages from a workspace Returns alist of (package-name . package) pairs Packages without a version inherit the workspace version.