spack package

Subpackages

Submodules

spack.abi module

class spack.abi.ABI

Bases: object

This class provides methods to test ABI compatibility between specs. The current implementation is rather rough and could be improved.

architecture_compatible(parent, child)

Return true if parent and child have ABI compatible targets.

compatible(parent, child, **kwargs)

Returns true iff a parent and child spec are ABI compatible

compiler_compatible(parent, child, **kwargs)

Return true if compilers for parent and child are ABI compatible.

spack.architecture module

This module contains all the elements that are required to create an architecture object. These include, the target processor, the operating system, and the architecture platform (i.e. cray, darwin, linux, bgq, etc) classes.

On a multiple architecture machine, the architecture spec field can be set to build a package against any target and operating system that is present on the platform. On Cray platforms or any other architecture that has different front and back end environments, the operating system will determine the method of compiler detection.

There are two different types of compiler detection:
  1. Through the $PATH env variable (front-end detection)
  2. Through the tcl module system. (back-end detection)

Depending on which operating system is specified, the compiler will be detected using one of those methods.

For platforms such as linux and darwin, the operating system is autodetected and the target is set to be x86_64.

The command line syntax for specifying an architecture is as follows:

target=<Target name> os=<OperatingSystem name>

If the user wishes to use the defaults, either target or os can be left out of the command line and Spack will concretize using the default. These defaults are set in the ‘platforms/’ directory which contains the different subclasses for platforms. If the machine has multiple architectures, the user can also enter front-end, or fe or back-end or be. These settings will concretize to their respective front-end and back-end targets and operating systems. Additional platforms can be added by creating a subclass of Platform and adding it inside the platform directory.

Platforms are an abstract class that are extended by subclasses. If the user wants to add a new type of platform (such as cray_xe), they can create a subclass and set all the class attributes such as priority, front_target, back_target, front_os, back_os. Platforms also contain a priority class attribute. A lower number signifies higher priority. These numbers are arbitrarily set and can be changed though often there isn’t much need unless a new platform is added and the user wants that to be detected first.

Targets are created inside the platform subclasses. Most architecture (like linux, and darwin) will have only one target (x86_64) but in the case of Cray machines, there is both a frontend and backend processor. The user can specify which targets are present on front-end and back-end architecture

Depending on the platform, operating systems are either auto-detected or are set. The user can set the front-end and back-end operating setting by the class attributes front_os and back_os. The operating system as described earlier, will be responsible for compiler detection.

class spack.architecture.Arch(plat=None, os=None, target=None)

Bases: object

Architecture is now a class to help with setting attributes.

TODO: refactor so that we don’t need this class.

concrete
static from_dict(d)
to_dict()
exception spack.architecture.NoPlatformError

Bases: spack.error.SpackError

class spack.architecture.OperatingSystem(name, version)

Bases: object

Operating System will be like a class similar to platform extended by subclasses for the specifics. Operating System will contain the compiler finding logic. Instead of calling two separate methods to find compilers we call find_compilers method for each operating system

find_compiler(cmp_cls, *path)

Try to find the given type of compiler in the user’s environment. For each set of compilers found, this returns compiler objects with the cc, cxx, f77, fc paths and the version filled in.

This will search for compilers with the names in cc_names, cxx_names, etc. and it will group them if they have common prefixes, suffixes, and versions. e.g., gcc-mp-4.7 would be grouped with g++-mp-4.7 and gfortran-mp-4.7.

find_compilers(*paths)

Return a list of compilers found in the suppied paths. This invokes the find() method for each Compiler class, and appends the compilers detected to a list.

to_dict()
class spack.architecture.Platform(name)

Bases: object

Abstract class that each type of Platform will subclass. Will return a instance of it once it is returned.

add_operating_system(name, os_class)

Add the operating_system class object into the platform.operating_sys dictionary

add_target(name, target)

Used by the platform specific subclass to list available targets. Raises an error if the platform specifies a name that is reserved by spack as an alias.

back_end = None
back_os = None
default = None
default_os = None
classmethod detect()

Subclass is responsible for implementing this method. Returns True if the Platform class detects that it is the current platform and False if it’s not.

front_end = None
front_os = None
operating_system(name)
priority = None
reserved_oss = ['default_os', 'frontend', 'fe', 'backend', 'be']
reserved_targets = ['default_target', 'frontend', 'fe', 'backend', 'be']
classmethod setup_platform_environment(pkg, env)

Subclass can override this method if it requires any platform-specific build environment modifications.

target(name)

This is a getter method for the target dictionary that handles defaulting based on the values provided by default, front-end, and back-end. This can be overwritten by a subclass for which we want to provide further aliasing options.

class spack.architecture.Target(name, module_name=None)

Bases: object

Target is the processor of the host machine. The host machine may have different front-end and back-end targets, especially if it is a Cray machine. The target will have a name and also the module_name (e.g craype-compiler). Targets will also recognize which platform they came from using the set_platform method. Targets will have compiler finding strategies

spack.architecture.arch_for_spec(arch_spec)

Transforms the given architecture spec into an architecture objct.

spack.architecture.get_platform(platform_name)

Returns a platform object that corresponds to the given name.

spack.architecture.verify_platform(platform_name)

Determines whether or not the platform with the given name is supported in Spack. For more information, see the ‘spack.platforms’ submodule.

spack.build_environment module

This module contains all routines related to setting up the package build environment. All of this is set up by package.py just before install() is called.

There are two parts to the build environment:

  1. Python build environment (i.e. install() method)

    This is how things are set up when install() is called. Spack takes advantage of each package being in its own module by adding a bunch of command-like functions (like configure(), make(), etc.) in the package’s module scope. Ths allows package writers to call them all directly in Package.install() without writing ‘self.’ everywhere. No, this isn’t Pythonic. Yes, it makes the code more readable and more like the shell script from which someone is likely porting.

  2. Build execution environment

    This is the set of environment variables, like PATH, CC, CXX, etc. that control the build. There are also a number of environment variables used to pass information (like RPATHs and other information about dependencies) to Spack’s compiler wrappers. All of these env vars are also set up here.

Skimming this module is a nice way to get acquainted with the types of calls you can make from within the install() function.

exception spack.build_environment.ChildError(msg, traceback_string, build_log, package_context)

Bases: spack.error.SpackError

Special exception class for wrapping exceptions from child processes
in Spack’s build environment.

The main features of a ChildError are:

  1. They’re serializable, so when a child build fails, we can send one of these to the parent and let the parent report what happened.
  2. They have a traceback field containing a traceback generated on the child immediately after failure. Spack will print this on failure in lieu of trying to run sys.excepthook on the parent process, so users will see the correct stack trace from a child.
  3. They also contain package_context, which shows source code context in the Package implementation where the error happened. To get this, Spack searches the stack trace for the deepest frame where self is in scope and is an instance of PackageBase. This will generally find a useful spot in the package.py file.

The long_message of a ChildError displays all this stuff to the user, and SpackError handles displaying the special traceback if we’re in debug mode with spack -d.

long_message
exception spack.build_environment.InstallError(message, long_message=None)

Bases: spack.error.SpackError

Raised by packages when a package fails to install

class spack.build_environment.MakeExecutable(name, jobs)

Bases: spack.util.executable.Executable

Special callable executable object for make so the user can specify parallel or not on a per-invocation basis. Using ‘parallel’ as a kwarg will override whatever the package’s global setting is, so you can either default to true or false and override particular calls.

Note that if the SPACK_NO_PARALLEL_MAKE env var is set it overrides everything.

spack.build_environment.fork(pkg, function, dirty=False)

Fork a child process to do part of a spack build.

Parameters:
  • pkg – pkg whose environemnt we should set up the forked process for.
  • function – arg-less function to run in the child process.
  • dirty – If True, do NOT clean the environment before building.

Usage:

def child_fun():
    # do stuff
build_env.fork(pkg, child_fun)

Forked processes are run with the build environment set up by spack.build_environment. This allows package authors to have full control over the environment, etc. without affecting other builds that might be executed in the same spack call.

If something goes wrong, the child process is expected to print the error and the parent process will exit with error as well. If things go well, the child exits and the parent carries on.

spack.build_environment.get_package_context(traceback)

Return some context for an error message when the build fails.

Args: traceback – A traceback from some exception raised during install.

This function inspects the stack to find where we failed in the package file, and it adds detailed context to the long_message from there.

spack.build_environment.get_path_from_module(mod)

Inspects a TCL module for entries that indicate the absolute path at which the library supported by said module can be found.

spack.build_environment.get_rpath_deps(pkg)

Return immediate or transitive RPATHs depending on the package.

spack.build_environment.get_rpaths(pkg)

Get a list of all the rpaths for a package.

spack.build_environment.get_std_cmake_args(cmake_pkg)
spack.build_environment.load_external_modules(pkg)

traverse the spec list and find any specs that have external modules.

spack.build_environment.load_module(mod)

Takes a module name and removes modules until it is possible to load that module. It then loads the provided module. Depends on the modulecmd implementation of modules used in cray and lmod.

spack.build_environment.parent_class_modules(cls)

Get list of super class modules that are all descend from spack.Package

spack.build_environment.set_build_environment_variables(pkg, env, dirty=False)

This ensures a clean install environment when we build packages.

Arguments: dirty – skip unsetting the user’s environment settings.

spack.build_environment.set_compiler_environment_variables(pkg, env)
spack.build_environment.set_module_variables_for_package(pkg, module)

Populate the module scope of install() with some useful functions. This makes things easier for package writers.

spack.build_environment.setup_package(pkg, dirty=False)

Execute all environment setup routines.

spack.compiler module

class spack.compiler.Compiler(cspec, operating_system, target, paths, modules=[], alias=None, environment=None, extra_rpaths=None, **kwargs)

Bases: object

This class encapsulates a Spack “compiler”, which includes C, C++, and Fortran compilers. Subclasses should implement support for specific compilers, their possible names, arguments, and how to identify the particular type of compiler.

PrgEnv = None
PrgEnv_compiler = None
cc_names = []
cc_rpath_arg
classmethod cc_version(cc)
cxx11_flag
cxx14_flag
cxx17_flag
cxx_names = []
cxx_rpath_arg
classmethod cxx_version(cxx)
classmethod default_version(cc)

Override just this to override all compiler version functions.

f77_names = []
f77_rpath_arg
classmethod f77_version(f77)
fc_names = []
fc_rpath_arg
classmethod fc_version(fc)
openmp_flag
prefixes = []
setup_custom_environment(pkg, env)

Set any environment variables necessary to use the compiler.

suffixes = ['-.*']
version
spack.compiler.get_compiler_version(compiler_path, version_arg, regex='(.*)')

spack.concretize module

Functions here are used to take abstract specs and make them concrete. For example, if a spec asks for a version between 1.8 and 1.9, these functions might take will take the most recent 1.9 version of the package available. Or, if the user didn’t specify a compiler for a spec, then this will assign a compiler to the spec based on defaults or user preferences.

TODO: make this customizable and allow users to configure
concretization policies.
class spack.concretize.DefaultConcretizer

Bases: object

This class doesn’t have any state, it just provides some methods for concretization. You can subclass it to override just some of the default concretization strategies, or you can override all of them.

choose_virtual_or_external(spec)

Given a list of candidate virtual and external packages, try to find one that is most ABI compatible.

concretize_architecture(spec)

If the spec is empty provide the defaults of the platform. If the architecture is not a basestring, then check if either the platform, target or operating system are concretized. If any of the fields are changed then return True. If everything is concretized (i.e the architecture attribute is a namedtuple of classes) then return False. If the target is a string type, then convert the string into a concretized architecture. If it has no architecture and the root of the DAG has an architecture, then use the root otherwise use the defaults on the platform.

concretize_compiler(spec)

If the spec already has a compiler, we’re done. If not, then take the compiler used for the nearest ancestor with a compiler spec and use that. If the ancestor’s compiler is not concrete, then used the preferred compiler as specified in spackconfig.

Intuition: Use the spackconfig default if no package that depends on this one has a strict compiler requirement. Otherwise, try to build with the compiler that will be used by libraries that link to this one, to maximize compatibility.

concretize_compiler_flags(spec)

The compiler flags are updated to match those of the spec whose compiler is used, defaulting to no compiler flags in the spec. Default specs set at the compiler level will still be added later.

concretize_variants(spec)

If the spec already has variants filled in, return. Otherwise, add the user preferences from packages.yaml or the default variants from the package specification.

concretize_version(spec)

If the spec is already concrete, return. Otherwise take the preferred version from spackconfig, and default to the package’s version if there are no available versions.

TODO: In many cases we probably want to look for installed
versions of each package and use an installed version if we can link to it. The policy implemented here will tend to rebuild a lot of stuff becasue it will prefer a compiler in the spec to any compiler already- installed things were built with. There is likely some better policy that finds some middle ground between these two extremes.
exception spack.concretize.NoBuildError(spec)

Bases: spack.error.SpackError

Raised when a package is configured with the buildable option False, but no satisfactory external versions can be found

exception spack.concretize.NoValidVersionError(spec)

Bases: spack.error.SpackError

Raised when there is no way to have a concrete version for a particular spec.

exception spack.concretize.UnavailableCompilerVersionError(compiler_spec, operating_system, target)

Bases: spack.error.SpackError

Raised when there is no available compiler that satisfies a compiler spec.

spack.concretize.find_spec(spec, condition)

Searches the dag from spec in an intelligent order and looks for a spec that matches a condition

spack.config module

This module implements Spack’s configuration file handling.

This implements Spack’s configuration system, which handles merging multiple scopes with different levels of precedence. See the documentation on Configuration Scopes for details on how Spack’s configuration system behaves. The scopes are:

  1. default
  2. site
  3. user

And corresponding per-platform scopes. Important functions in this module are:

get_config reads in YAML data for a particular scope and returns it. Callers can then modify the data and write it back with update_config.

When read in, Spack validates configurations with jsonschemas. The schemas are in submodules of spack.schema.

exception spack.config.ConfigError(message, long_message=None)

Bases: spack.error.SpackError

exception spack.config.ConfigFileError(message, long_message=None)

Bases: spack.config.ConfigError

exception spack.config.ConfigFormatError(validation_error, data)

Bases: spack.config.ConfigError

Raised when a configuration format does not match its schema.

exception spack.config.ConfigSanityError(validation_error, data)

Bases: spack.config.ConfigFormatError

Same as ConfigFormatError, raised when config is written by Spack.

class spack.config.ConfigScope(name, path)

Bases: object

This class represents a configuration scope.

A scope is one directory containing named configuration files. Each file is a config “section” (e.g., mirrors, compilers, etc).

clear()

Empty cached config information.

get_section(section)
get_section_filename(section)
write_section(section)
spack.config.clear_config_caches()

Clears the caches for configuration files, which will cause them to be re-read upon the next request

spack.config.extend_with_default(validator_class)

Add support for the ‘default’ attr for properties and patternProperties.

jsonschema does not handle this out of the box – it only validates. This allows us to set default values for configs where certain fields are None b/c they’re deleted or commented out.

spack.config.get_config(section, scope=None)

Get configuration settings for a section.

If scope is None or not provided, return the merged contents of all of Spack’s configuration scopes. If scope is provided, return only the confiugration as specified in that scope.

This off the top-level name from the YAML section. That is, for a YAML config file that looks like this:

config:
  install_tree: $spack/opt/spack
  module_roots:
    lmod:   $spack/share/spack/lmod

get_config('config') will return:

{ 'install_tree': '$spack/opt/spack',
  'module_roots: {
      'lmod': '$spack/share/spack/lmod'
  }
}
spack.config.get_config_filename(scope, section)

For some scope and section, get the name of the configuration file

spack.config.get_path(path, data)
spack.config.highest_precedence_scope()

Get the scope with highest precedence (prefs will override others).

spack.config.override(string)

Test if a spack YAML string is an override.

See spack_yaml for details. Keys in Spack YAML can end in ::, and if they do, their values completely replace lower-precedence configs instead of merging into them.

spack.config.print_section(section)

Print a configuration to stdout.

