spack.environment package

This package implements Spack environments.

spack.lock format

Spack environments have existed since Spack v0.12.0, and there have been different spack.lock formats since then. The formats are documented here.

The high-level format of a Spack lockfile hasn’t changed much between versions, but the contents have. Lockfiles are JSON-formatted and their top-level sections are:

1. _meta (object): this contains details about the file format, including:

   • file-type: always "spack-lockfile"

   • lockfile-version: an integer representing the lockfile format version

   • specfile-version: an integer representing the spec format version (since v0.17)

2. spack (object): optional, this identifies information about Spack used to concretize the environment:

   • type: required, identifies form Spack version took (e.g., git, release)

   • commit: the commit if the version is from git

   • version: the Spack version

3. roots (list): an ordered list of records representing the roots of the Spack environment. Each has two fields:

   • hash: a Spack spec hash uniquely identifying the concrete root spec

   • spec: a string representation of the abstract spec that was concretized

4. concrete_specs: a dictionary containing the specs in the environment.

5. include_concrete (dictionary): an optional dictionary that includes the roots and concrete specs from the included environments, keyed by the path to that environment

Compatibility

New versions of Spack can (so far) read all old lockfile formats – they are backward-compatible. Old versions cannot read new lockfile formats, and you’ll need to upgrade Spack to use them.

Lockfile version compatibility across Spack versions

Spack version	v1	v2	v3	v4	v5	v6	v7
v0.12:0.14	✅
v0.15:0.16	✅	✅
v0.17	✅	✅	✅
v0.18:	✅	✅	✅	✅
v0.22:v0.23	✅	✅	✅	✅	✅
v1.0:1.1	✅	✅	✅	✅	✅	✅
v1.2:	✅	✅	✅	✅	✅	✅	✅

Version 1

When lockfiles were first created, there was only one hash in Spack: the DAG hash. This DAG hash (we’ll call it the old DAG hash) did not include build dependencies – it only included transitive link and run dependencies.

The spec format at this time was keyed by name. Each spec started with a key for its name, whose value was a dictionary of other spec attributes. The lockfile put these name-keyed specs into dictionaries keyed by their DAG hash, and the spec records did not actually have a “hash” field in the lockfile – you have to associate the hash from the key with the spec record after the fact.

Dependencies in original lockfiles were keyed by "hash", i.e. the old DAG hash.

{
    "_meta": {
        "file-type": "spack-lockfile",
        "lockfile-version": 1
    },
    "roots": [
        {
            "hash": "<old_dag_hash 1>",
            "spec": "<abstract spec 1>"
        },
        {
            "hash": "<old_dag_hash 2>",
            "spec": "<abstract spec 2>"
        }
    ],
    "concrete_specs": {
        "<old_dag_hash 1>": {
            "... <spec dict attributes> ...": { },
            "dependencies": {
                "depname_1": {
                    "hash": "<old_dag_hash for depname_1>",
                    "type": ["build", "link"]
                },
                "depname_2": {
                    "hash": "<old_dag_hash for depname_3>",
                    "type": ["build", "link"]
                }
            },
            "hash": "<old_dag_hash 1>"
        },
        "<old_dag_hash 2>": {
            "... <spec dict attributes> ...": { },
            "dependencies": {
                "depname_3": {
                    "hash": "<old_dag_hash for depname_3>",
                    "type": ["build", "link"]
                },
                "depname_4": {
                    "hash": "<old_dag_hash for depname_4>",
                    "type": ["build", "link"]
                },
            },
            "hash": "<old_dag_hash 2>"
        },
    }
}

Version 2

Version 2 changes one thing: specs in the lockfile are now keyed by build_hash instead of the old dag_hash. Specs have a hash attribute with their real DAG hash, so you can’t go by the dictionary key anymore to identify a spec – you have to read it in and look at "hash". Dependencies are still keyed by old DAG hash.

Even though we key lockfiles by build_hash, specs in Spack were still deployed with the old, coarser DAG hash. This means that in v2 and v3 lockfiles (which are keyed by build hash), there may be multiple versions of the same spec with different build dependencies, which means they will have different build hashes but the same DAG hash. Spack would only have been able to actually install one of these.

{
    "_meta": {
        "file-type": "spack-lockfile",
        "lockfile-version": 2
    },
    "roots": [
        {
            "hash": "<build_hash 1>",
            "spec": "<abstract spec 1>"
        },
        {
            "hash": "<build_hash 2>",
            "spec": "<abstract spec 2>"
        }
    ],
    "concrete_specs": {
        "<build_hash 1>": {
            "... <spec dict attributes> ...": { },
            "dependencies": {
                "depname_1": {
                    "hash": "<old_dag_hash for depname_1>",
                    "type": ["build", "link"]
                },
                "depname_2": {
                    "hash": "<old_dag_hash for depname_3>",
                    "type": ["build", "link"]
                }
            },
            "hash": "<old_dag_hash 1>",
        },
        "<build_hash 2>": {
            "... <spec dict attributes> ...": { },
            "dependencies": {
                "depname_3": {
                    "hash": "<old_dag_hash for depname_3>",
                    "type": ["build", "link"]
                },
                "depname_4": {
                    "hash": "<old_dag_hash for depname_4>",
                    "type": ["build", "link"]
                }
            },
            "hash": "<old_dag_hash 2>"
        }
    }
}

Version 3

Version 3 doesn’t change the top-level lockfile format, but this was when we changed the specfile format. Specs in concrete_specs are now keyed by the build hash, with no inner dictionary keyed by their package name. The package name is in a name field inside each spec dictionary. The dependencies field in the specs is a list instead of a dictionary, and each element of the list is a record with the name, dependency types, and hash of the dependency. Instead of a key called hash, dependencies are keyed by build_hash. Each spec still has a hash attribute.

Version 3 adds the specfile_version field to _meta and uses the new JSON spec format.

{
    "_meta": {
        "file-type": "spack-lockfile",
        "lockfile-version": 3,
        "specfile-version": 2
    },
    "roots": [
        {
            "hash": "<build_hash 1>",
            "spec": "<abstract spec 1>"
        },
        {
            "hash": "<build_hash 2>",
            "spec": "<abstract spec 2>"
        },
    ],
    "concrete_specs": {
        "<build_hash 1>": {
            "... <spec dict attributes> ...": { },
            "dependencies": [
                {
                    "name": "depname_1",
                    "build_hash": "<build_hash for depname_1>",
                    "type": ["build", "link"]
                },
                {
                    "name": "depname_2",
                    "build_hash": "<build_hash for depname_2>",
                    "type": ["build", "link"]
                },
            ],
            "hash": "<old_dag_hash 1>",
        },
        "<build_hash 2>": {
            "... <spec dict attributes> ...": { },
            "dependencies": [
                {
                    "name": "depname_3",
                    "build_hash": "<build_hash for depname_3>",
                    "type": ["build", "link"]
                },
                {
                    "name": "depname_4",
                    "build_hash": "<build_hash for depname_4>",
                    "type": ["build", "link"]
                },
            ],
            "hash": "<old_dag_hash 2>"
        }
    }
}

