spack.environment package

Submodules

spack.environment.environment module

class spack.environment.environment.Environment(path, init_file=None, with_view=None, keep_relative=False)

Bases: object

property active

True if this environment is currently active.

add(user_spec, list_name='specs')

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

Return type

(bool)

add_default_view_to_env(env_mod)

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

Parameters

env_mod (spack.util.environment.EnvironmentModifications) – the environment modifications object that is modified.

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.

Note these hashes exclude build dependencies.

all_specs()

Return all specs, even those a user spec would shadow.

check_views()

Checks if the environments default view can be activated.

clear(re_read=False)

Clear the contents of the environment

Parameters

re_read (bool) – If True, do not clear new_specs nor new_installs values. These values cannot be read from yaml, and need to be maintained when re-reading an existing environment.

concretize(force=False, tests=False, reuse=False)

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 (bool) – re-concretize ALL specs, even those that were already concretized

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

• reuse (bool) – if True try to maximize reuse of already installed specs, if False don’t account for installation status.

Returns

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

concretize_and_add(user_spec, concrete_spec=None, tests=False)

Concretize and add a single spec to the environment.

Concretize the provided user_spec and add it along with the concretized result to the environment. If the given user_spec was already present in the environment, this does not add a duplicate. The concretized spec will be added unless the user_spec was already present and an associated concrete spec was already present.

Parameters

concrete_spec – if provided, then it is assumed that it is the result of concretizing the provided user_spec

concretized_specs()

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

config_scopes()

A list of all configuration scopes for this environment.

property default_view

destroy()

Remove this environment from Spack entirely.

develop(spec, path, clone=False)

Add dev-build info for package

Parameters

• spec (spack.spec.Spec) – Set constraints on development specs. Must include a concrete version.

• path (str) – Path to find code for developer builds. Relative paths will be resolved relative to the environment.

• clone (bool) – Clone the package code to the path. If clone is False Spack will assume the code is already present at path.

Returns

True iff the environment was changed.

Return type

(bool)

env_file_config_scope()

Get the configuration scope for the environment’s manifest file.

env_file_config_scope_name()

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

property env_subdir_path

Path to directory where the env stores repos, logs, views.

included_config_scopes()

List of included configuration scopes from the environment.

Scopes are listed in the YAML file in order from highest to lowest precedence, so configuration from earlier scope will take precedence over later ones.

This routine returns them in the order they should be pushed onto the internal scope stack (so, in reverse, from lowest to highest).

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=None, **install_args)

property internal

Whether this environment is managed by Spack.

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 log_path

property manifest_path

Path to spack.yaml file in this environment.

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.

property name

Human-readable representation of the environment.

This is the path for directory environments, and just the name for named environments.

regenerate_views()