spack.config.section_schemas = {'mirrors': {'additionalProperties': False, 'patternProperties': {'mirrors': {'default': {}, 'additionalProperties': False, 'patternProperties': {'\\w[\\w-]*': {'type': 'string'}}, 'type': 'object'}}, '$schema': 'http://json-schema.org/schema#', 'type': 'object', 'title': 'Spack mirror configuration file schema'}, 'repos': {'additionalProperties': False, 'patternProperties': {'repos': {'default': [], 'items': {'type': 'string'}, 'type': 'array'}}, '$schema': 'http://json-schema.org/schema#', 'type': 'object', 'title': 'Spack repository configuration file schema'}, 'modules': {'title': 'Spack module file configuration file schema', 'patternProperties': {'modules': {'default': {}, 'additionalProperties': False, 'type': 'object', 'properties': {'tcl': {'allOf': [{'$ref': '#/definitions/module_type_configuration'}, {}]}, 'enable': {'default': [], 'items': {'enum': ['tcl', 'dotkit', 'lmod'], 'type': 'string'}, 'type': 'array'}, 'lmod': {'allOf': [{'$ref': '#/definitions/module_type_configuration'}, {'core_compilers': {'$ref': '#/definitions/array_of_strings'}, 'hierarchical_scheme': {'$ref': '#/definitions/array_of_strings'}}]}, 'dotkit': {'allOf': [{'$ref': '#/definitions/module_type_configuration'}, {}]}, 'prefix_inspections': {'patternProperties': {'\\w[\\w-]*': {'$ref': '#/definitions/array_of_strings'}}, 'type': 'object'}}}}, 'additionalProperties': False, 'definitions': {'dependency_selection': {'enum': ['none', 'direct', 'all'], 'type': 'string'}, 'array_of_strings': {'default': [], 'items': {'type': 'string'}, 'type': 'array'}, 'module_file_configuration': {'default': {}, 'additionalProperties': False, 'type': 'object', 'properties': {'load': {'$ref': '#/definitions/array_of_strings'}, 'environment': {'default': {}, 'additionalProperties': False, 'type': 'object', 'properties': {'append_path': {'$ref': '#/definitions/dictionary_of_strings'}, 'set': {'$ref': '#/definitions/dictionary_of_strings'}, 'prepend_path': {'$ref': '#/definitions/dictionary_of_strings'}, 'unset': {'$ref': '#/definitions/array_of_strings'}}}, 'prerequisites': {'$ref': '#/definitions/dependency_selection'}, 'autoload': {'$ref': '#/definitions/dependency_selection'}, 'filter': {'default': {}, 'additionalProperties': False, 'type': 'object', 'properties': {'environment_blacklist': {'default': [], 'items': {'type': 'string'}, 'type': 'array'}}}, 'conflict': {'$ref': '#/definitions/array_of_strings'}, 'suffixes': {'$ref': '#/definitions/dictionary_of_strings'}}}, 'dictionary_of_strings': {'patternProperties': {'\\w[\\w-]*': {'type': 'string'}}, 'type': 'object'}, 'module_type_configuration': {'default': {}, 'anyOf': [{'properties': {'blacklist': {'$ref': '#/definitions/array_of_strings'}, 'whitelist': {'$ref': '#/definitions/array_of_strings'}, 'hash_length': {'default': 7, 'minimum': 0, 'type': 'integer'}, 'naming_scheme': {'type': 'string'}}}, {'patternProperties': {'\\w[\\w-]*': {'$ref': '#/definitions/module_file_configuration'}}}], 'type': 'object'}}, '$schema': 'http://json-schema.org/schema#', 'type': 'object'}, 'packages': {'additionalProperties': False, 'patternProperties': {'packages': {'default': {}, 'additionalProperties': False, 'patternProperties': {'\\w[\\w-]*': {'default': {}, 'additionalProperties': False, 'type': 'object', 'properties': {'paths': {'default': {}, 'type': 'object'}, 'providers': {'default': {}, 'additionalProperties': False, 'patternProperties': {'\\w[\\w-]*': {'default': [], 'items': {'type': 'string'}, 'type': 'array'}}, 'type': 'object'}, 'modules': {'default': {}, 'type': 'object'}, 'buildable': {'default': True, 'type': 'boolean'}, 'version': {'default': [], 'items': {'anyOf': [{'type': 'string'}, {'type': 'number'}]}, 'type': 'array'}, 'variants': {'oneOf': [{'type': 'string'}, {'items': {'type': 'string'}, 'type': 'array'}]}, 'compiler': {'default': [], 'items': {'type': 'string'}, 'type': 'array'}}}}, 'type': 'object'}}, '$schema': 'http://json-schema.org/schema#', 'type': 'object', 'title': 'Spack package configuration file schema'}, 'config': {'additionalProperties': False, 'patternProperties': {'config': {'default': {}, 'additionalProperties': False, 'type': 'object', 'properties': {'install_tree': {'type': 'string'}, 'verify_ssl': {'type': 'boolean'}, 'dirty': {'type': 'boolean'}, 'source_cache': {'type': 'string'}, 'checksum': {'type': 'boolean'}, 'module_roots': {'additionalProperties': False, 'type': 'object', 'properties': {'tcl': {'type': 'string'}, 'lmod': {'type': 'string'}, 'dotkit': {'type': 'string'}}}, 'build_stage': {'oneOf': [{'type': 'string'}, {'items': {'type': 'string'}, 'type': 'array'}]}, 'misc_cache': {'type': 'string'}}}}, '$schema': 'http://json-schema.org/schema#', 'type': 'object', 'title': 'Spack module file configuration file schema'}, 'compilers': {'additionalProperties': False, 'patternProperties': {'compilers': {'items': {'compiler': {'additionalProperties': False, 'required': ['paths', 'spec', 'modules', 'operating_system'], 'type': 'object', 'properties': {'environment': {'default': {}, 'additionalProperties': False, 'type': 'object', 'properties': {'set': {'patternProperties': {'\\w[\\w-]*': {'type': 'string'}}, 'type': 'object'}}}, 'paths': {'additionalProperties': False, 'required': ['cc', 'cxx', 'f77', 'fc'], 'type': 'object', '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'}]}}}, 'operating_system': {'type': 'string'}, 'flags': {'additionalProperties': False, 'type': 'object', 'properties': {'cppflags': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'cflags': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'fflags': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'cxxflags': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'ldflags': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'ldlibs': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}}, 'alias': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'extra_rpaths': {'default': [], 'items': {'type': 'string'}, 'type': 'array'}, 'modules': {'anyOf': [{'type': 'string'}, {'type': 'null'}, {'type': 'array'}]}, 'spec': {'type': 'string'}}}}, 'type': 'array'}}, '$schema': 'http://json-schema.org/schema#', 'type': 'object', 'title': 'Spack compiler configuration file schema'}}

OrderedDict of config scopes keyed by name. Later scopes will override earlier scopes.

spack.config.update_config(section, update_data, scope=None)

Update the configuration file for a particular scope.

Overwrites contents of a section in a scope with update_data, then writes out the config file.

update_data should have the top-level section name stripped off (it will be re-added). Data itself can be a list, dict, or any other yaml-ish structure.

spack.config.validate_scope(scope)

Ensure that scope is valid, and return a valid scope if it is None.

This should be used by routines in config.py to validate scope name arguments, and to determine a default scope where no scope is specified.

spack.config.validate_section(data, schema)

Validate data read in from a Spack YAML file.

This leverages the line information (start_mark, end_mark) stored on Spack YAML structures.

spack.config.validate_section_name(section)

Exit if the section is not a valid section.

spack.database module

Spack’s installation tracking database.

The database serves two purposes:

  1. It implements a cache on top of a potentially very large Spack directory hierarchy, speeding up many operations that would otherwise require filesystem access.
  2. It will allow us to track external installations as well as lost packages and their dependencies.

Prior to the implementation of this store, a directory layout served as the authoritative database of packages in Spack. This module provides a cache and a sanity checking mechanism for what is in the filesystem.

exception spack.database.CorruptDatabaseError(message, long_message=None)

Bases: spack.error.SpackError

Raised when errors are found while reading the database.

class spack.database.Database(root, db_dir=None)

Bases: object

add(spec_like, *args, **kwargs)
get_record(spec_like, *args, **kwargs)
installed_dependents(spec_like, *args, **kwargs)
installed_extensions_for(spec_like, *args, **kwargs)
missing(spec)
query(query_spec=<built-in function any>, known=<built-in function any>, installed=True, explicit=<built-in function any>)

Run a query on the database.

query_spec
Queries iterate through specs in the database and return those that satisfy the supplied query_spec. If query_spec is any, This will match all specs in the database. If it is a spec, we’ll evaluate spec.satisfies(query_spec).

The query can be constrained by two additional attributes:

known

Possible values: True, False, any

Specs that are “known” are those for which Spack can locate a package.py file – i.e., Spack “knows” how to install them. Specs that are unknown may represent packages that existed in a previous version of Spack, but have since either changed their name or been removed.

installed

Possible values: True, False, any

Specs for which a prefix exists are “installed”. A spec that is NOT installed will be in the database if some other spec depends on it but its installation has gone away since Spack installed it.

TODO: Specs are a lot like queries. Should there be a
wildcard spec object, and should specs have attributes like installed and known that can be queried? Or are these really special cases that only belong here?
query_one(query_spec, known=<built-in function any>, installed=True)

Query for exactly one spec that matches the query spec.

Raises an assertion error if more than one spec matches the query. Returns None if no installed package matches.

read_transaction(timeout=60)

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

reindex(directory_layout)

Build database index from scratch based on a directory layout.

Locks the DB if it isn’t locked already.

remove(spec_like, *args, **kwargs)
write_transaction(timeout=60)

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

class spack.database.InstallRecord(spec, path, installed, ref_count=0, explicit=False)

Bases: object

A record represents one installation in the DB.

The record keeps track of the spec for the installation, its install path, AND whether or not it is installed. We need the installed flag in case a user either:

  1. blew away a directory, or
  2. used spack uninstall -f to get rid of it

If, in either case, the package was removed but others still depend on it, we still need to track its spec, so we don’t actually remove from the database until a spec has no installed dependents left.

classmethod from_dict(spec, dictionary)
to_dict()
exception spack.database.InvalidDatabaseVersionError(expected, found)

Bases: spack.error.SpackError

exception spack.database.NonConcreteSpecAddError(message, long_message=None)

Bases: spack.error.SpackError

Raised when attemptint to add non-concrete spec to DB.

spack.directives module

This package contains directives that can be used within a package.

Directives are functions that can be called inside a package definition to modify the package, for example:

class OpenMpi(Package):
depends_on(“hwloc”) provides(“mpi”) ...

provides and depends_on are spack directives.

The available directives are:

  • version
  • depends_on
  • provides
  • extends
  • patch
  • variant
  • resource
spack.directives.version(*args, **kwargs)

Adds a version and metadata describing how to fetch it. Metadata is just stored as a dict in the package’s versions dictionary. Package must turn it into a valid fetch strategy later.

spack.directives.depends_on(*args, **kwargs)

Creates a dict of deps with specs defining when they apply. This directive is to be used inside a Package definition to declare that the package requires other packages to be built first. @see The section “Dependency specs” in the Spack Packaging Guide.

spack.directives.extends(*args, **kwargs)

Same as depends_on, but dependency is symlinked into parent prefix.

This is for Python and other language modules where the module needs to be installed into the prefix of the Python installation. Spack handles this by installing modules into their own prefix, but allowing ONE module version to be symlinked into a parent Python install at a time.

keyword arguments can be passed to extends() so that extension packages can pass parameters to the extendee’s extension mechanism.

spack.directives.provides(*args, **kwargs)

Allows packages to provide a virtual dependency. If a package provides ‘mpi’, other packages can declare that they depend on “mpi”, and spack can use the providing package to satisfy the dependency.

spack.directives.patch(*args, **kwargs)

Packages can declare patches to apply to source. You can optionally provide a when spec to indicate that a particular patch should only be applied when the package’s spec meets certain conditions (e.g. a particular version).

spack.directives.variant(*args, **kwargs)

Define a variant for the package. Packager can specify a default value (on or off) as well as a text description.

spack.directives.resource(*args, **kwargs)

Define an external resource to be fetched and staged when building the package. Based on the keywords present in the dictionary the appropriate FetchStrategy will be used for the resource. Resources are fetched and staged in their own folder inside spack stage area, and then moved into the stage area of the package that needs them.

List of recognized keywords:

  • ‘when’ : (optional) represents the condition upon which the resource is needed
  • ‘destination’ : (optional) path where to move the resource. This path must be relative to the main package stage area.
  • ‘placement’ : (optional) gives the possibility to fine tune how the resource is moved into the main package stage area.

spack.directory_layout module

class spack.directory_layout.DirectoryLayout(root)

Bases: object

A directory layout is used to associate unique paths with specs. Different installations are going to want differnet layouts for their install, and they can use this to customize the nesting structure of spack installs.

add_extension(spec, ext_spec)

Add to the list of currently installed extensions.

all_specs()

To be implemented by subclasses to traverse all specs for which there is a directory within the root.

check_activated(spec, ext_spec)

Ensure that ext_spec can be removed from spec.

If not, raise NoSuchExtensionError.

check_extension_conflict(spec, ext_spec)

Ensure that ext_spec can be activated in spec.

If not, raise ExtensionAlreadyInstalledError or ExtensionConflictError.

check_installed(spec)

Checks whether a spec is installed.

Return the spec’s prefix, if it is installed, None otherwise.

Raise an exception if the install is inconsistent or corrupt.

create_install_directory(spec)

Creates the installation directory for a spec.

extension_map(spec)

Get a dict of currently installed extension packages for a spec.

Dict maps { name : extension_spec } Modifying dict does not affect internals of this layout.

hidden_file_paths

Return a list of hidden files used by the directory layout.

Paths are relative to the root of an install directory.

If the directory layout uses no hidden files to maintain state, this should return an empty container, e.g. [] or (,).

path_for_spec(spec)

Return absolute path from the root to a directory for the spec.

relative_path_for_spec(spec)

Implemented by subclasses to return a relative path from the install root to a unique location for the provided spec.

remove_extension(spec, ext_spec)

Remove from the list of currently installed extensions.

remove_install_directory(spec)

Removes a prefix and any empty parent directories from the root. Raised RemoveFailedError if something goes wrong.

exception spack.directory_layout.DirectoryLayoutError(message, long_msg=None)

Bases: spack.error.SpackError

Superclass for directory layout errors.

exception spack.directory_layout.ExtensionAlreadyInstalledError(spec, ext_spec)

Bases: spack.directory_layout.DirectoryLayoutError

Raised when an extension is added to a package that already has it.

exception spack.directory_layout.ExtensionConflictError(spec, ext_spec, conflict)

Bases: spack.directory_layout.DirectoryLayoutError

Raised when an extension is added to a package that already has it.

exception spack.directory_layout.InconsistentInstallDirectoryError(message, long_msg=None)

Bases: spack.directory_layout.DirectoryLayoutError

Raised when a package seems to be installed to the wrong place.

exception spack.directory_layout.InstallDirectoryAlreadyExistsError(path)

Bases: spack.directory_layout.DirectoryLayoutError

Raised when create_install_directory is called unnecessarily.

exception spack.directory_layout.InvalidExtensionSpecError(message, long_msg=None)

Bases: spack.directory_layout.DirectoryLayoutError

Raised when an extension file has a bad spec in it.

exception spack.directory_layout.NoSuchExtensionError(spec, ext_spec)

Bases: spack.directory_layout.DirectoryLayoutError

Raised when an extension isn’t there on deactivate.

exception spack.directory_layout.RemoveFailedError(installed_spec, prefix, error)

Bases: spack.directory_layout.DirectoryLayoutError

Raised when a DirectoryLayout cannot remove an install prefix.

exception spack.directory_layout.SpecHashCollisionError(installed_spec, new_spec)

Bases: spack.directory_layout.DirectoryLayoutError

Raised when there is a hash collision in an install layout.

exception spack.directory_layout.SpecReadError(message, long_msg=None)

Bases: spack.directory_layout.DirectoryLayoutError

Raised when directory layout can’t read a spec.

class spack.directory_layout.YamlDirectoryLayout(root, **kwargs)

Bases: spack.directory_layout.DirectoryLayout

Lays out installation directories like this::
<install root>/
<platform-os-target>/
<compiler>-<compiler version>/
<name>-<version>-<variants>-<hash>

The hash here is a SHA-1 hash for the full DAG plus the build spec. TODO: implement the build spec.

To avoid special characters (like ~) in the directory name, only enabled variants are included in the install path. Disabled variants are omitted.

add_extension(spec, ext_spec)
all_specs()
build_env_path(spec)
build_log_path(spec)
build_packages_path(spec)
check_activated(spec, ext_spec)
check_extension_conflict(spec, ext_spec)
check_installed(spec)
create_install_directory(spec)
extension_file_path(spec)

Gets full path to an installed package’s extension file

extension_map(spec)