Version 4

Version 4 removes build hashes and is keyed by the new DAG hash (hash). The hash now includes build dependencies and a canonical hash of the package.py file. Dependencies are keyed by hash (DAG hash) as well. There are no more build_hash fields in the specs, and there are no more issues with lockfiles being able to store multiple specs with the same DAG hash (because the DAG hash is now finer-grained). An optional spack property may be included to track version information, such as the commit or version.

{
    "_meta": {
        "file-type": "spack-lockfile",
        "lockfile-version": 4,
        "specfile-version": 3
    },
    "roots": [
        {
            "hash": "<dag_hash 1>",
            "spec": "<abstract spec 1>"
        },
        {
            "hash": "<dag_hash 2>",
            "spec": "<abstract spec 2>"
        }
    ],
    "concrete_specs": {
        "<dag_hash 1>": {
            "... <spec dict attributes> ...": { },
            "dependencies": [
                {
                    "name": "depname_1",
                    "hash": "<dag_hash for depname_1>",
                    "type": ["build", "link"]
                },
                {
                    "name": "depname_2",
                    "hash": "<dag_hash for depname_2>",
                    "type": ["build", "link"]
                }
            ],
            "hash": "<dag_hash 1>",
        },
        "<daghash 2>": {
            "... <spec dict attributes> ...": { },
            "dependencies": [
                {
                    "name": "depname_3",
                    "hash": "<dag_hash for depname_3>",
                    "type": ["build", "link"]
                },
                {
                    "name": "depname_4",
                    "hash": "<dag_hash for depname_4>",
                    "type": ["build", "link"]
                }
            ],
            "hash": "<dag_hash 2>"
        }
    }
}

Version 5

Version 5 doesn’t change the top-level lockfile format, but an optional dictionary is added. The dictionary has the root and concrete_specs of the included environments, which are keyed by the path to that environment. Since this is optional if the environment does not have any included environments include_concrete will not be a part of the lockfile.

{
    "_meta": {
        "file-type": "spack-lockfile",
        "lockfile-version": 5,
        "specfile-version": 3
    },
    "roots": [
        {
            "hash": "<dag_hash 1>",
            "spec": "<abstract spec 1>"
        },
        {
            "hash": "<dag_hash 2>",
            "spec": "<abstract spec 2>"
        }
    ],
    "concrete_specs": {
        "<dag_hash 1>": {
            "... <spec dict attributes> ...": { },
            "dependencies": [
                {
                    "name": "depname_1",
                    "hash": "<dag_hash for depname_1>",
                    "type": ["build", "link"]
                },
                {
                    "name": "depname_2",
                    "hash": "<dag_hash for depname_2>",
                    "type": ["build", "link"]
                }
            ],
            "hash": "<dag_hash 1>",
        },
        "<daghash 2>": {
            "... <spec dict attributes> ...": { },
            "dependencies": [
                {
                    "name": "depname_3",
                    "hash": "<dag_hash for depname_3>",
                    "type": ["build", "link"]
                },
                {
                    "name": "depname_4",
                    "hash": "<dag_hash for depname_4>",
                    "type": ["build", "link"]
                }
            ],
            "hash": "<dag_hash 2>"
        }
    }
    "include_concrete": {
        "<path to environment>": {
            "roots": [
                {
                    "hash": "<dag_hash 1>",
                    "spec": "<abstract spec 1>"
                },
                {
                    "hash": "<dag_hash 2>",
                    "spec": "<abstract spec 2>"
                }
            ],
            "concrete_specs": {
                "<dag_hash 1>": {
                    "... <spec dict attributes> ...": { },
                    "dependencies": [
                        {
                            "name": "depname_1",
                            "hash": "<dag_hash for depname_1>",
                            "type": ["build", "link"]
                        },
                        {
                            "name": "depname_2",
                            "hash": "<dag_hash for depname_2>",
                            "type": ["build", "link"]
                        }
                    ],
                    "hash": "<dag_hash 1>",
                },
                "<daghash 2>": {
                    "... <spec dict attributes> ...": { },
                    "dependencies": [
                        {
                            "name": "depname_3",
                            "hash": "<dag_hash for depname_3>",
                            "type": ["build", "link"]
                        },
                        {
                            "name": "depname_4",
                            "hash": "<dag_hash for depname_4>",
                            "type": ["build", "link"]
                        }
                    ],
                    "hash": "<dag_hash 2>"
                }
            }
        }
    }
}

Version 6

Version 6 uses specs where compilers are modeled as real dependencies, and not as a node attribute. It doesn’t change the top-level lockfile format.

As part of Spack v1.0, compilers stopped being a node attribute, and became a build-only dependency. Packages may declare a dependency on the c, cxx, or fortran languages, which are now treated as virtuals, and compilers would be providers for one or more of those languages. Compilers can also inject runtime dependency, on the node being compiled. The compiler-wrapper is explicitly represented as a node in the DAG, and enters the hash.

{
  "_meta": {
    "file-type": "spack-lockfile",
    "lockfile-version": 6,
    "specfile-version": 5
  },
  "spack": {
    "version": "1.0.0.dev0",
    "type": "git",
    "commit": "395b34f17417132389a6a8ee4dbf831c4a04f642"
  },
  "roots": [
    {
      "hash": "tivmbe3xjw7oqv4c3jv3v4jw42a7cajq",
      "spec": "zlib-ng"
    }
  ],
  "concrete_specs": {
    "tivmbe3xjw7oqv4c3jv3v4jw42a7cajq": {
      "name": "zlib-ng",
      "version": "2.2.3",
      "<other attributes>": {}
    }
    "dependencies": [
      {
        "name": "compiler-wrapper",
        "hash": "n5lamxu36f4cx4sm7m7gocalctve4mcx",
        "parameters": {
          "deptypes": [
            "build"
          ],
          "virtuals": []
        }
      },
      {
        "name": "gcc",
        "hash": "b375mbpprxze4vxy4ho7aixhuchsime2",
        "parameters": {
          "deptypes": [
            "build"
          ],
          "virtuals": [
            "c",
            "cxx"
          ]
        }
      },
      {
        "<other dependencies>": {}
      }
    ],
    "annotations": {
      "original_specfile_version": 5
    },
  }
}

Version 7

Version 7 adds the additional attribute group to roots.

As part of Spack v1.2 each environment can define multiple groups of specs, and fine-tune their concretization separately. This attribute is needed to associate each root spec with the corresponding group.

{
  "_meta": {
    "file-type": "spack-lockfile",
    "lockfile-version": 7,
    "specfile-version": 5
  },
  "spack": {
    "version": "1.2.0.dev0",
    "type": "git",
    "commit": "94b055476f874f424f20e3c0f33b0f22de29220a"
  },
  "roots": [
    {
      "hash": "o72mlpqvb5xijyqg4iyubpnvd5bfcomb",
      "spec": "hdf5",
      "group": "default"
    }
  ],
  "concrete_specs": {
  }
}