remove(query_spec, list_name='specs', 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 nexg concretize.

property repo

property repos_path

rm_default_view_from_env(env_mod)

Collect the environment modifications to deactivate an environment using the default view. Reverses the action of add_default_view_to_env.

Parameters

env_mod (spack.util.environment.EnvironmentModifications) – the environment modifications object that is modified.

roots()

Specs explicitly requested by the user in this environment.

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

undevelop(spec)

Remove develop info for abstract spec spec.

returns True on success, False if no entry existed.

uninstalled_specs()

Return a list of all uninstalled (and non-dev) specs.

update_default_view(viewpath)

update_stale_references(from_list=None)

Iterate over spec lists updating references.

property user_specs

property view_path_default

write(regenerate=True)

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 (bool) – 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.environment.SpackEnvironmentError(message, long_message=None)

Bases: spack.error.SpackError

Superclass for all errors to do with Spack environments.

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

Bases: spack.environment.environment.SpackEnvironmentError

Class for errors regarding view generation.

class spack.environment.environment.ViewDescriptor(base_path, root, projections={}, select=[], exclude=[], link='all', link_type='symlink')

Bases: object

content_hash(specs)

exclude_fn(spec)

static from_dict(base_path, d)

get_projection_for_spec(spec)

Get projection for spec relative to view root

Getting the projection from the underlying root will get the temporary projection. This gives the permanent projection relative to the root symlink.

regenerate(all_specs, roots)

select_fn(spec)

specs_for_view(all_specs, roots)

to_dict()

view(new=None)

Generate the FilesystemView object for this ViewDescriptor

By default, this method returns a FilesystemView object rooted at the current underlying root of this ViewDescriptor (self._current_root)

Raise if new is None and there is no current view

Parameters

new (str or None) – 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 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()

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 named Environments.

spack.environment.environment.config_dict(yaml_data)

Get the configuration scope section out of an spack.yaml

spack.environment.environment.create(name, init_file=None, with_view=None, keep_relative=False)

Create a named environment in Spack.

spack.environment.environment.deactivate()

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

spack.environment.environment.deactivate_config_scope(env)

Remove any scopes from env from the global config path.

spack.environment.environment.default_manifest_yaml = '# This is a Spack Environment file.\n#\n# It describes a set of packages to be installed, along with\n# configuration settings.\nspack:\n  # add package specs to the `specs` list\n  specs: []\n  view: true\n'

default spack.yaml file to put in new environments

spack.environment.environment.display_specs(concretized_specs)

Displays the list of specs returned by Environment.concretize().

Parameters

concretized_specs (list) – list of specs returned by Environment.concretize()

spack.environment.environment.env_path = '/home/docs/checkouts/readthedocs.org/user_builds/spack/checkouts/v0.17.0/lib/spack/docs/_spack_root/var/spack/environments'

path where environments are stored in the spack tree

spack.environment.environment.env_subdir_name = '.spack-env'

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

spack.environment.environment.exists(name)

Whether an environment with this name exists or not.

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 True if the manifest file is at the latest schema format, False otherwise.

Parameters

manifest (str) – manifest file to be analyzed

spack.environment.environment.lockfile_format_version = 3

version of the lockfile format. Must increase monotonically.

spack.environment.environment.lockfile_name = 'spack.lock'

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 = 'spack.yaml'

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.prepare_config_scope(env)

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

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.spack_env_var = 'SPACK_ENV'

environment variable used to indicate the active environment

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 = '^\\w[\\w-]*$'

regex for validating enviroment names

spack.environment.environment.validate_env_name(name)

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

Returns whether two spack yaml items are equivalent, including overrides

spack.environment.shell module

spack.environment.shell.activate(env, use_env_repo=False, add_view=True)

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 (spack.environment.Environment) – the environment to activate

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

• add_view (bool) – generate commands to add view to path variables

Returns

Environment variables modifications to activate environment.

Return type

spack.util.environment.EnvironmentModifications

spack.environment.shell.activate_header(env, shell, prompt=None)

spack.environment.shell.deactivate()

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.

Return type

spack.util.environment.EnvironmentModifications

spack.environment.shell.deactivate_header(shell)

Module contents

class spack.environment.Environment(path, init_file=None, with_view=None, keep_relative=False)

Bases: object

property active

True if this environment is currently active.

add(user_spec, list_name='specs')

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

Return type

(bool)

add_default_view_to_env(env_mod)

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

Parameters

env_mod (spack.util.environment.EnvironmentModifications) – the environment modifications object that is modified.

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.

Note these hashes exclude build dependencies.

all_specs()

Return all specs, even those a user spec would shadow.

check_views()

Checks if the environments default view can be activated.

clear(re_read=False)

Clear the contents of the environment

Parameters

re_read (bool) – If True, do not clear new_specs nor new_installs values. These values cannot be read from yaml, and need to be maintained when re-reading an existing environment.

concretize(force=False, tests=False, reuse=False)

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 (bool) – re-concretize ALL specs, even those that were already concretized

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

• reuse (bool) – if True try to maximize reuse of already installed specs, if False don’t account for installation status.

Returns

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

concretize_and_add(user_spec, concrete_spec=None, tests=False)

Concretize and add a single spec to the environment.

Concretize the provided user_spec and add it along with the concretized result to the environment. If the given user_spec was already present in the environment, this does not add a duplicate. The concretized spec will be added unless the user_spec was already present and an associated concrete spec was already present.

Parameters

concrete_spec – if provided, then it is assumed that it is the result of concretizing the provided user_spec

concretized_specs()

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

config_scopes()

A list of all configuration scopes for this environment.

property default_view

destroy()

Remove this environment from Spack entirely.

develop(spec, path, clone=False)

Add dev-build info for package

Parameters

• spec (spack.spec.Spec) – Set constraints on development specs. Must include a concrete version.

• path (str) – Path to find code for developer builds. Relative paths will be resolved relative to the environment.

• clone (bool) – Clone the package code to the path. If clone is False Spack will assume the code is already present at path.

Returns

True iff the environment was changed.

Return type

(bool)

env_file_config_scope()

Get the configuration scope for the environment’s manifest file.

env_file_config_scope_name()

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

property env_subdir_path

Path to directory where the env stores repos, logs, views.

included_config_scopes()

List of included configuration scopes from the environment.

Scopes are listed in the YAML file in order from highest to lowest precedence, so configuration from earlier scope will take precedence over later ones.

This routine returns them in the order they should be pushed onto the internal scope stack (so, in reverse, from lowest to highest).

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=None, **install_args)

property internal

Whether this environment is managed by Spack.

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 log_path

property manifest_path

Path to spack.yaml file in this environment.

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.

property name

Human-readable representation of the environment.

This is the path for directory environments, and just the name for named environments.

regenerate_views()

remove(query_spec, list_name='specs', 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 nexg concretize.

property repo

property repos_path

rm_default_view_from_env(env_mod)

Collect the environment modifications to deactivate an environment using the default view. Reverses the action of add_default_view_to_env.

Parameters

env_mod (spack.util.environment.EnvironmentModifications) – the environment modifications object that is modified.

roots()

Specs explicitly requested by the user in this environment.

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

undevelop(spec)

Remove develop info for abstract spec spec.

returns True on success, False if no entry existed.

uninstalled_specs()

Return a list of all uninstalled (and non-dev) specs.

update_default_view(viewpath)

update_stale_references(from_list=None)

Iterate over spec lists updating references.

property user_specs

property view_path_default

write(regenerate=True)

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 (bool) – 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.SpackEnvironmentError(message, long_message=None)

Bases: spack.error.SpackError

Superclass for all errors to do with Spack environments.

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

Activate an environment.

To activate an environment, we add its 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()

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 named Environments.

spack.environment.config_dict(yaml_data)

Get the configuration scope section out of an spack.yaml

spack.environment.create(name, init_file=None, with_view=None, keep_relative=False)

Create a named environment in Spack.

spack.environment.deactivate()

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

spack.environment.display_specs(concretized_specs)

Displays the list of specs returned by Environment.concretize().

Parameters

concretized_specs (list) – list of specs returned by Environment.concretize()

spack.environment.exists(name)

Whether an environment with this name exists or not.

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 True if the manifest file is at the latest schema format, False otherwise.

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