Global System Configurations

Flude uses a global configuration file — conventionally named ude_global_config.json (the engine also recognizes the legacy name ude_global.json) — to control system-wide behaviors that apply to every target compilation pipeline: logging verbosity, the on-disk build cache location, Doxygen discovery, and documentation-coverage gating.

---

📋 File Schema Overview

The global config is auto-discovered by walking up the directory tree from the doc-config's own directory (unless an explicit --global-config path is passed on the CLI). It is parsed into a strictly-typed GlobalConfig model with extra="ignore" semantics — unknown keys are silently dropped, not rejected — so a typo in a key name will not raise an error, it will simply have no effect.

IMPORTANT

There is no free-form logging or caching block. The real schema is a flat set of top-level keys — see below.

The real, validated fields of GlobalConfig are:

Key	Type	Default	Purpose
doxygen_path	string | null	null	Directory containing the Doxygen executable. If set, it is resolved to an absolute path and prepended to the process PATH environment variable — this is the only place in the engine that touches an environment variable.
log_level	string	"WARNING"	Passed straight to Python's logging module. An invalid value silently falls back to WARNING rather than raising.
log_file	string | null	null	If set, log output is also written to this file, in addition to always going to stderr. If the file can't be opened, this only logs a warning — it never crashes the build.
cache_root_dir	string | null	null	Root directory for the on-disk build cache: L1 (collected Doxygen XML), L2 (rendered output), and per-file native AST parse caching when using parser_backend: native. Note that per-file caching only applies to the native backend; the default Doxygen path's cache is necessarily whole-project since Doxygen itself is a single whole-tree invocation. Resolved to an absolute path relative to the global config file's own directory.
global_templates_dir	string | null	null	Root directory for shared global templates (e.g. a shared Doxyfile tier). Resolved the same way as cache_root_dir.
error_policy	string	"fail-fast"	Pipeline error handling policy. The other value seen in real-world configs is "continue-on-error".
translation_service	string | null	null	Optional identifier of a configured translation backend.
coverage_mode	"allow-undocumented" | "reject-undocumented"	"allow-undocumented"	Documentation coverage gate mode.
coverage_threshold	float (0.0–1.0)	1.0	Minimum fraction of documented entities required to pass the coverage gate.

CAUTION

coverage_threshold is a fraction, not a percentage. 0.98 means 98%. This is easy to confuse with the ude audit CLI command's --threshold flag, which takes a human-friendly percentage (e.g. 98) and divides it by 100 at the CLI boundary before it ever reaches this config. If you copy a number from one to the other without converting, your gate will be silently wrong (e.g. passing 98 here would require 9800% coverage — impossible — so the gate would always fail).

---

🪦 The Removed sidebar_structures_dir Key

If a global config JSON still contains a sidebar_structures_dir key — left over from an older config generation — loading it raises a fatal, explicit error:

UdeException: sidebar_structures_dir is removed; folder taxonomy is now sourced exclusively from sidebar.toml [groups].

IMPORTANT

Migration trap: this is one of the few keys the engine actively rejects rather than silently ignoring, specifically to stop a stale config from producing a build that runs but silently drops the intended sidebar taxonomy. If you hit this exception, remove sidebar_structures_dir from the global config and move the equivalent structure into a project's sidebar.toml [groups] table instead (see Target Settings for the [groups] schema).

---

📂 A Real Example

ude_projects/ude_global_config.json, as of the 2026-08-31 config audit (DEL-B37):

{
    "error_policy": "continue-on-error",
    "log_level": "INFO",
    "stylesheet_dir": "../engine/ude/templates/css/default",
    "output_base_dir": "../.workdir/output",
    "cache_root_dir": "../.workdir/cache",
    "api_version": "27.6"
}

• error_policy, log_level, cache_root_dir map onto real GlobalConfig fields.
• stylesheet_dir, output_base_dir, api_version are real and meaningful, but not through GlobalConfig. The orchestrator reads these directly off the merged config dictionary (the result of the global → SDK → doc-config cascade described in Target Settings), not off the typed GlobalConfig object. stylesheet_dir picks the CSS asset source for HTML/ODA HTML output; output_base_dir pairs with a doc-config's output_subdir to build the final output path; api_version is a template-interpolation variable used by renderers, defaulting to "27.6" if it's absent anywhere in the merged config.

CAUTION

Until 2026-08-31 this file instead had "logging": {"level": "INFO", "file": "../ude_system.log"} and "doxygen_binary": "doxygen". Neither matches a real GlobalConfig field (the real names are flat log_level/log_file and doxygen_path), so both were silently dropped by extra="ignore" — logging level/file-logging and Doxygen-path resolution from this file were inert no-ops the whole time this shipped. doxygen_binary was dropped rather than renamed to doxygen_path (not merely renamed): doxygen_path expects a directory to prepend to PATH, not a binary name, and Doxygen was already resolving correctly via PATH (shutil.which("doxygen")) regardless of this key — so there was nothing for the corrected key to actually do. log_file was likewise dropped rather than activated: it isn't resolved relative to the global config's own directory the way cache_root_dir/stylesheet_dir are — it's passed straight to logging.FileHandler, so it resolves relative to the process's current working directory at invocation time. Since every project's generate_docs.bat does pushd "%~dp0" into its own project folder first, a value like "../ude_system.log" would have landed inside each SDK's own folder — one scattered log file per SDK per run, not one shared log — the moment the key name was fixed and the feature activated for the first time. If persistent file logging is wanted, set log_file to an absolute path (or accept the per-invocation-CWD behavior deliberately) rather than reusing the old relative value.

If you need this file's schema before this fix, see git history for ude_projects/ude_global_config.json (pre-DEL-B37).

---

🧭 Where This Fits

For the full 3-tier cascade that combines this global config with an SDK/product config and a per-target doc config — including how lists and dicts merge differently, and how the sidebar.toml [groups] taxonomy has its own nested 3-tier cascade — see Target Settings.