bau/config

Search:
Group by:

Parses and merges Bau configuration files.

Types

BauConfig = object
  package*: PackageInfo      ## Package metadata.
  build*: BuildInfo          ## Default build settings.
  toolchain*: ToolchainInfo  ## Toolchain constraints.
  governance*: GovernanceInfo ## Dependency policy.
  cache*: CacheInfo          ## Task-cache configuration.
  install*: InstallInfo      ## Install defaults.
  docs*: DocsInfo            ## Documentation settings.
  test*: TestInfo            ## Test runner and matrix settings.
  profiles*: Table[string, ProfileInfo] ## Profiles keyed by name.
  targets*: seq[TargetInfo]  ## Explicit build targets.
  deps*: Table[string, DepInfo] ## Dependency requirements keyed by name.
  patches*: Table[string, DepInfo] ## Root-level dependency replacements.
  sources*: Table[string, SourceInfo] ## Named dependency sources.
  features*: Table[string, FeatureInfo] ## Feature declarations keyed by name.
  aliases*: Table[string, string] ## Project command aliases keyed by command name.
  catalogs*: Table[string, Table[string, string]] ## Version catalogs keyed by catalog and dependency.
  scripts*: ScriptInfo       ## Lifecycle hook commands.
  buildScripts*: seq[TaskInfo] ## Build scripts that can emit compiler directives.
  tasks*: seq[TaskInfo]      ## User-defined tasks.
Fully parsed Bau project configuration. 
BuildInfo = object
  name*: string              ## Optional CLI name for the default target.
  kind*: BuildKind           ## Default artifact category.
  source*: string            ## Source directory relative to the project root.
  main*: string              ## Main Nim source file relative to the project root.
  output*: string            ## Default output binary or library name.
  nim*: string               ## Explicit Nim compiler command, if configured.
  backend*: string           ## Compiler backend such as `c`, `cpp`, or `js`.
  includeDefault*: bool      ## Whether `bau build` includes the default target when explicit targets exist.
Default build target settings from [build]. 
BuildKind = enum
  bkBin = "bin",            ## Build an executable binary.
  bkLib = "lib",            ## Build a library module.
  bkTest = "test"            ## Build a test target.
Build artifact category requested for a target. 
CacheInfo = object
  dir*: string               ## Local cache directory relative to the project root.
  remote*: string            ## Remote cache URL or file path.
  read*: bool                ## Whether local or remote cache reads are allowed.
  write*: bool               ## Whether local or remote cache writes are allowed.
Task-cache location and remote cache behavior. 
DepInfo = object
  url*: Option[string]       ## Git URL for Git-sourced dependencies.
  tag*: Option[string]       ## Git tag to check out.
  branch*: Option[string]    ## Git branch to track.
  rev*: Option[string]       ## Exact Git revision to use.
  path*: Option[string]      ## Local path dependency location.
  version*: Option[string]   ## Registry version requirement.
  registry*: Option[string]  ## Named registry source to resolve through.
  optional*: bool            ## Whether the dependency is enabled only by features.
Dependency requirement or source override. 
DocsInfo = object
  outDir*: string            ## Documentation output directory.
  docRoot*: string           ## Nim doc source-root mode or URL root.
  entrypoints*: seq[string]  ## Explicit documentation entrypoint files.
  includeFiles*: seq[string] ## Additional documentation source patterns.
  excludeFiles*: seq[string] ## Documentation source patterns to skip.
  flags*: seq[string]        ## Additional Nim doc compiler flags.
  project*: bool             ## Whether to discover project modules automatically.
  index*: bool               ## Whether to generate Bau's documentation index page.
  runExamples*: bool         ## Whether Nim doc should compile runnable examples.
  includePrivate*: bool      ## Whether private symbols are included in API docs.
  sourceUrl*: string         ## Template URL for generated source links.
  configured*: bool          ## True when `[docs]` was present in config input.
API documentation generation settings. 
FeatureInfo = object
  enables*: seq[string]      ## Feature names or `dep:name` entries enabled together.
Feature declaration and what it enables. 
FullConfig = object
  bau*: Option[BauConfig]    ## Project configuration, when present.
  workspace*: Option[WorkspaceConfig] ## Workspace configuration, when present.
  globalProfile*: Option[ProfileInfo] ## User-level profile defaults.
  globalTasks*: seq[TaskInfo] ## User-level tasks appended to projects.
Optional global, workspace, and project config bundle. 
GovernanceInfo = object
  blocked*: seq[string]      ## Dependency names that must not be used.
  trusted*: seq[string]      ## Dependency names approved by policy.
  minimumReleaseAgeHours*: int ## Minimum age for resolved package releases.
Dependency policy configured for a project or workspace. 
InstallInfo = object
  dir*: string               ## Installation directory override.
