Aria uses one dependencies.json. Each dependency has source fields, an optional requested version, and a generated resolved object. Sources are recorded once. A missing/empty version or "latest" means latest stable when first resolved or deliberately updated; normal builds reuse the persisted result. Commit this file to reproduce the selection in CI.

Complete usage: English · 中文. These guides cover mixed fixed/latest policies, selective updates, command-line overrides, offline operation and rollback.

CLI and selection

Dependency resolution, source verification and shared artifact storage use ForgeDeps. Build recipes are supplied by the separately versioned ForgeRecipes package. Install its pinned version with Python 3.14+ in the environment used to build:

python -m pip install -r requirements-build.txt

python -m forgedeps init /path/to/shared-dependencies

CMake invokes that package for both cold and verified-cache builds; an offline build still needs Python and ForgeDeps installed. Core-only builds with tests and HTTP disabled do not load them. scripts/build.py passes its own interpreter to CMake. With direct CMake invocation, select it using -DFORGEDEPS_PYTHON_EXECUTABLE=/path/to/python when necessary. The optional FORGEDEPS_CMAKE_DIR points at the package's CMake directory; it is normally located with python -m forgedeps cmake-dir. The optional authenticated gh CLI can supply GitHub API access.

python3 scripts/dependencies.py update --file dependencies.json
python3 scripts/dependencies.py update --file dependencies.json --only mira
python3 scripts/dependencies.py update --file dependencies.json --version json=3.12.0 --version openssl=4.0.3
python3 scripts/dependencies.py resolve --file dependencies.json --offline

An invocation-specific version overrides an explicit declaration. A declaration with a fixed version is restored by the next resolution without that override. If the declaration uses the default/latest policy, ordinary resolution keeps a previous command-line selection until another explicit request or update. --only limits writes to selected entries; include every override in that list when combining the two arguments.

Resolution is atomic across the selected entries. It records complete GitHub commits and SHA256 values for downloads. The result's request_hash binds the source fields and requested policy; editing either invalidates the old result. The hash is a consistency check, not an upstream signature. Editing resolved by hand is unsupported. Cached downloads and extracted sources are independently verified before reuse. A successful update still requires compatibility testing.

CMake source integration

set(ARIA_DEPENDENCIES_FILE "${CMAKE_SOURCE_DIR}/dependencies.json" CACHE FILEPATH "")
include("${ARIA_DIR}/cmake/ariaDependencies.cmake")
aria_resolve_dependency(NAME json VERSION json_version URL json_url SHA256 json_sha)
 
include("${ARIA_DIR}/cmake/ariaFetchPinned.cmake")
aria_fetch_pinned_archive(NAME json)
# ARIA_PINNED_JSON_SOURCE_DIR names the verified source directory.

NAME is case insensitive. FILE selects another complete dependency file for one lookup. REVISION and TAG optionally name output variables. Parents must include declarations for every dependency used by their selected Aria features. Fetch helpers retain their explicit VERSION/URL/SHA256 interface for unrelated dependencies. These wrappers contain Aria policy only; ForgeDeps owns resolution, downloads, extraction, locking and cache verification. Cache layouts are private to ForgeDeps; an old Aria-only cache may need one online population.

JSON, doctest and OpenSSL are built once by ForgeRecipes into the registered shared workspace, then imported from their verified installation prefixes. The same actual compiler, SDK, architecture, configuration and ABI flags select the same artifact across consumers. Changed inputs replace the stable slot only after active readers finish; build directories do not contain a second vendor build. FORGEDEPS_HOME selects another initialized workspace explicitly.

scripts/build.py prepares all dependency environments, then holds their complete dependency graph under a reader lease while configuring, building and running tests. forgedeps-environment.json records the chosen generations. Direct CMake prepares and verifies the same environment; to protect a separate build/install invocation against concurrent package replacement, run it with:

python -m forgedeps run --environment build/flavors/custom/forgedeps-environment.json -- cmake --build build/flavors/custom

For multi-config generators, set ARIA_DEPENDENCIES_CONFIGURATION to the configuration you will build. The portable driver passes this automatically. Mira may still be integrated as the selected release source or an explicit ARIA_PIN_MIRA_SOURCE_DIR. When a parent supplies a complete Mira SDK through its dependency environment, Aria imports it instead. A shared Aria SDK recipe must declare its HTTP dependencies in that graph before taking the build lease. Complete parent targets and explicit package prefixes retain priority.

When the latest upstream release still has a reproducible defect affecting required behavior, follow the shared maintenance policy: maintain a focused fork, preserve upstream history and licenses, add regression coverage, publish immutable tested releases and continue tracking upstream.

Source-library version options: ARIA_DEP_JSON_VERSION, ARIA_DEP_DOCTEST_VERSION, ARIA_DEP_MIRA_VERSION, ARIA_DEP_OPENSSL_VERSION. For example:

cmake -S . -B build/flavors/custom -DARIA_BUILD_HTTP=ON -DARIA_DEP_JSON_VERSION=3.12.0

Overrides and missing results are resolved to an ignored build-directory dependencies.json, leaving the source file unchanged. The effective file binds the complete source-file fingerprint; updating source requirements or results invalidates older build selections. Clear a cached version option, for example -DARIA_DEP_JSON_VERSION=, to return to project policy and results. Use the updater to persist a shared selection instead of editing build caches.

Offline builds and local sources

resolve --offline requires matching embedded metadata. CMake's -DARIA_DEPENDENCIES_OFFLINE=ON additionally requires cached source downloads. The shared workspace must already contain the selected sources and artifacts. FORGEDEPS_CACHE_DIR continues to select the legacy source cache used for Mira source integration and the generic fetch helper; it does not relocate shared artifact installations.

-DARIA_PIN_JSON_SOURCE_DIR=/path/to/json supplies a source directory directly; Mira, doctest and OpenSSL have equivalent source overrides. Third-party overrides are snapshotted and content-hashed by the shared store; they do not mutate the verified download cache. The caller owns their compatibility. Mira source integration uses the explicit directory directly. Preexisting dependency targets supplied by a parent also take precedence over source-version requests.

Installed Qt SDK

Qt is discovered, not installed by the updater. aria_find_qt6 requests natural descending version-directory order within CMake-visible locations while preserving explicit Qt6_DIR, CMAKE_PREFIX_PATH and toolchain precedence. -DARIA_DEP_QT_VERSION=6.10.0 requires that exact installed SDK; an unavailable version fails rather than selecting another one. The helper restores the parent's package-sort settings after its lookup.