class spack.environment.Environment(manifest_dir: str | Path)

Bases: object

A Spack environment, which bundles together configuration and a list of specs.

property active

True if this environment is currently active.

add(user_spec, list_name=USER_SPECS_KEY) → bool

Add a single user_spec (non-concretized) to the Environment

Returns:

True if the spec was added, False if it was already present and did not need to be added

add_concrete_spec(spec: Spec, concrete: Spec, *, new: bool = True, group: str | None = None)

Called when a new concretized spec is added to the environment.

This ensures that all internal data structures are kept in sync.

Parameters:

• spec – user spec that resulted in the concrete spec

• concrete – spec concretized within this environment

• new – whether to write this spec’s package to the env repo on write()

add_view_to_env(env_mod: EnvironmentModifications, view: str) → EnvironmentModifications

Collect the environment modifications to activate an environment using the provided view. Removes duplicate paths.

Parameters:

• env_mod – the environment modifications object that is modified.

• view – the name of the view to activate.

added_specs()

Specs that are not yet installed.

Yields the user spec for non-concretized specs, and the concrete spec for already concretized but not yet installed specs.

all_hashes()

Return hashes of all specs.

all_matching_specs(*specs: Spec) → List[Spec]

Returns all concretized specs in the environment satisfying any of the input specs

all_specs() → List[Spec]

Returns a list of all concrete specs

all_specs_generator() → Iterable[Spec]

Returns a generator for all concrete specs

apply_develop(specs: List[Spec], paths: List[str] | None = None)

Mutate concrete specs to include dev_path provenance pointing to path.

This will fail if any existing concrete spec for the same package does not satisfy the

given develop spec.

change_existing_spec(change_spec: Spec, list_name: str = USER_SPECS_KEY, match_spec: Spec | None = None, allow_changing_multiple_specs=False)

Find the spec identified by match_spec and change it to change_spec.

Parameters:

• change_spec – defines the spec properties that need to be changed. This will not change attributes of the matched spec unless they conflict with change_spec.

• list_name – identifies the spec list in the environment that should be modified

• match_spec – if set, this identifies the spec that should be changed. If not set, it is assumed we are looking for a spec with the same name as change_spec.

check_views()

Checks if the environments default view can be activated.

clear()

Clear the contents of the environment

clear_concretized_specs() → None

Clears the currently concretized specs

concrete_roots()

Same as concretized_specs, except it returns the list of concrete roots without associated user spec

concretize(*, force: bool | None = None, tests: bool | Sequence[str] = False) → Sequence[Tuple[Spec, Spec]]

Concretize user_specs in this environment.

Only concretizes specs that haven’t been concretized yet unless force is True.

This only modifies the environment in memory. write() will write out a lockfile containing concretized specs.

Parameters:

• force – re-concretize ALL specs, even those that were already concretized; defaults to spack.config.get("concretizer:force")

• tests – False to run no tests, True to test all packages, or a list of package names to run tests for some

Returns:

List of specs that have been concretized. Each entry is a tuple of the user spec and the corresponding concretized spec.

concretized_roots: List[ConcretizedRootInfo]

Information on concretized roots

concretized_specs()

Tuples of (user spec, concrete spec) for all concrete specs.

concretized_specs_by(*, group: str) → Iterable[Tuple[Spec, Spec]]

Generates all the (abstract, concrete) spec pairs for a given group

concretized_specs_from_all_included_environments()

concretized_specs_from_included_environment(included_env: str, *, _seen: Set[Tuple[Spec, str]] | None = None)

config_override_for_group(*, group: str)

deconcretize_by_hash(dag_hash: str) → None

Removes a concrete spec from the environment concretization

deconcretize_by_user_spec(spec: Spec, *, group: str | None = None) → None

Removes a user spec from the environment concretization

Parameters:

• spec – user spec to deconcretize

• group – group of the spec to remove. If not specified, the spec is removed from the default group

property default_view

delete_default_view() → None

Deletes the default view associated with this environment.

destroy()

Remove this environment from Spack entirely.

property dev_specs

ensure_env_directory_exists(dot_env: bool = False) → None

Ensure that the root directory of the environment exists

Parameters:

dot_env – if True also ensures that the <root>/.env directory exists

explicit_roots()

get_by_hash(dag_hash: str) → List[Spec]

get_one_by_hash(dag_hash)

Returns the single spec from the environment which matches the provided hash. Raises an AssertionError if no specs match or if more than one spec matches.

has_groups() → bool

has_view(view_name: str) → bool

include_concrete_envs()

Copy and save the included environments’ specs internally.

included_concrete_env_root_dirs: List[str]

Environment root dirs for concrete (lockfile) included environments

included_concrete_spec_data: Dict[str, Dict[str, List[str]]]

First-level included concretized spec data from/to the lockfile.

included_concretized_roots: Dict[str, List[ConcretizedRootInfo]]

Roots from included environments from the last concretization, keyed by env path

included_specs_by_hash: Dict[str, Dict[str, Spec]]

Concretized specs by hash from the included environments

property included_user_specs: SpecList

Included concrete user (or root) specs from last concretization.

install_all(**install_args)

Install all concretized specs in an environment.

Note: this does not regenerate the views for the environment; that needs to be done separately with a call to write().

Parameters:

install_args (dict) – keyword install arguments

install_specs(specs: List[Spec] | None = None, **install_args)

invalidate_repository_cache()

is_develop(spec)

Returns true when the spec is built from local sources

property lock_path

Path to spack.lock file in this environment.

property manifest_path

Path to spack.yaml file in this environment.

manifest_uptodate_or_warn()

Emits a warning if the manifest file is not up-to-date.

matching_spec(spec)

Given a spec (likely not concretized), find a matching concretized spec in the environment.

The matching spec does not have to be installed in the environment, but must be concrete (specs added with spack add without an intervening spack concretize will not be matched).

If there is a single root spec that matches the provided spec or a single dependency spec that matches the provided spec, then the concretized instance of that spec will be returned.

If multiple root specs match the provided spec, or no root specs match and multiple dependency specs match, then this raises an error and reports all matching specs.

mutate(selectors: List[Spec], mutators: List[Spec], validators: List[Spec] | None = None, msgs: List[str] | None = None)

Mutate concrete specs of an environment

Mutate any spec that matches selector. Invalidate caches on parents of mutated specs. If a validator spec is supplied, throw an error if a selected spec does not satisfy the validator.

regenerate_views()

remove(query_spec, list_name=USER_SPECS_KEY, force=False)

Remove specs from an environment that match a query_spec

removed_specs()

Tuples of (user spec, concrete spec) for all specs that will be removed on next concretize.

property repo

property repos_path

