spack.schema package¶
This module contains jsonschema files for all of Spack’s YAML formats.
- class spack.schema.DeprecationMessage(message, error)[source]¶
Bases:
NamedTuple
- spack.schema.merge_yaml(dest, source, prepend=False, append=False)[source]¶
Merges source into dest; entries in source take precedence over dest.
This routine may modify dest and should be assigned to dest, in case dest was None to begin with, e.g.:
dest = merge_yaml(dest, source)
In the result, elements from lists from
sourcewill appear before elements of lists fromdest. Likewise, when iterating over keys or items in mergedOrderedDictobjects, keys fromsourcewill appear before keys fromdest.Config file authors can optionally end any attribute in a dict with
::instead of:, and the key will override that of the parent instead of merging.+:will extend the default prepend merge strategy to include string concatenation-:will change the merge strategy to append, it also includes string concatenation
- spack.schema.override(string: str) bool[source]¶
Test if a spack YAML string is an override.
See
spack_yamlfor details. Keys in Spack YAML can end in::, and if they do, their values completely replace lower-precedence configs instead of merging into them.
Submodules¶
spack.schema.bootstrap module¶
Schema for bootstrap.yaml configuration file.
- spack.schema.bootstrap.schema¶
Full schema with metadata
spack.schema.buildcache_spec module¶
Schema for a buildcache spec.yaml file
properties: Dict[str, Any] = {
# `buildinfo` is no longer needed as of Spack 0.21
"buildinfo": {"type": "object"},
"spec": {**spack.schema.spec.spec_node, "additionalProperties": True},
"buildcache_layout_version": {"type": "number"},
}
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack buildcache specfile schema",
"type": "object",
"additionalProperties": True,
"properties": properties,
}
spack.schema.cdash module¶
Schema for cdash.yaml configuration file.
properties: Dict[str, Any] = {
"cdash": {
"type": "object",
"additionalProperties": False,
"required": ["build-group"],
"description": "Configuration for uploading build results to CDash",
"properties": {
"build-group": {
"type": "string",
"description": "Unique build group name for this stack",
},
"url": {"type": "string", "description": "CDash server URL"},
"project": {"type": "string", "description": "CDash project name"},
"site": {"type": "string", "description": "Site identifier for CDash reporting"},
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack cdash configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
}
- spack.schema.cdash.schema¶
Full schema with metadata
spack.schema.ci module¶
Schema for gitlab-ci.yaml configuration file.
script_schema = {
"type": "array",
"items": {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]},
}
# Schema for CI image
image_schema = {
"oneOf": [
{"type": "string"},
{
"type": "object",
"properties": {
"name": {"type": "string"},
"entrypoint": {"type": "array", "items": {"type": "string"}},
},
},
]
}
# Additional attributes are allowed and will be forwarded directly to the CI target YAML for each
# job.
ci_job_attributes = {
"type": "object",
"additionalProperties": True,
"properties": {
"image": image_schema,
"tags": {"type": "array", "items": {"type": "string"}},
"variables": {
"type": "object",
"patternProperties": {r"^[\w\-\.]+$": {"type": ["string", "number"]}},
},
"before_script": script_schema,
"script": script_schema,
"after_script": script_schema,
},
}
ref_ci_job_attributes = {"$ref": "#/definitions/ci_job_attributes"}
submapping_schema = {
"type": "object",
"additionalProperties": False,
"required": ["submapping"],
"properties": {
"match_behavior": {"type": "string", "enum": ["first", "merge"], "default": "first"},
"submapping": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": False,
"required": ["match"],
"properties": {
"match": {"type": "array", "items": {"type": "string"}},
"build-job": ref_ci_job_attributes,
"build-job-remove": ref_ci_job_attributes,
},
},
},
},
}
dynamic_mapping_schema = {
"type": "object",
"additionalProperties": False,
"required": ["dynamic-mapping"],
"properties": {
"dynamic-mapping": {
"type": "object",
"required": ["endpoint"],
"properties": {
"name": {"type": "string"},
# "endpoint" cannot have http patternProperties constraint since it is required
# Constrain is applied in code
"endpoint": {"type": "string"},
"timeout": {"type": "integer", "minimum": 0},
"verify_ssl": {"type": "boolean", "default": False},
"header": {"type": "object", "additionalProperties": {"type": "string"}},
"allow": {"type": "array", "items": {"type": "string"}},
"require": {"type": "array", "items": {"type": "string"}},
"ignore": {"type": "array", "items": {"type": "string"}},
},
}
},
}
def job_schema(name: str):
return {
"type": "object",
"additionalProperties": False,
"properties": {
f"{name}-job": ref_ci_job_attributes,
f"{name}-job-remove": ref_ci_job_attributes,
},
}
pipeline_gen_schema = {
"type": "array",
"items": {
"oneOf": [
submapping_schema,
dynamic_mapping_schema,
job_schema("any"),
job_schema("build"),
job_schema("cleanup"),
job_schema("copy"),
job_schema("noop"),
job_schema("reindex"),
job_schema("signing"),
]
},
}
#: Properties for inclusion in other schemas
properties: Dict[str, Any] = {
"ci": {
"type": "object",
"properties": {
"pipeline-gen": pipeline_gen_schema,
"rebuild-index": {"type": "boolean"},
"broken-specs-url": {"type": "string"},
"broken-tests-packages": {"type": "array", "items": {"type": "string"}},
"target": {"type": "string", "default": "gitlab"},
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack CI configuration file schema",
"type": "object",
"additionalProperties": False,
"definitions": {"ci_job_attributes": ci_job_attributes},
"properties": properties,
}
- spack.schema.ci.schema¶
Full schema with metadata
spack.schema.compilers module¶
Schema for compilers.yaml configuration file.
"type": "object",
"additionalProperties": False,
"description": "Flags to pass to the compiler during compilation and linking",
"properties": {
"cflags": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Flags for C compiler, e.g. -std=c11",
},
"cxxflags": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Flags for C++ compiler, e.g. -std=c++14",
},
"fflags": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Flags for Fortran 77 compiler, e.g. -ffixed-line-length-none",
},
"cppflags": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Flags for C preprocessor, e.g. -DFOO=1",
},
"ldflags": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Flags passed to the compiler driver during linking, e.g. "
"-Wl,--gc-sections",
},
"ldlibs": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Flags for linker libraries, e.g. -lpthread",
},
},
}
extra_rpaths: Dict[str, Any] = {
"type": "array",
"default": [],
"items": {"type": "string"},
"description": "List of extra rpaths to inject by Spack's compiler wrappers",
}
implicit_rpaths: Dict[str, Any] = {
"anyOf": [{"type": "array", "items": {"type": "string"}}, {"type": "boolean"}],
"description": "List of non-default link directories to register at runtime as rpaths",
}
#: Properties for inclusion in other schemas
properties: Dict[str, Any] = {
"compilers": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": False,
"properties": {
"compiler": {
"type": "object",
"additionalProperties": False,
"required": ["paths", "spec", "modules", "operating_system"],
"properties": {
"paths": {
"type": "object",
"required": ["cc", "cxx", "f77", "fc"],
"additionalProperties": False,
"properties": {
"cc": {"anyOf": [{"type": "string"}, {"type": "null"}]},
"cxx": {"anyOf": [{"type": "string"}, {"type": "null"}]},
"f77": {"anyOf": [{"type": "string"}, {"type": "null"}]},
"fc": {"anyOf": [{"type": "string"}, {"type": "null"}]},
},
},
"flags": flags,
"spec": {"type": "string"},
"operating_system": {"type": "string"},
"target": {"type": "string"},
"alias": {"anyOf": [{"type": "string"}, {"type": "null"}]},
"modules": {
"anyOf": [
{"type": "null"},
{"type": "array", "items": {"type": "string"}},
]
},
"implicit_rpaths": implicit_rpaths,
"environment": spack.schema.environment.ref_env_modifications,
"extra_rpaths": extra_rpaths,
},
}
},
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack compiler configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
"definitions": {"env_modifications": spack.schema.environment.env_modifications},
}
- spack.schema.compilers.schema¶
Full schema with metadata
spack.schema.concretizer module¶
Schema for concretizer.yaml configuration file.
LIST_OF_SPECS = {"type": "array", "items": {"type": "string"}}
properties: Dict[str, Any] = {
"concretizer": {
"type": "object",
"additionalProperties": False,
"description": "Concretizer configuration that controls dependency selection, package "
"reuse, and solver behavior",
"properties": {
"force": {
"type": "boolean",
"default": False,
"description": "Force re-concretization when concretizing environments",
},
"reuse": {
"description": "Controls how aggressively Spack reuses installed packages and "
"build caches during concretization",
"oneOf": [
{
"type": "boolean",
"description": "If true, reuse installed packages and build caches for "
"all specs; if false, always perform fresh concretization",
},
{
"type": "string",
"enum": ["dependencies"],
"description": "Reuse installed packages and build caches only for "
"dependencies, not root specs",
},
{
"type": "object",
"description": "Advanced reuse configuration with fine-grained control "
"over which specs are reused",
"properties": {
"roots": {
"type": "boolean",
"description": "If true, root specs are reused; if false, only "
"dependencies of root specs are reused",
},
"include": {
**LIST_OF_SPECS,
"description": "List of spec constraints. Reusable specs must "
"match at least one constraint",
},
"exclude": {
**LIST_OF_SPECS,
"description": "List of spec constraints. Reusable specs must "
"not match any constraint",
},
"from": {
"type": "array",
"description": "List of sources from which reused specs are taken",
"items": {
"type": "object",
"description": "Source configuration for reusable specs",
"properties": {
"type": {
"type": "string",
"enum": [
"local",
"buildcache",
"external",
"environment",
],
"description": "Type of source: 'local' (installed "
"packages), 'buildcache' (remote binaries), "
"'external' (system packages), or 'environment' "
"(from specific environment)",
},
"path": {
"type": "string",
"description": "Path to the source (for environment "
"type sources)",
},
"include": {
**LIST_OF_SPECS,
"description": "Spec constraints that must be "
"matched for this source (overrides global include)",
},
"exclude": {
**LIST_OF_SPECS,
"description": "Spec constraints that must not be "
"matched for this source (overrides global exclude)",
},
},
},
},
},
},
],
},
"targets": {
"type": "object",
"description": "Controls which target microarchitectures are considered "
"during concretization",
"properties": {
"host_compatible": {
"type": "boolean",
"description": "If true, only allow targets compatible with the "
"current host; if false, allow any target (e.g., concretize for icelake "
"while running on haswell)",
},
"granularity": {
"type": "string",
"enum": ["generic", "microarchitectures"],
"description": "Target selection granularity: 'microarchitectures' "
"(e.g., haswell, skylake) or 'generic' (e.g., x86_64_v3, aarch64)",
},
},
},
"unify": {
"description": "Controls whether environment specs are concretized together "
"or separately",
"oneOf": [
{
"type": "boolean",
"description": "If true, concretize environment root specs together "
"for unified dependencies; if false, concretize each spec independently",
},
{
"type": "string",
"enum": ["when_possible"],
"description": "Maximizes reuse, while allowing multiple instances of the "
"same package",
},
],
},
"compiler_mixing": {
"oneOf": [{"type": "boolean"}, {"type": "array"}],
"description": "Whether to allow compiler mixing between link/run dependencies",
},
"splice": {
"type": "object",
"additionalProperties": False,
"description": "Configuration for spec splicing: replacing dependencies "
"with ABI-compatible alternatives to improve package reuse",
"properties": {
"explicit": {
"type": "array",
"default": [],
"description": "List of explicit splice configurations to replace "
"specific dependencies",
"items": {
"type": "object",
"required": ["target", "replacement"],
"additionalProperties": False,
"description": "Explicit splice configuration",
"properties": {
"target": {
"type": "string",
"description": "Abstract spec to be replaced (e.g., 'mpi' "
"or specific package)",
},
"replacement": {
"type": "string",
"description": "Concrete spec with hash to use as "
"replacement (e.g., 'mpich/abcdef')",
},
"transitive": {
"type": "boolean",
"default": False,
"description": "If true, use transitive splice (conflicts "
"resolved using replacement dependencies); if false, use "
"intransitive splice (conflicts resolved using original "
"dependencies)",
},
},
},
},
"automatic": {
"type": "boolean",
"description": "Enable automatic splicing for ABI-compatible packages "
"(experimental feature)",
},
},
},
"duplicates": {
"type": "object",
"description": "Controls whether the dependency graph can contain multiple "
"configurations of the same package",
"properties": {
"strategy": {
"type": "string",
"enum": ["none", "minimal", "full"],
"description": "Duplication strategy: 'none' (single config per "
"package), 'minimal' (allow build-tools duplicates), 'full' "
"(experimental: allow full build-tool stack separation)",
},
"max_dupes": {
"type": "object",
"description": "Maximum number of duplicates allowed per package when "
"using strategies that permit duplicates",
"additionalProperties": {
"type": "integer",
"minimum": 1,
"description": "Maximum number of duplicate instances for this "
"package",
},
},
},
},
"static_analysis": {
"type": "boolean",
"description": "Enable static analysis to reduce concretization time by "
"generating smaller ASP problems",
},
"timeout": {
"type": "integer",
"minimum": 0,
"description": "Maximum time in seconds for the solve phase (0 means no "
"time limit)",
},
"error_on_timeout": {
"type": "boolean",
"description": "If true, timeout always results in error; if false, use best "
"suboptimal solution found before timeout (yields unreproducible results)",
},
"os_compatible": {
"type": "object",
"additionalProperties": {"type": "array"},
"description": "Compatibility mapping between operating systems for reuse of "
"compilers and packages (key: target OS, value: list of compatible source OSes)",
},
"concretization_cache": {
"type": "object",
"description": "Configuration for caching solver outputs from successful "
"concretization runs",
"properties": {
"enable": {
"type": "boolean",
"description": "Whether to utilize a cache of solver outputs from "
"successful concretization runs",
},
"url": {
"type": "string",
"description": "Path to the location where Spack will root the "
"concretization cache",
},
"entry_limit": {
"type": "integer",
"minimum": 0,
"description": "Limit on the number of concretization results that "
"Spack will cache (0 disables pruning)",
},
},
},
"externals": {
"type": "object",
"description": "Configuration for how Spack handles external packages during "
"concretization",
"properties": {
"completion": {
"type": "string",
"enum": ["architecture_only", "default_variants"],
"description": "Controls how missing information (variants, etc.) is "
"completed for external packages: 'architecture_only' completes only "
"mandatory architectural information; 'default_variants' also completes "
"missing variants using their default values",
}
},
},
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack concretizer configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
}
- spack.schema.concretizer.schema¶
Full schema with metadata
spack.schema.config module¶
Schema for config.yaml configuration file.
"config": {
"type": "object",
"default": {},
"description": "Spack's basic configuration options",
"properties": {
"flags": {
"type": "object",
"description": "Build flag configuration options",
"properties": {
"keep_werror": {
"type": "string",
"enum": ["all", "specific", "none"],
"description": "Whether to keep -Werror flags active in package builds",
}
},
},
"shared_linking": {
"description": "Control how shared libraries are located at runtime on Linux",
"anyOf": [
{"type": "string", "enum": ["rpath", "runpath"]},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["rpath", "runpath"],
"description": "Whether to use RPATH or RUNPATH for runtime "
"library search paths",
},
"bind": {
"type": "boolean",
"description": "Embed absolute paths of dependent libraries "
"directly in ELF binaries (experimental)",
},
"missing_library_policy": {
"enum": ["error", "warn", "ignore"],
"description": "How to handle missing dynamic libraries after "
"installation",
},
},
},
],
},
"install_tree": {
"type": "object",
"description": "Installation tree configuration",
"properties": {
"root": {
"type": "string",
"description": "The location where Spack will install packages and "
"their dependencies",
},
"padded_length": {
"oneOf": [{"type": "integer", "minimum": 0}, {"type": "boolean"}],
"description": "Length to pad installation paths to allow better "
"relocation of binaries (true for max length, integer for specific "
"length)",
},
**spack.schema.projections.ref_properties,
},
},
"install_hash_length": {
"type": "integer",
"minimum": 1,
"description": "Length of hash used in installation directory names",
},
"build_stage": {
"oneOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}],
"description": "Temporary locations Spack can try to use for builds",
},
"stage_name": {
"type": "string",
"description": "Name format for build stage directories",
},
"develop_stage_link": {
"type": "string",
"description": "Name for development spec build stage directories. Setting to "
"None will disable develop stage links.",
},
"test_stage": {
"type": "string",
"description": "Directory in which to run tests and store test results",
},
"extensions": {
"type": "array",
"items": {"type": "string"},
"description": "List of Spack extensions to load",
},
"template_dirs": {
"type": "array",
"items": {"type": "string"},
"description": "Locations where templates should be found",
},
"license_dir": {
"type": "string",
"description": "Directory where licenses should be located",
},
"source_cache": {
"type": "string",
"description": "Location to cache downloaded tarballs and repositories",
},
"misc_cache": {
"type": "string",
"description": "Temporary directory to store long-lived cache files, such as "
"indices of packages",
},
"environments_root": {
"type": "string",
"description": "Directory where Spack managed environments are created and stored",
},
"connect_timeout": {
"type": "integer",
"minimum": 0,
"description": "Abort downloads after this many seconds if no data is received "
"(0 disables timeout)",
},
"verify_ssl": {
"type": "boolean",
"description": "When true, Spack will verify certificates of remote hosts when "
"making SSL connections",
},
"ssl_certs": {
"type": "string",
"description": "Path to custom certificates for SSL verification",
},
"suppress_gpg_warnings": {
"type": "boolean",
"description": "Suppress GPG warnings from binary package verification",
},
"debug": {
"type": "boolean",
"description": "Enable debug mode for additional logging",
},
"checksum": {
"type": "boolean",
"description": "When true, Spack verifies downloaded source code using checksums",
},
"deprecated": {
"type": "boolean",
"description": "If true, Spack will fetch deprecated versions without warning",
},
"locks": {
"type": "boolean",
"description": "When true, concurrent instances of Spack will use locks to avoid "
"conflicts (strongly recommended)",
},
"dirty": {
"type": "boolean",
"description": "When true, builds will NOT clean potentially harmful variables "
"from the environment",
},
"build_language": {
"type": "string",
"description": "The language the build environment will use (C for English, "
"empty string for user's environment)",
},
"build_jobs": {
"type": "integer",
"minimum": 1,
"description": "The maximum number of jobs to use for the build system (e.g. "
"make -j), defaults to 16",
},
"concurrent_packages": {
"type": "integer",
"minimum": 0,
"description": "The maximum number of concurrent package builds a single Spack "
"instance will run",
},
"ccache": {
"type": "boolean",
"description": "When true, Spack's compiler wrapper will use ccache when "
"compiling C and C++",
},
"db_lock_timeout": {
"type": "integer",
"minimum": 1,
"description": "How long to wait to lock the Spack installation database",
},
"package_lock_timeout": {
"anyOf": [{"type": "integer", "minimum": 1}, {"type": "null"}],
"description": "How long to wait when attempting to modify a package (null for "
"never timeout)",
},
"allow_sgid": {
"type": "boolean",
"description": "Allow installation on filesystems that don't allow setgid bit "
"manipulation",
},
"install_status": {
"type": "boolean",
"description": "Whether to show status information in the terminal title during "
"the build",
},
"url_fetch_method": {
"anyOf": [{"enum": ["urllib", "curl"]}, {"type": "string", "pattern": r"^curl "}],
"description": "The default URL fetch method to use (urllib or curl)",
},
"additional_external_search_paths": {
"type": "array",
"items": {"type": "string"},
"description": "Additional paths to search for external packages",
},
"binary_index_ttl": {
"type": "integer",
"minimum": 0,
"description": "Number of seconds a buildcache's index.json is cached locally "
"before probing for updates",
},
"aliases": {
"type": "object",
"additionalProperties": {"type": "string"},
"description": "A mapping of aliases that can be used to define new "
"Spack commands",
},
"installer": {
"type": "string",
"enum": ["old", "new"],
"description": "Which installer to use. The new installer is experimental.",
},
"sandbox": {
"type": "object",
"description": "Restrict filesystem and network access during builds.",
"additionalProperties": False,
"properties": {
"enable": {
"type": "boolean",
"description": "Enable or disable the build sandbox.",
},
"allow_network": {
"type": "boolean",
"description": "Allow TCP network access during the build phase.",
},
"allow_read": {
"type": "array",
"items": {"type": "string"},
"description": "Additional paths with read and execute permissions.",
},
"allow_write": {
"type": "array",
"items": {"type": "string"},
"description": "Additional paths with write and execute permissions.",
},
},
},
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack core configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
"definitions": {"projections": spack.schema.projections.projections},
}
def update(data: dict) -> bool:
"""Update the data in place to remove deprecated properties.
Args:
data: dictionary to be updated
Returns: True if data was changed, False otherwise
"""
changed = False
data = data["config"]
shared_linking = data.get("shared_linking", None)
if isinstance(shared_linking, str):
# deprecated short-form shared_linking: rpath/runpath
# add value as `type` in updated shared_linking
data["shared_linking"] = {"type": shared_linking, "bind": False}
changed = True
return changed
- spack.schema.config.schema¶
Full schema with metadata
spack.schema.container module¶
Schema for the container subsection of Spack environments.
- spack.schema.container.container_schema¶
Schema for the container attribute included in Spack environments
spack.schema.cray_manifest module¶
Schema for Cray descriptive manifest: this describes a set of installed packages on the system and also specifies dependency relationships between them (so this provides more information than external entries in packages configuration).
This does not specify a configuration - it is an input format that is consumed and transformed into Spack DB records.
spack.schema.database_index module¶
Schema for database index.json file
"type": "object",
"required": ["installs", "version"],
"additionalProperties": False,
"properties": {
"installs": {
"type": "object",
"patternProperties": {
r"^[a-z0-9]{32}$": {
"type": "object",
"properties": {
"spec": spack.schema.spec.spec_node,
"path": {"oneOf": [{"type": "string"}, {"type": "null"}]},
"installed": {"type": "boolean"},
"ref_count": {"type": "integer", "minimum": 0},
"explicit": {"type": "boolean"},
"installation_time": {"type": "number"},
},
}
},
},
"version": {"type": "string"},
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack spec schema",
"type": "object",
"required": ["database"],
"additionalProperties": False,
"properties": properties,
}
- spack.schema.database_index.schema¶
Full schema with metadata
spack.schema.definitions module¶
Schema for definitions
properties: Dict[str, Any] = {
"definitions": {
"type": "array",
"default": [],
"description": "Named spec lists to be referred to with $name in the specs section of "
"environments",
"items": {
"type": "object",
"description": "Named definition entry containing a named spec list and optional "
"conditional 'when' clause",
"properties": {
"when": {
"type": "string",
"description": "Python code condition evaluated as boolean. Specs are "
"appended to the named list only if the condition is True. Available "
"variables: platform, os, target, arch, arch_str, re, env, hostname",
}
},
"additionalProperties": spec_list_schema,
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack definitions configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
}
- spack.schema.definitions.schema¶
Full schema with metadata
spack.schema.develop module¶
- spack.schema.develop.schema¶
Full schema with metadata
spack.schema.env module¶
Schema for env.yaml configuration file.
TOP_LEVEL_KEY = "spack"
# (DEPRECATED) include concrete entries to be merged under the include key
include_concrete = {
"type": "array",
"default": [],
"description": "List of paths to other environments. Includes concrete specs "
"from their spack.lock files without modifying the source environments. Useful "
"for phased deployments where you want to build on existing concrete specs.",
"items": {"type": "string"},
}
group_name_and_deps = {
"group": {"type": "string", "description": "Name for this group of specs"},
"explicit": {
"type": "boolean",
"default": True,
"description": "When false, specs in this group are installed as implicit "
"dependencies and are eligible for garbage collection.",
},
"needs": {
"type": "array",
"description": "Groups of specs that are needed by this group",
"items": {"type": "string"},
},
"override": {
"type": "object",
"description": "Top-most configuration scope for this group of specs",
"additionalProperties": False,
"properties": {**spack.schema.merged.ref_sections},
},
}
properties: Dict[str, Any] = {
"spack": {
"type": "object",
"default": {},
"description": "Spack environment configuration, including specs, view, and any other "
"config section (config, packages, concretizer, mirrors, etc.)",
"additionalProperties": False,
"properties": {
# merged configuration scope schemas
**spack.schema.merged.ref_sections,
# extra environment schema properties
"specs": {
"type": "array",
"description": "List of specs to include in the environment, "
"supporting both simple specs and matrix configurations",
"default": [],
"items": {
"anyOf": [
{
"type": "object",
"description": "Matrix configuration for generating multiple specs"
" from combinations of constraints",
"additionalProperties": False,
"properties": {**spec_list_properties},
},
{"type": "string", "description": "Simple spec string"},
{"type": "null"},
{
"type": "object",
"description": "User spec group with a single matrix",
"additionalProperties": False,
"properties": {**spec_list_properties, **group_name_and_deps},
},
{
"type": "object",
"description": "User spec group with multiple matrices",
"additionalProperties": False,
"properties": {**group_name_and_deps, "specs": spec_list_schema},
},
]
},
},
# (DEPRECATED) include concrete to be merged under the include key
"include_concrete": include_concrete,
},
}
}
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack environment file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
"definitions": spack.schema.merged.defs,
}
def update(data: Dict[str, Any]) -> bool:
"""Update the spack.yaml data to the new format.
Args:
data: dictionary to be updated
Returns:
``True`` if data was changed, ``False`` otherwise
"""
if not isinstance(data, dict):
return False
if "include_concrete" not in data:
return False
# Move the old 'include_concrete' paths to reside under the 'include',
# ensuring that the lock file name is appended.
includes = []
for path in data["include_concrete"]:
if os.path.basename(path) != "spack.lock":
path = os.path.join(path, "spack.lock")
includes.append(path)
# Now add back the includes the environment file already has.
if "include" in data:
for path in data["include"]:
includes.append(path)
data["include"] = includes
del data["include_concrete"]
return True
- spack.schema.env.TOP_LEVEL_KEY¶
Top level key in a manifest file
spack.schema.env_vars module¶
Schema for env_vars.yaml configuration file.
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack env_vars configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
"definitions": {"env_modifications": spack.schema.environment.env_modifications},
}
- spack.schema.env_vars.schema¶
Full schema with metadata
spack.schema.environment module¶
Schema for environment modifications. Meant for inclusion in other schemas.
- spack.schema.environment.parse(config_obj)[source]¶
Returns an EnvironmentModifications object containing the modifications parsed from input.
- Parameters:
config_obj – a configuration dictionary conforming to the schema definition for environment modifications
- spack.schema.environment.ref_env_modifications¶
$ref pointer for use in merged schema
spack.schema.include module¶
Schema for include.yaml configuration file.
#: Properties for inclusion in other schemas
properties: Dict[str, Any] = {
"include": {
"type": "array",
"default": [],
"additionalProperties": False,
"description": "Include external configuration files to pull in configuration from "
"other files/URLs for modular and reusable configurations",
"items": {
"anyOf": [
# local, required path
{
"type": "string",
"description": "Simple include entry specifying path to required "
"configuration file/directory",
},
# local or remote paths that may be optional or conditional
{
"type": "object",
"description": "Advanced include entry with optional conditions and "
"remote file support",
"properties": {
"when": {
"type": "string",
"description": "Include this config only when the condition (as "
"Python code) evaluates to true",
},
"name": {"type": "string"},
"path_override_env_var": {"type": "string"},
"path": {
"type": "string",
"description": "Path to configuration file/directory (absolute, "
"relative, or URL). URLs must be raw file content (GitHub/GitLab "
"raw form). Supports file, ftp, http, https schemes and "
"Spack/environment variables",
},
"sha256": {
"type": "string",
"description": "Required SHA256 hash for remote URLs to verify "
"file integrity",
},
"optional": {
"type": "boolean",
"description": "If true, include only if path exists; if false "
"(default), path is required and missing files cause errors",
},
"prefer_modify": {"type": "boolean"},
},
"required": ["path"],
"additionalProperties": False,
},
# remote git paths that may be optional or conditional
{
"type": "object",
"description": "Include configuration files from a git repository with "
"conditional and optional support",
"properties": {
"git": {
"type": "string",
"description": "URL of the git repository to clone (e.g., "
"https://github.com/spack/spack-configs)",
},
"branch": {
"type": "string",
"description": "Branch to check out from the repository",
},
"commit": {
"type": "string",
"description": "Specific commit SHA to check out from the repository",
},
"tag": {
"type": "string",
"description": "Tag to check out from the repository",
},
"paths": {
"type": "array",
"items": {
"type": "string",
"description": "Relative path within the repository to a "
"configuration file to include",
},
"description": "List of relative paths within the repository where "
"configuration files are located",
},
"name": {"type": "string"},
"when": {
"type": "string",
"description": "Include this config only when the condition (as "
"Python code) evaluates to true",
},
"optional": {
"type": "boolean",
"description": "If true, include only if repository is accessible; "
"if false (default), inaccessible repository causes errors",
},
},
"required": ["git", "paths"],
"additionalProperties": False,
},
]
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack include configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
}
- spack.schema.include.schema¶
Full schema with metadata
spack.schema.merged module¶
Schema for configuration merged into one file.
import spack.schema.view
#: Properties for inclusion in other schemas
sections: Dict[str, Any] = {
**spack.schema.bootstrap.properties,
**spack.schema.cdash.properties,
**spack.schema.compilers.properties,
**spack.schema.concretizer.properties,
**spack.schema.config.properties,
**spack.schema.container.properties,
**spack.schema.ci.properties,
**spack.schema.definitions.properties,
**spack.schema.develop.properties,
**spack.schema.env_vars.properties,
**spack.schema.include.properties,
**spack.schema.mirrors.properties,
**spack.schema.modules.properties,
**spack.schema.packages.properties,
**spack.schema.repos.properties,
**spack.schema.toolchains.properties,
**spack.schema.upstreams.properties,
**spack.schema.view.properties,
}
#: Canonical definitions for JSON Schema $ref
defs: Dict[str, Any] = {
# Section schemas, prefixed to avoid collisions with sub-schema definitions
**{f"section_{name}": schema for name, schema in sections.items()},
# Sub-schema definitions hoisted for $ref resolution in env.py
"ci_job_attributes": spack.schema.ci.ci_job_attributes,
"env_modifications": spack.schema.environment.env_modifications,
"module_file_configuration": spack.schema.modules.module_file_configuration,
"projections": spack.schema.projections.projections,
}
#: Properties using $ref pointers into $defs
ref_sections: Dict[str, Any] = {
name: {"$ref": f"#/definitions/section_{name}"} for name in sections
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack merged configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": ref_sections,
"definitions": defs,
}
- spack.schema.merged.schema¶
Full schema with metadata
spack.schema.mirrors module¶
Schema for mirrors.yaml configuration file.
#: Common properties for connection specification
connection = {
"url": {
"type": "string",
"description": "URL pointing to the mirror directory, can be local filesystem "
"(file://) or remote server (http://, https://, s3://, oci://)",
},
"view": {"type": "string"},
"access_pair": {
"type": "object",
"description": "Authentication credentials for accessing private mirrors with ID and "
"secret pairs",
"required": ["secret_variable"],
# Only allow id or id_variable to be set, not both
"oneOf": [{"required": ["id"]}, {"required": ["id_variable"]}],
"properties": {
"id": {
"type": "string",
"description": "Static access ID or username for authentication",
},
"id_variable": {
"type": "string",
"description": "Environment variable name containing the access ID or username",
},
"secret_variable": {
"type": "string",
"description": "Environment variable name containing the secret key, password, "
"or access token",
},
},
},
"profile": {
"type": ["string", "null"],
"description": "AWS profile name to use for S3 mirror authentication",
},
"endpoint_url": {
"type": ["string", "null"],
"description": "Custom endpoint URL for S3-compatible storage services",
},
"access_token_variable": {
"type": ["string", "null"],
"description": "Environment variable containing an access token for OCI registry "
"authentication",
},
}
#: Mirror connection inside pull/push keys
fetch_and_push = {
"description": "Mirror connection configuration for fetching or pushing packages, can be a"
"simple URL string or detailed connection object",
"anyOf": [
{
"type": "string",
"description": "Simple URL string for basic mirror connections without authentication",
},
{
"type": "object",
"description": "Detailed connection configuration with authentication and custom "
"settings",
"additionalProperties": False,
"properties": {**connection},
},
],
}
#: Mirror connection when no pull/push keys are set
mirror_entry = {
"type": "object",
"description": "Mirror configuration entry supporting both source package archives and "
"binary build caches with optional authentication",
"additionalProperties": False,
"anyOf": [{"required": ["url"]}, {"required": ["fetch"]}, {"required": ["pull"]}],
"properties": {
"source": {
"type": "boolean",
"description": "Whether this mirror provides source package archives (tarballs) for "
"building from source",
},
"binary": {
"type": "boolean",
"description": "Whether this mirror provides binary build caches for installing "
"precompiled packages",
},
"signed": {
"type": "boolean",
"description": "Whether to require GPG signature verification for packages from "
"this mirror",
},
"fetch": {
**fetch_and_push,
"description": "Configuration for fetching/downloading packages from this mirror",
},
"push": {
**fetch_and_push,
"description": "Configuration for pushing/uploading packages to this mirror for "
"build cache creation",
},
"autopush": {
"type": "boolean",
"description": "Automatically push packages to this build cache immediately after "
"they are installed locally",
},
**connection,
},
}
#: Properties for inclusion in other schemas
properties: Dict[str, Any] = {
"mirrors": {
"type": "object",
"default": {},
"description": "Configure local and remote mirrors that provide repositories of source "
"tarballs and binary build caches for faster package installation",
"additionalProperties": {
"description": "Named mirror configuration that can be a simple URL string or "
"detailed mirror entry with authentication and build cache settings",
"anyOf": [
{
"type": "string",
"description": "Simple mirror URL for basic source package or build "
"cache access",
},
mirror_entry,
],
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack mirror configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
}
- spack.schema.mirrors.connection¶
Common properties for connection specification
- spack.schema.mirrors.fetch_and_push¶
Mirror connection inside pull/push keys
- spack.schema.mirrors.mirror_entry¶
Mirror connection when no pull/push keys are set
- spack.schema.mirrors.schema¶
Full schema with metadata
spack.schema.modules module¶
Schema for modules.yaml configuration file.
#: Definitions for parts of module schema
array_of_strings = {"type": "array", "default": [], "items": {"type": "string"}}
dependency_selection = {"type": "string", "enum": ["none", "run", "direct", "all"]}
module_file_configuration = {
"type": "object",
"default": {},
"description": "Configuration for individual module file behavior and content customization",
"additionalProperties": False,
"properties": {
"filter": {
"type": "object",
"default": {},
"description": "Filter out specific environment variable modifications from "
"module files",
"additionalProperties": False,
"properties": {
"exclude_env_vars": {
"type": "array",
"default": [],
"items": {"type": "string"},
"description": "List of environment variable names to exclude from module "
"file modifications",
}
},
},
"template": {
"type": "string",
"description": "Path to custom template file for generating module files",
},
"autoload": {
**dependency_selection,
"description": "Automatically load dependency modules when this module is loaded",
},
"prerequisites": {
**dependency_selection,
"description": "Mark dependency modules as prerequisites instead of autoloading them",
},
"conflict": {
**array_of_strings,
"description": "List of modules that conflict with this one and should not be loaded "
"simultaneously",
},
"load": {
**array_of_strings,
"description": "List of additional modules to load when this module is loaded",
},
"suffixes": {
"type": "object",
"description": "Add custom suffixes to module names based on spec matching for better "
"readability",
"additionalKeysAreSpecs": True,
"additionalProperties": {"type": "string"}, # key
},
"environment": spack.schema.environment.ref_env_modifications,
},
}
ref_module_file_configuration = {"$ref": "#/definitions/module_file_configuration"}
projections_scheme = {"$ref": "#/definitions/projections"}
common_props = {
"verbose": {
"type": "boolean",
"default": False,
"description": "Enable verbose output during module file generation",
},
"hash_length": {
"type": "integer",
"minimum": 0,
"default": 7,
"description": "Length of package hash to include in module file names (0-32, shorter "
"hashes may cause naming conflicts)",
},
"include": {
**array_of_strings,
"description": "List of specs to explicitly include for module file generation, even if "
"they would normally be excluded",
},
"exclude": {
**array_of_strings,
"description": "List of specs to exclude from module file generation",
},
"exclude_implicits": {
"type": "boolean",
"default": False,
"description": "Exclude implicit dependencies from module file generation while still "
"allowing autoloading",
},
"defaults": {
**array_of_strings,
"description": "List of specs for which to create default module symlinks when multiple "
"versions exist",
},
"hide_implicits": {
"type": "boolean",
"default": False,
"description": "Hide implicit dependency modules from 'module avail' but still allow "
"autoloading (requires module system support)",
},
"naming_scheme": {
"type": "string",
"description": "Custom naming scheme for module files using format strings",
},
"projections": {
**projections_scheme,
"description": "Custom directory structure and naming convention for module files using "
"projection format",
},
"all": ref_module_file_configuration,
}
tcl_configuration = {
"type": "object",
"default": {},
"description": "Configuration for TCL module files compatible with Environment Modules and "
"Lmod",
"additionalKeysAreSpecs": True,
"properties": {**common_props},
"additionalProperties": ref_module_file_configuration,
}
lmod_configuration = {
"type": "object",
"default": {},
"description": "Configuration for Lua module files compatible with Lmod hierarchical module "
"system",
"additionalKeysAreSpecs": True,
"properties": {
**common_props,
"core_compilers": {
**array_of_strings,
"description": "List of core compilers that are always available at the top level of "
"the Lmod hierarchy",
},
"hierarchy": {
**array_of_strings,
"description": "List of packages to use for building the Lmod module hierarchy "
"(typically compilers and MPI implementations)",
},
"core_specs": {
**array_of_strings,
"description": "List of specs that should be placed in the core level of the Lmod "
"hierarchy regardless of dependencies",
},
"filter_hierarchy_specs": {
"type": "object",
"description": "Filter which specs are included at different levels of the Lmod "
"hierarchy based on spec matching",
"additionalKeysAreSpecs": True,
"additionalProperties": array_of_strings,
},
},
"additionalProperties": ref_module_file_configuration,
}
module_config_properties = {
"use_view": {
"anyOf": [{"type": "string"}, {"type": "boolean"}],
"description": "Generate modules relative to an environment view instead of install "
"tree (True for default view, string for named view, False to disable)",
},
"arch_folder": {
"type": "boolean",
"description": "Whether to include architecture-specific subdirectories in module file "
"paths",
},
"roots": {
"type": "object",
"description": "Custom root directories for different module file types",
"properties": {
"tcl": {"type": "string", "description": "Root directory for TCL module files"},
"lmod": {"type": "string", "description": "Root directory for Lmod module files"},
},
},
"enable": {
"type": "array",
"default": [],
"description": "List of module types to automatically generate during package "
"installation",
"items": {"type": "string", "enum": ["tcl", "lmod"]},
},
"lmod": {
**lmod_configuration,
"description": "Configuration for Lmod hierarchical module system",
},
"tcl": {
**tcl_configuration,
"description": "Configuration for TCL module files compatible with Environment Modules",
},
"prefix_inspections": {
"type": "object",
"description": "Control which package subdirectories are added to environment variables "
"(e.g., bin to PATH, lib to LIBRARY_PATH)",
"additionalProperties": {
# prefix-relative path to be inspected for existence
**array_of_strings,
"description": "List of environment variables to update with this prefix-relative "
"path if it exists",
},
},
}
# Properties for inclusion into other schemas (requires definitions)
properties: Dict[str, Any] = {
"modules": {
"type": "object",
"description": "Configure automatic generation of module files for Environment Modules "
"and Lmod to manage user environments at HPC centers",
"properties": {
"prefix_inspections": {
"type": "object",
"description": "Global prefix inspection settings that apply to all module sets, "
"controlling which subdirectories are added to environment variables",
"additionalProperties": {
# prefix-relative path to be inspected for existence
**array_of_strings,
"description": "List of environment variables to update with this "
"prefix-relative path if it exists",
},
}
},
"additionalProperties": {
"type": "object",
"default": {},
"description": "Named module set configuration (e.g., 'default') defining how module "
"files are generated for a specific set of packages",
"additionalProperties": False,
"properties": module_config_properties,
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack module file configuration file schema",
"type": "object",
"additionalProperties": False,
"definitions": {
"module_file_configuration": module_file_configuration,
"projections": spack.schema.projections.projections,
"env_modifications": spack.schema.environment.env_modifications,
},
"properties": properties,
}
- spack.schema.modules.array_of_strings¶
Definitions for parts of module schema
- spack.schema.modules.schema¶
Full schema with metadata
spack.schema.packages module¶
Schema for packages.yaml configuration files.
from .compilers import extra_rpaths, flags, implicit_rpaths
permissions = {
"type": "object",
"description": "File permissions settings for package installations",
"additionalProperties": False,
"properties": {
"read": {
"type": "string",
"enum": ["user", "group", "world"],
"description": "Who can read the files installed by a package",
},
"write": {
"type": "string",
"enum": ["user", "group", "world"],
"description": "Who can write to the files installed by a package",
},
"group": {
"type": "string",
"description": "The group that owns the files installed by a package",
},
},
}
variants = {
"oneOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}],
"description": "Soft variant preferences as a single spec string or list of variant "
"specifications (ignored if the concretizer can reuse existing installations)",
}
requirements = {
"description": "Package requirements that must be satisfied during concretization",
"oneOf": [
# 'require' can be a list of requirement_groups. each requirement group is a list of one or
# more specs. Either at least one or exactly one spec in the group must be satisfied
# (depending on whether you use "any_of" or "one_of", respectively)
{
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": False,
"properties": {
"one_of": {
"type": "array",
"items": {"type": "string"},
"description": "List of specs where exactly one must be satisfied",
},
"any_of": {
"type": "array",
"items": {"type": "string"},
"description": "List of specs where at least one must be "
"satisfied",
},
"spec": {
"type": "string",
"description": "Single spec requirement that must be satisfied",
},
"message": {
"type": "string",
"description": "Custom error message when requirement is not "
"satisfiable",
},
"when": {
"type": "string",
"description": "Conditional spec that triggers this requirement",
},
},
},
{"type": "string"},
]
},
},
# Shorthand for a single requirement group with one member
{"type": "string"},
],
}
prefer_and_conflict = {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": False,
"properties": {
"spec": {"type": "string", "description": "Spec constraint to apply"},
"message": {
"type": "string",
"description": "Custom message explaining the constraint",
},
"when": {
"type": "string",
"description": "Conditional spec that triggers this constraint",
},
},
},
{"type": "string"},
]
},
}
package_attributes = {
"type": "object",
"description": "Class-level attributes to assign to package instances "
"(accessible in package.py methods)",
"additionalProperties": False,
"patternProperties": {r"^[a-zA-Z_]\w*$": {}},
}
REQUIREMENT_URL = "https://spack.readthedocs.io/en/latest/packages_yaml.html#package-requirements"
#: Properties for inclusion in other schemas
properties: Dict[str, Any] = {
"packages": {
"type": "object",
"description": "Package-specific build settings and external package configurations",
"default": {},
"properties": {
"all": {
"type": "object",
"description": "Default settings that apply to all packages (can be overridden "
"by package-specific settings)",
"default": {},
"additionalProperties": False,
"properties": {
"require": requirements,
"prefer": {
"description": "Strong package preferences that influence concretization "
"without imposing hard constraints",
**prefer_and_conflict,
},
"conflict": {
"description": "Package conflicts that prevent certain spec combinations",
**prefer_and_conflict,
},
# target names
"target": {
"type": "array",
"description": "Ordered list of soft preferences for target "
"architectures for all packages (ignored if the concretizer can reuse "
"existing installations)",
"default": [],
"items": {"type": "string"},
},
# compiler specs
"compiler": {
"type": "array",
"description": "Soft preferences for compiler specs for all packages "
"(deprecated)",
"default": [],
"items": {"type": "string"},
},
"buildable": {
"type": "boolean",
"description": "Whether packages should be built from source (false "
"prevents building)",
"default": True,
},
"permissions": permissions,
# If 'get_full_repo' is promoted to a Package-level
# attribute, it could be useful to set it here
"package_attributes": package_attributes,
"providers": {
"type": "object",
"description": "Soft preferences for providers of virtual packages "
"(ignored if the concretizer can reuse existing installations)",
"default": {},
"additionalProperties": {
"type": "array",
"description": "Ordered list of preferred providers for this virtual "
"package",
"default": [],
"items": {"type": "string"},
},
},
"variants": variants,
},
"deprecatedProperties": [
{
"names": ["compiler"],
"message": "The packages:all:compiler preference has been deprecated in "
"Spack v1.0, and is currently ignored. It will be removed from config in "
"Spack v1.2.",
"error": False,
}
],
}
},
# package names
"additionalProperties": {
"type": "object",
"description": "Package-specific settings that override defaults from 'all'",
"default": {},
"additionalProperties": False,
"properties": {
"require": requirements,
"prefer": {
"description": "Strong package preferences that influence concretization "
"without imposing hard constraints",
**prefer_and_conflict,
},
"conflict": {
"description": "Package conflicts that prevent certain spec combinations",
**prefer_and_conflict,
},
"version": {
"type": "array",
"description": "Ordered list of soft preferences for versions for this "
"package (ignored if the concretizer can reuse existing installations)",
"default": [],
# version strings
"items": {"anyOf": [{"type": "string"}, {"type": "number"}]},
},
"buildable": {
"type": "boolean",
"description": "Whether this package should be built from source (false "
"prevents building)",
"default": True,
},
"permissions": permissions,
# If 'get_full_repo' is promoted to a Package-level
# attribute, it could be useful to set it here
"package_attributes": package_attributes,
"variants": variants,
"externals": {
"type": "array",
"description": "List of external, system-installed instances of this package",
"items": {
"type": "object",
"properties": {
"spec": {
"type": "string",
"description": "Spec string describing this external package "
"instance. Typically name@version and relevant variants",
},
"prefix": {
"type": "string",
"description": "Installation prefix path for this external "
"package (typically /usr, *excluding* bin/, lib/, etc.)",
},
"modules": {
"type": "array",
"description": "Environment modules to load for this external "
"package",
"items": {"type": "string"},
},
"id": {"type": "string"},
"extra_attributes": {
"type": "object",
"description": "Additional information needed by the package "
"to use this external",
"additionalProperties": {"type": "string"},
"properties": {
"compilers": {
"type": "object",
"description": "Compiler executable paths for external "
"compiler packages",
"properties": {
"c": {
"type": "string",
"description": "Path to the C compiler "
"executable (e.g. /usr/bin/gcc)",
},
"cxx": {
"type": "string",
"description": "Path to the C++ compiler "
"executable (e.g. /usr/bin/g++)",
},
"fortran": {
"type": "string",
"description": "Path to the Fortran compiler "
"executable (e.g. /usr/bin/gfortran)",
},
},
"patternProperties": {r"^\w": {"type": "string"}},
"additionalProperties": False,
},
"environment": spack.schema.environment.ref_env_modifications,
"extra_rpaths": extra_rpaths,
"implicit_rpaths": implicit_rpaths,
"flags": flags,
},
},
"dependencies": {
"type": "array",
"description": "List of dependencies for this external package, "
"specifying dependency relationships explicitly",
"items": {
"type": "object",
"description": "Dependency specification for an external "
"package",
"properties": {
"id": {
"type": "string",
"description": "Explicit reference ID to another "
"external package (provides unambiguous reference)",
},
"spec": {
"type": "string",
"description": "Spec string that matches an "
"available external package",
},
"deptypes": {
"oneOf": [
{
"type": "string",
"description": "Single dependency type "
"(e.g., 'build', 'link', 'run', 'test')",
},
{
"type": "array",
"items": {
"type": "string",
"description": "Dependency type (e.g., "
"'build', 'link', 'run', 'test')",
},
"description": "List of dependency types "
"(e.g., ['build', 'link'])",
},
],
"description": "Dependency types; if not specified, "
"inferred from package recipe",
},
"virtuals": {
"type": "string",
"description": "Virtual package name this dependency "
"provides (e.g., 'mpi')",
},
},
},
},
},
"additionalProperties": False,
"required": ["spec"],
},
},
},
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack package configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
"definitions": {"env_modifications": spack.schema.environment.env_modifications},
}
def update(data):
data = data["packages"]
changed = False
for key in data:
version = data[key].get("version")
if not version or all(isinstance(v, str) for v in version):
continue
data[key]["version"] = [str(v) for v in version]
changed = True
return changed
- spack.schema.packages.schema¶
Full schema with metadata
spack.schema.projections module¶
Schema for projections.yaml configuration file.
projections: Dict[str, Any] = {
"type": "object",
"description": "Customize directory structure and naming schemes by mapping specs to "
"format strings.",
"properties": {
"all": {
"type": "string",
"description": "Default projection format string used as fallback for all specs "
"that do not match other entries. Uses spec format syntax like "
'"{name}/{version}/{hash:16}".',
}
},
"additionalKeysAreSpecs": True,
"additionalProperties": {
"type": "string",
"description": "Projection format string for specs matching this key. Uses spec "
"format syntax supporting tokens like {name}, {version}, {compiler.name}, "
"{^dependency.name}, etc.",
},
}
#: $ref pointer for use in merged schema
ref_properties: Dict[str, Any] = {"projections": {"$ref": "#/definitions/projections"}}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack view projection configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": ref_properties,
"definitions": {"projections": projections},
}
- spack.schema.projections.schema¶
Full schema with metadata
spack.schema.repos module¶
Schema for repos.yaml configuration file.
{
# old format: array of strings
"type": "array",
"items": {
"type": "string",
"description": "Path to a Spack package repository directory",
},
"description": "Legacy format: list of local paths to package repository "
"directories",
},
{
# new format: object with named repositories
"type": "object",
"description": "Named repositories mapping configuration names to repository "
"definitions",
"additionalProperties": {
"oneOf": [
{
# local path
"type": "string",
"description": "Path to a local Spack package repository directory "
"containing repo.yaml and packages/",
},
{
# remote git repository
"type": "object",
"properties": {
"git": {
"type": "string",
"description": "Git repository URL for remote package "
"repository",
},
"branch": {
"type": "string",
"description": "Git branch name to checkout (default branch "
"if not specified)",
},
"commit": {
"type": "string",
"description": "Specific git commit hash to pin the "
"repository to",
},
"tag": {
"type": "string",
"description": "Git tag name to pin the repository to",
},
"destination": {
"type": "string",
"description": "Custom local directory path where the Git "
"repository should be cloned",
},
"paths": {
"type": "array",
"items": {"type": "string"},
"description": "List of relative paths (from the Git "
"repository root) that contain Spack package repositories "
"(overrides spack-repo-index.yaml)",
},
},
"additionalProperties": False,
},
]
},
},
],
"default": {},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack repository configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
}
def update(data: Dict[str, Any]) -> bool:
"""Update the repos.yaml configuration data to the new format."""
if not isinstance(data["repos"], list):
return False
from spack.llnl.util import tty
from spack.repo import from_path
# Convert old format [paths...] to new format {namespace: path, ...}
repos = {}
for path in data["repos"]:
try:
repo = from_path(path)
except Exception as e:
tty.warn(f"package repository {path} is disabled due to: {e}")
continue
if repo.namespace is not None:
repos[repo.namespace] = path
data["repos"] = repos
return True
- spack.schema.repos.schema¶
Full schema with metadata
spack.schema.spec module¶
Schema for a spec found in spec descriptor or database index.json files
"oneOf": [
{
"type": "string",
"description": 'Target as a string (e.g. "zen2" or "haswell:broadwell") used in '
"abstract specs",
},
{
"type": "object",
"additionalProperties": False,
"required": ["name", "vendor", "features", "generation", "parents"],
"properties": {
"name": {"type": "string"},
"vendor": {"type": "string"},
"features": {"type": "array", "items": {"type": "string"}},
"generation": {"type": "integer"},
"parents": {"type": "array", "items": {"type": "string"}},
"cpupart": {"type": "string"},
},
"description": "Target as an object with detailed fields, used in concrete specs",
},
],
}
arch = {
"type": "object",
"additionalProperties": False,
"properties": {
"platform": {
"type": ["string", "null"],
"description": 'Target platform (e.g. "linux" or "darwin"). May be null for abstract '
"specs",
},
"platform_os": {
"type": ["string", "null"],
"description": 'Target operating system (e.g. "ubuntu24.04"). May be '
"null for abstract specs",
},
"target": target,
},
}
#: Corresponds to specfile format v1
dependencies_v1 = {
"type": "object",
"description": "Specfile v1 style dependencies specification (package name to dependency "
"info)",
"additionalProperties": {
"type": "object",
"properties": {
"hash": {"type": "string", "description": "Unique identifier of the dependency"},
"type": {
"type": "array",
"items": {"enum": ["build", "link", "run", "test"]},
"description": "Dependency types",
},
},
},
}
#: Corresponds to specfile format v2-v3
dependencies_v2_v3 = {
"type": "array",
"description": "Specfile v2-v3 style dependencies specification (array of dependencies)",
"items": {
"type": "object",
"additionalProperties": False,
"required": ["name", "hash", "type"],
"properties": {
"name": {"type": "string", "description": "Name of the dependency package"},
"hash": {"type": "string", "description": "Unique identifier of the dependency"},
"type": {
"type": "array",
"items": {"enum": ["build", "link", "run", "test"]},
"description": "Dependency types",
},
},
},
}
#: Corresponds to specfile format v4+
dependencies_v4_plus = {
"type": "array",
"description": "Specfile v4+ style dependencies specification (array of dependencies)",
"items": {
"type": "object",
"additionalProperties": False,
"required": ["name", "hash", "parameters"],
"properties": {
"name": {"type": "string", "description": "Name of the dependency package"},
"hash": {"type": "string", "description": "Unique identifier of the dependency"},
"parameters": {
"type": "object",
"additionalProperties": False,
"required": ["deptypes", "virtuals"],
"properties": {
"deptypes": {
"type": "array",
"items": {"enum": ["build", "link", "run", "test"]},
"description": "Dependency types",
},
"virtuals": {
"type": "array",
"items": {"type": "string"},
"description": "Virtual dependencies used by the parent",
},
"direct": {
"type": "boolean",
"description": "Whether the dependency is direct (only on abstract specs)",
},
},
},
},
},
}
dependencies = {"oneOf": [dependencies_v1, dependencies_v2_v3, dependencies_v4_plus]}
build_spec = {
"type": "object",
"additionalProperties": False,
"required": ["name", "hash"],
"properties": {"name": {"type": "string"}, "hash": {"type": "string"}},
"description": "Records the origin spec as it was built (used in splicing)",
}
#: Schema for a single spec node (used in both spec files and database entries)
spec_node = {
"type": "object",
"additionalProperties": False,
"required": ["name"],
"properties": {
"name": {
"type": ["string", "null"],
"description": "Name is a string for concrete specs, but may be null for abstract "
"specs",
},
"hash": {"type": "string", "description": "The DAG hash, which identifies the spec"},
"package_hash": {"type": "string", "description": "The package hash (concrete specs)"},
"full_hash": {
"type": "string",
"description": "This hash was used on some specs prior to 0.18",
},
"build_hash": {
"type": "string",
"description": "This hash was used on some specs prior to 0.18",
},
"version": {"type": "string", "description": "A single, concrete version (e.g. @=1.2)"},
"versions": {
"type": "array",
"items": {"type": "string"},
"description": "Abstract version (e.g. @1.2)",
},
"propagate": {
"type": "array",
"items": {"type": "string"},
"description": "List of variants to propagate (for abstract specs)",
},
"abstract": {
"type": "array",
"items": {"type": "string"},
"description": "List of multi-valued variants that are abstract, i.e. foo=bar,baz "
"instead of foo:=bar,baz (for abstract specs)",
},
"concrete": {
"type": "boolean",
"description": "Whether the spec is concrete or not, when omitted defaults to true",
},
"arch": arch,
"compiler": {
"type": "object",
"additionalProperties": False,
"properties": {"name": {"type": "string"}, "version": {"type": "string"}},
"description": "Compiler name and version (in spec file v5 listed as normal "
"dependencies)",
},
"namespace": {"type": "string", "description": "Package repository namespace"},
"parameters": {
"type": "object",
"additionalProperties": True,
"description": "Variants and other parameters",
"properties": {
"patches": {"type": "array", "items": {"type": "string"}},
"cflags": {"type": "array", "items": {"type": "string"}},
"cppflags": {"type": "array", "items": {"type": "string"}},
"cxxflags": {"type": "array", "items": {"type": "string"}},
"fflags": {"type": "array", "items": {"type": "string"}},
"ldflags": {"type": "array", "items": {"type": "string"}},
"ldlibs": {"type": "array", "items": {"type": "string"}},
},
},
"patches": {
"type": "array",
"items": {"type": "string"},
"description": "List of patches, similar to the patches variant under parameters",
},
"dependencies": dependencies,
"build_spec": build_spec,
"external": {
"type": "object",
"additionalProperties": False,
"description": "If path or module (or both) are set, the spec is an external "
"system-installed package",
"properties": {
"path": {
"type": ["string", "null"],
"description": "Install prefix on the system, e.g. /usr",
},
"module": {
"anyOf": [{"type": "array", "items": {"type": "string"}}, {"type": "null"}],
"description": 'List of module names, e.g. ["pkg/1.2"]',
},
"extra_attributes": {
"type": "object",
"description": "Package.py specific attributes to use the external package, "
"such as paths to compiler executables",
},
},
},
"annotations": {
"type": "object",
"properties": {
"original_specfile_version": {"type": "number"},
"compiler": {"type": "string"},
},
"required": ["original_specfile_version"],
"additionalProperties": False,
"description": "Currently used to preserve compiler information of old specs when "
"upgrading to a newer spec format",
},
},
}
#: Properties for inclusion in other schemas
properties: Dict[str, Any] = {
"spec": {
"type": "object",
"additionalProperties": False,
"required": ["_meta", "nodes"],
"properties": {
"_meta": {
"type": "object",
"properties": {"version": {"type": "number"}},
"description": "Spec schema version metadata, used for parsing spec files",
},
"nodes": {
"type": "array",
"items": spec_node,
"description": "List of spec nodes which, combined with dependencies, induce a "
"DAG",
},
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack spec schema",
"type": "object",
"additionalProperties": False,
"required": ["spec"],
"properties": properties,
}
- spack.schema.spec.dependencies_v1¶
Corresponds to specfile format v1
- spack.schema.spec.dependencies_v2_v3¶
Corresponds to specfile format v2-v3
- spack.schema.spec.dependencies_v4_plus¶
Corresponds to specfile format v4+
- spack.schema.spec.schema¶
Full schema with metadata
- spack.schema.spec.spec_node¶
Schema for a single spec node (used in both spec files and database entries)
spack.schema.spec_list module¶
spack.schema.toolchains module¶
Schema for toolchains.yaml configuration file.
#: Properties for inclusion in other schemas
properties: Dict[str, Any] = {
"toolchains": {
"type": "object",
"default": {},
"description": "Define named compiler sets (toolchains) that group compiler constraints "
"under a single user-defined name for easy reference with specs like %my_toolchain",
"additionalProperties": {
"description": "Named toolchain definition that can be referenced in specs to apply "
"a complex set of compiler choices for C, C++, and Fortran",
"oneOf": [
{
"type": "string",
"description": "Simple toolchain alias containing a spec string directly",
},
{
"type": "array",
"description": "List of conditional compiler constraints and specifications "
"that define the toolchain behavior",
"items": {
"type": "object",
"description": "Individual toolchain entry with a spec constraint and "
"optional condition for when it applies",
"properties": {
"spec": {
"type": "string",
"description": "Spec constraint to apply such as compiler "
"selection (%c=llvm), flags (cflags=-O3), or other virtual "
"dependencies (%mpi=openmpi)",
},
"when": {
"type": "string",
"description": "Condition that determines when this spec "
"constraint is applied, typically checking for language "
"dependencies like %c, %cxx, %fortran, or other virtual packages "
"like %mpi",
},
},
},
},
],
"default": [],
},
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack toolchain configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
}
- spack.schema.toolchains.schema¶
Full schema with metadata
spack.schema.upstreams module¶
- spack.schema.upstreams.schema¶
Full schema with metadata
spack.schema.url_buildcache_manifest module¶
Schema for buildcache entry manifest file
from typing import Any, Dict
properties: Dict[str, Any] = {
"version": {"type": "integer"},
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"contentLength",
"mediaType",
"compression",
"checksumAlgorithm",
"checksum",
],
"properties": {
"contentLength": {"type": "integer"},
"mediaType": {"type": "string"},
"compression": {"type": "string"},
"checksumAlgorithm": {"type": "string"},
"checksum": {"type": "string"},
},
"additionalProperties": True,
},
},
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Buildcache manifest schema",
"type": "object",
"required": ["version", "data"],
"additionalProperties": True,
"properties": properties,
}
- spack.schema.url_buildcache_manifest.schema¶
Full schema with metadata
spack.schema.view module¶
Schema for view
#: Properties for inclusion in other schemas
properties: Dict[str, Any] = {
"view": {
"description": "Environment filesystem view configuration for creating a directory with "
"traditional structure where all files of installed packages are linked",
"anyOf": [
{
"type": "boolean",
"description": "Enable or disable default views. If 'true', the view is "
"generated under .spack-env/view",
},
{"type": "string", "description": "Path where the default view should be created"},
{
"type": "object",
"description": "Advanced view configuration with one or more named view "
"descriptors",
"additionalProperties": {
"description": "Named view descriptor (use 'default' for the view activated "
"with environment)",
"required": ["root"],
"additionalProperties": False,
"properties": {
"root": {
"type": "string",
"description": "Root directory path where the view will be created",
},
"group": {
"oneOf": [
{
"type": "array",
"items": {"type": "string"},
"description": "Groups of specs to include in the view",
},
{
"type": "string",
"description": "Groups of specs to include in the view",
},
]
},
"link": {
"enum": ["roots", "all", "run"],
"description": "Which specs to include: 'all' (environment roots "
"with transitive run+link deps), 'run' (environment roots with "
"transitive run deps), 'roots' (environment roots only)",
},
"link_type": {
"type": "string",
"enum": ["symlink", "hardlink", "copy"],
"description": "How files are linked in the view: 'symlink' "
"(default), 'hardlink', or 'copy'",
},
"link_dirs": {
"type": "boolean",
"description": "Whether to link directories in the view, or only files"
" (default: true, only applicable when link_type is 'symlink')",
"default": True,
},
"select": {
"type": "array",
"items": {"type": "string"},
"description": "List of specs to include in the view "
"(default: select everything)",
},
"exclude": {
"type": "array",
"items": {"type": "string"},
"description": "List of specs to exclude from the view "
"(default: exclude nothing)",
},
**spack.schema.projections.ref_properties,
},
},
},
],
}
}
#: Full schema with metadata
schema = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spack view configuration file schema",
"type": "object",
"additionalProperties": False,
"properties": properties,
"definitions": {"projections": spack.schema.projections.projections},
}
- spack.schema.view.schema¶
Full schema with metadata