Defensive copying version of _extension_map() for external API.

hidden_file_paths
metadata_path(spec)
read_spec(path)

Read the contents of a file and parse them as a spec

relative_path_for_spec(spec)
remove_extension(spec, ext_spec)
spec_file_path(spec)

Gets full path to spec file

specs_by_hash()
write_spec(spec, path)

Write a spec out to a file.

spack.environment module

class spack.environment.AppendPath(name, value, **kwargs)

Bases: spack.environment.NameValueModifier

execute()
class spack.environment.EnvironmentModifications(other=None)

Bases: object

Keeps track of requests to modify the current environment.

Each call to a method to modify the environment stores the extra information on the caller in the request: - ‘filename’ : filename of the module where the caller is defined - ‘lineno’: line number where the request occurred - ‘context’ : line of code that issued the request that failed

append_path(name, path, **kwargs)

Stores in the current object a request to append a path to a path list

Args:
name: name of the path list in the environment path: path to be appended
apply_modifications()

Applies the modifications and clears the list

clear()

Clears the current list of modifications

extend(other)
static from_sourcing_files(*args, **kwargs)

Creates an instance of EnvironmentModifications that, if executed, has the same effect on the environment as sourcing the files passed as parameters

Parameters:*args – list of files to be sourced
Return type:instance of EnvironmentModifications
group_by_name()

Returns a dict of the modifications grouped by variable name

Returns:
dict mapping the environment variable name to the modifications to be done on it
prepend_path(name, path, **kwargs)

Same as append_path, but the path is pre-pended

Args:
name: name of the path list in the environment path: path to be pre-pended
remove_path(name, path, **kwargs)

Stores in the current object a request to remove a path from a path list

Args:
name: name of the path list in the environment path: path to be removed
set(name, value, **kwargs)

Stores in the current object a request to set an environment variable

Args:
name: name of the environment variable to be set value: value of the environment variable
set_path(name, elts, **kwargs)

Stores a request to set a path generated from a list.

Args:
name: name o the environment variable to be set. elts: elements of the path to set.
unset(name, **kwargs)

Stores in the current object a request to unset an environment variable

Args:
name: name of the environment variable to be set
class spack.environment.NameModifier(name, **kwargs)

Bases: object

update_args(**kwargs)
class spack.environment.NameValueModifier(name, value, **kwargs)

Bases: object

update_args(**kwargs)
class spack.environment.PrependPath(name, value, **kwargs)

Bases: spack.environment.NameValueModifier

execute()
class spack.environment.RemovePath(name, value, **kwargs)

Bases: spack.environment.NameValueModifier

execute()
class spack.environment.SetEnv(name, value, **kwargs)

Bases: spack.environment.NameValueModifier

execute()
class spack.environment.SetPath(name, value, **kwargs)

Bases: spack.environment.NameValueModifier

execute()
class spack.environment.UnsetEnv(name, **kwargs)

Bases: spack.environment.NameModifier

execute()
spack.environment.concatenate_paths(paths, separator=':')

Concatenates an iterable of paths into a string of paths separated by separator, defaulting to colon

Args:
paths: iterable of paths separator: the separator to use, default ‘:’
Returns:
string
spack.environment.filter_environment_blacklist(env, variables)

Generator that filters out any change to environment variables present in the input list

Args:
env: list of environment modifications variables: list of variable names to be filtered
Yields:
items in env if they are not in variables
spack.environment.set_or_unset_not_first(variable, changes, errstream)

Check if we are going to set or unset something after other modifications have already been requested

spack.environment.validate(env, errstream)

Validates the environment modifications to check for the presence of suspicious patterns. Prompts a warning for everything that was found

Current checks: - set or unset variables after other changes on the same variable

Args:
env: list of environment modifications

spack.error module

exception spack.error.NoNetworkConnectionError(message, url)

Bases: spack.error.SpackError

Raised when an operation needs an internet connection.

exception spack.error.SpackError(message, long_message=None)

Bases: exceptions.Exception

This is the superclass for all Spack errors. Subclasses can be found in the modules they have to do with.

die()
long_message
exception spack.error.UnsupportedPlatformError(message)

Bases: spack.error.SpackError

Raised by packages when a platform is not supported

spack.fetch_strategy module

Fetch strategies are used to download source code into a staging area in order to build it. They need to define the following methods:

  • fetch()

    This should attempt to download/check out source from somewhere.

  • check()

    Apply a checksum to the downloaded source code, e.g. for an archive. May not do anything if the fetch method was safe to begin with.

  • expand()

    Expand (e.g., an archive) downloaded file to source.

  • reset()

    Restore original state of downloaded code. Used by clean commands. This may just remove the expanded source and re-expand an archive, or it may run something like git reset –hard.

  • archive()

    Archive a source directory, e.g. for creating a mirror.

class spack.fetch_strategy.CacheURLFetchStrategy(*args, **kwargs)

Bases: spack.fetch_strategy.URLFetchStrategy

The resource associated with a cache URL may be out of date.

fetch(*args, **kwargs)
exception spack.fetch_strategy.ChecksumError(message, long_message=None)

Bases: spack.fetch_strategy.FetchError

Raised when archive fails to checksum.

exception spack.fetch_strategy.FailedDownloadError(url, msg='')

Bases: spack.fetch_strategy.FetchError

Raised wen a download fails.

exception spack.fetch_strategy.FetchError(message, long_message=None)

Bases: spack.error.SpackError

Superclass fo fetcher errors.

class spack.fetch_strategy.FetchStrategy

Bases: object

Superclass of all fetch strategies.

archive(destination)
cachable

Return whether the fetcher is capable of caching the resource it retrieves. This generally is determined by whether the resource is identifiably associated with a specific package version.

check()
enabled = False
expand()
fetch()
classmethod matches(args)
required_attributes = None
reset()
set_stage(stage)

This is called by Stage before any of the fetching methods are called on the stage.

class spack.fetch_strategy.FsCache(root)

Bases: object

destroy()
fetcher(targetPath, digest, **kwargs)
store(fetcher, relativeDst)
class spack.fetch_strategy.GitFetchStrategy(**kwargs)

Bases: spack.fetch_strategy.VCSFetchStrategy

Fetch strategy that gets source code from a git repository. Use like this in a package:

version(‘name’, git=’https://github.com/project/repo.git‘)

Optionally, you can provide a branch, or commit to check out, e.g.:

version(‘1.1’, git=’https://github.com/project/repo.git‘, tag=’v1.1’)

You can use these three optional attributes in addition to git:

  • branch: Particular branch to build from (default is master)
  • tag: Particular tag to check out
  • commit: Particular commit hash in the repo
archive(destination)
cachable
enabled = True
fetch(*args, **kwargs)
git
git_version
required_attributes = ('git',)
reset(*args, **kwargs)
class spack.fetch_strategy.GoFetchStrategy(**kwargs)

Bases: spack.fetch_strategy.VCSFetchStrategy

Fetch strategy that employs the go get infrastructure Use like this in a package:

version(‘name’,
go=’github.com/monochromegane/the_platinum_searcher/...’)

Go get does not natively support versions, they can be faked with git

archive(destination)
enabled = True
fetch(*args, **kwargs)
go
go_version
required_attributes = ('go',)
reset(*args, **kwargs)
class spack.fetch_strategy.HgFetchStrategy(**kwargs)

Bases: spack.fetch_strategy.VCSFetchStrategy

Fetch strategy that gets source code from a Mercurial repository. Use like this in a package:

version(‘name’, hg=’https://jay.grs.rwth-aachen.de/hg/lwm2‘)

Optionally, you can provide a branch, or revision to check out, e.g.:

version(‘torus’,
hg=’https://jay.grs.rwth-aachen.de/hg/lwm2‘, branch=’torus’)

You can use the optional ‘revision’ attribute to check out a branch, tag, or particular revision in hg. To prevent non-reproducible builds, using a moving target like a branch is discouraged.

  • revision: Particular revision, branch, or tag.
archive(destination)
cachable
enabled = True
fetch(*args, **kwargs)
hg
required_attributes = ['hg']
reset(*args, **kwargs)
exception spack.fetch_strategy.InvalidArgsError(pkg, version)

Bases: spack.fetch_strategy.FetchError

exception spack.fetch_strategy.NoArchiveFileError(message, long_message=None)

Bases: spack.fetch_strategy.FetchError

“Raised when an archive file is expected but none exists.

exception spack.fetch_strategy.NoCacheError(message, long_message=None)

Bases: spack.fetch_strategy.FetchError

Raised when there is no cached archive for a package.

exception spack.fetch_strategy.NoDigestError(message, long_message=None)

Bases: spack.fetch_strategy.FetchError

Raised after attempt to checksum when URL has no digest.

exception spack.fetch_strategy.NoStageError(method)

Bases: spack.fetch_strategy.FetchError

Raised when fetch operations are called before set_stage().

class spack.fetch_strategy.SvnFetchStrategy(**kwargs)

Bases: spack.fetch_strategy.VCSFetchStrategy

Fetch strategy that gets source code from a subversion repository. Use like this in a package:

version(‘name’, svn=’http://www.example.com/svn/trunk‘)

Optionally, you can provide a revision for the URL:

version(‘name’, svn=’http://www.example.com/svn/trunk‘,
revision=‘1641’)
archive(destination)
cachable
enabled = True
fetch(*args, **kwargs)
required_attributes = ['svn']
reset(*args, **kwargs)
svn
class spack.fetch_strategy.URLFetchStrategy(url=None, digest=None, **kwargs)

Bases: spack.fetch_strategy.FetchStrategy

FetchStrategy that pulls source code from a URL for an archive, checks the archive against a checksum,and decompresses the archive.

archive(destination)

Just moves this archive to the destination.

archive_file

Path to the source archive within this stage directory.

cachable
check(*args, **kwargs)

Check the downloaded archive against a checksum digest. No-op if this stage checks code out of a repository.

curl
enabled = True
expand(*args, **kwargs)
fetch(*args, **kwargs)
required_attributes = ['url']
reset(*args, **kwargs)

Removes the source path if it exists, then re-expands the archive.

class spack.fetch_strategy.VCSFetchStrategy(name, *rev_types, **kwargs)

Bases: spack.fetch_strategy.FetchStrategy

archive(*args, **kwargs)
check(*args, **kwargs)
expand(*args, **kwargs)
spack.fetch_strategy.args_are_for(args, fetcher)
spack.fetch_strategy.for_package_version(pkg, version)

Determine a fetch strategy based on the arguments supplied to version() in the package description.

spack.fetch_strategy.from_kwargs(**kwargs)

Construct the appropriate FetchStrategy from the given keyword arguments.

Parameters:kwargs – dictionary of keyword arguments
Returns:fetcher or raise a FetchError exception
spack.fetch_strategy.from_list_url(pkg)

If a package provides a URL which lists URLs for resources by version, this can can create a fetcher for a URL discovered for the specified package’s version.

spack.fetch_strategy.from_url(url)

Given a URL, find an appropriate fetch strategy for it. Currently just gives you a URLFetchStrategy that uses curl.

TODO: make this return appropriate fetch strategies for other
types of URLs.

spack.file_cache module

exception spack.file_cache.CacheError(message, long_message=None)

Bases: spack.error.SpackError

class spack.file_cache.FileCache(root)

Bases: object

This class manages cached data in the filesystem.

  • Cache files are fetched and stored by unique keys. Keys can be relative paths, so that thre can be some hierarchy in the cache.
  • The FileCache handles locking cache files for reading and writing, so client code need not manage locks for cache entries.
cache_path(key)

Path to the file in the cache for a particular key.

destroy()

Remove all files under the cache root.

init_entry(key)

Ensure we can access a cache file. Create a lock for it if needed.

Return whether the cache file exists yet or not.

mtime(key)

Return modification time of cache file, or 0 if it does not exist.

Time is in units returned by os.stat in the mtime field, which is platform-dependent.

read_transaction(key)

Get a read transaction on a file cache item.

Returns a ReadTransaction context manager and opens the cache file for reading. You can use it like this:

with file_cache_object.read_transaction(key) as cache_file:
cache_file.read()
remove(key)
write_transaction(key)

Get a write transaction on a file cache item.

Returns a WriteTransaction context manager that opens a temporary file for writing. Once the context manager finishes, if nothing went wrong, moves the file into place on top of the old file atomically.

spack.graph module

Functions for graphing DAGs of dependencies.

This file contains code for graphing DAGs of software packages (i.e. Spack specs). There are two main functions you probably care about:

graph_ascii() will output a colored graph of a spec in ascii format, kind of like the graph git shows with “git log –graph”, e.g.:

o  mpileaks
|    | |    | o |  callpath
|/| |
| |\|
| |\     | | |\     | | | | o  adept-utils
| |_|_|/|
|/| | | |
o | | | |  mpi
 / / / /
| | o |  dyninst
| |/| |
|/|/| |
| | |/
| o |  libdwarf
|/ /
o |  libelf
 /
o  boost

graph_dot() will output a graph of a spec (or multiple specs) in dot format.

Note that graph_ascii assumes a single spec while graph_dot can take a number of specs as input.

spack.graph.topological_sort(spec, reverse=False, deptype=None)

Topological sort for specs.

Return a list of dependency specs sorted topologically. The spec argument is not modified in the process.

spack.graph.graph_ascii(spec, node='o', out=None, debug=False, indent=0, color=None, deptype=None)
class spack.graph.AsciiGraph

Bases: object

write(spec, **kwargs)

Write out an ascii graph of the provided spec.

Arguments: spec – spec to graph. This only handles one spec at a time.

Optional arguments:

out – file object to write out to (default is sys.stdout)

color – whether to write in color. Default is to autodetect
based on output file.
spack.graph.graph_dot(specs, deptype=None, static=False, out=None)

Generate a graph in dot format of all provided specs.

Print out a dot formatted graph of all the dependencies between package. Output can be passed to graphviz, e.g.:

spack graph –dot qt | dot -Tpdf > spack-graph.pdf

spack.mirror module

This file contains code for creating spack mirror directories. A mirror is an organized hierarchy containing specially named archive files. This enabled spack to know where to find files in a mirror if the main server for a particular package is down. Or, if the computer where spack is run is not connected to the internet, it allows spack to download packages directly from a mirror (e.g., on an intranet).

exception spack.mirror.MirrorError(msg, long_msg=None)

Bases: spack.error.SpackError

Superclass of all mirror-creation related errors.

spack.mirror.add_single_spec(spec, mirror_root, categories, **kwargs)
spack.mirror.create(path, specs, **kwargs)

Create a directory to be used as a spack mirror, and fill it with package archives.

Arguments:
path: Path to create a mirror directory hierarchy in. specs: Any package versions matching these specs will be added to the mirror.
Keyword args:
no_checksum: If True, do not checkpoint when fetching (default False) num_versions: Max number of versions to fetch per spec, if spec is ambiguous (default is 0 for all of them)
Return Value:

Returns a tuple of lists: (present, mirrored, error)

  • present: Package specs that were already present.
  • mirrored: Package specs that were successfully mirrored.
  • error: Package specs that failed to mirror due to some error.

This routine iterates through all known package versions, and it creates specs for those versions. If the version satisfies any spec in the specs list, it is downloaded and added to the mirror.

spack.mirror.get_matching_versions(specs, **kwargs)

Get a spec for EACH known version matching any spec in the list.

spack.mirror.mirror_archive_filename(spec, fetcher, resourceId=None)

Get the name of the spec’s archive in the mirror.

spack.mirror.mirror_archive_path(spec, fetcher, resourceId=None)

Get the relative path to the spec’s archive within a mirror.

spack.mirror.suggest_archive_basename(resource)

Return a tentative basename for an archive.

Raises an exception if the name is not an allowed archive type.

Parameters:fetcher –
Returns:

spack.modules module

This module contains code for creating environment modules, which can include dotkits, tcl modules, lmod, and others.

The various types of modules are installed by post-install hooks and removed after an uninstall by post-uninstall hooks. This class consolidates the logic for creating an abstract description of the information that module systems need.

This module also includes logic for coming up with unique names for the module files so that they can be found by the various shell-support files in $SPACK/share/spack/setup-env.*.

Each hook in hooks/ implements the logic for writing its specific type of module file.

class spack.modules.EnvModule(spec=None)

Bases: object

autoload(spec)
blacklisted
category
file_name

Subclasses should implement this to return the name of the file where this module lives.

formats = {}
header
module_specific_content(configuration)
name = 'env_module'
naming_scheme
prerequisite(spec)
process_environment_command(env)
remove()
use_name

Subclasses should implement this to return the name the module command uses to refer to the package.

write(overwrite=False)

Writes out a module file for this object.

This method employs a template pattern and expects derived classes to: - override the header property - provide formats for autoload, prerequisites and environment changes

class spack.modules.Dotkit(spec=None)

Bases: spack.modules.EnvModule

autoload_format = 'dk_op {module_file}\n'
default_naming_format = '${PACKAGE}-${VERSION}-${COMPILERNAME}-${COMPILERVER}'
environment_modifications_formats = {<class 'spack.environment.SetEnv'>: 'dk_setenv {name} {value}\n', <class 'spack.environment.PrependPath'>: 'dk_alter {name} {value}\n', <class 'spack.environment.RemovePath'>: 'dk_unalter {name} {value}\n'}
file_name
header
name = 'dotkit'
path = '/home/docs/checkouts/readthedocs.org/user_builds/nersc-spack/checkouts/nersc_tutorial/share/spack/dotkit'
prerequisite(spec)
class spack.modules.TclModule(spec=None)

Bases: spack.modules.EnvModule

autoload_format = 'if ![ is-loaded {module_file} ] {{\n puts stderr "Autoloading {module_file}"\n module load {module_file}\n}}\n\n'
default_naming_format = '${PACKAGE}-${VERSION}-${COMPILERNAME}-${COMPILERVER}'
file_name
header
module_specific_content(configuration)
name = 'tcl'
path = '/home/docs/checkouts/readthedocs.org/user_builds/nersc-spack/checkouts/nersc_tutorial/share/spack/modules'
prerequisite_format = 'prereq {module_file}\n'
process_environment_command(env)

spack.multimethod module

This module contains utilities for using multi-methods in spack. You can think of multi-methods like overloaded methods – they’re methods with the same name, and we need to select a version of the method based on some criteria. e.g., for overloaded methods, you would select a version of the method to call based on the types of its arguments.

In spack, multi-methods are used to ease the life of package authors. They allow methods like install() (or other methods called by install()) to declare multiple versions to be called when the package is instantiated with different specs. e.g., if the package is built with OpenMPI on x86_64,, you might want to call a different install method than if it was built for mpich2 on BlueGene/Q. Likewise, you might want to do a different type of install for different versions of the package.

Multi-methods provide a simple decorator-based syntax for this that avoids overly complicated rat nests of if statements. Obviously, depending on the scenario, regular old conditionals might be clearer, so package authors should use their judgement.

exception spack.multimethod.MultiMethodError(message)

Bases: spack.error.SpackError

Superclass for multimethod dispatch errors

exception spack.multimethod.NoSuchMethodError(cls, method_name, spec, possible_specs)

Bases: spack.error.SpackError

Raised when we can’t find a version of a multi-method.

class spack.multimethod.SpecMultiMethod(default=None)

Bases: object

This implements a multi-method for Spack specs. Packages are instantiated with a particular spec, and you may want to execute different versions of methods based on what the spec looks like. For example, you might want to call a different version of install() for one platform than you call on another.

The SpecMultiMethod class implements a callable object that handles method dispatch. When it is called, it looks through registered methods and their associated specs, and it tries to find one that matches the package’s spec. If it finds one (and only one), it will call that method.

The package author is responsible for ensuring that only one condition on multi-methods ever evaluates to true. If multiple methods evaluate to true, this will raise an exception.

This is intended for use with decorators (see below). The decorator (see docs below) creates SpecMultiMethods and registers method versions with them.

To register a method, you can do something like this:
mm = SpecMultiMethod() mm.register(“^chaos_5_x86_64_ib”, some_method)

The object registered needs to be a Spec or some string that will parse to be a valid spec.

When the mm is actually called, it selects a version of the method to call based on the sys_type of the object it is called on.

See the docs for decorators below for more details.

register(spec, method)

Register a version of a method for a particular sys_type.

class spack.multimethod.when(spec)

Bases: object

This annotation lets packages declare multiple versions of methods like install() that depend on the package’s spec. For example:

class SomePackage(Package):
    ...

    def install(self, prefix):
        # Do default install

    @when('arch=chaos_5_x86_64_ib')
    def install(self, prefix):
        # This will be executed instead of the default install if
        # the package's platform() is chaos_5_x86_64_ib.

    @when('arch=bgqos_0")
    def install(self, prefix):
        # This will be executed if the package's sys_type is bgqos_0

This allows each package to have a default version of install() AND specialized versions for particular platforms. The version that is called depends on the architecutre of the instantiated package.

Note that this works for methods other than install, as well. So, if you only have part of the install that is platform specific, you could do this:

class SomePackage(Package):
    ...
    # virtual dependence on MPI.
    # could resolve to mpich, mpich2, OpenMPI
    depends_on('mpi')

    def setup(self):
        # do nothing in the default case
        pass

    @when('^openmpi')
    def setup(self):
        # do something special when this is built with OpenMPI for
        # its MPI implementations.


    def install(self, prefix):
        # Do common install stuff
        self.setup()
        # Do more common install stuff

There must be one (and only one) @when clause that matches the package’s spec. If there is more than one, or if none match, then the method will raise an exception when it’s called.

Note that the default version of decorated methods must always come first. Otherwise it will override all of the platform-specific versions. There’s not much we can do to get around this because of the way decorators work.

spack.package module

This is where most of the action happens in Spack. See the Package docs for detailed instructions on how the class works and on how to write your own packages.

The spack package structure is based strongly on Homebrew (http://wiki.github.com/mxcl/homebrew/), mainly because Homebrew makes it very easy to create packages. For a complete rundown on spack and how it differs from homebrew, look at the README.

exception spack.package.ActivationError(msg, long_msg=None)

Bases: spack.package.ExtensionError

exception spack.package.DependencyConflictError(conflict)

Bases: spack.error.SpackError

Raised when the dependencies cannot be flattened as asked for.

exception spack.package.ExtensionConflictError(path)

Bases: spack.package.ExtensionError

exception spack.package.ExtensionError(message, long_msg=None)

Bases: spack.package.PackageError

exception spack.package.ExternalPackageError(message, long_msg=None)

Bases: spack.package.InstallError

Raised by install() when a package is only for external use.

exception spack.package.FetchError(message, long_msg=None)

Bases: spack.error.SpackError

Raised when something goes wrong during fetch.

exception spack.package.InstallError(message, long_msg=None)

Bases: spack.error.SpackError

Raised when something goes wrong during install or uninstall.

class spack.package.InstallPhase(name)

Bases: object

Manages a single phase of the installation

This descriptor stores at creation time the name of the method it should search for execution. The method is retrieved at __get__ time, so that it can be overridden by subclasses of whatever class declared the phases.

It also provides hooks to execute prerequisite and sanity checks.

copy()
exception spack.package.NoURLError(cls)

Bases: spack.package.PackageError

Raised when someone tries to build a URL for a package with no URLs.

class spack.package.Package(spec)

Bases: spack.package.PackageBase

build_system_class = 'Package'
phases = ['install']
class spack.package.PackageBase(spec)

Bases: object

This is the superclass for all spack packages.

*The Package class*

Package is where the bulk of the work of installing packages is done.

A package defines how to fetch, verfiy (via, e.g., md5), build, and install a piece of software. A Package also defines what other packages it depends on, so that dependencies can be installed along with the package itself. Packages are written in pure python.

Packages are all submodules of spack.packages. If spack is installed in $prefix, all of its python files are in $prefix/lib/spack. Most of them are in the spack module, so all the packages live in $prefix/lib/spack/spack/packages.

All you have to do to create a package is make a new subclass of Package in this directory. Spack automatically scans the python files there and figures out which one to import when you invoke it.

An example package

Let’s look at the cmake package to start with. This package lives in $prefix/var/spack/repos/builtin/packages/cmake/package.py:

from spack import *
class Cmake(Package):
    homepage  = 'https://www.cmake.org'
    url       = 'http://www.cmake.org/files/v2.8/cmake-2.8.10.2.tar.gz'
    md5       = '097278785da7182ec0aea8769d06860c'

    def install(self, spec, prefix):
        configure('--prefix=%s'   % prefix,
                  '--parallel=%s' % make_jobs)
        make()
        make('install')

Naming conventions

There are two names you should care about:

  1. The module name, cmake.

    • User will refers to this name, e.g. ‘spack install cmake’.
    • It can include _, -, and numbers (it can even start with a number).

  2. The class name, “Cmake”. This is formed by converting - or _ in the module name to camel case. If the name starts with a number, we prefix the class name with _. Examples:

    Module Name Class Name
    foo_bar FooBar
    docbook-xml DocbookXml
    FooBar Foobar
    3proxy _3proxy

    The class name is what spack looks for when it loads a package module.

Required Attributes

Aside from proper naming, here is the bare minimum set of things you need when you make a package:

homepage:
informational URL, so that users know what they’re installing.
url or url_for_version(self, version):
If url, then the URL of the source archive that spack will fetch. If url_for_version(), then a method returning the URL required to fetch a particular version.
install():
This function tells spack how to build and install the software it downloaded.

Optional Attributes

You can also optionally add these attributes, if needed:

list_url:
Webpage to scrape for available version strings. Default is the directory containing the tarball; use this if the default isn’t correct so that invoking ‘spack versions’ will work for this package.
url_version(self, version):
When spack downloads packages at particular versions, it just converts version to string with str(version). Override this if your package needs special version formatting in its URL. boost is an example of a package that needs this.

*Creating Packages*

As a package creator, you can probably ignore most of the preceding information, because you can use the ‘spack create’ command to do it all automatically.

You as the package creator generally only have to worry about writing your install function and specifying dependencies.

spack create

Most software comes in nicely packaged tarballs, like this one

http://www.cmake.org/files/v2.8/cmake-2.8.10.2.tar.gz

Taking a page from homebrew, spack deduces pretty much everything it needs to know from the URL above. If you simply type this:

spack create http://www.cmake.org/files/v2.8/cmake-2.8.10.2.tar.gz

Spack will download the tarball, generate an md5 hash, figure out the version and the name of the package from the URL, and create a new package file for you with all the names and attributes set correctly.

Once this skeleton code is generated, spack pops up the new package in your $EDITOR so that you can modify the parts that need changes.

Dependencies

If your package requires another in order to build, you can specify that like this:

class Stackwalker(Package):
    ...
    depends_on("libdwarf")
    ...

This tells spack that before it builds stackwalker, it needs to build the libdwarf package as well. Note that this is the module name, not the class name (The class name is really only used by spack to find your package).

Spack will download an install each dependency before it installs your package. In addtion, it will add -L, -I, and rpath arguments to your compiler and linker for each dependency. In most cases, this allows you to avoid specifying any dependencies in your configure or cmake line; you can just run configure or cmake without any additional arguments and it will find the dependencies automatically.

The Install Function

The install function is designed so that someone not too terribly familiar with Python could write a package installer. For example, we put a number of commands in install scope that you can use almost like shell commands. These include make, configure, cmake, rm, rmtree, mkdir, mkdirp, and others.

You can see above in the cmake script that these commands are used to run configure and make almost like they’re used on the command line. The only difference is that they are python function calls and not shell commands.

It may be puzzling to you where the commands and functions in install live. They are NOT instance variables on the class; this would require us to type ‘self.’ all the time and it makes the install code unnecessarily long. Rather, spack puts these commands and variables in module scope for your Package subclass. Since each package has its own module, this doesn’t pollute other namespaces, and it allows you to more easily implement an install function.

For a full list of commands and variables available in module scope, see the add_commands_to_module() function in this class. This is where most of them are created and set on the module.

Parallel Builds

By default, Spack will run make in parallel when you run make() in your install function. Spack figures out how many cores are available on your system and runs make with -j<cores>. If you do not want this behavior, you can explicitly mark a package not to use parallel make:

class SomePackage(Package):
    ...
    parallel = False
    ...

This changes the default behavior so that make is sequential. If you still want to build some parts in parallel, you can do this in your install function:

make(parallel=True)

Likewise, if you do not supply parallel = True in your Package, you can keep the default parallel behavior and run make like this when you want a sequential build:

make(parallel=False)

Package Lifecycle

This section is really only for developers of new spack commands.

A package’s lifecycle over a run of Spack looks something like this:

p = Package()             # Done for you by spack

p.do_fetch()              # downloads tarball from a URL
p.do_stage()              # expands tarball in a temp directory
p.do_patch()              # applies patches to expanded source
p.do_install()            # calls package's install() function
p.do_uninstall()          # removes install directory

There are also some other commands that clean the build area:

p.do_clean()              # removes the stage directory entirely
p.do_restage()            # removes the build directory and
                          # re-expands the archive.

The convention used here is that a do_* function is intended to be called internally by Spack commands (in spack.cmd). These aren’t for package writers to override, and doing so may break the functionality of the Package class.

Package creators override functions like install() (all of them do this), clean() (some of them do this), and others to provide custom behavior.

activate(extension, **kwargs)

Symlinks all files from the extension into extendee’s install dir.

Package authors can override this method to support other extension mechanisms. Spack internals (commands, hooks, etc.) should call do_activate() method so that proper checks are always executed.

activated
all_urls
architecture

Get the spack.architecture.Arch object that represents the environment in which this package will be built.

build_log_path
compiler

Get the spack.compiler.Compiler object used to build this package

deactivate(extension, **kwargs)

Unlinks all files from extension out of this package’s install dir.

Package authors can override this method to support other extension mechanisms. Spack internals (commands, hooks, etc.) should call do_deactivate() method so that proper checks are always executed.

dependencies_of_type(*deptypes)

Get subset of the dependencies with certain types.

do_activate(force=False)

Called on an extension to invoke the extendee’s activate method.

Commands should call this routine, and should not call activate() directly.

do_clean()

Removes the package’s build stage and source tarball.

do_deactivate(**kwargs)

Called on the extension to invoke extendee’s deactivate() method.

do_fake_install()

Make a fake install directory containing a ‘fake’ file in bin.

do_fetch(mirror_only=False)

Creates a stage directory and downloads the tarball for this package. Working directory will be set to the stage directory.

do_install(keep_prefix=False, keep_stage=False, install_deps=True, skip_patch=False, verbose=False, make_jobs=None, run_tests=False, fake=False, explicit=False, dirty=None, **kwargs)

Called by commands to install a package and its dependencies.

Package implementations should override install() to describe their build process.

Parameters:
  • keep_prefix – Keep install prefix on failure. By default, destroys it.
  • keep_stage – By default, stage is destroyed only if there are no exceptions during build. Set to True to keep the stage even with exceptions.
  • install_deps – Install dependencies before installing this package
  • fake – Don’t really build; install fake stub files instead.
  • skip_patch – Skip patch stage of build if True.
  • verbose – Display verbose build output (by default, suppresses it)
  • dirty – Don’t clean the build environment before installing.
  • make_jobs – Number of make jobs to use for install. Default is ncpus
  • force – Install again, even if already installed.
  • run_tests – Run tests within the package’s install()
do_patch()

Calls do_stage(), then applied patches to the expanded tarball if they haven’t been applied already.

do_restage()

Reverts expanded/checked out source to a pristine state.

do_stage(mirror_only=False)

Unpacks the fetched tarball, then changes into the expanded tarball directory.

do_uninstall(force=False)
extendable = False

When True, add RPATHs for the entire DAG. When False, add RPATHs only for immediate dependencies.

extendee_args

Spec of the extendee of this package, or None if it is not an extension

extendee_spec

Spec of the extendee of this package, or None if it is not an extension

extends(spec)
fetch_remote_versions()

Try to find remote versions of this package using the list_url and any other URLs described in the package file.

fetcher
format_doc(**kwargs)

Wrap doc string at 72 characters and format nicely

global_license_dir

Returns the directory where global license files for all packages are stored.

global_license_file

Returns the path where a global license file for this particular package should be stored.

installed
is_extension
log()
make_jobs = None

By default do not run tests within package’s install()

module

Use this to add variables to the class’s module’s scope. This lets us use custom syntax in the install method.

namespace
nearest_url(version)

Finds the URL for the next lowest version with a URL. If there is no lower version with a URL, uses the package url property. If that isn’t there, uses a higher URL, and if that isn’t there raises an error.

static on_package_attributes(**attrs)
package_dir

Return the directory where the package.py file lives.

parallel = True

# jobs to use for parallel make. If set, overrides default of ncpus.

possible_dependencies(visited=None)

Return set of possible transitive dependencies of this package.

classmethod precondition(*args)
prefix

Get the prefix into which this package should be installed.

prefix_lock

Prefix lock is a byte range lock on the nth byte of a file.

The lock file is spack.store.db.prefix_lock – the DB tells us what to call it and it lives alongside the install DB.

n is the sys.maxsize-bit prefix of the DAG hash. This makes likelihood of collision is very low AND it gives us readers-writer lock semantics with just a single lockfile, so no cleanup required.

prefix_locks = {}
provides(vpkg_name)

True if this package provides a virtual package with the specified name

remove_prefix()

Removes the prefix for a package along with any empty parent directories

rpath

Get the rpath this package links with, as a list of paths.

rpath_args

Get the rpath args as a string, with -Wl,-rpath, for each element

run_tests = False

By default do not setup mockup XCode on macOS with Clang

classmethod sanity_check(*args)
sanity_check_is_dir = []

Per-process lock objects for each install prefix.

sanity_check_is_file = []

List of prefix-relative directory paths (or a single path). If these do not exist after install, or if they exist but are not directories, sanity checks will fail.

sanity_check_prefix()

This function checks whether install succeeded.

setup_dependent_environment(spack_env, run_env, dependent_spec)

Set up the environment of packages that depend on this one.

This is similar to setup_environment, but it is used to modify the compile and runtime environments of packages that depend on this one. This gives packages like Python and others that follow the extension model a way to implement common environment or compile-time settings for dependencies.

By default, this delegates to self.setup_environment()

Example:

  1. Installing python modules generally requires PYTHONPATH to point to the lib/pythonX.Y/site-packages directory in the module’s install prefix. This could set that variable.

Args:

spack_env (EnvironmentModifications): list of
modifications to be applied when the dependent package is bulit within Spack.
run_env (EnvironmentModifications): list of environment
changes to be applied when the dependent package is run outside of Spack.
dependent_spec (Spec): The spec of the dependent package
about to be built. This allows the extendee (self) to query the dependent’s state. Note that this package’s spec is available as self.spec.

This is useful if there are some common steps to installing all extensions for a certain package.

setup_dependent_package(module, dependent_spec)

Set up Python module-scope variables for dependent packages.

Called before the install() method of dependents.

Default implementation does nothing, but this can be overridden by an extendable package to set up the module of its extensions. This is useful if there are some common steps to installing all extensions for a certain package.

Example :

  1. Extensions often need to invoke the python interpreter from the Python installation being extended. This routine can put a ‘python’ Executable object in the module scope for the extension package to simplify extension installs.
  2. MPI compilers could set some variables in the dependent’s scope that point to mpicc, mpicxx, etc., allowing them to be called by common names regardless of which MPI is used.
  3. BLAS/LAPACK implementations can set some variables indicating the path to their libraries, since these paths differ by BLAS/LAPACK implementation.

Args:

module (module): The Python module object of the
dependent package. Packages can use this to set module-scope variables for the dependent to use.
dependent_spec (Spec): The spec of the dependent package
about to be built. This allows the extendee (self) to query the dependent’s state. Note that this package’s spec is available as self.spec.

This is useful if there are some common steps to installing all extensions for a certain package.

setup_environment(spack_env, run_env)

Set up the compile and runtime environments for a package.

spack_env and run_env are EnvironmentModifications objects. Package authors can call methods on them to alter the environment within Spack and at runtime.

Both spack_env and run_env are applied within the build process, before this package’s install() method is called.

Modifications in run_env will also be added to the generated environment modules for this package.

Default implementation does nothing, but this can be overridden if the package needs a particular environment.

Examples:

  1. Qt extensions need QTDIR set.
Args:
spack_env (EnvironmentModifications): list of
modifications to be applied when this package is built within Spack.
run_env (EnvironmentModifications): list of environment
changes to be applied when this package is run outside of Spack.
stage
transitive_rpaths = True

List of prefix-relative file paths (or a single path). If these do not exist after install, or if they exist but are not files, sanity checks fail.

url_for_version(version)

Returns a URL from which the specified version of this package may be downloaded.

version: class Version
The version for which a URL is sought.

See Class Version (version.py)

url_version(version)

Given a version, this returns a string that should be substituted into the package’s URL to download that version.

By default, this just returns the version string. Subclasses may need to override this, e.g. for boost versions where you need to ensure that there are _’s in the download URL.

use_xcode = False

Most packages are NOT extendable. Set to True if you want extensions.

version
version_urls = <functools.partial object>
exception spack.package.PackageError(message, long_msg=None)

Bases: spack.error.SpackError

Raised when something is wrong with a package definition.

class spack.package.PackageMeta(name, bases, attr_dict)

Bases: spack.directives.DirectiveMetaMixin

Conveniently transforms attributes to permit extensible phases

Iterates over the attribute ‘phases’ and creates / updates private InstallPhase attributes in the class that is being initialized

phase_fmt = '_InstallPhase_{0}'
exception spack.package.PackageStillNeededError(spec, dependents)

Bases: spack.package.InstallError

Raised when package is still needed by another on uninstall.

exception spack.package.PackageVersionError(version)

Bases: spack.package.PackageError

Raised when a version URL cannot automatically be determined.

exception spack.package.VersionFetchError(cls)

Bases: spack.package.PackageError

Raised when a version URL cannot automatically be determined.

spack.package.dump_packages(spec, path)

Dump all package information for a spec and its dependencies.

This creates a package repository within path for every namespace in the spec DAG, and fills the repos wtih package files and patch files for every node in the DAG.

spack.package.flatten_dependencies(spec, flat_dir)

Make each dependency of spec present in dir via symlink.

Execute a dummy install and flatten dependencies

spack.package.print_pkg(message)

Outputs a message with a package icon.

spack.package.use_cray_compiler_names()

Compiler names for builds that rely on cray compiler names.

spack.package_test module

spack.package_test.compare_output(current_output, blessed_output)

Compare blessed and current output of executables.

spack.package_test.compare_output_file(current_output, blessed_output_file)

Same as above, but when the blessed output is given as a file.

spack.package_test.compile_c_and_execute(source_file, include_flags, link_flags)

Compile C @p source_file with @p include_flags and @p link_flags, run and return the output.

spack.parse module

exception spack.parse.LexError(message, string, pos)

Bases: spack.parse.ParseError

Raised when we don’t know how to lex something.

class spack.parse.Lexer(lexicon)

Bases: object

Base class for Lexers that keep track of line numbers.

lex(text)
token(type, value='')
exception spack.parse.ParseError(message, string, pos)

Bases: spack.error.SpackError

Raised when we don’t hit an error while parsing.

class spack.parse.Parser(lexer)

Bases: object

Base class for simple recursive descent parsers.

accept(id)

Put the next symbol in self.token if accepted, then call gettok()

expect(id)

Like accept(), but fails if we don’t like the next token.

gettok()

Puts the next token in the input stream into self.next.

last_token_error(message)

Raise an error about the previous token in the stream.

next_token_error(message)

Raise an error about the next token in the stream.

parse(text)
push_tokens(iterable)

Adds all tokens in some iterable to the token stream.

setup(text)
unexpected_token()
class spack.parse.Token(type, value='', start=0, end=0)

Represents tokens; generated from input by lexer and fed to parse().

is_a(type)

spack.patch module

class spack.patch.FilePatch(pkg, path_or_url, level)

Bases: spack.patch.Patch

Describes a patch that is retrieved from a file in the repository

exception spack.patch.NoSuchPatchFileError(package, path)

Bases: spack.error.SpackError

Raised when user specifies a patch file that doesn’t exist.

class spack.patch.Patch(pkg, path_or_url, level)

Bases: object

Base class to describe a patch that needs to be applied to some expanded source code.

apply(stage)

Apply the patch at self.path to the source code in the supplied stage

Args:
stage: stage for the package that needs to be patched
static create(pkg, path_or_url, level, **kwargs)

Factory method that creates an instance of some class derived from Patch

Args:
pkg: package that needs to be patched path_or_url: path or url where the patch is found level: patch level
Returns:
instance of some Patch class
class spack.patch.UrlPatch(pkg, path_or_url, level, **kwargs)

Bases: spack.patch.Patch

Describes a patch that is retrieved from a URL

apply(stage)

Retrieve the patch in a temporary stage, computes self.path and calls super().apply(stage)

Args:
stage: stage for the package that needs to be patched

spack.preferred_packages module

class spack.preferred_packages.PreferredPackages

Bases: object

architecture_compare(pkgname, a, b)

Return less-than-0, 0, or greater than 0 if architecture a of pkgname is respectively less-than, equal-to, or greater-than architecture b of pkgname. One architecture is less-than another if it is preferred over the other.

compiler_compare(pkgname, a, b)

Return less-than-0, 0, or greater than 0 if compiler a of pkgname is respecively less-than, equal-to, or greater-than compiler b of pkgname. One compiler is less-than another if it is preferred over the other.

provider_compare(pkgname, provider_str, a, b)

Return less-than-0, 0, or greater than 0 if a is respecively less-than, equal-to, or greater-than b. A and b are possible implementations of provider_str. One provider is less-than another if it is preferred over the other. For example, provider_compare(‘scorep’, ‘mpi’, ‘mvapich’, ‘openmpi’) would return -1 if mvapich should be preferred over openmpi for scorep.

spec_has_preferred_provider(pkgname, provider_str)

Return True iff the named package has a list of preferred providers

spec_preferred_variants(pkgname)

Return a VariantMap of preferred variants and their values

variant_compare(pkgname, a, b)

Return less-than-0, 0, or greater than 0 if variant a of pkgname is respectively less-than, equal-to, or greater-than variant b of pkgname. One variant is less-than another if it is preferred over the other.

version_compare(pkgname, a, b)

Return less-than-0, 0, or greater than 0 if version a of pkgname is respectively less-than, equal-to, or greater-than version b of pkgname. One version is less-than another if it is preferred over the other.

spack.provider_index module

The virtual module contains utility classes for virtual dependencies.

class spack.provider_index.ProviderIndex(specs=None, restrict=False)

Bases: object

This is a dict of dicts used for finding providers of particular virtual dependencies. The dict of dicts looks like:

{ vpkg name :
{ full vpkg spec : set(packages providing spec) } }

Callers can use this to first find which packages provide a vpkg, then find a matching full spec. e.g., in this scenario:

{ ‘mpi’ :
{ mpi@:1.1 : set([mpich]),
mpi@:2.3 : set([mpich2@1.9:]) } }

Calling providers_for(spec) will find specs that provide a matching implementation of MPI.

copy()

Deep copy of this ProviderIndex.

static from_yaml(stream)
merge(other)

Merge other ProviderIndex into this one.

providers_for(*vpkg_specs)

Gives specs of all packages that provide virtual packages with the supplied specs.

remove_provider(pkg_name)

Remove a provider from the ProviderIndex.

satisfies(other)

Check that providers of virtual specs are compatible.

to_yaml(stream=None)
update(spec)
exception spack.provider_index.ProviderIndexError(message, long_message=None)

Bases: spack.error.SpackError

Raised when there is a problem with a ProviderIndex.

spack.repository module

exception spack.repository.BadRepoError(message, long_message=None)

Bases: spack.repository.RepoError

Raised when repo layout is invalid.

exception spack.repository.DuplicateRepoError(message, long_message=None)

Bases: spack.repository.RepoError

Raised when duplicate repos are added to a RepoPath.

exception spack.repository.FailedConstructorError(name, exc_type, exc_obj, exc_tb)

Bases: spack.repository.PackageLoadError

Raised when a package’s class constructor fails.

exception spack.repository.InvalidNamespaceError(message, long_message=None)

Bases: spack.repository.RepoError

Raised when an invalid namespace is encountered.

exception spack.repository.NoRepoConfiguredError(message, long_message=None)

Bases: spack.repository.RepoError

Raised when there are no repositories configured.

exception spack.repository.PackageLoadError(message, long_message=None)

Bases: spack.error.SpackError

Superclass for errors related to loading packages.

class spack.repository.Repo(root, namespace='spack.pkg')

Bases: object

Class representing a package repository in the filesystem.

Each package repository must have a top-level configuration file called repo.yaml.

Currently, repo.yaml this must define:

namespace:
A Python namespace where the repository’s packages should live.
all_package_names()

Returns a sorted list of all package names in the Repo.

all_packages()

Iterator over all packages in the repository.

Use this with care, because loading packages is slow.

dirname_for_package_name(spec_like, *args, **kwargs)
dump_provenance(spec_like, *args, **kwargs)
exists(pkg_name)

Whether a package with the supplied name exists.

extensions_for(spec_like, *args, **kwargs)
filename_for_package_name(spec_like, *args, **kwargs)
find_module(fullname, path=None)

Python find_module import hook.

Returns this Repo if it can load the module; None if not.

get(spec_like, *args, **kwargs)
get_pkg_class(pkg_name)

Get the class for the package out of its module.

First loads (or fetches from cache) a module for the package. Then extracts the package class from the module according to Spack’s naming convention.

is_prefix(fullname)

True if fullname is a prefix of this Repo’s namespace.

is_virtual(pkg_name)

True if the package with this name is virtual, False otherwise.

load_module(fullname)

Python importer load hook.

Tries to load the module; raises an ImportError if it can’t.

provider_index

A provider index with names specific to this repo.

providers_for(spec_like, *args, **kwargs)
purge()

Clear entire package instance cache.

real_name(import_name)

Allow users to import Spack packages using Python identifiers.

A python identifier might map to many different Spack package names due to hyphen/underscore ambiguity.

Easy example:
num3proxy -> 3proxy
Ambiguous:
foo_bar -> foo_bar, foo-bar
More ambiguous:
foo_bar_baz -> foo_bar_baz, foo-bar-baz, foo_bar-baz, foo-bar_baz
exception spack.repository.RepoError(message, long_message=None)

Bases: spack.error.SpackError

Superclass for repository-related errors.

class spack.repository.RepoPath(*repo_dirs, **kwargs)

Bases: object

A RepoPath is a list of repos that function as one.

It functions exactly like a Repo, but it operates on the combined results of the Repos in its list instead of on a single package repository.

all_package_names()

Return all unique package names in all repositories.

all_packages()
dirname_for_package_name(pkg_name)
dump_provenance(spec_like, *args, **kwargs)
exists(pkg_name)

Whether package with the give name exists in the path’s repos.

Note that virtual packages do not “exist”.

extensions_for(spec_like, *args, **kwargs)
filename_for_package_name(pkg_name)
find_module(fullname, path=None)

Implements precedence for overlaid namespaces.

Loop checks each namespace in self.repos for packages, and also handles loading empty containing namespaces.

first_repo()

Get the first repo in precedence order.

get(spec_like, *args, **kwargs)
get_pkg_class(pkg_name)

Find a class for the spec’s package and return the class object.

get_repo(namespace, default=<object object>)

Get a repository by namespace.

Arguments:

namespace:

Look up this namespace in the RepoPath, and return it if found.

Optional Arguments:

default:

If default is provided, return it when the namespace isn’t found. If not, raise an UnknownNamespaceError.
is_virtual(pkg_name)

True if the package with this name is virtual, False otherwise.

load_module(fullname)

Handles loading container namespaces when necessary.

See Repo for how actual package modules are loaded.

provider_index

Merged ProviderIndex from all Repos in the RepoPath.

providers_for(spec_like, *args, **kwargs)
put_first(repo)

Add repo first in the search path.

put_last(repo)

Add repo last in the search path.

remove(repo)

Remove a repo from the search path.

repo_for_pkg(spec_like, *args, **kwargs)
swap(other)

Convenience function to make swapping repositories easier.

This is currently used by mock tests. TODO: Maybe there is a cleaner way.

class spack.repository.SpackNamespace(namespace)

Bases: module

Allow lazy loading of modules.

exception spack.repository.UnknownNamespaceError(namespace)

Bases: spack.repository.PackageLoadError

Raised when we encounter an unknown namespace

exception spack.repository.UnknownPackageError(name, repo=None)

Bases: spack.repository.PackageLoadError

Raised when we encounter a package spack doesn’t have.

spack.repository.create_repo(root, namespace=None)

Create a new repository in root with the specified namespace.

If the namespace is not provided, use basename of root. Return the canonicalized path and namespace of the created repository.

spack.resource module

Describes an optional resource needed for a build.

Typically a bunch of sources that can be built in-tree within another package to enable optional features.

class spack.resource.Resource(name, fetcher, destination, placement)

Bases: object

Represents an optional resource to be fetched by a package.

Aggregates a name, a fetcher, a destination and a placement.

spack.spec module

Spack allows very fine-grained control over how packages are installed and over how they are built and configured. To make this easy, it has its own syntax for declaring a dependence. We call a descriptor of a particular package configuration a “spec”.

The syntax looks like this:

$ spack install mpileaks ^openmpi @1.2:1.4 +debug %intel @12.1 =bgqos_0
                0        1        2        3      4      5     6

The first part of this is the command, ‘spack install’. The rest of the line is a spec for a particular installation of the mpileaks package.

  1. The package to install

  2. A dependency of the package, prefixed by ^

  3. A version descriptor for the package. This can either be a specific version, like “1.2”, or it can be a range of versions, e.g. “1.2:1.4”. If multiple specific versions or multiple ranges are acceptable, they can be separated by commas, e.g. if a package will only build with versions 1.0, 1.2-1.4, and 1.6-1.8 of mavpich, you could say:

    depends_on(“mvapich@1.0,1.2:1.4,1.6:1.8”)

  4. A compile-time variant of the package. If you need openmpi to be built in debug mode for your package to work, you can require it by adding +debug to the openmpi spec when you depend on it. If you do NOT want the debug option to be enabled, then replace this with -debug.

  5. The name of the compiler to build with.

  6. The versions of the compiler to build with. Note that the identifier for a compiler version is the same ‘@’ that is used for a package version. A version list denoted by ‘@’ is associated with the compiler only if if it comes immediately after the compiler name. Otherwise it will be associated with the current package spec.

  7. The architecture to build with. This is needed on machines where cross-compilation is required

Here is the EBNF grammar for a spec:

spec-list    = { spec [ dep-list ] }
dep_list     = { ^ spec }
spec         = id [ options ]
options      = { @version-list | +variant | -variant | ~variant |
                 %compiler | arch=architecture | [ flag ]=value}
flag         = { cflags | cxxflags | fcflags | fflags | cppflags |
                 ldflags | ldlibs }
variant      = id
architecture = id
compiler     = id [ version-list ]
version-list = version [ { , version } ]
version      = id | id: | :id | id:id
id           = [A-Za-z0-9_][A-Za-z0-9_.-]*

Identifiers using the <name>=<value> command, such as architectures and compiler flags, require a space before the name.

There is one context-sensitive part: ids in versions may contain ‘.’, while other ids may not.

There is one ambiguity: since ‘-‘ is allowed in an id, you need to put whitespace space before -variant for it to be tokenized properly. You can either use whitespace, or you can just use ~variant since it means the same thing. Spack uses ~variant in directory names and in the canonical form of specs to avoid ambiguity. Both are provided because ~ can cause shell expansion when it is the first character in an id typed on the command line.

class spack.spec.Spec(spec_like, *dep_like, **kwargs)

Bases: object

colorized()
common_dependencies(other)

Return names of dependencies that self an other have in common.

concrete

A spec is concrete if it can describe only ONE build of a package. If any of the name, version, architecture, compiler, variants, or depdenencies are ambiguous,then it is not concrete.

concretize()

A spec is concrete if it describes one build of a package uniquely. This will ensure that this spec is concrete.

If this spec could describe more than one version, variant, or build of a package, this will add constraints to make it concrete.

Some rigorous validation and checks are also performed on the spec. Concretizing ensures that it is self-consistent and that it’s consistent with requirements of its pacakges. See flatten() and normalize() for more details on this.

concretized()

This is a non-destructive version of concretize(). First clones, then returns a concrete version of this package without modifying this package.

constrain(other, deps=True)

Merge the constraints of other with self.

Returns True if the spec changed as a result, False if not.

constrained(other, deps=True)

Return a constrained copy without modifying this spec.

copy(deps=True)

Return a copy of this spec.

By default, returns a deep copy. To control how dependencies are copied, supply:

deps=True: deep copy

deps=False: shallow copy (no dependencies)

deps=(‘link’, ‘build’):
only build and link dependencies. Similar for other deptypes.
cshort_spec

Returns a version of the spec with the dependencies hashed instead of completely enumerated.

dag_hash(length=None)

Return a hash of the entire spec DAG, including connectivity.

dag_hash_bit_prefix(bits)

Get the first <bits> bits of the DAG hash as an integer type.

dep_difference(other)

Returns dependencies in self that are not in other.

dep_string()
dependencies(deptype=None)
dependencies_dict(deptype=None)
dependents(deptype=None)
dependents_dict(deptype=None)
eq_dag(other, deptypes=True)

True if the full dependency DAGs of specs are equal.

eq_node(other)

Equality with another spec, not including dependencies.

flat_dependencies(**kwargs)

Return a DependencyMap containing all of this spec’s dependencies with their constraints merged.

If copy is True, returns merged copies of its dependencies without modifying the spec it’s called on.

If copy is False, clears this spec’s dependencies and returns them.

format(format_string='$_$@$%@+$+$=', **kwargs)

Prints out particular pieces of a spec, depending on what is in the format string. The format strings you can provide are:

$_   Package name
$.   Full package name (with namespace)
$@   Version with '@' prefix
$%   Compiler with '%' prefix
$%@  Compiler with '%' prefix & compiler version with '@' prefix
$%+  Compiler with '%' prefix & compiler flags prefixed by name
$%@+ Compiler, compiler version, and compiler flags with same
     prefixes as above
$+   Options
$=   Architecture prefixed by 'arch='
$#   7-char prefix of DAG hash with '-' prefix
$$   $

You can also use full-string versions, which elide the prefixes:

${PACKAGE}       Package name
${VERSION}       Version
${COMPILER}      Full compiler string
${COMPILERNAME}  Compiler name
${COMPILERVER}   Compiler version
${COMPILERFLAGS} Compiler flags
${OPTIONS}       Options
${ARCHITECTURE}  Architecture
${SHA1}          Dependencies 8-char sha1 prefix
${HASH:len}      DAG hash with optional length specifier

${SPACK_ROOT}    The spack root directory
${SPACK_INSTALL} The default spack install directory,
                 ${SPACK_PREFIX}/opt
${PREFIX}        The package prefix

Note these are case-insensitive: for example you can specify either ${PACKAGE} or ${package}.

Optionally you can provide a width, e.g. $20_ for a 20-wide name. Like printf, you can provide ‘-‘ for left justification, e.g. $-20_ for a left-justified name.

Anything else is copied verbatim into the output stream.

Example: $_$@$+ translates to the name, version, and options of the package, but no dependencies, arch, or compiler.

TODO: allow, e.g., $6# to customize short hash length TODO: allow, e.g., $## for full hash.

static from_dict(data)

Construct a spec from YAML.

Parameters: data – a nested dict/list data structure read from YAML or JSON.

static from_json(stream)

Construct a spec from JSON.

Parameters: stream – string or file object to read from.

static from_node_dict(node)
static from_yaml(stream)

Construct a spec from YAML.

Parameters: stream – string or file object to read from.

fullname
get_dependency(name)
index(deptype=None)

Return DependencyMap that points to all the dependencies in this spec.

static is_virtual(name)

Test if a name is virtual without requiring a Spec.

ne_dag(other, deptypes=True)

True if the full dependency DAGs of specs are not equal.

ne_node(other)

Inequality with another spec, not including dependencies.

normalize(force=False)

When specs are parsed, any dependencies specified are hanging off the root, and ONLY the ones that were explicitly provided are there. Normalization turns a partial flat spec into a DAG, where:

  1. Known dependencies of the root package are in the DAG.
  2. Each node’s dependencies dict only contains its known direct deps.
  3. There is only ONE unique spec for each package in the DAG.
    • This includes virtual packages. If there a non-virtual package that provides a virtual package that is in the spec, then we replace the virtual package with the non-virtual one.

TODO: normalize should probably implement some form of cycle detection, to ensure that the spec is actually a DAG.

normalized()

Return a normalized copy of this spec without modifying this spec.

package
package_class

Internal package call gets only the class object for a package. Use this to just get package metadata.

prefix
static read_yaml_dep_specs(dependency_dict)

Read the DependencySpec portion of a YAML-formatted Spec.

This needs to be backward-compatible with older spack spec formats so that reindex will work on old specs/databases.

root

Follow dependent links and find the root of this spec’s DAG. In spack specs, there should be a single root (the package being installed). This will throw an assertion error if that is not the case.

satisfies(other, deps=True, strict=False)

Determine if this spec satisfies all constraints of another.

There are two senses for satisfies:

  • loose (default): the absence of a constraint in self implies that it could be satisfied by other, so we only check that there are no conflicts with other for constraints that this spec actually has.
  • strict: strict means that we must meet all the constraints specified on other.
satisfies_dependencies(other, strict=False)

This checks constraints on common dependencies against each other.

short_spec

Returns a version of the spec with the dependencies hashed instead of completely enumerated.

sorted_deps()

Return a list of all dependencies sorted by name.

to_dict()
to_json(stream=None)
to_node_dict()
to_yaml(stream=None)
traverse(**kwargs)
traverse_edges(visited=None, d=0, deptype=None, deptype_query=None, dep_spec=None, **kwargs)

Generic traversal of the DAG represented by this spec. This will yield each node in the spec. Options:

order [=pre|post]

Order to traverse spec nodes. Defaults to preorder traversal. Options are:

‘pre’: Pre-order traversal; each node is yielded before its
children in the dependency DAG.
‘post’: Post-order traversal; each node is yielded after its
children in the dependency DAG.
cover [=nodes|edges|paths]

Determines how extensively to cover the dag. Possible values:

‘nodes’: Visit each node in the dag only once. Every node
yielded by this function will be unique.
‘edges’: If a node has been visited once but is reached along a
new path from the root, yield it but do not descend into it. This traverses each ‘edge’ in the DAG once.
‘paths’: Explore every unique path reachable from the root.
This descends into visited subtrees and will yield nodes twice if they’re reachable by multiple paths.
depth [=False]
Defaults to False. When True, yields not just nodes in the spec, but also their depth from the root in a (depth, node) tuple.
key [=id]
Allow a custom key function to track the identity of nodes in the traversal.
root [=True]
If False, this won’t yield the root node, just its descendents.
direction [=children|parents]
If ‘children’, does a traversal of this spec’s children. If ‘parents’, traverses upwards in the DAG towards the root.
tree(**kwargs)

Prints out this spec and its dependencies, tree-formatted with indentation.

validate_names()

This checks that names of packages and compilers in this spec are real. If they’re not, it will raise either UnknownPackageError or UnsupportedCompilerError.

version
virtual

Right now, a spec is virtual if no package exists with its name.

TODO: revisit this – might need to use a separate namespace and be more explicit about this. Possible idea: just use conventin and make virtual deps all caps, e.g., MPI vs mpi.

virtual_dependencies()

Return list of any virtual deps in this spec.

spack.spec.canonical_deptype(deptype)
spack.spec.validate_deptype(deptype)
spack.spec.parse(string)

Returns a list of specs from an input string. For creating one spec, see Spec() constructor.

spack.spec.parse_anonymous_spec(spec_like, pkg_name)

Allow the user to omit the package name part of a spec if they know what it has to be already.

e.g., provides(‘mpi@2’, when='@1.9:’) says that this package provides MPI-3 when its version is higher than 1.9.

exception spack.spec.SpecError(message, long_message=None)

Bases: spack.error.SpackError

Superclass for all errors that occur while constructing specs.

exception spack.spec.SpecParseError(parse_error)

Bases: spack.spec.SpecError

Wrapper for ParseError for when we’re parsing specs.

exception spack.spec.DuplicateDependencyError(message, long_message=None)

Bases: spack.spec.SpecError

Raised when the same dependency occurs in a spec twice.

exception spack.spec.DuplicateVariantError(message, long_message=None)

Bases: spack.spec.SpecError

Raised when the same variant occurs in a spec twice.

exception spack.spec.DuplicateCompilerSpecError(message, long_message=None)

Bases: spack.spec.SpecError

Raised when the same compiler occurs in a spec twice.

exception spack.spec.UnsupportedCompilerError(compiler_name)

Bases: spack.spec.SpecError

Raised when the user asks for a compiler spack doesn’t know about.

exception spack.spec.UnknownVariantError(pkg, variant)

Bases: spack.spec.SpecError

Raised when the same variant occurs in a spec twice.

exception spack.spec.DuplicateArchitectureError(message, long_message=None)

Bases: spack.spec.SpecError

Raised when the same architecture occurs in a spec twice.

exception spack.spec.InconsistentSpecError(message, long_message=None)

Bases: spack.spec.SpecError

Raised when two nodes in the same spec DAG have inconsistent constraints.

exception spack.spec.InvalidDependencyError(message, long_message=None)

Bases: spack.spec.SpecError

Raised when a dependency in a spec is not actually a dependency of the package.

exception spack.spec.InvalidDependencyTypeError(message, long_message=None)

Bases: spack.spec.SpecError

Raised when a dependency type is not a legal Spack dep type.

exception spack.spec.NoProviderError(vpkg)

Bases: spack.spec.SpecError

Raised when there is no package that provides a particular virtual dependency.

exception spack.spec.MultipleProviderError(vpkg, providers)

Bases: spack.spec.SpecError

Raised when there is no package that provides a particular virtual dependency.

exception spack.spec.UnsatisfiableSpecError(provided, required, constraint_type)

Bases: spack.spec.SpecError

Raised when a spec conflicts with package constraints. Provide the requirement that was violated when raising.

exception spack.spec.UnsatisfiableSpecNameError(provided, required)

Bases: spack.spec.UnsatisfiableSpecError

Raised when two specs aren’t even for the same package.

exception spack.spec.UnsatisfiableVersionSpecError(provided, required)

Bases: spack.spec.UnsatisfiableSpecError

Raised when a spec version conflicts with package constraints.

exception spack.spec.UnsatisfiableCompilerSpecError(provided, required)

Bases: spack.spec.UnsatisfiableSpecError

Raised when a spec comiler conflicts with package constraints.

exception spack.spec.UnsatisfiableVariantSpecError(provided, required)

Bases: spack.spec.UnsatisfiableSpecError

Raised when a spec variant conflicts with package constraints.

exception spack.spec.UnsatisfiableCompilerFlagSpecError(provided, required)

Bases: spack.spec.UnsatisfiableSpecError

Raised when a spec variant conflicts with package constraints.

exception spack.spec.UnsatisfiableArchitectureSpecError(provided, required)

Bases: spack.spec.UnsatisfiableSpecError

Raised when a spec architecture conflicts with package constraints.

exception spack.spec.UnsatisfiableProviderSpecError(provided, required)

Bases: spack.spec.UnsatisfiableSpecError

Raised when a provider is supplied but constraints don’t match a vpkg requirement

exception spack.spec.UnsatisfiableDependencySpecError(provided, required)

Bases: spack.spec.UnsatisfiableSpecError

Raised when some dependency of constrained specs are incompatible

exception spack.spec.AmbiguousHashError(msg, *specs)

Bases: spack.spec.SpecError

spack.stage module

exception spack.stage.ChdirError(message, long_message=None)

Bases: spack.stage.StageError

Raised when Spack can’t change directories.

class spack.stage.DIYStage(path)

Bases: object

Simple class that allows any directory to be a spack stage.

cache_local()
chdir()
chdir_to_source()
check()
destroy()
expand_archive()
fetch(*args, **kwargs)
restage()
class spack.stage.ResourceStage(url_or_fetch_strategy, root, resource, **kwargs)

Bases: spack.stage.Stage

expand_archive()
exception spack.stage.RestageError(message, long_message=None)

Bases: spack.stage.StageError

“Error encountered during restaging.

class spack.stage.Stage(url_or_fetch_strategy, name=None, mirror_path=None, keep=False, path=None, lock=True, search_fn=None)

Bases: object

Manages a temporary stage directory for building.

A Stage object is a context manager that handles a directory where some source code is downloaded and built before being installed. It handles fetching the source code, either as an archive to be expanded or by checking it out of a repository. A stage’s lifecycle looks like this:

with Stage() as stage:      # Context manager creates and destroys the
                            # stage directory
    stage.fetch()           # Fetch a source archive into the stage.
    stage.expand_archive()  # Expand the source archive.
    <install>               # Build and install the archive.
                            # (handled by user of Stage)

When used as a context manager, the stage is automatically destroyed if no exception is raised by the context. If an excpetion is raised, the stage is left in the filesystem and NOT destroyed, for potential reuse later.

You can also use the stage’s create/destroy functions manually, like this:

stage = Stage()
try:
    stage.create()          # Explicitly create the stage directory.
    stage.fetch()           # Fetch a source archive into the stage.
    stage.expand_archive()  # Expand the source archive.
    <install>               # Build and install the archive.
                            # (handled by user of Stage)
finally:
    stage.destroy()         # Explicitly destroy the stage directory.

If spack.use_tmp_stage is True, spack will attempt to create stages in a tmp directory. Otherwise, stages are created directly in spack.stage_path.

There are two kinds of stages: named and unnamed. Named stages can persist between runs of spack, e.g. if you fetched a tarball but didn’t finish building it, you won’t have to fetch it again.

Unnamed stages are created using standard mkdtemp mechanisms or similar, and are intended to persist for only one run of spack.

archive_file

Path to the source archive within this stage directory.

cache_local()
chdir()

Changes directory to the stage path. Or dies if it is not set up.

chdir_to_source()

Changes directory to the expanded archive directory. Dies with an error if there was no expanded archive.

check()

Check the downloaded archive against a checksum digest. No-op if this stage checks code out of a repository.

create()

Creates the stage directory.

If get_tmp_root() is None, the stage directory is created directly under spack.stage_path, otherwise this will attempt to create a stage in a temporary directory and link it into spack.stage_path.

Spack will use the first writable location in spack.tmp_dirs to create a stage. If there is no valid location in tmp_dirs, fall back to making the stage inside spack.stage_path.

destroy()

Removes this stage directory.

expand_archive()

Changes to the stage directory and attempt to expand the downloaded archive. Fail if the stage is not set up or if the archive is not yet downloaded.

expected_archive_files

Possible archive file paths.

fetch(mirror_only=False)

Downloads an archive or checks out code from a repository.

restage()

Removes the expanded archive path if it exists, then re-expands the archive.

save_filename
source_path

Returns the path to the expanded/checked out source code.

To find the source code, this method searches for the first subdirectory of the stage that it can find, and returns it. This assumes nothing besides the archive file will be in the stage path, but it has the advantage that we don’t need to know the name of the archive or its contents.

If the fetch strategy is not supposed to expand the downloaded file, it will just return the stage path. If the archive needs to be expanded, it will return None when no archive is found.

stage_locks = {}
exception spack.stage.StageError(message, long_message=None)

Bases: spack.error.SpackError

“Superclass for all errors encountered during staging.

spack.stage.ensure_access(file='/home/docs/checkouts/readthedocs.org/user_builds/nersc-spack/checkouts/nersc_tutorial/var/spack/stage')

Ensure we can access a directory and die with an error if we can’t.

spack.stage.get_tmp_root()
spack.stage.purge()

Remove all build directories in the top-level stage path.

spack.store module

Components that manage Spack’s installation tree.

An install tree, or “build store” consists of two parts:

  1. A package database that tracks what is installed.
  2. A directory layout that determines how the installations are laid out.

The store contains all the install prefixes for packages installed by Spack. The simplest store could just contain prefixes named by DAG hash, but we use a fancier directory layout to make browsing the store and debugging easier.

The directory layout is currently hard-coded to be a YAMLDirectoryLayout, so called because it stores build metadata within each prefix, in spec.yaml files. In future versions of Spack we may consider allowing install trees to define their own layouts with some per-tree configuration.

spack.url module

This module has methods for parsing names and versions of packages from URLs. The idea is to allow package creators to supply nothing more than the download location of the package, and figure out version and name information from there.

Example: when spack is given the following URL:

It can figure out that the package name is ruby, and that it is at version 1.9.1-p243. This is useful for making the creation of packages simple: a user just supplies a URL and skeleton code is generated automatically.

Spack can also figure out that it can most likely download 1.8.1 at this URL:

This is useful if a user asks for a package at a particular version number; spack doesn’t need anyone to tell it where to get the tarball even though it’s never been told about that version before.

exception spack.url.UndetectableNameError(path)

Bases: spack.url.UrlParseError

Raised when we can’t parse a package name from a string.

exception spack.url.UndetectableVersionError(path)

Bases: spack.url.UrlParseError

Raised when we can’t parse a version from a string.

exception spack.url.UrlParseError(msg, path)

Bases: spack.error.SpackError

Raised when the URL module can’t parse something correctly.

spack.url.color_url(path, **kwargs)

Color the parts of the url according to Spack’s parsing.

Colors are:

Cyan: The version found by parse_version_offset(). Red: The name found by parse_name_offset().

Green: Instances of version string from substitute_version(). Magenta: Instances of the name (protected from substitution).

Optional args:
errors=True Append parse errors at end of string. subs=True Color substitutions as well as parsed name/version.
spack.url.cumsum(elts, init=0, fn=<function <lambda>>)

Return cumulative sum of result of fn on each element in elts.

spack.url.determine_url_file_extension(path)

This returns the type of archive a URL refers to. This is sometimes confusing because of URLs like:

Where the URL doesn’t actually contain the filename. We need to know what type it is so that we can appropriately name files in mirrors.

spack.url.find_list_url(url)

Finds a good list URL for the supplied URL. This depends on the site. By default, just assumes that a good list URL is the dirname of an archive path. For github URLs, this returns the URL of the project’s releases page.

spack.url.insensitize(string)

Change upper and lowercase letters to be case insensitive in the provided string. e.g., ‘a’ becomes ‘[Aa]’, ‘B’ becomes ‘[bB]’, etc. Use for building regexes.

spack.url.parse_name(path, ver=None)
spack.url.parse_name_and_version(path)
spack.url.parse_name_offset(path, v=None, debug=False)
spack.url.parse_version(path, debug=False)

Given a URL or archive name, extract a version from it and return a version object.

spack.url.parse_version_offset(path, debug=False)

Try to extract a version string from a filename or URL. This is taken largely from Homebrew’s Version class.

spack.url.split_url_extension(path)

Some URLs have a query string, e.g.:

In (1), the query string needs to be stripped to get at the extension, but in (2), the filename is IN a single final query argument.

This strips the URL into three pieces: prefix, ext, and suffix. The suffix contains anything that was stripped off the URL to get at the file extension. In (1), it will be ‘?raw=true’, but in (2), it will be empty. e.g.:

spack.url.strip_query_and_fragment(path)
spack.url.substitute_version(path, new_version)

Given a URL or archive name, find the version in the path and substitute the new version for it. Replace all occurrences of the version if they don’t overlap with the package name.

Simple example::
substitute_version(‘http://www.mr511.de/software/libelf-0.8.13.tar.gz‘, ‘2.9.3’) ->’http://www.mr511.de/software/libelf-2.9.3.tar.gz‘
Complex examples::

substitute_version(‘http://mvapich.cse.ohio-state.edu/download/mvapich/mv2/mvapich2-2.0.tar.gz‘, 2.1) -> ‘http://mvapich.cse.ohio-state.edu/download/mvapich/mv2/mvapich2-2.1.tar.gz‘

# In this string, the “2” in mvapich2 is NOT replaced. substitute_version(‘http://mvapich.cse.ohio-state.edu/download/mvapich/mv2/mvapich2-2.tar.gz‘, 2.1) -> ‘http://mvapich.cse.ohio-state.edu/download/mvapich/mv2/mvapich2-2.1.tar.gz‘

spack.url.substitution_offsets(path)

This returns offsets for substituting versions and names in the provided path. It is a helper for substitute_version().

spack.url.wildcard_version(path)

Find the version in the supplied path, and return a regular expression that will match this path with any version in its place.

spack.variant module

Variant is a class describing flags on builds, or “variants”.

Could be generalized later to describe aribitrary parameters, but currently variants are just flags.

class spack.variant.Variant(default, description)

Bases: object

Represents a variant on a build. Can be either on or off.

spack.version module

This module implements Version and version-ish objects. These are:

Version
A single version of a package.
VersionRange
A range of versions of a package.
VersionList
A list of Versions and VersionRanges.

All of these types support the following operations, which can be called on any of the types:

__eq__, __ne__, __lt__, __gt__, __ge__, __le__, __hash__
__contains__
satisfies
overlaps
union
intersection
concrete
class spack.version.Version(string)

Bases: object

Class to represent versions

concrete
dashed
dotted
highest()
intersection(a, b, *args, **kwargs)
is_predecessor(other)

True if the other version is the immediate predecessor of this one. That is, NO versions v exist such that: (self < v < other and v not in self).

is_successor(other)
isdevelop()

Triggers on the special case of the @develop version.

isnumeric()

Tells if this version is numeric (vs. a non-numeric version). A version will be numeric as long as the first section of it is, even if it contains non-numerica portions.

Some numeric versions:
1 1.1 1.1a 1.a.1b
Some non-numeric versions:
develop system myfavoritebranch
joined
lowest()
overlaps(a, b, *args, **kwargs)
satisfies(a, b, *args, **kwargs)

A Version ‘satisfies’ another if it is at least as specific and has a common prefix. e.g., we want gcc@4.7.3 to satisfy a request for gcc@4.7 so that when a user asks to build with gcc@4.7, we can find a suitable compiler.

underscored
union(a, b, *args, **kwargs)
up_to(index)

Return a version string up to the specified component, exclusive. e.g., if this is 10.8.2, self.up_to(2) will return ‘10.8’.

wildcard()

Create a regex that will match variants of this version string.

class spack.version.VersionRange(start, end)

Bases: object

concrete
highest()
intersection(a, b, *args, **kwargs)
lowest()
overlaps(a, b, *args, **kwargs)
satisfies(a, b, *args, **kwargs)

A VersionRange satisfies another if some version in this range would satisfy some version in the other range. To do this it must either:

  1. Overlap with the other range
  2. The start of this range satisfies the end of the other range.

This is essentially the same as overlaps(), but overlaps assumes that its arguments are specific. That is, 4.7 is interpreted as 4.7.0.0.0.0... . This funciton assumes that 4.7 woudl be satisfied by 4.7.3.5, etc.

Rationale:

If a user asks for gcc@4.5:4.7, and a package is only compatible with gcc@4.7.3:4.8, then that package should be able to build under the constraints. Just using overlaps() would not work here.

Note that we don’t need to check whether the end of this range would satisfy the start of the other range, because overlaps() already covers that case.

Note further that overlaps() is a symmetric operation, while satisfies() is not.

union(a, b, *args, **kwargs)
class spack.version.VersionList(vlist=None)

Bases: object

Sorted, non-redundant list of Versions and VersionRanges.

add(version)
concrete
copy()
static from_dict(dictionary)

Parse dict from to_dict.

highest()

Get the highest version in the list.

intersect(a, b, *args, **kwargs)

Intersect this spec’s list with other.

Return True if the spec changed as a result; False otherwise

intersection(a, b, *args, **kwargs)
lowest()

Get the lowest version in the list.

overlaps(a, b, *args, **kwargs)
satisfies(a, b, *args, **kwargs)

A VersionList satisfies another if some version in the list would satisfy some version in the other list. This uses essentially the same algorithm as overlaps() does for VersionList, but it calls satisfies() on member Versions and VersionRanges.

If strict is specified, this version list must lie entirely within the other in order to satisfy it.

to_dict()

Generate human-readable dict for YAML.

union(a, b, *args, **kwargs)
update(a, b, *args, **kwargs)
spack.version.ver(obj)

Parses a Version, VersionRange, or VersionList from a string or list of strings.

Module contents

class spack.Package(spec)

Bases: spack.package.PackageBase

build_system_class = 'Package'
phases = ['install']
class spack.CMakePackage(spec)

Bases: spack.package.PackageBase

Specialized class for packages that are built using cmake

This class provides three phases that can be overridden: - cmake - build - install

They all have sensible defaults and for many packages the only thing necessary will be to override cmake_args

build(spec, prefix)

The usual make after cmake

build_directory()

Override to provide another place to build the package

build_system_class = 'CMakePackage'
build_type()

Override to provide the correct build_type in case a complex logic is needed

check()

Default test : search the Makefile for the target test and run them if found.

cmake(spec, prefix)

Run cmake in the build directory

cmake_args()

Method to be overridden. Should return an iterable containing all the arguments that must be passed to configure, except: - CMAKE_INSTALL_PREFIX - CMAKE_BUILD_TYPE

install(spec, prefix)

...and the final make install after cmake

phases = ['cmake', 'build', 'install']
root_cmakelists_dir()

Directory where to find the root CMakeLists.txt

std_cmake_args

Standard cmake arguments provided as a property for convenience of package writers

class spack.AutotoolsPackage(spec)

Bases: spack.package.PackageBase

Specialized class for packages that are built using GNU Autotools

This class provides four phases that can be overridden: - autoreconf - configure - build - install

They all have sensible defaults and for many packages the only thing necessary will be to override configure_args

Additionally, you may specify make targets for build and install phases by overriding build_targets and install_targets

autoreconf(spec, prefix)

Not needed usually, configure should be already there

build(spec, prefix)

Make the build targets

build_system_class = 'AutotoolsPackage'
build_targets = []
check()

Default test : search the Makefile for targets test and check and run them if found.

configure(spec, prefix)

Runs configure with the arguments specified in configure_args and an appropriately set prefix

configure_args()

Method to be overridden. Should return an iterable containing all the arguments that must be passed to configure, except –prefix

do_patch_config_guess()

Some packages ship with an older config.guess and need to have this updated when installed on a newer architecture.

install(spec, prefix)

Make the install targets

install_targets = ['install']
is_configure_or_die()

Checks the presence of a configure file after the autoreconf phase

patch()

Perform any required patches.

patch_config_guess = True
phases = ['autoreconf', 'configure', 'build', 'install']
class spack.MakefilePackage(spec)

Bases: spack.package.PackageBase

Specialized class for packages that are built using editable Makefiles

This class provides three phases that can be overridden: - edit - build - install

It is necessary to override the ‘edit’ phase, while ‘build’ and ‘install’ have sensible defaults.

build(spec, prefix)

Default build phase : call make passing build_args

build_directory()

Directory where the main Makefile is located

build_system_class = 'MakefilePackage'
build_targets = []
edit(spec, prefix)

This phase cannot be defaulted for obvious reasons...

install(spec, prefix)

Default install phase : call make passing install_args

install_targets = ['install']
phases = ['edit', 'build', 'install']
class spack.Version(string)

Bases: object

Class to represent versions

concrete
dashed
dotted
highest()
intersection(a, b, *args, **kwargs)
is_predecessor(other)

True if the other version is the immediate predecessor of this one. That is, NO versions v exist such that: (self < v < other and v not in self).

is_successor(other)
isdevelop()

Triggers on the special case of the @develop version.

isnumeric()

Tells if this version is numeric (vs. a non-numeric version). A version will be numeric as long as the first section of it is, even if it contains non-numerica portions.

Some numeric versions:
1 1.1 1.1a 1.a.1b
Some non-numeric versions:
develop system myfavoritebranch
joined
lowest()
overlaps(a, b, *args, **kwargs)
satisfies(a, b, *args, **kwargs)

A Version ‘satisfies’ another if it is at least as specific and has a common prefix. e.g., we want gcc@4.7.3 to satisfy a request for gcc@4.7 so that when a user asks to build with gcc@4.7, we can find a suitable compiler.

underscored
union(a, b, *args, **kwargs)
up_to(index)

Return a version string up to the specified component, exclusive. e.g., if this is 10.8.2, self.up_to(2) will return ‘10.8’.

wildcard()

Create a regex that will match variants of this version string.

spack.ver(obj)

Parses a Version, VersionRange, or VersionList from a string or list of strings.

class spack.Spec(spec_like, *dep_like, **kwargs)

Bases: object

colorized()
common_dependencies(other)

Return names of dependencies that self an other have in common.

concrete

A spec is concrete if it can describe only ONE build of a package. If any of the name, version, architecture, compiler, variants, or depdenencies are ambiguous,then it is not concrete.

concretize()

A spec is concrete if it describes one build of a package uniquely. This will ensure that this spec is concrete.

If this spec could describe more than one version, variant, or build of a package, this will add constraints to make it concrete.

Some rigorous validation and checks are also performed on the spec. Concretizing ensures that it is self-consistent and that it’s consistent with requirements of its pacakges. See flatten() and normalize() for more details on this.

concretized()

This is a non-destructive version of concretize(). First clones, then returns a concrete version of this package without modifying this package.

constrain(other, deps=True)

Merge the constraints of other with self.

Returns True if the spec changed as a result, False if not.

constrained(other, deps=True)

Return a constrained copy without modifying this spec.

copy(deps=True)

Return a copy of this spec.

By default, returns a deep copy. To control how dependencies are copied, supply:

deps=True: deep copy

deps=False: shallow copy (no dependencies)

deps=(‘link’, ‘build’):
only build and link dependencies. Similar for other deptypes.
cshort_spec

Returns a version of the spec with the dependencies hashed instead of completely enumerated.

dag_hash(length=None)

Return a hash of the entire spec DAG, including connectivity.

dag_hash_bit_prefix(bits)

Get the first <bits> bits of the DAG hash as an integer type.

dep_difference(other)

Returns dependencies in self that are not in other.

dep_string()
dependencies(deptype=None)
dependencies_dict(deptype=None)
dependents(deptype=None)
dependents_dict(deptype=None)
eq_dag(other, deptypes=True)

True if the full dependency DAGs of specs are equal.

eq_node(other)

Equality with another spec, not including dependencies.

flat_dependencies(**kwargs)

Return a DependencyMap containing all of this spec’s dependencies with their constraints merged.

If copy is True, returns merged copies of its dependencies without modifying the spec it’s called on.

If copy is False, clears this spec’s dependencies and returns them.

format(format_string='$_$@$%@+$+$=', **kwargs)

Prints out particular pieces of a spec, depending on what is in the format string. The format strings you can provide are:

$_   Package name
$.   Full package name (with namespace)
$@   Version with '@' prefix
$%   Compiler with '%' prefix
$%@  Compiler with '%' prefix & compiler version with '@' prefix
$%+  Compiler with '%' prefix & compiler flags prefixed by name
$%@+ Compiler, compiler version, and compiler flags with same
     prefixes as above
$+   Options
$=   Architecture prefixed by 'arch='
$#   7-char prefix of DAG hash with '-' prefix
$$   $

You can also use full-string versions, which elide the prefixes:

${PACKAGE}       Package name
${VERSION}       Version
${COMPILER}      Full compiler string
${COMPILERNAME}  Compiler name
${COMPILERVER}   Compiler version
${COMPILERFLAGS} Compiler flags
${OPTIONS}       Options
${ARCHITECTURE}  Architecture
${SHA1}          Dependencies 8-char sha1 prefix
${HASH:len}      DAG hash with optional length specifier

${SPACK_ROOT}    The spack root directory
${SPACK_INSTALL} The default spack install directory,
                 ${SPACK_PREFIX}/opt
${PREFIX}        The package prefix

Note these are case-insensitive: for example you can specify either ${PACKAGE} or ${package}.

Optionally you can provide a width, e.g. $20_ for a 20-wide name. Like printf, you can provide ‘-‘ for left justification, e.g. $-20_ for a left-justified name.

Anything else is copied verbatim into the output stream.

Example: $_$@$+ translates to the name, version, and options of the package, but no dependencies, arch, or compiler.

TODO: allow, e.g., $6# to customize short hash length TODO: allow, e.g., $## for full hash.

static from_dict(data)

Construct a spec from YAML.

Parameters: data – a nested dict/list data structure read from YAML or JSON.

static from_json(stream)

Construct a spec from JSON.

Parameters: stream – string or file object to read from.

static from_node_dict(node)
static from_yaml(stream)

Construct a spec from YAML.

Parameters: stream – string or file object to read from.

fullname
get_dependency(name)
index(deptype=None)

Return DependencyMap that points to all the dependencies in this spec.

static is_virtual(name)

Test if a name is virtual without requiring a Spec.

ne_dag(other, deptypes=True)

True if the full dependency DAGs of specs are not equal.

ne_node(other)

Inequality with another spec, not including dependencies.

normalize(force=False)

When specs are parsed, any dependencies specified are hanging off the root, and ONLY the ones that were explicitly provided are there. Normalization turns a partial flat spec into a DAG, where:

  1. Known dependencies of the root package are in the DAG.
  2. Each node’s dependencies dict only contains its known direct deps.
  3. There is only ONE unique spec for each package in the DAG.
    • This includes virtual packages. If there a non-virtual package that provides a virtual package that is in the spec, then we replace the virtual package with the non-virtual one.

TODO: normalize should probably implement some form of cycle detection, to ensure that the spec is actually a DAG.

normalized()

Return a normalized copy of this spec without modifying this spec.

package
package_class

Internal package call gets only the class object for a package. Use this to just get package metadata.

prefix
static read_yaml_dep_specs(dependency_dict)

Read the DependencySpec portion of a YAML-formatted Spec.

This needs to be backward-compatible with older spack spec formats so that reindex will work on old specs/databases.

root

Follow dependent links and find the root of this spec’s DAG. In spack specs, there should be a single root (the package being installed). This will throw an assertion error if that is not the case.

satisfies(other, deps=True, strict=False)

Determine if this spec satisfies all constraints of another.

There are two senses for satisfies:

  • loose (default): the absence of a constraint in self implies that it could be satisfied by other, so we only check that there are no conflicts with other for constraints that this spec actually has.
  • strict: strict means that we must meet all the constraints specified on other.
satisfies_dependencies(other, strict=False)

This checks constraints on common dependencies against each other.

short_spec

Returns a version of the spec with the dependencies hashed instead of completely enumerated.

sorted_deps()

Return a list of all dependencies sorted by name.

to_dict()
to_json(stream=None)
to_node_dict()
to_yaml(stream=None)
traverse(**kwargs)
traverse_edges(visited=None, d=0, deptype=None, deptype_query=None, dep_spec=None, **kwargs)

Generic traversal of the DAG represented by this spec. This will yield each node in the spec. Options:

order [=pre|post]

Order to traverse spec nodes. Defaults to preorder traversal. Options are:

‘pre’: Pre-order traversal; each node is yielded before its
children in the dependency DAG.
‘post’: Post-order traversal; each node is yielded after its
children in the dependency DAG.
cover [=nodes|edges|paths]

Determines how extensively to cover the dag. Possible values:

‘nodes’: Visit each node in the dag only once. Every node
yielded by this function will be unique.
‘edges’: If a node has been visited once but is reached along a
new path from the root, yield it but do not descend into it. This traverses each ‘edge’ in the DAG once.
‘paths’: Explore every unique path reachable from the root.
This descends into visited subtrees and will yield nodes twice if they’re reachable by multiple paths.
depth [=False]
Defaults to False. When True, yields not just nodes in the spec, but also their depth from the root in a (depth, node) tuple.
key [=id]
Allow a custom key function to track the identity of nodes in the traversal.
root [=True]
If False, this won’t yield the root node, just its descendents.
direction [=children|parents]
If ‘children’, does a traversal of this spec’s children. If ‘parents’, traverses upwards in the DAG towards the root.
tree(**kwargs)

Prints out this spec and its dependencies, tree-formatted with indentation.

validate_names()

This checks that names of packages and compilers in this spec are real. If they’re not, it will raise either UnknownPackageError or UnsupportedCompilerError.

version
virtual

Right now, a spec is virtual if no package exists with its name.

TODO: revisit this – might need to use a separate namespace and be more explicit about this. Possible idea: just use conventin and make virtual deps all caps, e.g., MPI vs mpi.

virtual_dependencies()

Return list of any virtual deps in this spec.

class spack.when(spec)

Bases: object

This annotation lets packages declare multiple versions of methods like install() that depend on the package’s spec. For example:

class SomePackage(Package):
    ...

    def install(self, prefix):
        # Do default install

    @when('arch=chaos_5_x86_64_ib')
    def install(self, prefix):
        # This will be executed instead of the default install if
        # the package's platform() is chaos_5_x86_64_ib.

    @when('arch=bgqos_0")
    def install(self, prefix):
        # This will be executed if the package's sys_type is bgqos_0

This allows each package to have a default version of install() AND specialized versions for particular platforms. The version that is called depends on the architecutre of the instantiated package.

Note that this works for methods other than install, as well. So, if you only have part of the install that is platform specific, you could do this:

class SomePackage(Package):
    ...
    # virtual dependence on MPI.
    # could resolve to mpich, mpich2, OpenMPI
    depends_on('mpi')

    def setup(self):
        # do nothing in the default case
        pass

    @when('^openmpi')
    def setup(self):
        # do something special when this is built with OpenMPI for
        # its MPI implementations.


    def install(self, prefix):
        # Do common install stuff
        self.setup()
        # Do more common install stuff

There must be one (and only one) @when clause that matches the package’s spec. If there is more than one, or if none match, then the method will raise an exception when it’s called.

Note that the default version of decorated methods must always come first. Otherwise it will override all of the platform-specific versions. There’s not much we can do to get around this because of the way decorators work.

class spack.FileFilter(*filenames)

Bases: object

Convenience class for calling filter_file a lot.

filter(regex, repl, **kwargs)
class spack.LibraryList(libraries)

Bases: _abcoll.Sequence

Sequence of absolute paths to libraries

Provides a few convenience methods to manipulate library paths and get commonly used compiler flags or names

basenames

Stable de-duplication of the base-names in the list

>>> l = LibraryList(['/dir1/liba.a', '/dir2/libb.a', '/dir3/liba.a'])
>>> assert l.basenames == ['liba.a', 'libb.a']
directories

Stable de-duplication of the directories where the libraries reside

>>> l = LibraryList(['/dir1/liba.a', '/dir2/libb.a', '/dir1/libc.a'])
>>> assert l.directories == ['/dir1', '/dir2']
joined(separator=' ')
ld_flags

Search flags + link flags

>>> l = LibraryList(['/dir1/liba.a', '/dir2/libb.a', '/dir1/liba.so'])
>>> assert l.search_flags == '-L/dir1 -L/dir2 -la -lb'
link_flags

Link flags for the libraries

>>> l = LibraryList(['/dir1/liba.a', '/dir2/libb.a', '/dir1/liba.so'])
>>> assert l.search_flags == '-la -lb'
names

Stable de-duplication of library names in the list

>>> l = LibraryList(['/dir1/liba.a', '/dir2/libb.a', '/dir3/liba.so'])
>>> assert l.names == ['a', 'b']
search_flags

Search flags for the libraries

>>> l = LibraryList(['/dir1/liba.a', '/dir2/libb.a', '/dir1/liba.so'])
>>> assert l.search_flags == '-L/dir1 -L/dir2'
spack.ancestor(dir, n=1)

Get the nth ancestor of a directory.

spack.can_access(file_name)

True if we have read/write access to the file.

spack.change_sed_delimiter(old_delim, new_delim, *filenames)

Find all sed search/replace commands and change the delimiter. e.g., if the file contains seds that look like ‘s///’, you can call change_sed_delimiter(‘/’, ‘@’, file) to change the delimiter to ‘@’.

NOTE that this routine will fail if the delimiter is ‘ or ”. Handling those is left for future work.

spack.copy_mode(src, dest)
spack.filter_file(regex, repl, *filenames, **kwargs)

Like sed, but uses python regular expressions.

Filters every line of each file through regex and replaces the file with a filtered version. Preserves mode of filtered files.

As with re.sub, repl can be either a string or a callable. If it is a callable, it is passed the match object and should return a suitable replacement string. If it is a string, it can contain , , etc. to represent back-substitution as sed would allow.

Keyword Options:
string[=False] If True, treat regex as a plain string. backup[=True] Make backup file(s) suffixed with ~ ignore_absent[=False] Ignore any files that don’t exist.
spack.find_libraries(args, root, shared=True, recurse=False)

Returns an iterable object containing a list of full paths to libraries if found.

Args:
args: iterable object containing a list of library names to search for (e.g. ‘libhdf5’) root: root folder where to start searching shared: if True searches for shared libraries, otherwise for static recurse: if False search only root folder, if True descends top-down from the root
Returns:
list of full paths to the libraries that have been found
spack.fix_darwin_install_name(path)

Fix install name of dynamic libraries on Darwin to have full path. There are two parts of this task: (i) use install_name(‘-id’,...) to change install name of a single lib; (ii) use install_name(‘-change’,...) to change the cross linking between libs. The function assumes that all libraries are in one folder and currently won’t follow subfolders.

Args:
path: directory in which .dylib files are located
spack.force_remove(*paths)

Remove files without printing errors. Like rm -f, does NOT remove directories.

spack.force_symlink(src, dest)
spack.install(src, dest)

Manually install a file to a particular location.

spack.install_tree(src, dest, **kwargs)

Manually install a directory tree to a particular location.

spack.is_exe(path)

True if path is an executable file.

spack.join_path(prefix, *args)
spack.mkdirp(*paths)

Creates a directory, as well as parent directories if needed.

spack.remove_dead_links(root)

Removes any dead link that is present in root

Args:
root: path where to search for dead links
spack.remove_if_dead_link(path)

Removes the argument if it is a dead link, does nothing otherwise

Args:
path: the potential dead link
spack.remove_linked_tree(path)

Removes a directory and its contents. If the directory is a symlink, follows the link and removes the real directory before removing the link.

Args:
path: directory to be removed
spack.set_executable(path)
spack.set_install_permissions(path)

Set appropriate permissions on the installed file.

spack.touch(path)

Creates an empty file at the specified path.

spack.touchp(path)

Like touch, but creates any parent directories needed for the file.

spack.traverse_tree(source_root, dest_root, rel_path='', **kwargs)

Traverse two filesystem trees simultaneously.

Walks the LinkTree directory in pre or post order. Yields each file in the source directory with a matching path from the dest directory, along with whether the file is a directory. e.g., for this tree:

root/
  a/
    file1
    file2
  b/
    file3

When called on dest, this yields:

('root',         'dest')
('root/a',       'dest/a')
('root/a/file1', 'dest/a/file1')
('root/a/file2', 'dest/a/file2')
('root/b',       'dest/b')
('root/b/file3', 'dest/b/file3')

Optional args:

order=[pre|post] – Whether to do pre- or post-order traversal.

ignore=<predicate> – Predicate indicating which files to ignore.

follow_nonexisting – Whether to descend into directories in
src that do not exit in dest. Default True.

follow_links – Whether to descend into symlinks in src.

spack.unset_executable_mode(path)
spack.working_dir(*args, **kwds)
spack.version(*args, **kwargs)

Adds a version and metadata describing how to fetch it. Metadata is just stored as a dict in the package’s versions dictionary. Package must turn it into a valid fetch strategy later.

spack.depends_on(*args, **kwargs)

Creates a dict of deps with specs defining when they apply. This directive is to be used inside a Package definition to declare that the package requires other packages to be built first. @see The section “Dependency specs” in the Spack Packaging Guide.

spack.extends(*args, **kwargs)

Same as depends_on, but dependency is symlinked into parent prefix.

This is for Python and other language modules where the module needs to be installed into the prefix of the Python installation. Spack handles this by installing modules into their own prefix, but allowing ONE module version to be symlinked into a parent Python install at a time.

keyword arguments can be passed to extends() so that extension packages can pass parameters to the extendee’s extension mechanism.

spack.provides(*args, **kwargs)

Allows packages to provide a virtual dependency. If a package provides ‘mpi’, other packages can declare that they depend on “mpi”, and spack can use the providing package to satisfy the dependency.

spack.patch(*args, **kwargs)

Packages can declare patches to apply to source. You can optionally provide a when spec to indicate that a particular patch should only be applied when the package’s spec meets certain conditions (e.g. a particular version).

spack.variant(*args, **kwargs)

Define a variant for the package. Packager can specify a default value (on or off) as well as a text description.

spack.resource(*args, **kwargs)

Define an external resource to be fetched and staged when building the package. Based on the keywords present in the dictionary the appropriate FetchStrategy will be used for the resource. Resources are fetched and staged in their own folder inside spack stage area, and then moved into the stage area of the package that needs them.

List of recognized keywords:

  • ‘when’ : (optional) represents the condition upon which the resource is needed
  • ‘destination’ : (optional) path where to move the resource. This path must be relative to the main package stage area.
  • ‘placement’ : (optional) gives the possibility to fine tune how the resource is moved into the main package stage area.
class spack.Executable(name)

Bases: object

Class representing a program that can be run on the command line.

add_default_arg(arg)
add_default_env(key, value)
command
spack.which(name, **kwargs)

Finds an executable in the path like command-line which.

exception spack.ProcessError(message, long_message=None)

Bases: spack.error.SpackError

ProcessErrors are raised when Executables exit with an error code.

spack.install_dependency_symlinks(pkg, spec, prefix)

Execute a dummy install and flatten dependencies

spack.flatten_dependencies(spec, flat_dir)

Make each dependency of spec present in dir via symlink.

exception spack.DependencyConflictError(conflict)

Bases: spack.error.SpackError

Raised when the dependencies cannot be flattened as asked for.

exception spack.InstallError(message, long_msg=None)

Bases: spack.error.SpackError

Raised when something goes wrong during install or uninstall.

exception spack.ExternalPackageError(message, long_msg=None)

Bases: spack.package.InstallError

Raised by install() when a package is only for external use.