rm_view_from_env(env_mod: EnvironmentModifications, view: str) → EnvironmentModifications

Collect the environment modifications to deactivate an environment using the provided view. Reverses the action of add_view_to_env.

Parameters:

• env_mod – the environment modifications object that is modified.

• view – the name of the view to deactivate.

roots()

Specs explicitly requested by the user in this environment.

Yields both added and installed specs that have user specs in spack.yaml.

property scope_name

Name of the config scope of this environment’s manifest file.

spec_lists: Dict[str, SpecList]

Specs from “spack.yaml”

specs_by_hash: Dict[str, Spec]

Concretized specs by hash

sync_concretized_specs() → None

Removes concrete specs that no longer correlate to a user spec

unify_specs() → None

uninstalled_specs()

Return root specs that are not installed, or are installed, but are development specs themselves or have those among their dependencies.

update_default_view(path_or_bool: str | bool) → None

Updates the path of the default view.

If the argument passed as input is False the default view is deleted, if present. The manifest will have an entry view: false.

If the argument passed as input is True a default view is created, if not already present. The manifest will have an entry view: true. If a default view is already declared, it will be left untouched.

If the argument passed as input is a path a default view pointing to that path is created, if not present already. If a default view is already declared, only its “root” will be changed.

Parameters:

path_or_bool – either True, or False or a path

update_environment_repository() → None

Updates the repository associated with the environment.

update_lockfile() → None

user_spec_with_hash(dag_hash: str) → bool

Returns True if any user spec is associated with a concrete spec with the given hash

property user_specs: SpecList

user_specs_by(*, group: str | None) → SpecList

Returns a dictionary of user specs keyed by their group.

property view_path_default: str

write(regenerate: bool = True) → None

Writes an in-memory environment to its location on disk.

Write out package files for each newly concretized spec. Also regenerate any views associated with the environment and run post-write hooks, if regenerate is True.

Parameters:

regenerate – regenerate views and run post-write hooks as well as writing if True.

write_transaction()

Get a write lock context manager for use in a with block.

exception spack.environment.SpackEnvironmentConfigError(msg, filename)

Bases: SpackEnvironmentError

Class for Spack environment-specific configuration errors.

exception spack.environment.SpackEnvironmentDevelopError(message: str, long_message: str | None = None)

Bases: SpackEnvironmentError

Class for errors in applying develop information to an environment.

exception spack.environment.SpackEnvironmentError(message: str, long_message: str | None = None)

Bases: SpackError

Superclass for all errors to do with Spack environments.

exception spack.environment.SpackEnvironmentViewError(message: str, long_message: str | None = None)

Bases: SpackEnvironmentError

Class for errors regarding view generation.

spack.environment.activate(env, use_env_repo=False)

Activate an environment.

To activate an environment, we add its manifest’s configuration scope to the existing Spack configuration, and we set active to the current environment.

Parameters:

• env (Environment) – the environment to activate

• use_env_repo (bool) – use the packages exactly as they appear in the environment’s repository

spack.environment.active(name)

True if the named environment is active.

spack.environment.active_environment() → Environment | None

Returns the active environment when there is any

spack.environment.all_environment_names()

List the names of environments that currently exist.

spack.environment.all_environments()

Generator for all managed Environments.

spack.environment.as_env_dir(name_or_dir)

Translate an environment name or directory to the environment directory

spack.environment.create(name: str, init_file: str | Path | None = None, with_view: str | Path | bool | None = None, keep_relative: bool = False, include_concrete: List[str] | None = None) → Environment

Create a managed environment in Spack and returns it.

A managed environment is created in a root directory managed by this Spack instance, so that Spack can keep track of them.

Files with suffix .json or .lock are considered lockfiles. Files with any other name are considered manifest files.

Parameters:

• name – name of the managed environment

• init_file – either a lockfile, a manifest file, or None

• with_view – whether a view should be maintained for the environment. If the value is a string, it specifies the path to the view

• keep_relative – if True, develop paths are copied verbatim into the new environment file, otherwise they are made absolute

• include_concrete – concrete environment names/paths to be included

spack.environment.create_in_dir(root: str | Path, init_file: str | Path | None = None, with_view: str | Path | bool | None = None, keep_relative: bool = False, include_concrete: List[str] | None = None) → Environment

Create an environment in the directory passed as input and returns it.

Files with suffix .json or .lock are considered lockfiles. Files with any other name are considered manifest files.

Parameters:

• root – directory where to create the environment.

• init_file – either a lockfile, a manifest file, an env directory, or None

• with_view – whether a view should be maintained for the environment. If the value is a string, it specifies the path to the view

• keep_relative – if True, develop paths are copied verbatim into the new environment file, otherwise they are made absolute

• include_concrete – concrete environment names/paths to be included

spack.environment.deactivate()

Undo any configuration or repo settings modified by activate().

spack.environment.default_manifest_yaml()

default spack.yaml file to put in new environments

spack.environment.display_specs(specs: List[Spec], *, highlight_non_defaults: bool = False) → None

Displays a list of specs traversed breadth-first, covering nodes, with install status.

Parameters:

• specs – list of specs to be displayed

• highlight_non_defaults – if True, highlights non-default versions and variants in the specs being displayed

spack.environment.environment_dir_from_name(name: str, exists_ok: bool = True) → str

Returns the directory associated with a named environment.

Parameters:

• name – name of the environment

• exists_ok – if False, raise an error if the environment exists already

Raises:

SpackEnvironmentError – if exists_ok is False and the environment exists already

spack.environment.environment_from_name_or_dir(name_or_dir)

Get an environment with the supplied name.

spack.environment.environment_path_scope(name: str, path: str) → ConfigScope | None

Retrieve the suitably named environment path scope

Parameters:

• name – configuration scope name

• path – path to configuration file(s)

Returns: list of environment scopes, if any, or None

spack.environment.exists(name)

Whether an environment with this name exists or not.

spack.environment.initialize_environment_dir(environment_dir: str | Path, envfile: str | Path | None) → None

Initialize an environment directory starting from an envfile.

Files with suffix .json or .lock are considered lockfiles. Files with any other name are considered manifest files.

Parameters:

• environment_dir – directory where the environment should be placed

• envfile – manifest file or lockfile used to initialize the environment

Raises:

SpackEnvironmentError – if the directory can’t be initialized

spack.environment.installed_specs()

Returns the specs of packages installed in the active environment or None if no packages are installed.

spack.environment.is_env_dir(path)

Whether a directory contains a spack environment.

spack.environment.is_latest_format(manifest)

Return False if the manifest file exists and is not in the latest schema format.

Parameters:

manifest (str) – manifest file to be analyzed

spack.environment.manifest_file(env_name_or_dir)

Return the absolute path to a manifest file given the environment name or directory.

Parameters:

env_name_or_dir (str) – either the name of a valid environment or a directory where a manifest file resides

Raises:

AssertionError – if the environment is not found