Defaults for installing built targets. 
PackageInfo = object
  name*: string              ## Package name used for defaults and generated metadata.
  version*: string           ## Package version string.
  description*: string       ## Human-readable package summary.
  authors*: seq[string]      ## Package author names or contact strings.
  license*: string           ## SPDX-style or free-form license identifier.
  edition*: string           ## Bau configuration edition used by this project.
  repository*: string        ## Public source repository URL.
  homepage*: string          ## Project homepage URL.
  includeFiles*: seq[string] ## Extra package file patterns to include.
  excludeFiles*: seq[string] ## Package file patterns to exclude.
Package metadata read from the [package] table. 
ProfileInfo = object
  flags*: seq[string]        ## Raw Nim compiler flags.
  gc*: string                ## Nim memory-management strategy.
  define*: Table[string, string] ## `--define` values keyed by symbol name.
  extends*: string           ## Parent profile name to inherit before merging.
  backend*: string           ## Profile-specific compiler backend override.
Compiler settings attached to a named profile. 
ScriptInfo = object
  preBuild*: Option[string]  ## Command run before compiling.
  postBuild*: Option[string] ## Command run after compiling.
  postInstall*: Option[string] ## Command run after installing.
Legacy lifecycle hook commands. 
SourceInfo = object
  registry*: string          ## Remote Atlas registry URL.
  directory*: string         ## Local directory containing package sources.
  localRegistry*: string     ## Local Atlas registry path.
  git*: string               ## Git repository backing this source.
  replaceWith*: string       ## Alternate source name that supersedes this one.
Named package source used for dependency resolution. 
TargetInfo = object
  name*: string              ## Target name used by CLI commands.
  kind*: BuildKind           ## Artifact category for this target.
  main*: string              ## Target main source file.
  output*: string            ## Artifact output name, when it differs from `name`.
  source*: string            ## Source directory override for this target.
  paths*: seq[string]        ## Extra Nim import paths for this target.
  profile*: string           ## Default profile for this target.
  requiredFeatures*: seq[string] ## Features that must be enabled to build it.
  tags*: seq[string]         ## Free-form labels used by commands such as `affected`.
Explicit build target declaration. 
TaskInfo = object
  name*: string              ## Task name used for lookup and diagnostics.
  cmd*: string               ## Command line to execute.
  command*: string           ## Built-in Bau command to execute instead of `cmd`.
  description*: string       ## Human-readable task summary.
  deps*: seq[string]         ## Task dependencies that must run first.
  inputs*: seq[string]       ## Input file patterns for freshness and cache keys.
  outputs*: seq[string]      ## Output file patterns produced by the task.
  cwd*: Option[string]       ## Working directory relative to the project root.
  env*: Table[string, string] ## Environment variables set for the task.
  envInputs*: seq[string]    ## Environment variable names included in cache keys.
  watch*: seq[string]        ## Paths watched by long-running workflows.
  shell*: string             ## Explicit shell command used to run `cmd`.
  profile*: string           ## Profile used when the task invokes a built-in command.
  cache*: bool               ## Whether task outputs can be cached.
  acceptArgs*: bool          ## Whether `bau task <name> -- ...` is allowed.
  requiredFeatures*: seq[string] ## Features required before running this task.
  tags*: seq[string]         ## Free-form labels used by task selection.
Declarative task or build-script command. 
TestInfo = object
  runner*: string            ## Explicit test runner file relative to the project root.
  profiles*: seq[string]     ## Profiles used as the test matrix.
  defaultProfile*: string    ## Single profile used for fast local test runs.
  fullProfiles*: seq[string] ## Full profile matrix used by `bau test --full` and CI.
  recursive*: bool           ## Whether test file discovery descends into subdirectories.
  exclude*: seq[string]      ## Test filenames or relative paths to skip.
  showOutput*: string        ## Default test output mode: auto, always, or never.
  configured*: bool          ## True when `[test]` was present in config input.
Test discovery and runner settings from [test]. 
ToolchainInfo = object
  nim*: string               ## Nim compiler version requirement.
  atlas*: string             ## Atlas version requirement.
Minimum external tool versions required by a project. 
WorkspaceConfig = object
  members*: seq[string]      ## Workspace member path patterns.
  defaultMembers*: seq[string] ## Members selected when no explicit subset is given.
  exclude*: seq[string]      ## Member path patterns to ignore.
  package*: PackageInfo      ## Package defaults inherited by members.
  deps*: Table[string, DepInfo] ## Shared dependency defaults.
  sources*: Table[string, SourceInfo] ## Shared dependency sources.
  profiles*: Table[string, ProfileInfo] ## Shared profiles inherited by members.
  catalogs*: Table[string, Table[string, string]] ## Shared version catalogs.
  governance*: GovernanceInfo ## Shared dependency policy.
Workspace-level defaults from [workspace].

Procs