spack.environment.no_active_environment()

Deactivate the active environment for the duration of the context. Has no effect when there is no active environment.

spack.environment.read(name)

Get an environment with the supplied name.

spack.environment.root(name)

Get the root directory for an environment by name.

spack.environment.update_yaml(manifest, backup_file)

Update a manifest file from an old format to the current one.

Parameters:

• manifest (str) – path to a manifest file

• backup_file (str) – file where to copy the original manifest

Returns:

True if the manifest was updated, False otherwise.

Raises:

AssertionError – in case anything goes wrong during the update

Submodules

spack.environment.depfile module

This module contains the traversal logic and models that can be used to generate depfiles from an environment.

class spack.environment.depfile.DepfileNode(target: Spec, prereqs: List[Spec], buildcache: UseBuildCache)

Bases: object

Contains a spec, a subset of its dependencies, and a flag whether it should be buildcache only/never/auto.

class spack.environment.depfile.DepfileSpecVisitor(pkg_buildcache: UseBuildCache, deps_buildcache: UseBuildCache)

Bases: object

This visitor produces an adjacency list of a (reduced) DAG, which is used to generate depfile targets with their prerequisites. Currently it only drops build deps when using buildcache only mode.

Note that the DAG could be reduced even more by dropping build edges of specs installed at the moment the depfile is generated, but that would produce stateful depfiles that would not fail when the database is wiped later.

accept(node)

neighbors(node)

Produce a list of spec to follow from node

class spack.environment.depfile.MakefileModel(env: Environment, roots: List[Spec], adjacency_list: List[DepfileNode], make_prefix: str | None, jobserver: bool)

Bases: object

This class produces all data to render a makefile for specs of an environment.

property empty

static from_env(env: Environment, *, filter_specs: List[Spec] | None = None, pkg_buildcache: UseBuildCache = UseBuildCache.AUTO, dep_buildcache: UseBuildCache = UseBuildCache.AUTO, make_prefix: str | None = None, jobserver: bool = True) → MakefileModel

Produces a MakefileModel from an environment and a list of specs.

Parameters:

• env – the environment to use

• filter_specs – if provided, only these specs will be built from the environment, otherwise the environment roots are used.

• pkg_buildcache – whether to only use the buildcache for top-level specs.

• dep_buildcache – whether to only use the buildcache for non-top-level specs.

• make_prefix – the prefix for the makefile targets

• jobserver – when enabled, make will invoke Spack with jobserver support. For dry-run this should be disabled.

to_dict()

class spack.environment.depfile.MakefileSpec(spec)

Bases: object

Limited interface to spec to help generate targets etc. without introducing unwanted special characters.

safe_format(format_str)

safe_name()

spec_hash()

unsafe_format(format_str)

class spack.environment.depfile.UseBuildCache(*values)

Bases: Enum

AUTO

NEVER

ONLY

static from_string(s: str) → UseBuildCache

spack.environment.environment module

spack.environment.environment.CURRENT_LOCKFILE_VERSION

version of the lockfile format. Must increase monotonically.

class spack.environment.environment.ConcretizedRootInfo(*, root_spec: Spec, root_hash: str, new: bool = False, group: str)

Bases: object

Data on root specs that have been concretized

static from_info_dict(info_dict: Dict[str, str]) → ConcretizedRootInfo

group

hash

new

root

class spack.environment.environment.Environment(manifest_dir: str | Path)

Bases: object

A Spack environment, which bundles together configuration and a list of specs.

property active

True if this environment is currently active.

add(user_spec, list_name=USER_SPECS_KEY) → bool

Add a single user_spec (non-concretized) to the Environment

Returns:

True if the spec was added, False if it was already present and did not need to be added

add_concrete_spec(spec: Spec, concrete: Spec, *, new: bool = True, group: str | None = None)

Called when a new concretized spec is added to the environment.

This ensures that all internal data structures are kept in sync.

Parameters:

• spec – user spec that resulted in the concrete spec

• concrete – spec concretized within this environment

• new – whether to write this spec’s package to the env repo on write()

add_view_to_env(env_mod: EnvironmentModifications, view: str) → EnvironmentModifications

Collect the environment modifications to activate an environment using the provided view. Removes duplicate paths.

Parameters:

• env_mod – the environment modifications object that is modified.

• view – the name of the view to activate.

added_specs()

Specs that are not yet installed.

Yields the user spec for non-concretized specs, and the concrete spec for already concretized but not yet installed specs.

all_hashes()

Return hashes of all specs.

all_matching_specs(*specs: Spec) → List[Spec]

Returns all concretized specs in the environment satisfying any of the input specs

all_specs() → List[Spec]

Returns a list of all concrete specs

all_specs_generator() → Iterable[Spec]

Returns a generator for all concrete specs

apply_develop(specs: List[Spec], paths: List[str] | None = None)

Mutate concrete specs to include dev_path provenance pointing to path.

This will fail if any existing concrete spec for the same package does not satisfy the

given develop spec.

change_existing_spec(change_spec: Spec, list_name: str = USER_SPECS_KEY, match_spec: Spec | None = None, allow_changing_multiple_specs=False)

Find the spec identified by match_spec and change it to change_spec.

Parameters:

• change_spec – defines the spec properties that need to be changed. This will not change attributes of the matched spec unless they conflict with change_spec.

• list_name – identifies the spec list in the environment that should be modified

• match_spec – if set, this identifies the spec that should be changed. If not set, it is assumed we are looking for a spec with the same name as change_spec.

check_views()

Checks if the environments default view can be activated.

clear()

Clear the contents of the environment

clear_concretized_specs() → None

Clears the currently concretized specs

concrete_roots()

Same as concretized_specs, except it returns the list of concrete roots without associated user spec

concretize(*, force: bool | None = None, tests: bool | Sequence[str] = False) → Sequence[Tuple[Spec, Spec]]

Concretize user_specs in this environment.

Only concretizes specs that haven’t been concretized yet unless force is True.

This only modifies the environment in memory. write() will write out a lockfile containing concretized specs.

Parameters:

• force – re-concretize ALL specs, even those that were already concretized; defaults to spack.config.get("concretizer:force")

• tests – False to run no tests, True to test all packages, or a list of package names to run tests for some

Returns:

List of specs that have been concretized. Each entry is a tuple of the user spec and the corresponding concretized spec.

concretized_roots: List[ConcretizedRootInfo]

Information on concretized roots

concretized_specs()

Tuples of (user spec, concrete spec) for all concrete specs.

concretized_specs_by(*, group: str) → Iterable[Tuple[Spec, Spec]]

Generates all the (abstract, concrete) spec pairs for a given group

concretized_specs_from_all_included_environments()

concretized_specs_from_included_environment(included_env: str, *, _seen: Set[Tuple[Spec, str]] | None = None)

config_override_for_group(*, group: str)

deconcretize_by_hash(dag_hash: str) → None

Removes a concrete spec from the environment concretization

deconcretize_by_user_spec(spec: Spec, *, group: str | None = None) → None

Removes a user spec from the environment concretization

Parameters:

• spec – user spec to deconcretize

• group – group of the spec to remove. If not specified, the spec is removed from the default group

property default_view

delete_default_view() → None

Deletes the default view associated with this environment.

destroy()

Remove this environment from Spack entirely.

property dev_specs

ensure_env_directory_exists(dot_env: bool = False) → None

Ensure that the root directory of the environment exists

Parameters:

dot_env – if True also ensures that the <root>/.env directory exists

explicit_roots()

get_by_hash(dag_hash: str) → List[Spec]

get_one_by_hash(dag_hash)

Returns the single spec from the environment which matches the provided hash. Raises an AssertionError if no specs match or if more than one spec matches.

has_groups() → bool

has_view(view_name: str) → bool

include_concrete_envs()

Copy and save the included environments’ specs internally.

included_concrete_env_root_dirs: List[str]

Environment root dirs for concrete (lockfile) included environments

included_concrete_spec_data: Dict[str, Dict[str, List[str]]]

First-level included concretized spec data from/to the lockfile.

included_concretized_roots: Dict[str, List[ConcretizedRootInfo]]

Roots from included environments from the last concretization, keyed by env path

included_specs_by_hash: Dict[str, Dict[str, Spec]]

Concretized specs by hash from the included environments

property included_user_specs: SpecList

Included concrete user (or root) specs from last concretization.

install_all(**install_args)

Install all concretized specs in an environment.

Note: this does not regenerate the views for the environment; that needs to be done separately with a call to write().

Parameters:

install_args (dict) – keyword install arguments

install_specs(specs: List[Spec] | None = None, **install_args)

invalidate_repository_cache()

is_develop(spec)

Returns true when the spec is built from local sources

property lock_path

Path to spack.lock file in this environment.

property manifest_path

Path to spack.yaml file in this environment.

manifest_uptodate_or_warn()

Emits a warning if the manifest file is not up-to-date.

matching_spec(spec)

Given a spec (likely not concretized), find a matching concretized spec in the environment.

The matching spec does not have to be installed in the environment, but must be concrete (specs added with spack add without an intervening spack concretize will not be matched).

If there is a single root spec that matches the provided spec or a single dependency spec that matches the provided spec, then the concretized instance of that spec will be returned.

If multiple root specs match the provided spec, or no root specs match and multiple dependency specs match, then this raises an error and reports all matching specs.

mutate(selectors: List[Spec], mutators: List[Spec], validators: List[Spec] | None = None, msgs: List[str] | None = None)

Mutate concrete specs of an environment

Mutate any spec that matches selector. Invalidate caches on parents of mutated specs. If a validator spec is supplied, throw an error if a selected spec does not satisfy the validator.

regenerate_views()

remove(query_spec, list_name=USER_SPECS_KEY, force=False)

Remove specs from an environment that match a query_spec

removed_specs()

Tuples of (user spec, concrete spec) for all specs that will be removed on next concretize.

property repo

property repos_path

rm_view_from_env(env_mod: EnvironmentModifications, view: str) → EnvironmentModifications

Collect the environment modifications to deactivate an environment using the provided view. Reverses the action of add_view_to_env.

Parameters:

• env_mod – the environment modifications object that is modified.

• view – the name of the view to deactivate.

roots()

Specs explicitly requested by the user in this environment.

Yields both added and installed specs that have user specs in spack.yaml.

property scope_name

Name of the config scope of this environment’s manifest file.

spec_lists: Dict[str, SpecList]

Specs from “spack.yaml”

specs_by_hash: Dict[str, Spec]

Concretized specs by hash

sync_concretized_specs() → None

Removes concrete specs that no longer correlate to a user spec

unify_specs() → None

uninstalled_specs()

Return root specs that are not installed, or are installed, but are development specs themselves or have those among their dependencies.

update_default_view(path_or_bool: str | bool) → None

Updates the path of the default view.

If the argument passed as input is False the default view is deleted, if present. The manifest will have an entry view: false.

If the argument passed as input is True a default view is created, if not already present. The manifest will have an entry view: true. If a default view is already declared, it will be left untouched.

If the argument passed as input is a path a default view pointing to that path is created, if not present already. If a default view is already declared, only its “root” will be changed.

Parameters:

path_or_bool – either True, or False or a path

update_environment_repository() → None

Updates the repository associated with the environment.

update_lockfile() → None

user_spec_with_hash(dag_hash: str) → bool

Returns True if any user spec is associated with a concrete spec with the given hash

property user_specs: SpecList

user_specs_by(*, group: str | None) → SpecList

Returns a dictionary of user specs keyed by their group.

property view_path_default: str

views: Dict[str, ViewDescriptor]

write(regenerate: bool = True) → None

Writes an in-memory environment to its location on disk.

Write out package files for each newly concretized spec. Also regenerate any views associated with the environment and run post-write hooks, if regenerate is True.

Parameters:

regenerate – regenerate views and run post-write hooks as well as writing if True.

write_transaction()

Get a write lock context manager for use in a with block.

class spack.environment.environment.EnvironmentConcretizer(env: Environment)

Bases: object

concretize(*, force: bool | None = None, tests: bool | Sequence[str] = False) → List[Tuple[Spec, Spec]]

class spack.environment.environment.EnvironmentManifestFile(manifest_dir: Path | str, name: str | None = None)

Bases: Mapping

Manages the in-memory representation of a manifest file, and its synchronization with the actual manifest on disk.

add_definition(user_spec: str, list_name: str) → None

Appends a user spec to the first active definition matching the name passed as argument.

Parameters:

• user_spec – user spec to be appended

• list_name – name of the definition where to append

Raises:

SpackEnvironmentError – is no valid definition exists already

add_user_spec(user_spec: str, *, group: str | None = None) → None

Appends the user spec passed as input to the list of root specs for the given group.

Parameters:

• user_spec – user spec to be appended

• group – group where the spec should be added. If None, the default group is used.

clear() → None

Clear all user specs from the list of root specs

config_override(*, group: str | None = None) → InternalConfigScope | None

property configuration

Return the dictionaries in the pristine YAML, without the top level attribute

deactivate_config_scope() → None

Remove the manifest’s scope from the global config path.

property env_config_scope: ConfigScope

The configuration scope for the environment manifest

flush() → None

Synchronizes the object with the manifest file on disk.

static from_lockfile(manifest_dir: Path | str) → EnvironmentManifestFile

Returns an environment manifest file compatible with the lockfile already present in the environment directory.

This function also writes a spack.yaml file that is consistent with the spack.lock already existing in the directory.

Parameters:

manifest_dir – directory containing the manifest and lockfile

groups() → KeysView

Returns the list of groups defined in the manifest

is_explicit(*, group: str | None = None) → bool

Returns whether specs in a group are marked explicit.