proc applyPatches(cfg: var BauConfig) {....raises: [KeyError, ValueError],
                                        tags: [], forbids: [].}
Apply root-level dependency patches over normal dependency entries. 
proc applyWorkspaceDefaults(cfg: var BauConfig; ws: WorkspaceConfig) {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}

Apply workspace defaults to a project configuration.

Project-local values win over workspace defaults except for additive policy lists and merged profiles.

proc defaultTargetName(cfg: BauConfig): string {....raises: [], tags: [],
    forbids: [].}
Return the CLI identity for the default [build] target. 
proc initBauConfig(): BauConfig {....raises: [], tags: [], forbids: [].}
Return a project configuration populated with Bau defaults. 
proc initBuildInfo(): BuildInfo {....raises: [], tags: [], forbids: [].}
Return default build settings for a binary project. 
proc initCacheInfo(): CacheInfo {....raises: [], tags: [], forbids: [].}
Return default local task-cache settings. 
proc initDocsInfo(): DocsInfo {....raises: [], tags: [], forbids: [].}
Return default API documentation settings. 
proc initGovernanceInfo(): GovernanceInfo {....raises: [], tags: [], forbids: [].}
Return empty dependency-governance policy. 
proc initInstallInfo(): InstallInfo {....raises: [], tags: [], forbids: [].}
Return empty install settings. 
proc initPackageInfo(): PackageInfo {....raises: [], tags: [], forbids: [].}
Return package defaults used when [package] omits values. 
proc initProfileInfo(): ProfileInfo {....raises: [], tags: [], forbids: [].}
Return an empty compiler profile. 
proc initTestInfo(): TestInfo {....raises: [], tags: [], forbids: [].}
Return default test discovery and output settings. 
proc initToolchainInfo(): ToolchainInfo {....raises: [], tags: [], forbids: [].}
Return empty toolchain constraints. 
proc loadEffectiveConfig(projectDir: string; workspaceRoot: string = ""): BauConfig {....raises: [
    IOError, ValueError, OSError, TomlError, KeyError, Exception, Exception], tags: [
    ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect, ReadEnvEffect],
    forbids: [].}
Load the project config after workspace, local, global, and env overrides. 
proc loadGlobalConfig(): Option[FullConfig] {....raises: [], tags: [ReadEnvEffect,
    ReadIOEffect, ReadDirEffect, RootEffect, WriteIOEffect], forbids: [].}

Load optional user-level Bau config from the platform config directory.

Invalid global config is ignored so local project commands remain usable.

proc loadLocalConfig(projectDir: string): Option[BauConfig] {....raises: [],
    tags: [ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect], forbids: [].}

Load an optional bau.local.toml override for a project.

Invalid local config is ignored by design.

proc loadWorkspaceConfig(path: string): Option[WorkspaceConfig] {....raises: [],
    tags: [ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect], forbids: [].}

Load a workspace table from a config file, if one exists.

Invalid workspace config returns none.

proc mergeBauConfig(base: var BauConfig; override: BauConfig) {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}

Merge an override configuration into base.

This is used for local and layered config where populated override values should replace or extend the already-loaded project configuration.

proc mergePackageDefaults(base: var PackageInfo; defaults: PackageInfo) {.
    ...raises: [], tags: [], forbids: [].}
Fill missing package fields in base from workspace defaults. 
proc mergeProfile(base: var ProfileInfo; override: ProfileInfo) {....raises: [],
    tags: [], forbids: [].}

Merge a profile override into base.

Flags and defines are additive; scalar fields replace only when populated.

proc parseBauConfig(data: string; fileName: string = ""): BauConfig {.
    ...raises: [IOError, OSError, TomlError, ValueError, KeyError, Exception],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect], forbids: [].}

Parse TOML configuration text into a BauConfig.

fileName is used only for parser diagnostics.

proc parseBauConfigFile(path: string): BauConfig {.
    ...raises: [IOError, ValueError, OSError, TomlError, KeyError, Exception],
    tags: [ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect], forbids: [].}
Load and parse a bau.toml file, raising on missing or invalid paths. 
proc parseTasksToml(data: string): seq[TaskInfo] {.
    ...raises: [IOError, OSError, TomlError, ValueError, KeyError, Exception],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect], forbids: [].}
Parse a standalone task TOML document into task definitions. 
proc resolveCatalogDeps(cfg: var BauConfig) {....raises: [KeyError, ValueError],
    tags: [], forbids: [].}
Replace catalog: dependency version references with concrete catalog values. 
proc resolveProfile(profiles: Table[string, ProfileInfo]; name: string): ProfileInfo {.
    ...raises: [ValueError, KeyError], tags: [], forbids: [].}
Resolve a profile by name, including any inherited parent profile.

Made with Nim. Generated: 2026-05-23 13:54:23 UTC