When False, specs in the group are installed as implicit dependencies and are eligible for garbage collection once no other spec depends on them.

needs(*, group: str | None = None) → Tuple[str, ...]

Returns the dependencies of a group of user specs.

override_definition(user_spec: str, *, override: str, list_name: str) → None

Overrides a user spec from an active definition that matches the name passed as argument.

Parameters:

• user_spec – user spec to be overridden

• override – new spec to be used

• list_name – name of the definition where to override the spec

Raises:

SpackEnvironmentError – if the user spec cannot be overridden

override_user_spec(user_spec: str, idx: int) → None

Overrides the user spec at index idx with the one passed as input.

Parameters:

• user_spec – new user spec

• idx – index of the spec to be overridden

Raises:

SpackEnvironmentError – when the user spec cannot be overridden

prepare_config_scope() → None

Add the manifest’s scope to the global configuration search path.

remove_default_view() → None

Removes the default view from the manifest file

remove_definition(user_spec: str, list_name: str) → None

Removes a user spec from an active definition that matches the name passed as argument.

Parameters:

• user_spec – user spec to be removed

• list_name – name of the definition where to remove the spec from

Raises:

SpackEnvironmentError – if the user spec cannot be removed from the list, or the list does not exist

remove_user_spec(user_spec: str) → None

Removes the user spec passed as input from the default list of root specs

Parameters:

user_spec – user spec to be removed

Raises:

SpackEnvironmentError – when the user spec is not in the list

set_default_view(view: bool | str | Path | Dict[str, str]) → None

Sets the default view root in the manifest to the value passed as input.

Parameters:

view – If the value is a string or a path, it specifies the path to the view. If True the default view is used for the environment, if False there’s no view.

set_include_concrete(include_concrete: List[str]) → None

Sets the included concrete environments in the manifest to the value(s) passed as input.

Parameters:

include_concrete – list of already existing concrete environments to include

use_config()

Ensure only the manifest’s configuration scopes are global.

user_specs(*, group: str | None = None) → List

class spack.environment.environment.ReusableSpecsFactory(*, env: Environment, group: str)

Bases: object

Creates a list of SpecFilters to generate the reusable specs for the environment

exception spack.environment.environment.SpackEnvironmentConfigError(msg, filename)

Bases: SpackEnvironmentError

Class for Spack environment-specific configuration errors.

exception spack.environment.environment.SpackEnvironmentDevelopError(message: str, long_message: str | None = None)

Bases: SpackEnvironmentError

Class for errors in applying develop information to an environment.

exception spack.environment.environment.SpackEnvironmentError(message: str, long_message: str | None = None)

Bases: SpackError

Superclass for all errors to do with Spack environments.

exception spack.environment.environment.SpackEnvironmentViewError(message: str, long_message: str | None = None)

Bases: SpackEnvironmentError

Class for errors regarding view generation.

class spack.environment.environment.ViewDescriptor(base_path: str, root: str, *, projections: Dict[str, str] | None = None, select: List[str] | None = None, exclude: List[str] | None = None, link: str = default_view_link, link_type: Literal['hardlink', 'hard', 'copy', 'relocate', 'add', 'symlink', 'soft'] = 'symlink', link_dirs: bool = True, groups: str | List[str] | None = None)

Bases: object

content_hash(specs)

exclude_fn(spec: Spec) → bool

static from_dict(base_path: str, d) → ViewDescriptor

get_projection_for_spec(spec)

Get projection for spec. This function does not require the view to exist on the filesystem.

groups: List[str] | None

link_dirs: bool

link_type: Literal['hardlink', 'hard', 'copy', 'relocate', 'add', 'symlink', 'soft']

regenerate(env: Environment) → None

select_fn(spec: Spec) → bool

specs_for_view(concrete_roots: List[Spec]) → List[Spec]

Flatten the DAGs of the concrete roots, keep only unique, selected, and installed specs in topological order from root to leaf.

to_dict()

update_root(new_path: str) → None

view(new: str | None = None) → SimpleFilesystemView

Returns a view object for the underlying view directory. This means that the self.root symlink is followed, and that the view has to exist on the filesystem (unless new). This function is useful when writing to the view.

Raise if new is None and there is no current view

Parameters:

new – If a string, create a FilesystemView rooted at that path. Default None. This should only be used to regenerate the view, and cannot be used to access specs.

spack.environment.environment.activate(env, use_env_repo=False)

Activate an environment.

To activate an environment, we add its manifest’s configuration scope to the existing Spack configuration, and we set active to the current environment.

Parameters:

• env (Environment) – the environment to activate

• use_env_repo (bool) – use the packages exactly as they appear in the environment’s repository

spack.environment.environment.active(name)

True if the named environment is active.

spack.environment.environment.active_environment() → Environment | None

Returns the active environment when there is any

spack.environment.environment.all_environment_names()

List the names of environments that currently exist.

spack.environment.environment.all_environments()

Generator for all managed Environments.

spack.environment.environment.as_env_dir(name_or_dir)

Translate an environment name or directory to the environment directory

spack.environment.environment.create(name: str, init_file: str | Path | None = None, with_view: str | Path | bool | None = None, keep_relative: bool = False, include_concrete: List[str] | None = None) → Environment

Create a managed environment in Spack and returns it.

A managed environment is created in a root directory managed by this Spack instance, so that Spack can keep track of them.

Files with suffix .json or .lock are considered lockfiles. Files with any other name are considered manifest files.

Parameters:

• name – name of the managed environment

• init_file – either a lockfile, a manifest file, or None

• with_view – whether a view should be maintained for the environment. If the value is a string, it specifies the path to the view

• keep_relative – if True, develop paths are copied verbatim into the new environment file, otherwise they are made absolute

• include_concrete – concrete environment names/paths to be included

spack.environment.environment.create_in_dir(root: str | Path, init_file: str | Path | None = None, with_view: str | Path | bool | None = None, keep_relative: bool = False, include_concrete: List[str] | None = None) → Environment

Create an environment in the directory passed as input and returns it.

Files with suffix .json or .lock are considered lockfiles. Files with any other name are considered manifest files.

Parameters:

• root – directory where to create the environment.

• init_file – either a lockfile, a manifest file, an env directory, or None

• with_view – whether a view should be maintained for the environment. If the value is a string, it specifies the path to the view

• keep_relative – if True, develop paths are copied verbatim into the new environment file, otherwise they are made absolute

• include_concrete – concrete environment names/paths to be included

spack.environment.environment.deactivate()

Undo any configuration or repo settings modified by activate().

spack.environment.environment.default_env_path

default path where environments are stored in the spack tree

spack.environment.environment.default_manifest_yaml()

default spack.yaml file to put in new environments

spack.environment.environment.display_specs(specs: List[Spec], *, highlight_non_defaults: bool = False) → None

Displays a list of specs traversed breadth-first, covering nodes, with install status.

Parameters:

• specs – list of specs to be displayed

• highlight_non_defaults – if True, highlights non-default versions and variants in the specs being displayed

spack.environment.environment.ensure_env_root_path_exists()

spack.environment.environment.ensure_no_disallowed_env_config_mods(scope: ConfigScope) → None

spack.environment.environment.env_root_path() → str

Override default root path if the user specified it

spack.environment.environment.env_subdir_name

Name of the directory where environments store repos, logs, views, configs

spack.environment.environment.env_subdir_path(manifest_dir: str | Path) → str

Path to where the environment stores repos, logs, views, configs.

Parameters:

manifest_dir – directory containing the environment manifest file

Returns: directory the environment uses to manage its files

spack.environment.environment.environment_dir_from_name(name: str, exists_ok: bool = True) → str

Returns the directory associated with a named environment.

Parameters:

• name – name of the environment

• exists_ok – if False, raise an error if the environment exists already

Raises:

SpackEnvironmentError – if exists_ok is False and the environment exists already

spack.environment.environment.environment_from_name_or_dir(name_or_dir)

Get an environment with the supplied name.

spack.environment.environment.environment_name(path: str | Path) → str

Human-readable representation of the environment.

This is the path for independent environments, and just the name for managed environments.

spack.environment.environment.environment_path_scope(name: str, path: str) → ConfigScope | None

Retrieve the suitably named environment path scope

Parameters:

• name – configuration scope name

• path – path to configuration file(s)

Returns: list of environment scopes, if any, or None

spack.environment.environment.exists(name)

Whether an environment with this name exists or not.

spack.environment.environment.initialize_environment_dir(environment_dir: str | Path, envfile: str | Path | None) → None

Initialize an environment directory starting from an envfile.

Files with suffix .json or .lock are considered lockfiles. Files with any other name are considered manifest files.

Parameters:

• environment_dir – directory where the environment should be placed

• envfile – manifest file or lockfile used to initialize the environment

Raises:

SpackEnvironmentError – if the directory can’t be initialized

spack.environment.environment.installed_specs()

Returns the specs of packages installed in the active environment or None if no packages are installed.

spack.environment.environment.is_env_dir(path)

Whether a directory contains a spack environment.

spack.environment.environment.is_latest_format(manifest)

Return False if the manifest file exists and is not in the latest schema format.

Parameters:

manifest (str) – manifest file to be analyzed

spack.environment.environment.lockfile_name

Name of the input yaml file for an environment

spack.environment.environment.make_repo_path(root)

Make a RepoPath from the repo subdirectories in an environment.

spack.environment.environment.manifest_file(env_name_or_dir)

Return the absolute path to a manifest file given the environment name or directory.

Parameters:

env_name_or_dir (str) – either the name of a valid environment or a directory where a manifest file resides

Raises:

AssertionError – if the environment is not found

spack.environment.environment.manifest_name

Name of the input yaml file for an environment

spack.environment.environment.no_active_environment()

Deactivate the active environment for the duration of the context. Has no effect when there is no active environment.

spack.environment.environment.read(name)

Get an environment with the supplied name.

spack.environment.environment.root(name)

Get the root directory for an environment by name.

spack.environment.environment.set_included_envs_to_env_paths(include_concrete: List[str]) → None

If the included environment(s) is the environment name it is replaced by the path to the environment

Parameters:

include_concrete – list of env name or path to env

spack.environment.environment.spack_env_var

environment variable used to indicate the active environment

spack.environment.environment.spack_env_view_var

environment variable used to indicate the active environment view

spack.environment.environment.update_yaml(manifest, backup_file)

Update a manifest file from an old format to the current one.

Parameters:

• manifest (str) – path to a manifest file

• backup_file (str) – file where to copy the original manifest

Returns:

True if the manifest was updated, False otherwise.

Raises:

AssertionError – in case anything goes wrong during the update

spack.environment.environment.valid_env_name(name)

spack.environment.environment.valid_environment_name_re

regex for validating environment names

spack.environment.environment.validate_env_name(name)

spack.environment.environment.validate_included_envs_concrete(include_concrete: List[str]) → None

Checks that all of the included environments are concrete

Parameters:

include_concrete – list of already existing concrete environments to include

Raises:

SpackEnvironmentError – if any of the included environments are not concrete

spack.environment.environment.validate_included_envs_exists(include_concrete: List[str]) → None

Checks that all of the included environments exist

Parameters:

include_concrete – list of already existing concrete environments to include

Raises:

SpackEnvironmentError – if any of the included environments do not exist

spack.environment.environment.yaml_equivalent(first, second) → bool

Returns whether two spack yaml items are equivalent, including overrides

spack.environment.list module

class spack.environment.list.Definition(name, yaml_list, when)

Bases: NamedTuple

name: str

Alias for field number 0

when: str | None

Alias for field number 2

yaml_list: List[str | Dict]

Alias for field number 1

exception spack.environment.list.InvalidSpecConstraintError(message: str, long_message: str | None = None)

Bases: SpecListError

Error class for invalid spec constraints at concretize time.

class spack.environment.list.SpecList(*, name: str = 'specs', yaml_list=None, expanded_list=None, toolchains=None)

Bases: object

add(spec: Spec)

extend(other: SpecList, copy_reference=True) → None

property is_matrix

remove(spec)

property specs: List[Spec]

property specs_as_constraints

exception spack.environment.list.SpecListError(message: str, long_message: str | None = None)

Bases: SpackError

Error class for all errors related to SpecList objects.

class spack.environment.list.SpecListParser(*, toolchains=None)

Bases: object

Parse definitions and user specs from data in environments

definitions: Dict[str, SpecList]

parse_definitions(*, data: List[Dict[str, Any]]) → Dict[str, SpecList]

parse_user_specs(*, name, yaml_list) → SpecList

exception spack.environment.list.UndefinedReferenceError(message: str, long_message: str | None = None)

Bases: SpecListError

Error class for undefined references in Spack stacks.

spack.environment.shell module

spack.environment.shell.activate(env: Environment, use_env_repo=False, view: str | None = 'default') → EnvironmentModifications

Activate an environment and append environment modifications

To activate an environment, we add its configuration scope to the existing Spack configuration, and we set active to the current environment.

Parameters:

• env – the environment to activate

• use_env_repo – use the packages exactly as they appear in the environment’s repository

• view – generate commands to add runtime environment variables for named view

Returns:

Environment variables modifications to activate environment.

Return type:

spack.util.environment.EnvironmentModifications

spack.environment.shell.activate_header(env, shell, prompt=None, view: str | None = None)

spack.environment.shell.deactivate() → EnvironmentModifications

Deactivate an environment and collect corresponding environment modifications.

Note: unloads the environment in its current state, not in the state it was

loaded in, meaning that specs that were removed from the spack environment after activation are not unloaded.

Returns:

Environment variables modifications to activate environment.

spack.environment.shell.deactivate_header(shell)