Spack Package API¶

This document describes the Spack Package API (spack.package), the stable interface for Spack package authors. It is assumed you have already read the Spack Packaging Guide.

The Spack Package API is the only module in the Spack codebase considered public API. It re-exports essential functions and classes from various Spack modules, allowing package authors to import them directly from spack.package without needing to know Spack’s internal structure.

Spack Package API Versioning¶

The current Package API version is v2.5, defined in spack.package_api_version. Notice that the Package API is versioned independently from Spack itself:

The minor version is incremented when new functions or classes are exported from spack.package.
The major version is incremented when functions or classes are removed or have breaking changes to their signatures (a rare occurrence).

This independent versioning allows package authors to utilize new Spack features without waiting for a new Spack release.

Compatibility between Spack and package repositories is managed as follows:

Package repositories declare their minimum required Package API version in their repo.yaml file using the api: vX.Y format.
Spack checks if the declared API version falls within its supported range, specifically between spack.min_package_api_version and spack.package_api_version.

Spack version 1.2.0.dev0 supports package repositories with a Package API version between v1.0 and v2.5, inclusive.

Changelog¶

v2.5 (Spack v1.2.0)

Added cuda-lang and hip-lang as language virtuals, analogous to c, cxx, and fortran. Packages that use CUDA or HIP can now declare explicit language dependencies on these virtuals.

v2.4 (Spack v1.0.3)

The %% operator can be used on input specs to set propagated preferences, which is particularly useful for unify: false environments.

v2.3 (Spack v1.0.3)

The version() directive now supports the git_sparse_paths parameter, allowing sparse checkouts when fetching from git repositories.

v2.2 (Spack v1.0.0)

Renamed implicit builder attributes with backward compatibility:
- legacy_buildsystem to default_buildsystem,
- legacy_methods to package_methods,
- legacy_attributes to package_attributes,
- legacy_long_methods to package_long_methods.
Exported GenericBuilder, Package, and BuilderWithDefaults from spack.package.
Exported numerous utility functions and classes for file operations, library/header search, macOS/Windows support, compiler detection, and build system helpers.

v2.1 (Spack v1.0.0)

Exported CompilerError and SpackError from spack.package.

Spack Package API Reference¶

class spack.package.BaseBuilder(pkg: PackageBase)[source]¶

Bases: object

An interface for builders, without any phases defined. This class is exposed in the package API, so that packagers can create a single class to define setup_build_environment() and spack.phase_callbacks.run_before() and spack.phase_callbacks.run_after() callbacks that can be shared among different builders.

Example:

class AnyBuilder(BaseBuilder):
    @run_after("install")
    def fixup_install(self):
        # do something after the package is installed
        pass

    def setup_build_environment(self, env: EnvironmentModifications) -> None:
        env.set("MY_ENV_VAR", "my_value")


class CMakeBuilder(cmake.CMakeBuilder, AnyBuilder):
    pass


class AutotoolsBuilder(autotools.AutotoolsBuilder, AnyBuilder):
    pass

Added in version v2.0.

property prefix¶

setup_build_environment(env: EnvironmentModifications) → None[source]¶

Sets up the build environment for a package.

This method will be called before the current package prefix exists in Spack’s store.

Parameters:: env – environment modifications to be applied when the package is built. Package authors can call methods on it to alter the build environment.

setup_dependent_build_environment(env: EnvironmentModifications, dependent_spec: Spec) → None[source]¶

Sets up the build environment of a package that depends on this one.

This is similar to setup_build_environment, but it is used to modify the build environment of a package that depends on this one.

This gives packages the ability to set environment variables for the build of the dependent, which can be useful to provide search hints for headers or libraries if they are not in standard locations.

This method will be called before the dependent package prefix exists in Spack’s store.

Parameters:

env – environment modifications to be applied when the dependent package is built. Package authors can call methods on it to alter the build environment.
dependent_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

property spec: Spec¶

property stage¶

class spack.package.Builder(pkg: PackageBase)[source]¶

Bases: BaseBuilder, Sequence

A builder is a class that, given a package object (i.e. associated with concrete spec), knows how to install it.

The builder behaves like a sequence, and when iterated over return the phases of the installation in the correct order.

Added in version v2.0.

property archive_files: List[str]¶

build_system: str | None¶: Build system name. Must also be defined in derived classes.

build_time_test_callbacks: List[str]¶

install_time_test_callbacks: List[str]¶

legacy_attributes: Tuple[str, ...]¶

legacy_long_methods: Tuple[str, ...]¶

legacy_methods: Tuple[str, ...]¶

package_attributes: Tuple[str, ...]¶: Attributes that the adapter can find in Package classes, if a builder is not defined

package_long_methods: Tuple[str, ...]¶: Methods with the same signature as phases, that the adapter can find in Package classes, if a builder is not defined.

package_methods: Tuple[str, ...]¶: Methods, with no arguments, that the adapter can find in Package classes, if a builder is not defined.

phases: Tuple[str, ...]¶: Sequence of phases. Must be defined in derived classes

class spack.package.BuilderWithDefaults(pkg: PackageBase)[source]¶

Bases: Builder

Base class for all specific builders with common callbacks registered.

Added in version v2.2.

exception spack.package.CompilerError(message: str, long_message: str | None = None)[source]¶

Bases: SpackError

Raised if something goes wrong when probing or querying a compiler.

Added in version v2.1.

class spack.package.CompilerPropertyDetector(compiler_spec: Spec)[source]¶

Bases: object

Detects compiler properties of a given compiler spec. Useful for compiler wrappers.

Added in version v2.2.

compiler_environment()[source]¶: Sets the environment to run this compiler

compiler_verbose_output() → str | None[source]¶: Get the compiler verbose output from the cache or by compiling a dummy C source.

default_dynamic_linker() → str | None[source]¶: Determine the default dynamic linker path from the compiler verbose output.

default_libc() → Spec | None[source]¶: Determine libc targeted by the compiler from link line

implicit_rpaths() → List[str][source]¶: Obtain the implicit rpaths to be added from the default -L link directories, excluding system directories.

class spack.package.EnvironmentModifications(other: EnvironmentModifications | None = None, traced: None | bool = None)[source]¶

Bases: object

Tracks and applies a sequence of environment variable modifications.

This class provides a high-level interface for building up a list of environment changes, such as setting, unsetting, appending, prepending, or removing values from environment variables. Modifications are stored and can be applied to a given environment dictionary, or rendered as shell code.

Package authors typically receive an instance of this class and call set(), unset(), prepend_path(), remove_path(), etc., to queue up modifications. Spack runs apply_modifications() to apply these modifications to the environment when needed.

Modifications can be grouped by variable name, reversed (where possible), validated for suspicious patterns, and extended from other instances. The class also supports tracing the origin of modifications for debugging.

Example

env = EnvironmentModifications()
env.set("FOO", "bar")
env.prepend_path("PATH", "/custom/bin")
env.apply_modifications()  # applies changes to os.environ

Added in version v2.0.

append_flags(name: str, value: str, sep: str = ' ') → None[source]¶

Stores a request to append flags to an environment variable.

Parameters:

name – name of the environment variable
value – flags to be appended
sep – separator for the flags (default: " ")

append_path(name: str, path: str | PurePath, separator: str = os.pathsep) → None[source]¶

Stores a request to append a path to list of paths.

Parameters:

name – name of the environment variable
path – path to be appended
separator – separator for the paths (default: os.pathsep)

apply_modifications(env: MutableMapping[str, str] | None = None)[source]¶

Applies the modifications to the environment.

Parameters:: env – environment to be modified. If None, os.environ will be used.

clear()[source]¶: Clears the current list of modifications.

deprioritize_system_paths(name: str, separator: str = os.pathsep) → None[source]¶

Stores a request to deprioritize system paths in a path list, otherwise preserving the order.

Parameters:

name – name of the environment variable
separator – separator for the paths (default: os.pathsep)

drop(*name) → bool[source]¶: Drop all modifications to the variable with the given name.

extend(other: EnvironmentModifications)[source]¶: Extends the current instance with modifications from another instance.

static from_environment_diff(before: MutableMapping[str, str], after: MutableMapping[str, str], clean: bool = False) → EnvironmentModifications[source]¶

Constructs the environment modifications from the diff of two environments.

Parameters:

before – environment before the modifications are applied
after – environment after the modifications are applied
clean – in addition to removing empty entries, also remove duplicate entries

static from_sourcing_file(filename: str, *arguments: str, **kwargs: Any) → EnvironmentModifications[source]¶

Returns the environment modifications that have the same effect as sourcing the input file in a shell.

Parameters:

filename – the file to be sourced
*arguments – arguments to pass on the command line

Keyword Arguments:

shell (str) – the shell to use (default: bash)
shell_options (str) – options passed to the shell (default: -c)
source_command (str) – the command to run (default: source)
suppress_output (str) – redirect used to suppress output of command (default: &> /dev/null)
concatenate_on_success (str) – operator used to execute a command only when the previous command succeeds (default: &&)
exclude ([str or re.Pattern[str]]) – ignore any modifications of these variables (default: [])
include ([str or re.Pattern[str]]) – always respect modifications of these variables (default: []). Supersedes any excluded variables.
clean (bool) – in addition to removing empty entries, also remove duplicate entries (default: False).

group_by_name() → Dict[str, List[NameModifier | NameValueModifier]][source]¶: Returns a dict of the current modifications keyed by variable name.

is_unset(variable_name: str) → bool[source]¶: Returns True if the last modification to a variable is to unset it, False otherwise.

prepend_path(name: str, path: str | PurePath, separator: str = os.pathsep) → None[source]¶

Stores a request to prepend a path to list of paths.

Parameters:

name – name of the environment variable
path – path to be prepended
separator – separator for the paths (default: os.pathsep)

prune_duplicate_paths(name: str, separator: str = os.pathsep) → None[source]¶

Stores a request to remove duplicates from a path list, otherwise preserving the order.

Parameters:

name – name of the environment variable
separator – separator for the paths (default: os.pathsep)

remove_first_path(name: str, path: str | PurePath, separator: str = os.pathsep) → None[source]¶

Stores a request to remove first instance of path from a list of paths.

Parameters:

name – name of the environment variable
path – path to be removed
separator – separator for the paths (default: os.pathsep)

remove_flags(name: str, value: str, sep: str = ' ') → None[source]¶

Stores a request to remove flags from an environment variable

Parameters:

name – name of the environment variable
value – flags to be removed
sep – separator for the flags (default: " ")

remove_last_path(name: str, path: str | PurePath, separator: str = os.pathsep) → None[source]¶

Stores a request to remove last instance of path from a list of paths.

Parameters:

name – name of the environment variable
path – path to be removed
separator – separator for the paths (default: os.pathsep)

remove_path(name: str, path: str | PurePath, separator: str = os.pathsep) → None[source]¶

Stores a request to remove a path from a list of paths.

Parameters:

name – name of the environment variable
path – path to be removed
separator – separator for the paths (default: os.pathsep)

reversed() → EnvironmentModifications[source]¶

Returns the EnvironmentModifications object that will reverse self

Only creates reversals for additions to the environment, as reversing unset() and remove_path() modifications is impossible.

Reversible operations are set(), prepend_path(), append_path(), set_path(), and append_flags().

set(name: str, value: str, *, force: bool = False, raw: bool = False) → None[source]¶

Stores a request to set an environment variable.

Parameters:

name – name of the environment variable
value – value of the environment variable
force – if True, audit will not consider this modification a warning
raw – if True, format of value string is skipped

set_path(name: str, elements: List[str] | List[PurePath] | List[str | PurePath], separator: str = os.pathsep) → None[source]¶

Stores a request to set an environment variable to a list of paths, separated by a character defined in input.

Parameters:

name – name of the environment variable
elements – ordered list paths
separator – separator for the paths (default: os.pathsep)

shell_modifications(shell: str = DEFAULT_SHELL, explicit: bool = False, env: MutableMapping[str, str] | None = None) → str[source]¶: Return shell code to apply the modifications.

unset(name: str) → None[source]¶

Stores a request to unset an environment variable.

Parameters:: name – name of the environment variable

class spack.package.Executable(name: str | Path)[source]¶

Bases: object

Represent an executable file that can be run as a subprocess.

This class provides a simple interface for running executables with custom arguments and environment variables. It supports setting default arguments and environment modifications, copying instances, and running commands with various options for input/output/error handling.

Example usage:

ls = Executable("ls")
ls.add_default_arg("-l")
ls.add_default_env("LC_ALL", "C")
output = ls("-a", output=str)  # Run 'ls -l -a' and capture output as string

Added in version v2.0.

Runs this executable in a subprocess.

Parameters:

*args – command-line arguments to the executable to run
fail_on_error – if True, raises an exception if the subprocess returns an error The return code is available as returncode
ignore_errors – a sequence of error codes to ignore. If these codes are returned, this process will not raise an exception, even if fail_on_error is set to True
ignore_quotes – if False, warn users that quotes are not needed, as Spack does not use a shell. If None, use ignore_quotes.
timeout – the number of seconds to wait before killing the child process
env – the environment with which to run the executable
extra_env – extra items to add to the environment (neither requires nor precludes env)
input – where to read stdin from
output – where to send stdout
error – where to send stderr
_dump_env – dict to be set to the environment actually used (envisaged for testing purposes only)

Accepted values for input, output, and error:

Python streams: open Python file objects or os.devnull
str: the Python string type. If you set these to str, output and error will be written to pipes and returned as a string. If both output and error are set to str, then one string is returned containing output concatenated with error. Not valid for input.
str.split: the split method of the Python string type. Behaves the same as str, except that value is also written to stdout or stderr.

For output and error it’s also accepted to pass a string with a filename, which will be automatically opened for writing.

By default, the subprocess inherits the parent’s file descriptors.

add_default_arg(*args: str) → None[source]¶: Add default argument(s) to the command.

add_default_env(key: str, value: str) → None[source]¶

Set an environment variable when the command is run.

Parameters:

key – The environment variable to set
value – The value to set it to

add_default_envmod(envmod: EnvironmentModifications) → None[source]¶: Set an spack.util.environment.EnvironmentModifications to use when the command is run.

property command: str¶: Returns the entire command-line string

copy() → Executable[source]¶: Return a copy of this Executable.

ignore_quotes: bool¶: Whether to warn users that quotes are not needed, as Spack does not use a shell.

property name: str¶: Returns the executable name

property path: str¶: Returns the executable path

returncode: int¶: Return code of the last executed command.

with_default_args(*args: str) → Executable[source]¶: Same as add_default_arg, but returns a copy of the executable.

class spack.package.FileFilter(*filenames)[source]¶

Bases: object

Convenience class for repeatedly applying filter_file() to one or more files.

This class allows you to specify a set of filenames and then call filter() multiple times to perform search-and-replace operations using Python regular expressions, similar to sed.

Example usage:

foo_c = FileFilter("foo.c")
foo_c.filter(r"#define FOO", "#define BAR")
foo_c.filter(r"old_func", "new_func")

Added in version v2.0.

filter(regex: str, repl: str | Callable[[Match], str], string: bool = False, backup: bool = False, ignore_absent: bool = False, start_at: str | None = None, stop_at: str | None = None) → None[source]¶

class spack.package.FileList(files: str | Iterable[str])[source]¶

Bases: Sequence

Sequence of absolute paths to files.

Provides a few convenience methods to manipulate file paths.

Added in version v2.0.

property basenames: List[str]¶

Stable de-duplication of the base-names in the list

>>> l = LibraryList(["/dir1/liba.a", "/dir2/libb.a", "/dir3/liba.a"])
>>> l.basenames
["liba.a", "libb.a"]
>>> h = HeaderList(["/dir1/a.h", "/dir2/b.h", "/dir3/a.h"])
>>> h.basenames
["a.h", "b.h"]

Returns:: A list of base-names

property directories: List[str]¶

Stable de-duplication of the directories where the files reside.

>>> l = LibraryList(["/dir1/liba.a", "/dir2/libb.a", "/dir1/libc.a"])
>>> l.directories
["/dir1", "/dir2"]
>>> h = HeaderList(["/dir1/a.h", "/dir1/b.h", "/dir2/c.h"])
>>> h.directories
["/dir1", "/dir2"]

Returns:: A list of directories

joined(separator: str = ' ') → str[source]¶

class spack.package.GenericBuilder(pkg: PackageBase)[source]¶

Bases: BuilderWithDefaults

The associated builder for the Package base class. This class is typically only used in package.py files when a package has multiple build systems. Packagers need to implement the install() phase to define how the package is installed.

This is the only builder that is defined in the Spack core, all other builders are defined in the builtin package repository spack_repo.builtin.build_systems.

Example:

from spack.package import *

class MyPackage(Package):
    """A package that does not use a specific build system."""
    homepage = "https://example.com/mypackage"
    url = "https://example.com/mypackage-1.0.tar.gz"

    version("1.0", sha256="...")

class GenericBuilder(GenericBuilder):
    def install(self, pkg: Package, spec: Spec, prefix: Prefix) -> None:
        pass

Added in version v2.2.

build_system: str | None¶: Build system name. Must also be defined in derived classes.

install(pkg: Package, spec: Spec, prefix: Prefix) → None[source]¶: Install phase for the generic builder, to be implemented by packagers.

install_time_test_callbacks: List[str]¶: Callback names for post-install phase tests

package_attributes: Tuple[str, ...]¶: Names associated with package attributes in the old build-system format

package_methods: Tuple[str, ...]¶: Names associated with package methods in the old build-system format

phases: Tuple[str, ...]¶: A generic package has only the install phase

class spack.package.HKEY[source]¶

Bases: object

Predefined, open registry HKEYs From the Microsoft docs: An application must open a key before it can read data from the registry. To open a key, an application must supply a handle to another key in the registry that is already open. The system defines predefined keys that are always open. Predefined keys help an application navigate in the registry.

Added in version v2.2.

HKEY_CLASSES_ROOT¶

HKEY_CURRENT_CONFIG¶

HKEY_CURRENT_USER¶

HKEY_LOCAL_MACHINE¶

HKEY_PERFORMANCE_DATA¶

HKEY_USERS¶

class spack.package.HeaderList(files)[source]¶

Bases: FileList

Sequence of absolute paths to headers.

Provides a few convenience methods to manipulate header paths and get commonly used compiler flags or names.

Added in version v2.0.

add_macro(macro: str) → None[source]¶

Add a macro definition

Parameters:: macro – The macro to add

property cpp_flags: str¶

Include flags + macro definitions

>>> h = HeaderList(["/dir1/a.h", "/dir1/b.h", "/dir2/c.h"])
>>> h.cpp_flags
"-I/dir1 -I/dir2"
>>> h.add_macro("-DBOOST_DYN_LINK")
>>> h.cpp_flags
"-I/dir1 -I/dir2 -DBOOST_DYN_LINK"

Returns:: A joined list of include flags and macro definitions

property directories: List[str]¶: Directories to be searched for header files.

property headers: List[str]¶

Stable de-duplication of the headers.

Returns:: A list of header files

property include_flags: str¶

Include flags

>>> h = HeaderList(["/dir1/a.h", "/dir1/b.h", "/dir2/c.h"])
>>> h.include_flags
"-I/dir1 -I/dir2"

Returns:: A joined list of include flags

include_regex¶

property macro_definitions: str¶

Macro definitions

>>> h = HeaderList(["/dir1/a.h", "/dir1/b.h", "/dir2/c.h"])
>>> h.add_macro("-DBOOST_LIB_NAME=boost_regex")
>>> h.add_macro("-DBOOST_DYN_LINK")
>>> h.macro_definitions
"-DBOOST_LIB_NAME=boost_regex -DBOOST_DYN_LINK"

Returns:: A joined list of macro definitions

property names: List[str]¶

Stable de-duplication of header names in the list without extensions

>>> h = HeaderList(["/dir1/a.h", "/dir2/b.h", "/dir3/a.h"])
>>> h.names
["a", "b"]

Returns:: A list of files without extensions

exception spack.package.InstallError(message, long_msg=None, pkg=None)[source]¶

Bases: SpackError

Raised when something goes wrong during install or uninstall.

The error can be annotated with a pkg attribute to allow the caller to get the package for which the exception was raised.

Added in version v2.0.

spack.package.LC_ID_DYLIB¶: Constant for MachO LC_ID_DYLIB load command, from the macholib package (vendored in Spack).

Added in version v2.2.

class spack.package.LibraryList(files: str | Iterable[str])[source]¶

Bases: FileList

Sequence of absolute paths to libraries

Provides a few convenience methods to manipulate library paths and get commonly used compiler flags or names

Added in version v2.0.

property ld_flags: str¶

Search flags + link flags

>>> l = LibraryList(["/dir1/liba.a", "/dir2/libb.a", "/dir1/liba.so"])
>>> l.ld_flags
"-L/dir1 -L/dir2 -la -lb"

Returns:: A joined list of search flags and link flags

property libraries: List[str]¶

Stable de-duplication of library files.

Returns:: A list of library files

property link_flags: str¶

Link flags for the libraries

>>> l = LibraryList(["/dir1/liba.a", "/dir2/libb.a", "/dir1/liba.so"])
>>> l.link_flags
"-la -lb"

Returns:: A joined list of link flags

property names: List[str]¶

Stable de-duplication of library names in the list

>>> l = LibraryList(["/dir1/liba.a", "/dir2/libb.a", "/dir3/liba.so"])
>>> l.names
["a", "b"]

Returns:: A list of library names

property search_flags: str¶

Search flags for the libraries

>>> l = LibraryList(["/dir1/liba.a", "/dir2/libb.a", "/dir1/liba.so"])
>>> l.search_flags
"-L/dir1 -L/dir2"

Returns:: A joined list of search flags

class spack.package.LinkTree(source_root)[source]¶

Bases: object

Class to create trees of symbolic links from a source directory.

LinkTree objects are constructed with a source root. Their methods allow you to create and delete trees of symbolic links back to the source tree in specific destination directories. Trees comprise symlinks only to files; directories are never symlinked to, to prevent the source directory from ever being modified.

Added in version v2.2.

find_conflict(dest_root, ignore=None, ignore_file_conflicts=False)[source]¶: Returns the first file in dest that conflicts with src

find_dir_conflicts(dest_root, ignore)[source]¶

get_file_map(dest_root, ignore)[source]¶

merge(dest_root, ignore_conflicts: bool = False, ignore: Callable[[str], bool] | None = None, link: Callable = fs.symlink, relative: bool = False)[source]¶

Link all files in src into dest, creating directories if necessary.

Parameters:

ignore_conflicts – if True, do not break when the target exists; return a list of files that could not be linked
ignore – callable that returns True if a file is to be ignored in the merge (by default ignore nothing)
link – function to create links with (defaults to spack.llnl.util.filesystem.symlink)
relative – create all symlinks relative to the target (default False)

merge_directories(dest_root, ignore)[source]¶

unmerge(dest_root, ignore=None, remove_file=remove_link)[source]¶

Unlink all files in dest that exist in src.

Unlinks directories in dest if they are empty.

unmerge_directories(dest_root, ignore)[source]¶

class spack.package.MachO(filename, allow_unknown_load_commands=False)[source]¶

Bases: object

MachO class from the macholib package (vendored in Spack).

Added in version v2.2.

load(fh)[source]¶

load_fat(fh)[source]¶

load_header(fh, offset, size)[source]¶

rewriteLoadCommands(*args, **kw)[source]¶

write(f)[source]¶

class spack.package.MakeExecutable(name: str, *, jobs: int, supports_jobserver: bool = True)[source]¶

Bases: Executable

Special callable executable object for make so the user can specify parallelism options on a per-invocation basis.

Added in version v2.0.

Runs this make executable in a subprocess.

Parameters:

parallel – if False, parallelism is disabled
jobs_env – environment variable that will be set to the current level of parallelism
jobs_env_supports_jobserver – whether the jobs env supports a job server

For all the other **kwargs, refer to spack.util.executable.Executable.__call__().

class spack.package.ModuleChangePropagator(package: PackageBase)[source]¶

Bases: object

The function spack.package_base.PackageBase.setup_dependent_package() receives an instance of this class for the module argument. It’s used to set global variables in the module of a package, and propagate those globals to the modules of all classes in the inheritance hierarchy of the package. It’s reminiscent of spack.util.environment.EnvironmentModifications, but sets Python variables instead of environment variables. This class should typically not be instantiated in packages directly.

Added in version v2.2.

propagate_changes_to_mro()[source]¶

exception spack.package.NoHeadersError(message: str, long_message: str | None = None)[source]¶

Bases: SpackError

Raised when package headers are requested but cannot be found

Added in version v2.0.

exception spack.package.NoLibrariesError(message_or_name, prefix=None)[source]¶

Bases: SpackError

Raised when package libraries are requested but cannot be found

Added in version v2.0.

class spack.package.Package(spec: Spec)[source]¶

Bases: PackageBase

Build system base class for packages that do not use a specific build system. It adds the build_system=generic variant to the package.

This is the only build system base class defined in Spack core. All other build systems are defined in the builtin package repository spack_repo.builtin.build_systems.

The associated builder is GenericBuilder, which is only necessary when the package has multiple build systems.

Example:

from spack.package import *

class MyPackage(Package):
    """A package that does not use a specific build system."""

    homepage = "https://example.com/mypackage"
    url = "https://example.com/mypackage-1.0.tar.gz"

    version("1.0", sha256="...")

    def install(self, spec: Spec, prefix: Prefix) -> None:
        # Custom installation logic here
        pass

Note

The difference between Package and PackageBase is that PackageBase is the universal base class for all package classes, no matter their build system.

The Package class is a build system base class, similar to CMakePackage, and AutotoolsPackage. It is called Package and not GenericPackage for legacy reasons.

Added in version v2.2.

build_system_class: str¶: This attribute is used in UI queries that require to know which build-system class we are using

conflicts: Dict[Spec, List[Tuple[Spec, str | None]]]¶: Class level dictionary populated by conflicts() directives

default_buildsystem: str¶: Legacy buildsystem attribute used to deserialize and install old specs

dependencies: Dict[Spec, Dict[str, Dependency]]¶: Class level dictionary populated by depends_on() and extends() directives

disable_redistribute: Dict[Spec, DisableRedistribute]¶: Class level dictionary populated by redistribute() directives

extendees: Dict[str, Tuple[Spec, Spec]]¶: Class level dictionary populated by extends() directives

legacy_buildsystem: str¶: Use default_buildsystem instead of this attribute, which is deprecated

licenses: Dict[Spec, str]¶: Class level dictionary populated by license() directives

patches: Dict[Spec, List[Patch]]¶: Class level dictionary populated by patch() directives

provided: Dict[Spec, Set[Spec]]¶: Class level dictionary populated by provides() directives

provided_together: Dict[Spec, List[Set[str]]]¶: Class level dictionary populated by provides() directives

requirements: Dict[Spec, List[Tuple[Tuple[Spec, ...], str, str | None]]]¶: Class level dictionary populated by requires() directives

resources: Dict[Spec, List[Resource]]¶: Class level dictionary populated by resource() directives

splice_specs: Dict[Spec, Tuple[Spec, None | str | List[str]]]¶: Class level dictionary populated by can_splice() directives

variants: Dict[Spec, Dict[str, Variant]]¶: Class level dictionary populated by variant() directives

versions: Dict[StandardVersion, Dict[str, Any]]¶: Class level dictionary populated by version() directives

class spack.package.PackageBase(spec: Spec)[source]¶

Bases: WindowsRPath, PackageViewMixin

This is the universal base class for all Spack packages.

At its core, a package consists of a set of software to be installed. A package may focus on a piece of software and its associated software dependencies or it may simply be a set, or bundle, of software. The former requires defining how to fetch, verify (via, e.g., sha256), build, and install that software and the packages it depends on, so that dependencies can be installed along with the package itself. The latter, sometimes referred to as a “no-source” package, requires only defining the packages to be built.

There are two main parts of a Spack package:

The package class. Classes contain directives, which are functions such as spack.package.version(), spack.package.patch(), and spack.package.depends_on(), that store metadata on the package class. Directives provide the constraints that are used as input to the concretizer.
Package instances. Once instantiated with a concrete spec, a package can be passed to the spack.installer.PackageInstaller. It calls methods like do_stage() on the package instance, and it uses those to drive user-implemented methods like def patch and install phases like def configure and def install.

Packages are imported from package repositories (see spack.repo).

For most use cases, package creators typically just add attributes like homepage and, for a code-based package, url, or installation phases such as install(). There are many custom PackageBase subclasses in the spack_repo.builtin.build_systems package that make things even easier for specific build systems.

Note

Many methods and attributes that appear to be public interface are not meant to be overridden by packagers. They are “final”, but we currently have not adopted the @final decorator in the Spack codebase. For example, the do_* functions are intended only to be called internally by Spack commands. These aren’t for package writers to override, and doing so may break the functionality of the PackageBase class.

Added in version v2.0.

classmethod all_patches()[source]¶

Retrieve all patches associated with the package.

Retrieves patches on the package itself as well as patches on the dependencies of the package.

property all_urls: List[str]¶

A list of all URLs in a package.

Check both class-level and version-specific URLs.

Returns a list of URLs

all_urls_for_version(version: StandardVersion) → List[str][source]¶

Return all URLs derived from version_urls(), url, urls, and list_url (if it contains a version) in a package in that order.

Parameters:: version – the version for which a URL is sought

archive_install_test_log()[source]¶: Archive the install-phase test log, if present.

build_system_class: str¶: Used when reporting the build system to users

classmethod build_system_flags(name: str, flags: Iterable[str]) → Tuple[Iterable[str] | None, Iterable[str] | None, Iterable[str] | None][source]¶: See spack.package.build_system_flags().

property cmake_prefix_paths: List[str]¶: Return a list of paths to be used in CMake’s CMAKE_PREFIX_PATH.

property command: Executable¶: Returns the main executable for this package.

compiler¶

property configure_args_path¶: Return the configure args file path associated with staging.

conflicts: Dict[Spec, List[Tuple[Spec, str | None]]]¶: Class level dictionary populated by conflicts() directives

content_hash(content: bytes | None = None) → str[source]¶

Create a hash based on the artifacts and patches used to build this package.

This includes:

source artifacts (tarballs, repositories) used to build;
content hashes (sha256’s) of all patches applied by Spack; and
canonicalized contents the package.py recipe used to build.

This hash is only included in Spack’s DAG hash for concrete specs, but if it happens to be called on a package with an abstract spec, only applicable (i.e., determinable) portions of the hash will be included.

default_buildsystem: str¶: Must be defined as a fallback for old specs that don’t have the build_system variant

dependencies: Dict[Spec, Dict[str, Dependency]]¶: Class level dictionary populated by depends_on() and extends() directives

classmethod dependencies_by_name(when: bool = False)[source]¶

classmethod dependencies_of_type(deptypes: int)[source]¶

Get names of dependencies that can possibly have these deptypes.

This analyzes the package and determines which dependencies can be a certain kind of dependency. Note that they may not always be this kind of dependency, since dependencies can be optional, so something may be a build dependency in one configuration and a run dependency in another.

classmethod dependency_names()[source]¶

detect_dev_src_change() → bool[source]¶: Method for checking for source code changes to trigger rebuild/reinstall

disable_redistribute: Dict[Spec, DisableRedistribute]¶: Class level dictionary populated by redistribute() directives

do_clean()[source]¶: Removes the package’s build stage and source tarball.

do_fetch(mirror_only=False)[source]¶: Creates a stage directory and downloads the tarball for this package. Working directory will be set to the stage directory.

do_patch()[source]¶: Applies patches if they haven’t been applied already.

do_restage()[source]¶: Reverts expanded/checked out source to a pristine state.

do_stage(mirror_only=False)[source]¶: Unpacks and expands the fetched tarball.

do_test(*, dirty=False, externals=False, timeout: int | None = None)[source]¶

do_uninstall(force=False)[source]¶: Uninstall this package by spec.

property download_instr: str¶

Defines the default manual download instructions. Packages can override the property to provide more information.

Returns:: default manual download instructions

classmethod env_flags(name: str, flags: Iterable[str]) → Tuple[Iterable[str] | None, Iterable[str] | None, Iterable[str] | None][source]¶: See spack.package.env_flags().

property env_mods_path¶: Return the build environment modifications file path associated with staging.

property env_path¶: Return the build environment file path associated with staging.

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

property extendee_spec: Spec | None¶: Spec of the extendee of this package, or None if it is not an extension.

extendees: Dict[str, Tuple[Spec, Spec]]¶: Class level dictionary populated by extends() directives

extends(spec: Spec) → bool[source]¶

Returns True if this package extends the given spec.

If self.spec is concrete, this returns whether this package extends the given spec.

If self.spec is not concrete, this returns whether this package may extend the given spec.

fetch_options: Dict[str, Any]¶: Set of additional options used when fetching package versions.

fetch_remote_versions(concurrency: int | None = None) → Dict[StandardVersion, str][source]¶

Find remote versions of this package.

Uses list_url and any other URLs listed in the package file.

Returns:: a dictionary mapping versions to URLs

property fetcher¶

find_valid_url_for_version(version: StandardVersion) → str | None[source]¶

Returns a URL from which the specified version of this package may be downloaded after testing whether the url is valid. Will try url, urls, and list_url before failing.

Parameters:: version – The version for which a URL is sought.

property flag_handler: Callable[[str, Iterable[str]], Tuple[Iterable[str] | None, Iterable[str] | None, Iterable[str] | None]]¶

flags_to_build_system_args(flags: Dict[str, List[str]]) → None[source]¶

classmethod format_doc(**kwargs)[source]¶: Wrap doc string at 72 characters and format nicely

fullname¶: Name of this package, including the namespace

fullnames¶: Fullnames for this package and any packages from which it inherits.

get_variant(name: str) → Variant[source]¶

Get the highest precedence variant definition matching this package’s spec.

Parameters:: name – name of the variant definition to get

global_license_dir¶: Returns the directory where license files for all packages are stored.

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

has_code: bool¶: Most Spack packages are used to install source or binary code while those that do not can be used to install a set of other Spack packages.

classmethod has_variant(name) → bool[source]¶

property home¶

homepage: str | None | classproperty[str | None]¶: Package homepage where users can find more information about the package

classmethod inject_flags(name: str, flags: Iterable[str]) → Tuple[Iterable[str] | None, Iterable[str] | None, Iterable[str] | None][source]¶: See spack.package.inject_flags().

property install_configure_args_path¶: Return the configure args file path on successful installation.

property install_env_path¶: Return the build environment file path on successful installation.

property install_log_path¶: Return the (compressed) build log file path on successful installation

intersects(spec: Spec) → bool[source]¶

Context-ful intersection that takes into account package information.

By design, Spec.intersects() does not know anything about package metadata. This avoids unnecessary package lookups and keeps things efficient where extra information is not needed, and it decouples Spec from PackageBase.

In many cases, though, we can rule more cases out in intersects() if we know, for example, that certain variants are always single-valued, or that certain variants are conditional on other variants. This adds logic for such cases when they are knowable.

Note that because intersects() is conservative, it can only give false positives (“i.e., the two specs may overlap”), not false negatives. This method can fix false positives (i.e. it may return False when Spec.intersects() would return True, but it will never return True when Spec.intersects() returns False.

property is_extension¶

property keep_werror: Literal['all', 'specific', 'none'] | None¶

Keep -Werror flags, matches config:flags:keep_werror to override config.

Valid return values are:

"all": keep all -Werror flags.
"specific": keep only -Werror=specific-warning flags.
"none": filter out all -Werror* flags.
None: respect the user’s configuration ("none" by default).

legacy_buildsystem: str¶: Use default_buildsystem instead of this attribute, which is deprecated

license_comment: str¶: Contains the symbol used by the license manager to denote a comment. Defaults to #.

license_files: List[str]¶: These are files that the software searches for when looking for a license. All file paths must be relative to the installation directory. More complex packages like Intel may require multiple licenses for individual components. Defaults to the empty list.

license_required: bool¶: If set to True, this software requires a license. If set to False, all of the license_* attributes will be ignored. Defaults to False.

license_url: str¶: A URL pointing to license setup instructions for the software. Defaults to the empty string.

license_vars: List[str]¶: Environment variables that can be set to tell the software where to look for a license if it is not in the usual location. Defaults to the empty list.

licenses: Dict[Spec, str]¶: Class level dictionary populated by license() directives

list_depth: int¶: Link depth to which list_url should be searched for new versions

list_url: str | None | classproperty[str | None]¶: Default list URL (place to find available versions)

property log_path¶: Return the build log file path associated with staging.

maintainers: List[str]¶: List of GitHub usernames of package maintainers. Do not include @ here in order not to unnecessarily ping the users.

manual_download: bool¶: Boolean. Set to True for packages that require a manual download. This is currently used by package sanity tests and generation of a more meaningful fetch failure error.

property metadata_dir¶: Return the install metadata directory.

module¶

Module instance that this package class is defined in.

We use this to add variables to package modules. This makes install() methods easier to write (e.g., can call configure())

name¶: The name of this package.

namespace¶: Spack namespace for the package, which identifies its repo.

nearest_url(version)[source]¶

Finds the URL with the “closest” version to version.

This uses the following precedence order:

Find the next lowest or equal version with a URL.
If no lower URL, return the next higher URL.
If no higher URL, return None.

classmethod needs_commit(version) → bool[source]¶: Method for checking if the package instance needs a commit sha to be found

non_bindable_shared_objects: List[str]¶: List of shared objects that should be replaced with a different library at runtime. Typically includes stub libraries like libcuda.so. When linking against a library listed here, the dependent will only record its soname or filename, not its absolute path, so that the dynamic linker will search for it. Note: accepts both file names and directory names, for example ["libcuda.so", "stubs"] will ensure libcuda.so and all libraries in the stubs directory are not bound by path.

classmethod num_variant_definitions() → int[source]¶: Total number of variant definitions in this class so far.

package_dir¶: Directory where the package.py file lives.

parallel: bool¶: By default we build in parallel. Subclasses can override this.

patches: Dict[Spec, List[Patch]]¶: Class level dictionary populated by patch() directives

property phase_log_files¶: Find sorted phase log files written to the staging directory

property prefix¶: Get the prefix into which this package should be installed.

provided: Dict[Spec, Set[Spec]]¶: Class level dictionary populated by provides() directives

provided_together: Dict[Spec, List[Set[str]]]¶: Class level dictionary populated by provides() directives

classmethod provided_virtual_names()[source]¶: Return sorted list of names of virtuals that can be provided by this package.

provides(vpkg_name: str) → bool[source]¶: True if this package provides a virtual package with the specified name

property redistribute_binary¶: Whether it should be possible to create a binary out of an installed instance of this package.

classmethod redistribute_source(spec)[source]¶: Whether it should be possible to add the source of this package to a Spack mirror.

remove_prefix()[source]¶: Removes the prefix for a package along with any empty parent directories

requirements: Dict[Spec, List[Tuple[Tuple[Spec, ...], str, str | None]]]¶: Class level dictionary populated by requires() directives

resolve_binary_provenance()[source]¶: Method to ensure concrete spec has binary provenance. Base implementation will look up git commits when appropriate. Packages may override this implementation for custom implementations

resources: Dict[Spec, List[Resource]]¶: Class level dictionary populated by resource() directives

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

property rpath_args¶: Get the rpath args as a string, with -Wl,-rpath, for each element

run_tests: bool¶: By default do not run tests within package’s install()

sanity_check_is_dir: List[str]¶: 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_is_file: List[str]¶: 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.

setup_dependent_package(module, dependent_spec: Spec) → None[source]¶

Set up module-scope global variables for dependent packages.

This function is called when setting up the build and run environments of a DAG.

Examples:

Extensions often need to invoke the python interpreter from the Python installation being extended. This routine can put a python Executable as a global in the module scope for the extension package to simplify extension installs.
MPI compilers could set some variables in the dependent’s scope that point to mpicc, mpicxx, etc., allowing them to be called by common name regardless of which MPI is used.

Parameters:

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 – 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.

setup_dependent_run_environment(env: EnvironmentModifications, dependent_spec: Spec) → None[source]¶

Sets up the run environment of packages that depend on this one.

This is similar to setup_run_environment, but it is used to modify the run environment of a package that depends on this one.

This gives packages like Python and others that follow the extension model a way to implement common environment or run-time settings for dependencies.

Parameters:

env – environment modifications to be applied when the dependent package is run. Package authors can call methods on it to alter the build environment.
dependent_spec – The spec of the dependent package about to be run. This allows the extendee (self) to query the dependent’s state. Note that this package’s spec is available as self.spec

setup_run_environment(env: EnvironmentModifications) → None[source]¶

Sets up the run environment for a package.

Parameters:: env – environment modifications to be applied when the package is run. Package authors can call methods on it to alter the run environment.

splice_specs: Dict[Spec, Tuple[Spec, None | str | List[str]]]¶: Class level dictionary populated by can_splice() directives

property stage¶

Get the build staging area for this package.

This automatically instantiates a Stage object if the package doesn’t have one yet, but it does not create the Stage directory on the filesystem.

test_requires_compiler: bool¶: Set to True to indicate the stand-alone test requires a compiler. It is used to ensure a compiler and build dependencies like cmake are available to build a custom test code.

test_suite: Any | None¶: TestSuite instance used to manage stand-alone tests for 1+ specs.

property tester¶

property times_log_path¶: Return the times log json file.

transitive_rpaths: bool¶: When True, add RPATHs for the entire DAG. When False, add RPATHs only for immediate dependencies.

static uninstall_by_spec(spec, force=False, deprecator=None)[source]¶

unresolved_libraries: List[str]¶: List of fnmatch patterns of library file names (specifically DT_NEEDED entries) that are not expected to be locatable in RPATHs. Generally this is a problem, and Spack install with config:shared_linking:strict will cause install failures if such libraries are found. However, in certain cases it can be hard if not impossible to avoid accidental linking against system libraries; until that is resolved, this attribute can be used to suppress errors.

url_for_version(version: str | StandardVersion) → str[source]¶

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

Parameters:: version – The version for which a URL is sought.

url_version(version)[source]¶

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.

classmethod validate_variant_names(spec: Spec)[source]¶

Check that all variant names on Spec exist in this package.

Raises UnknownVariantError if invalid variants are on the spec.

classmethod variant_definitions(name: str) → List[Tuple[Spec, Variant]][source]¶: Iterator over (when_spec, Variant) for all variant definitions for a particular name.

classmethod variant_items() → Iterable[Tuple[Spec, Dict[str, Variant]]][source]¶: Iterate over cls.variants.items() with overridden definitions removed.

classmethod variant_names() → List[str][source]¶

variants: Dict[Spec, Dict[str, Variant]]¶: Class level dictionary populated by variant() directives

property version¶

classmethod version_or_package_attr(attr, version, default=NO_DEFAULT)[source]¶: Get an attribute that could be on the version or package with preference to the version

classmethod version_urls() → Dict[StandardVersion, str][source]¶

Dict of explicitly defined URLs for versions of this package.

Returns:: An dict mapping version to url, ordered by version.

A version’s URL only appears in the result if it has an an explicitly defined url argument. So, this list may be empty if a package only defines url at the top level.

versions: Dict[StandardVersion, Dict[str, Any]]¶: Class level dictionary populated by version() directives

view()[source]¶: Create a view with the prefix of this package as the root. Extensions added to this view will modify the installation prefix of this package.

virtual: bool¶: By default, packages are not virtual Virtual packages override this attribute

property virtuals_provided¶: virtual packages provided by this package with its spec

class spack.package.Prefix[source]¶

Bases: str

This class represents an installation prefix, but provides useful attributes for referring to directories inside the prefix.

Attributes of this object are created on the fly when you request them, so any of the following are valid:

>>> prefix = Prefix("/usr")
>>> prefix.bin
/usr/bin
>>> prefix.lib64
/usr/lib64
>>> prefix.share.man
/usr/share/man
>>> prefix.foo.bar.baz
/usr/foo/bar/baz
>>> prefix.join("dashed-directory").bin64
/usr/dashed-directory/bin64

Prefix objects behave identically to strings. In fact, they subclass str, so operators like + are legal:

print("foobar " + prefix)

This prints foobar /usr. All of this is meant to make custom installs easy.

Added in version v2.0.

join(string: str) → Prefix[source]¶

Concatenate a string to a prefix.

Useful for strings that are not valid variable names. This includes strings containing characters like - and ..

Parameters:: string – the string to append to the prefix
Returns:: the newly created installation prefix

exception spack.package.ProcessError(message: str, long_message: str | None = None)[source]¶

Bases: SpackError

Raised when Executable exits with an error code.

Added in version v2.0.

exception spack.package.SkipTest[source]¶

Bases: Exception

Raised when a test (part) is being skipped.

Added in version v2.0.

exception spack.package.SpackError(message: str, long_message: str | None = None)[source]¶

Bases: Exception

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

Added in version v2.1.

die()[source]¶

property long_message¶

print_context()[source]¶

Print extended debug information about this exception.

This is usually printed when the top-level Spack error handler calls die(), but it can be called separately beforehand if a lower-level error handler needs to print error context and continue without raising the exception to the top level.

class spack.package.Spec(spec_like=None, *, external_path=None, external_modules=None)[source]¶

Bases: object

Added in version v2.0.

add_dependency_edge(dependency_spec: Spec, *, depflag: int, virtuals: Tuple[str, ...], direct: bool = False, propagation: PropagationPolicy = PropagationPolicy.NONE, when: Spec | None = None)[source]¶

Add a dependency edge to this spec.

Parameters:

dependency_spec – spec of the dependency
depflag – dependency type for this edge
virtuals – virtuals provided by this edge
direct – if True denotes a direct dependency
propagation – propagation policy for this edge
when – if non-None, condition under which dependency holds

property anonymous¶

attach_git_version_lookup()[source]¶

property build_spec¶

cformat(format_string: str = DEFAULT_FORMAT) → str[source]¶: Same as format(), but color defaults to auto instead of False.

clear_caches(ignore: Tuple[str, ...] = ()) → None[source]¶: Clears all cached hashes in a Spec, while preserving other properties.

clear_dependencies()[source]¶: Trim the dependencies of this spec.

clear_edges()[source]¶: Trim the dependencies and dependents of this spec.

property clong_spec¶: Returns an auto-colorized version of long_spec.

property colored_str: str¶: Auto-colorized string representation of this spec.

compiler¶

property compilers¶

property concrete¶

A spec is concrete if it describes a single build of a package.

More formally, a spec is concrete if concretize() has been called on it and it has been marked _concrete.

Concrete specs either can be or have been built. All constraints have been resolved, optional dependencies have been added or removed, a compiler has been chosen, and all variants have values.

constrain(other, deps=True) → bool[source]¶

Constrains self with other, and returns True if self changed, False otherwise.

Parameters:

other – constraint to be added to self
deps – if False, constrain only the root node, otherwise constrain dependencies as well

Raises:

spack.error.UnsatisfiableSpecError – when self cannot be constrained

constrained(other, deps=True)[source]¶: Return a constrained copy without modifying this spec.

copy(deps: bool | str | List[str] | Tuple[str, ...] | int = True, **kwargs)[source]¶

Make a copy of this spec.

Parameters:

deps – Defaults to True. If boolean, controls whether dependencies are copied (copied if True). If a DepTypes or DepFlag is provided, only matching dependencies are copied.
kwargs – additional arguments for internal use (passed to _dup).

Returns:

A copy of this spec.

Examples

Deep copy with dependencies:

spec.copy()
spec.copy(deps=True)

Shallow copy (no dependencies):

spec.copy(deps=False)

Only build and run dependencies:

deps=("build", "run"):

property cshort_spec¶: Returns an auto-colorized version of short_spec.

dag_hash(length=None)[source]¶

This is Spack’s default hash, used to identify installations.

NOTE: Versions of Spack prior to 0.18 only included link and run deps. NOTE: Versions of Spack prior to 1.0 only did not include test deps.

dag_hash_bit_prefix(bits)[source]¶: Get the first <bits> bits of the DAG hash as an integer type.

static default_arch()[source]¶: Return an anonymous spec for the default architecture

Returns a list of direct dependencies (nodes in the DAG)

Parameters:

name – filter dependencies by package name
deptype – allowed dependency types
virtuals – allowed virtuals

dependents(name: str | None = None, deptype: str | List[str] | Tuple[str, ...] | int = dt.ALL) → List[Spec][source]¶

Return a list of direct dependents (nodes in the DAG).

Parameters:

name – filter dependents by package name
deptype – allowed dependency types

detach(deptype='all')[source]¶

Remove any reference that dependencies have of this node.

Parameters:: deptype (str or tuple) – dependency types tracked by the current spec

property edge_attributes: str¶: Helper method to print edge attributes in spec strings.

edges_from_dependents(name: str | None = None, depflag: int = dt.ALL, *, virtuals: str | Sequence[str] | None = None) → List[DependencySpec][source]¶

Return a list of edges connecting this node in the DAG to parents.

Parameters:

name – filter dependents by package name
depflag – allowed dependency types
virtuals – allowed virtuals

edges_to_dependencies(name: str | None = None, depflag: int = dt.ALL, *, virtuals: str | Sequence[str] | None = None) → List[DependencySpec][source]¶

Returns a list of edges connecting this node in the DAG to children.

Parameters:

name – filter dependencies by package name
depflag – allowed dependency types
virtuals – allowed virtuals

static ensure_no_deprecated(root: Spec) → None[source]¶

Raise if a deprecated spec is in the dag of the given root spec.

Raises:: spack.spec.SpecDeprecatedError – if any deprecated spec is found

static ensure_valid_variants(spec: Spec) → None[source]¶

Ensures that the variant attached to the given spec are valid.

Raises:: spack.variant.UnknownVariantError – on the first unknown variant found

eq_dag(other, deptypes=True, vs=None, vo=None)[source]¶: True if the full dependency DAGs of specs are equal.

eq_node(other)[source]¶: Equality with another spec, not including dependencies.

property external¶

property external_path¶

static extract_json_from_clearsig(data)[source]¶

format(format_string: str = DEFAULT_FORMAT, color: bool | None = False, *, highlight_version_fn: Callable[[Spec], bool] | None = None, highlight_variant_fn: Callable[[Spec, str], bool] | None = None) → str[source]¶

Prints out attributes of a spec according to a format string.

Using an {attribute} format specifier, any field of the spec can be selected. Those attributes can be recursive. For example, s.format({compiler.version}) will print the version of the compiler.

If the attribute in a format specifier evaluates to None, then the format specifier will evaluate to the empty string, "".

Commonly used attributes of the Spec for format strings include:

name
version
compiler_flags
compilers
variants
architecture
architecture.platform
architecture.os
architecture.target
prefix
namespace

Some additional special-case properties can be added:

hash[:len]    The DAG hash with optional length argument
spack_root    The spack root directory
spack_install The spack install directory

The ^ sigil can be used to access dependencies by name. s.format({^mpi.name}) will print the name of the MPI implementation in the spec.

The @, %, and / sigils can be used to include the sigil with the printed string. These sigils may only be used with the appropriate attributes, listed below:

@: {@version}, {@compiler.version}
%: {%compiler}, {%compiler.name}
/: {/hash}, {/hash:7}, etc

The @ sigil may also be used for any other property named version. Sigils printed with the attribute string are only printed if the attribute string is non-empty, and are colored according to the color of the attribute.

Variants listed by name naturally print with their sigil. For example, spec.format("{variants.debug}") prints either +debug or ~debug depending on the name of the variant. Non-boolean variants print as name=value. To print variant names or values independently, use spec.format("{variants.<name>.name}") or spec.format("{variants.<name>.value}").

There are a few attributes on specs that can be specified as key-value pairs that are not variants, e.g.: os, arch, architecture, target, namespace, etc. You can format these with an optional key= prefix, e.g. {namespace=namespace} or {arch=architecture}, etc. The key= prefix will be colorized along with the value.

When formatting specs, key-value pairs are separated from preceding parts of the spec by whitespace. To avoid printing extra whitespace when the formatted attribute is not set, you can add whitespace to the key inside the braces of the format string, e.g.:

{ namespace=namespace}

This evaluates to " namespace=builtin" if namespace is set to builtin, and to "" if namespace is None.

Spec format strings use \ as the escape character. Use \{ and \} for literal braces, and \\ for the literal \ character.

Parameters:

format_string – string containing the format to be expanded
color – True for colorized result; False for no color; None for auto color.
highlight_version_fn – optional callable that returns true on nodes where the version needs to be highlighted
highlight_variant_fn – optional callable that returns true on variants that need to be highlighted

format_path(format_string: str, _path_ctor: Callable[[Any], PurePath] | None = None) → str[source]¶

Given a format_string that is intended as a path, generate a string like from format(), but eliminate extra path separators introduced by formatting of Spec properties.

Path separators explicitly added to the string are preserved, so for example {name}/{version} would generate a directory based on the Spec’s name, and a subdirectory based on its version; this function guarantees though that the resulting string would only have two directories (i.e. that if under normal circumstances that str(self.version) would contain a path separator, it would not in this case).

static from_detection(spec_str: str, *, external_path: str, external_modules: List[str] | None = None, extra_attributes: Dict | None = None) → Spec[source]¶

Construct a spec from a spec string determined during external detection and attach extra attributes to it.

Parameters:

spec_str – spec string
external_path – prefix of the external spec
external_modules – optional module files to be loaded when the external spec is used
extra_attributes – dictionary containing extra attributes

static from_dict(data) → Spec[source]¶

Construct a spec from JSON/YAML.

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

static from_json(stream) → Spec[source]¶

Construct a spec from JSON.

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

static from_literal(spec_dict: dict, normal: bool = True) → Spec[source]¶

Builds a Spec from a dictionary containing the spec literal.

The dictionary must have a single top level key, representing the root, and as many secondary level keys as needed in the spec.

The keys can be either a string or a Spec or a tuple containing the Spec and the dependency types.

Parameters:

spec_dict – the dictionary containing the spec literal
normal – if True the same key appearing at different levels of the spec_dict will map to the same object in memory.

Examples

A simple spec foo with no dependencies:

{"foo": None}

A spec foo with a (build, link) dependency bar:

{"foo":
    {"bar:build,link": None}
}

A spec with a diamond dependency and various build types:

{"dt-diamond": {
    "dt-diamond-left:build,link": {
        "dt-diamond-bottom:build": None
    },
    "dt-diamond-right:build,link": {
        "dt-diamond-bottom:build,link,run": None
    }
}}

The same spec with a double copy of dt-diamond-bottom and no diamond structure:

Spec.from_literal({"dt-diamond": {
    "dt-diamond-left:build,link": {
        "dt-diamond-bottom:build": None
    },
    "dt-diamond-right:build,link": {
        "dt-diamond-bottom:build,link,run": None
    }
}, normal=False}

Constructing a spec using a Spec object as key:

mpich = Spec("mpich")
libelf = Spec("libelf@1.8.11")
expected_normalized = Spec.from_literal({
    "mpileaks": {
        "callpath": {
            "dyninst": {
                "libdwarf": {libelf: None},
                libelf: None
            },
            mpich: None
        },
        mpich: None
    },
})

static from_signed_json(stream)[source]¶

Construct a spec from clearsigned json spec file.

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

static from_specfile(path)[source]¶: Construct a spec from a JSON or YAML spec file path

static from_yaml(stream) → Spec[source]¶

Construct a spec from YAML.

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

property fullname¶

has_virtual_dependency(virtual: str) → bool[source]¶

index(deptype='all')[source]¶: Return a dictionary that points to all the dependencies in this spec.

install_status() → InstallStatus[source]¶: Helper for tree to print DB install status.

property installed¶

Installation status of a package.

Returns:: True if the package has been installed, False otherwise.

property installed_upstream¶

Whether the spec is installed in an upstream repository.

Returns:: True if the package is installed in an upstream, False otherwise.

intersects(other: str | Spec, deps: bool = True) → bool[source]¶

Return True if there exists at least one concrete spec that matches both self and other, otherwise False.

This operation is commutative, and if two specs intersect it means that one can constrain the other.

Parameters:

other – spec to be checked for compatibility
deps – if True check compatibility of dependency nodes too, if False only check root

property is_develop¶: Return whether the Spec represents a user-developed package in a Spack Environment (i.e. using spack develop).

property long_spec¶: Long string of the spec, including dependencies.

lookup_hash()[source]¶: Given a spec with an abstract hash, return a copy of the spec with all properties and dependencies by looking up the hash in the environment, store, or finally, binary caches. This is non-destructive.

mutate(mutator, rehash=True) → bool[source]¶

Mutate concrete spec to match constraints represented by mutator.

Mutation can modify the spec version, variants, compiler flags, and architecture. Mutation cannot change the spec name, namespace, dependencies, or abstract_hash. Any attribute which is unset will not be touched. Variant values can be replaced with the literal None to remove the variant. None as a variant value is represented by VariantValue(..., (None,)).

If rehash, concrete spec and its dependents have hashes updated.

Returns whether the spec was modified by the mutation

property namespace_if_anonymous¶

node_dict_with_hashes(hash: SpecHashDescriptor = ht.dag_hash) → Dict[str, Any][source]¶: Returns a node dict of this spec with the dag hash, and the provided hash (if not the dag hash).

original_spec_format() → int[source]¶: Returns the spec format originally used for this spec.

property os¶

static override(init_spec, change_spec)[source]¶

property package¶

package_hash()[source]¶: Compute the hash of the contents of the package for this node

property patches¶

Return patch objects for any patch sha256 sums on this Spec.

This is for use after concretization to iterate over any patches associated with this spec.

TODO: this only checks in the package; it doesn’t resurrect old patches from install directories, but it probably should.

property platform¶

property prefix: Prefix¶

replace_hash()[source]¶: Given a spec with an abstract hash, attempt to populate all properties and dependencies by looking up the hash in the environment, store, or finally, binary caches. This is destructive.

property root¶

Follow dependent links and find the root of this spec’s DAG.

Spack specs have a single root (the package being installed).

satisfies(other: str | Spec, deps: bool = True) → bool[source]¶

Return True if all concrete specs matching self also match other, otherwise False.

Parameters:

other – spec to be satisfied
deps – if True, descend to dependencies, otherwise only check root node

set_prefix(value: str) → None[source]¶

property short_spec¶: Short string of the spec, with hash and without dependencies.

property spack_install¶: Special field for using {spack_install} in format().

property spack_root¶: Special field for using {spack_root} in format().

spec_hash(hash: SpecHashDescriptor) → str[source]¶

Utility method for computing different types of Spec hashes.

Parameters:: hash – type of hash to generate.

splice(other: Spec, transitive: bool = True) → Spec[source]¶

Returns a new, spliced concrete Spec with the other dependency and, optionally, its dependencies.

Parameters:

other – alternate dependency
transitive – include other’s dependencies

Returns: a concrete, spliced version of the current Spec

When transitive is True, use the dependencies from other to reconcile conflicting dependencies. When transitive is False, use dependencies from self.

For example, suppose we have the following dependency graph:

T
| \
Z<-H

Spec T depends on H and Z, and H also depends on Z. Now we want to use a different H, called H'. This function can be used to splice in H' to create a new spec, called T*. If H' was built with Z', then transitive=True will ensure H' and T* both depend on Z':

T*
| \
Z'<-H'

If transitive=False, then H' and T* will both depend on the original Z, resulting in a new H'*:

T*
| \
Z<-H'*

Provenance of the build is tracked through the build_spec property of the spliced spec and any correspondingly modified dependency specs. The build specs are set to that of the original spec, so the original spec’s provenance is preserved unchanged.

property spliced¶: Returns whether or not this Spec is being deployed as built i.e. whether or not this Spec has ever been spliced.

property target¶

to_dict(hash: SpecHashDescriptor = ht.dag_hash) → Dict[str, Any][source]¶

Create a dictionary suitable for writing this spec to YAML or JSON.

This dictionary is like the one that is ultimately written to a spec.json file in each Spack installation directory. For example, for sqlite:

{
    "spec": {
        "_meta": {"version": 5},
        "nodes": [
            {
                "name": "sqlite",
                "version": "3.46.0",
                "arch": {
                    "platform": "linux",
                    "platform_os": "ubuntu24.04",
                    "target": "x86_64_v3"
                },
                "namespace": "builtin",
                "parameters": {
                    "build_system": "autotools",
                    "column_metadata": True,
                    "dynamic_extensions": True,
                    "fts": True,
                    "functions": False,
                    "rtree": True,
                    "cflags": [],
                    "cppflags": [],
                    "cxxflags": [],
                    "fflags": [],
                    "ldflags": [],
                    "ldlibs": [],
                },
                "package_hash": "umcghjlve5347o...xdzmfdba23nkdhe5jntlhia====",
                "dependencies": [
                    {
                        "name": "compiler-wrapper",
                        "hash": "c5bxlim3zge4snwrwtd6rzuvq2unek6s",
                        "parameters": {"deptypes": ("build",), "virtuals": ()},
                    },
                    {
                        "name": "gcc",
                        "hash": "6dzveld2rtt2dkhklxfnery5wbtb5uus",
                        "parameters": {"deptypes": ("build",), "virtuals": ("c",)},
                    },
                    ...
                ],
                "annotations": {"original_specfile_version": 5},
                "hash": "a2ubvvqnula6zdppckwqrjf3zmsdzpoh",
            },
            ...
        ],
    }
}

Note that this dictionary starts with the spec key, and what follows is a list starting with the root spec, followed by its dependencies in preorder.

The method from_dict() can be used to read back in a spec that has been converted to a dictionary, serialized, and read back in.

to_json(stream=None, *, hash=ht.dag_hash, pretty=False)[source]¶

to_node_dict(hash: SpecHashDescriptor = ht.dag_hash) → Dict[str, Any][source]¶

Create a dictionary representing the state of this Spec.

This method creates the content that is eventually hashed by Spack to create identifiers like the DAG hash (see dag_hash()). Example result of this function for the sqlite package:

{
    "name": "sqlite",
    "version": "3.46.0",
    "arch": {"platform": "linux", "platform_os": "ubuntu24.04", "target": "x86_64_v3"},
    "namespace": "builtin",
    "parameters": {
        "build_system": "autotools",
        "column_metadata": True,
        "dynamic_extensions": True,
        "fts": True,
        "functions": False,
        "rtree": True,
        "cflags": [],
        "cppflags": [],
        "cxxflags": [],
        "fflags": [],
        "ldflags": [],
        "ldlibs": [],
    },
    "package_hash": "umcghjlve5347o3q2odo7vfcso2zhxdzmfdba23nkdhe5jntlhia====",
    "dependencies": [
        {
            "name": "compiler-wrapper",
            "hash": "c5bxlim3zge4snwrwtd6rzuvq2unek6s",
            "parameters": {"deptypes": ("build",), "virtuals": ()},
        },
        {
            "name": "gcc",
            "hash": "6dzveld2rtt2dkhklxfnery5wbtb5uus",
            "parameters": {"deptypes": ("build",), "virtuals": ("c",)},
        },
        ...
    ],
    "annotations": {"original_specfile_version": 5},
}

Note that the dictionary returned does not include the hash of the root of the spec, though it does include hashes for each dependency and its own package hash.

See to_dict() for a “complete” spec hash, with hashes for each node and nodes for each dependency (instead of just their hashes).

Parameters:: hash – type of hash to generate.

to_yaml(stream=None, hash=ht.dag_hash)[source]¶

traverse(*, root: bool = True, order: Literal['pre', 'post', 'breadth', 'topo'] = 'pre', cover: Literal['nodes', 'edges', 'paths'] = 'nodes', direction: Literal['children', 'parents'] = 'children', deptype: int | str | List[str] | Tuple[str, ...] = 'all', depth: Literal[False] = False, key: Callable[[Spec], Any] = id, visited: Set[Any] | None = None) → Iterable[Spec][source]¶
traverse(*, root: bool = True, order: Literal['pre', 'post', 'breadth', 'topo'] = 'pre', cover: Literal['nodes', 'edges', 'paths'] = 'nodes', direction: Literal['children', 'parents'] = 'children', deptype: int | str | List[str] | Tuple[str, ...] = 'all', depth: Literal[True], key: Callable[[Spec], Any] = id, visited: Set[Any] | None = None) → Iterable[Tuple[int, Spec]]: Shorthand for traverse_nodes()

traverse_edges(*, root: bool = True, order: Literal['pre', 'post', 'breadth', 'topo'] = 'pre', cover: Literal['nodes', 'edges', 'paths'] = 'nodes', direction: Literal['children', 'parents'] = 'children', deptype: int | str | List[str] | Tuple[str, ...] = 'all', depth: Literal[False] = False, key: Callable[[Spec], Any] = id, visited: Set[Any] | None = None) → Iterable[DependencySpec][source]¶
traverse_edges(*, root: bool = True, order: Literal['pre', 'post', 'breadth', 'topo'] = 'pre', cover: Literal['nodes', 'edges', 'paths'] = 'nodes', direction: Literal['children', 'parents'] = 'children', deptype: int | str | List[str] | Tuple[str, ...] = 'all', depth: Literal[True], key: Callable[[Spec], Any] = id, visited: Set[Any] | None = None) → Iterable[Tuple[int, DependencySpec]]: Shorthand for traverse_edges()

tree(*, color: bool | None = None, depth: bool = False, hashes: bool = False, hashlen: int | None = None, cover: Literal['nodes', 'edges', 'paths'] = 'nodes', indent: int = 0, format: str = DEFAULT_FORMAT, deptypes: str | List[str] | Tuple[str, ...] | int = dt.ALL, show_types: bool = False, depth_first: bool = False, recurse_dependencies: bool = True, status_fn: Callable[[Spec], InstallStatus] | None = None, prefix: Callable[[Spec], str] | None = None, key=id, highlight_version_fn: Callable[[Spec], bool] | None = None, highlight_variant_fn: Callable[[Spec, str], bool] | None = None) → str[source]¶

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

See multi-spec spack.spec.tree() function for details.

Parameters:

specs – List of specs to format.
color – if True, always colorize the tree. If False, don’t colorize the tree. If None, use the default from spack.llnl.tty.color
depth – print the depth from the root
hashes – if True, print the hash of each node
hashlen – length of the hash to be printed
cover – either "nodes" or "edges"
indent – extra indentation for the tree being printed
format – format to be used to print each node
deptypes – dependency types to be represented in the tree
show_types – if True, show the (merged) dependency type of a node
depth_first – if True, traverse the DAG depth first when representing it as a tree
recurse_dependencies – if True, recurse on dependencies
status_fn – optional callable that takes a node as an argument and return its installation status
prefix – optional callable that takes a node as an argument and return its installation prefix
highlight_version_fn – optional callable that returns true on nodes where the version needs to be highlighted
highlight_variant_fn – optional callable that returns true on variants that need to be highlighted

trim(dep_name)[source]¶: Remove any package that is or provides dep_name transitively from this tree. This can also remove other dependencies if they are only present because of dep_name.

validate_or_raise()[source]¶: Checks that names and values in this spec are real. If they’re not, it will raise an appropriate exception.

property version¶

spack.package.Version(string: str | int) → StandardVersion | GitVersion[source]¶: Added in version v2.0.

class spack.package.WindowsRegistryView(key, root_key=HKEY.HKEY_CURRENT_USER)[source]¶

Bases: object

Interface to provide access, querying, and searching to Windows registry entries. This class represents a single key entrypoint into the Windows registry and provides an interface to this key’s values, its subkeys, and those subkey’s values. This class cannot be used to move freely about the registry, only subkeys/values of the root key used to instantiate this class.

Added in version v2.2.

class KeyMatchConditions[source]¶

Bases: object

static name_matcher(subkey_name)[source]¶

static regex_matcher(subkey_name)[source]¶

find_matching_subkey(subkey_name: str, recursive: bool = True)[source]¶

Perform a BFS of subkeys until a key matching subkey name regex is found Returns None or the first RegistryKey object corresponding to requested key name

Parameters:

subkey_name – subkey to be searched for
recursive – perform a recursive search

Returns:

the desired subkey as a RegistryKey object, or none

find_subkey(subkey_name: str, recursive: bool = True)[source]¶

Perform a BFS of subkeys until desired key is found Returns None or RegistryKey object corresponding to requested key name

Parameters:

subkey_name – subkey to be searched for
recursive – perform a recursive search

Returns:

the desired subkey as a RegistryKey object, or none

find_subkeys(subkey_name: str, recursive: bool = True)[source]¶

Exactly the same as find_subkey, except this function tries to match a regex to multiple keys

Parameters:: subkey_name – subkey to be searched for
Returns:: the desired subkeys as a list of RegistryKey object, or none

find_value(val_name: str, recursive: bool = True)[source]¶

If non recursive, return RegistryValue object corresponding to name

Parameters:

val_name – name of value desired from registry
recursive – optional argument, if True, the registry is searched recursively for the value of name val_name, else only the current key is searched

Returns:

The desired registry value as a RegistryValue object if it exists, otherwise, None

get_matching_subkeys(subkey_name)[source]¶

Returns all subkeys regex matching subkey name

Note: this method obtains only direct subkeys of the given key and does not descend to transitive subkeys. For this behavior, see find_matching_subkeys

get_subkey(subkey_name)[source]¶

get_subkeys()[source]¶

get_value(value_name)[source]¶: Return registry value corresponding to provided argument (if it exists)

get_values()[source]¶

invalid_reg_ref_error_handler()[source]¶

property reg¶

spack.package.ancestor(dir, n=1)[source]¶: Get the nth ancestor of a directory.

Added in version v2.0.

spack.package.any_combination_of(*values: str) → DisjointSetsOfValues[source]¶

Multi-valued variant that allows either any combination of the specified values, or none at all (using variant=none). The literal value none is used as sentinel for the empty set, since in the spec DSL we have to always specify a value for a variant.

It is up to the package implementation to handle the value none specially, if at all.

Parameters:: *values – allowed variant values

Example:

variant("cuda_arch", values=any_combination_of("10", "11"))

Returns:: a properly initialized instance of DisjointSetsOfValues

Added in version v2.0.

spack.package.apply_macos_rpath_fixups(builder: Builder)[source]¶

On Darwin, make installed libraries more easily relocatable.

Some build systems (handrolled, autotools, makefiles) can set their own rpaths that are duplicated by spack’s compiler wrapper. This fixup interrogates, and postprocesses if necessary, all libraries installed by the code.

It should be added as a run_after() to packaging systems (or individual packages) that do not install relocatable libraries by default.

Example:

run_after("install", when="platform=darwin")(apply_macos_rpath_fixups)

Parameters:: builder – builder that installed the package

Added in version v2.2.

spack.package.auto_or_any_combination_of(*values: str) → DisjointSetsOfValues[source]¶

Multi-valued variant that allows any combination of a set of values (but not the empty set) or auto.

Parameters:: *values – allowed variant values

Example:

variant(
    "file_systems",
    values=auto_or_any_combination_of("lustre", "gpfs", "nfs", "ufs"),
)

Returns:: a properly initialized instance of DisjointSetsOfValues

Added in version v2.0.

spack.package.bash_completion_path(root: str | Path) → Path[source]¶

Return standard path for bash completion scripts under root.

Parameters:: root – The prefix root under which to generate the path.
Returns:: Standard path for bash completion scripts under root.

Added in version v2.0.

spack.package.build_system(*values, **kwargs)[source]¶

Define the build system used by the package. This defines the build_system variant.

Example:

build_system("cmake", "autotools", "meson", default="cmake")

Added in version v2.0.

spack.package.build_system_flags(name: str, flags: Iterable[str]) → Tuple[Iterable[str] | None, Iterable[str] | None, Iterable[str] | None]¶

Assigning this to spack.package_base.PackageBase.flag_handler means that compiler flags are passed to the build system. This can be used in any package that derives from a build system class that implements spack.package_base.PackageBase.flags_to_build_system_args().

See also env_flags() and inject_flags().

Example:

from spack.package import *

class MyPackage(CMakePackage):
    flag_handler = build_system_flags

Added in version v2.0.

spack.package.cache_extra_test_sources(pkg: PackageBase, srcs: str | List[str])[source]¶

Copy relative source paths to the corresponding install test subdir

This routine is intended as an optional install test setup helper for grabbing source files/directories during the installation process and copying them to the installation test subdirectory for subsequent use during install testing.

Parameters:

pkg – package being tested
srcs – relative path for file(s) and or subdirectory(ies) located in the staged source path that are to be copied to the corresponding location(s) under the install testing directory.

Raises:

spack.error.InstallError – if any of the source paths are absolute or do not exist under the build stage

Added in version v2.0.

spack.package.can_access(file_name)[source]¶: True if the current process has read and write access to the file.

Added in version v2.0.

spack.package.can_splice(target: str, *, when: str, match_variants: None | str | List[str] = None)[source]¶

Declare whether the package is ABI-compatible with another package and thus can be spliced into concrete versions of that package.

Parameters:

target – The spec that the current package is ABI-compatible with.
when – An anonymous spec constraining current package for when it is ABI-compatible with target.
match_variants – A list of variants that must match between target spec and current package, with special value * which matches all variants. Example: a json variant is defined on two packages, and they are ABI-compatible whenever they agree on the json variant (regardless of whether it is turned on or off). Note that this cannot be applied to multi-valued variants and multi-valued variants will be skipped by *.

Added in version v2.0.

spack.package.cd(path)¶: Alias for os.chdir()

Added in version v2.0.

spack.package.change_sed_delimiter(old_delim: str, new_delim: str, *filenames: str) → None[source]¶

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.

Parameters:

old_delim – The delimiter to search for
new_delim – The delimiter to replace with
*filenames – One or more files to search and replace

Added in version v2.0.

spack.package.check_outputs(expected: list | set | str, actual: str)[source]¶

Ensure the expected outputs are contained in the actual outputs.

Parameters:

expected – expected raw output string(s)
actual – actual output string

Raises:

RuntimeError – the expected output is not found in the actual output

Added in version v2.0.

class spack.package.classproperty(callback: Callable[[Any], ClassPropertyType])[source]¶

Bases: Generic[ClassPropertyType]

Non-data descriptor to evaluate a class-level property. The function that performs the evaluation is injected at creation time and takes an owner (i.e., the class that originated the instance).

Added in version v2.2.

spack.package.compare_output(current_output: str, blessed_output: str) → None[source]¶: Compare blessed and current output of executables. Used in package tests.

Added in version v2.2.

spack.package.compare_output_file(current_output: str, blessed_output_file: str) → None[source]¶: Same as above, but when the blessed output is given as a file. Used in package tests.

Added in version v2.2.

spack.package.compile_c_and_execute(source_file: str, include_flags: List[str], link_flags: List[str]) → str[source]¶: Compile a C source file with the given include and link flags, execute the resulting binary, and return its output as a string. Used in package tests.

Added in version v2.2.

spack.package.compiler_spec(node: Spec) → Spec | None[source]¶

Returns a compiler Spec associated with the node passed as argument.

The function looks for a c, cxx, and fortran compiler in that order, and returns the first found. If the node does not depend on any of these languages, it returns None.

Use of this function is discouraged, because a single spec can have multiple compilers associated with it, and this function only returns one of them. It can be better to refer to compilers on a per-language basis, through the language virtuals: spec["c"], spec["cxx"], and spec["fortran"].

Added in version v2.2.

spack.package.conditional(*values: str | bool, when: Spec | str | bool | None = None)[source]¶: Conditional values that can be used in variant declarations.

Added in version v2.0.

spack.package.conflicts(conflict_spec: str, when: Spec | str | bool | None = None, msg: str | None = None)[source]¶

Declare a conflict for a package.

A conflict is a spec that is known to be invalid. For example, a package that cannot build with GCC 14 and above can declare:

conflicts("%gcc@14:")

To express the same constraint only when the foo variant is activated:

conflicts("%gcc@14:", when="+foo")

Parameters:

conflict_spec – constraint defining the known conflict
when – optional condition that triggers the conflict
msg – optional user defined message

Added in version v2.0.

spack.package.copy(src: str, dest: str, _permissions: bool = False) → None[source]¶

Copy the file(s) src to the file or directory dest.

If dest specifies a directory, the file will be copied into dest using the base filename from src.

src may contain glob characters.

Parameters:

src – the file(s) to copy
dest – the destination file or directory
_permissions – for internal use only

Raises:

OSError – if src does not match any files or directories
ValueError – if src matches multiple files but dest is not a directory

Added in version v2.0.

spack.package.copy_tree(src: str, dest: str, symlinks: bool = True, ignore: Callable[[str], bool] | None = None, _permissions: bool = False)[source]¶

Recursively copy an entire directory tree rooted at src.

If the destination directory dest does not already exist, it will be created as well as missing parent directories.

src may contain glob characters.

If symlinks is true, symbolic links in the source tree are represented as symbolic links in the new tree and the metadata of the original links will be copied as far as the platform allows; if false, the contents and metadata of the linked files are copied to the new tree.

If ignore is set, then each path relative to src will be passed to this function; the function returns whether that path should be skipped.

Parameters:

src – the directory to copy
dest – the destination directory
symlinks – whether or not to preserve symlinks
ignore – function indicating which files to ignore
_permissions – for internal use only

Raises:

OSError – if src does not match any files or directories
ValueError – if src is a parent directory of dest

Added in version v2.0.

spack.package.create_builder(pkg: PackageBase) → Builder¶: Given a package object with an associated concrete spec, return the builder object that can install it.

Added in version v2.2.

spack.package.dedupe(sequence, key=None)[source]¶

Yields a stable de-duplication of an hashable sequence by key

Parameters:

sequence – hashable sequence to be de-duplicated
key – callable applied on values before uniqueness test; identity by default.

Returns:

stable de-duplication of the sequence

Examples

Dedupe a list of integers:

[x for x in dedupe([1, 2, 1, 3, 2])] == [1, 2, 3]

[x for x in spack.llnl.util.lang.dedupe([1,-2,1,3,2], key=abs)] == [1, -2, 3]

Added in version v2.2.

spack.package.default_args(**kwargs)[source]¶

Context manager to override the default arguments of directives.

Example:

with default_args(type=("build", "run")):
    depends_on("py-foo")
    depends_on("py-bar")
    depends_on("py-baz")

Notice that unlike then when() context manager, this one is not composable, as it merely overrides the default argument values for the duration of the context. For example:

with default_args(when="+foo"):
    depends_on("pkg-a")
    depends_on("pkg-b", when="+bar")

is equivalent to:

depends_on("pkg-a", when="+foo")
depends_on("pkg-b", when="+bar")

Added in version v2.0.

spack.package.delete_needed_from_elf(f: BinaryIO, elf: ElfFile, needed: bytes) → None[source]¶: Delete a needed library from the dynamic section of an ELF file

Added in version v2.2.

spack.package.delete_rpath(path: str) → None[source]¶: Modifies a binary to remove the rpath. It zeros out the rpath string and also drops the DT_RPATH / DT_RUNPATH entry from the dynamic section, so it doesn’t show up in readelf -d file, nor in strings file.

Added in version v2.2.

Declare a dependency on another package.

Example:

depends_on("hwloc@2:", when="@1:", type="link")

Parameters:

spec – dependency spec
when – condition when this dependency applies
type – One or more of "build", "run", "test", or "link" (either a string or tuple). Defaults to ("build", "link").
patches – single result of patch() directive, a str to be passed to patch, or a list of these

Added in version v2.0.

spack.package.determine_number_of_jobs(*, parallel: bool = False, max_cpus: int = cpus_available(), config: Configuration | None = None) → int[source]¶

Packages that require sequential builds need 1 job. Otherwise we use the number of jobs set on the command line. If not set, then we use the config defaults (which is usually set through the builtin config scope), but we cap to the number of CPUs available to avoid oversubscription.

Parameters:

parallel – true when package supports parallel builds
max_cpus – maximum number of CPUs to use (defaults to cpus_available())
config – configuration object (defaults to global config)

Added in version v2.0.

spack.package.disjoint_sets(*sets: Tuple[str, ...]) → DisjointSetsOfValues[source]¶

Multi-valued variant that allows any combination picking from one of multiple disjoint sets of values, and also allows the user to specify none to choose none of them.

It is up to the package implementation to handle the value none specially, if at all.

Parameters:: *sets – sets of allowed values, each set is a tuple of strings
Returns:: a properly initialized instance of DisjointSetsOfValues

Added in version v2.0.

spack.package.env¶: Alias for os.environ

Added in version v2.0.

spack.package.env_flags(name: str, flags: Iterable[str]) → Tuple[Iterable[str] | None, Iterable[str] | None, Iterable[str] | None]¶

Assigning this to spack.package_base.PackageBase.flag_handler means that compiler flags are set as canonical environment variables.

Example:

from spack.package import *

class MyPackage(MakefilePackage):
    flag_handler = env_flags

Added in version v2.0.

spack.package.environment_modifications_for_specs(*specs: Spec, view=None, set_package_py_globals: bool = True)[source]¶

List of environment (shell) modifications to be processed for spec.

This list is specific to the location of the spec or its projection in the view.

Parameters:

specs – spec(s) for which to list the environment modifications
view – view associated with the spec passed as first argument
set_package_py_globals – whether or not to set the global variables in the package.py files (this may be problematic when using buildcaches that have been built on a different but compatible OS)

Added in version v2.2.

spack.package.execute_install_time_tests(builder: Builder)[source]¶

Execute the install-time tests prescribed by builder.

Parameters:: builder – builder prescribing the test callbacks. The name of the callbacks is stored as a list of strings in the install_time_test_callbacks attribute.

Added in version v2.2.

spack.package.extends(spec: str, when: Spec | str | bool | None = None, type: Tuple[str, ...] | str = ('build', 'run'), *, patches: Callable[[Type[PackageBase] | Dependency], None] | str | List[Callable[[Type[PackageBase] | Dependency], None] | str] | None = None)[source]¶: Same as depends_on(), but also adds this package to the extendee list. In case of Python, also adds a dependency on python-venv.

Note

Notice that the default type is ("build", "run"), which is different from depends_on() where the default is ("build", "link").

Added in version v2.0.

spack.package.filter_compiler_wrappers(*files: str, after: str = 'install', relative_root: str | None = None, ignore_absent: bool = True, backup: bool = False, recursive: bool = False, **kwargs) → None[source]¶

Registers a phase callback (e.g. post-install) to look for references to Spack’s compiler wrappers in the given files and replace them with the underlying compilers.

Example usage:

class MyPackage(Package):

    filter_compiler_wrappers("mpicc", "mpicxx", relative_root="bin")

This is useful for packages that register the path to the compiler they are built with to be used later at runtime. Spack’s compiler wrappers cannot be used at runtime, as they require Spack’s build environment to be set up. Using this function, the compiler wrappers are replaced with the actual compilers, so that the package works correctly at runtime.

Parameters:

*files – files to be filtered relative to the search root (install prefix by default).
after – specifies after which phase the files should be filtered (defaults to "install").
relative_root – path relative to install prefix where to start searching for the files to be filtered. If not set the install prefix will be used as the search root. It is highly recommended to set this, as searching recursively from the installation prefix can be very slow.
ignore_absent – if present, will be forwarded to filter_file()
backup – if present, will be forwarded to filter_file()
recursive – if present, will be forwarded to find()

Added in version v2.0.

spack.package.filter_file(regex: str, repl: str | Callable[[Match], str], *filenames: str, string: bool = False, backup: bool = False, ignore_absent: bool = False, start_at: str | None = None, stop_at: str | None = None, encoding: str | None = 'utf-8') → None[source]¶

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 \1, \2, etc. to represent back-substitution as sed would allow.

Parameters:

regex – The regular expression to search for
repl – The string to replace matches with
*filenames – One or more files to search and replace string: Treat regex as a plain string. Default it False backup: Make backup file(s) suffixed with ~. Default is False
ignore_absent – Ignore any files that don’t exist. Default is False
start_at – Marker used to start applying the replacements. If a text line matches this marker filtering is started at the next line. All contents before the marker and the marker itself are copied verbatim. Default is to start filtering from the first line of the file.
stop_at – Marker used to stop scanning the file further. If a text line matches this marker filtering is stopped and the rest of the file is copied verbatim. Default is to filter until the end of the file.
encoding – The encoding to use when reading and writing the files. Default is None, which uses the system’s default encoding.

Added in version v2.0.

spack.package.filter_shebang(path)[source]¶: Adds a second shebang line, using sbang, at the beginning of a file, if necessary. Note: Spack imposes a relaxed shebang line limit, meaning that a newline or end of file must occur before spack_shebang_limit bytes. If not, the file is not patched.

Added in version v2.2.

spack.package.filter_system_paths(paths: Iterable[str]) → List[str][source]¶: Returns a copy of the input where system paths are filtered out.

Deprecated since version v2.0.

Added in version v2.2.

Finds all files matching the patterns from files starting from root. This function returns a deterministic result for the same input and directory structure when run multiple times. Symlinked directories are followed, and unique directories are searched only once. Each matching file is returned only once at lowest depth in case multiple paths exist due to symlinked directories.

Accepts any glob characters accepted by fnmatch.fnmatch():

Pattern	Meaning
`*`	matches one or more characters
`?`	matches any single character
`[seq]`	matches any character in `seq`
`[!seq]`	matches any character not in `seq`

Examples:

>>> find("/usr", "*.txt", recursive=True, max_depth=2)

finds all files with the extension .txt in the directory /usr and subdirectories up to depth 2.

>>> find(["/usr", "/var"], ["*.txt", "*.log"], recursive=True)

finds all files with the extension .txt or .log in the directories /usr and /var at any depth.

>>> find("/usr", "GL/*.h", recursive=True)

finds all header files in a directory GL at any depth in the directory /usr.

Parameters:

root – One or more root directories to start searching from
files – One or more filename patterns to search for
recursive – if False search only root, if True descends from roots. Defaults to True.
max_depth – if set, don’t search below this depth. Cannot be set if recursive is False

Returns a list of absolute, matching file paths.

Added in version v2.0.

spack.package.find_all_headers(root: str) → HeaderList[source]¶

Convenience function that returns the list of all headers found in the directory passed as argument.

Parameters:: root – directory where to look recursively for header files
Returns:: List of all headers found in root and subdirectories.

Added in version v2.0.

spack.package.find_all_libraries(root: str, recursive: bool = False) → LibraryList[source]¶

Convenience function that returns the list of all libraries found in the directory passed as argument.

See documentation for find_libraries() for more information

Added in version v2.2.

spack.package.find_compilers(path_hints: List[str] | None = None, *, scope: str | None = None, max_workers: int | None = None) → List[Spec][source]¶

Searches for compiler in the paths given as argument. If any new compiler is found, the configuration is updated, and the list of new compiler objects is returned.

Parameters:

path_hints – list of path hints where to look for. A sensible default based on the PATH environment variable will be used if the value is None
scope – configuration scope to modify
max_workers – number of processes used to search for compilers

Added in version v2.2.

spack.package.find_first(root: str, files: Iterable[str] | str, bfs_depth: int = 2) → str | None[source]¶

Find the first file matching a pattern.

The following

$ find /usr -name 'abc*' -o -name 'def*' -quit

is equivalent to:

>>> find_first("/usr", ["abc*", "def*"])

Any glob pattern supported by fnmatch can be used.

The search order of this method is breadth-first over directories, until depth bfs_depth, after which depth-first search is used.

Parameters:

root – The root directory to start searching from
files – File pattern(s) to search for
bfs_depth – (advanced) parameter that specifies at which depth to switch to depth-first search.

Returns:

The matching file or None when no file is found.

Added in version v2.0.

spack.package.find_headers(headers: str | List[str], root: str, recursive: bool = False) → HeaderList[source]¶

Returns an iterable object containing a list of full paths to headers if found.

Accepts any glob characters accepted by fnmatch.fnmatch():

Pattern	Meaning
`*`	matches one or more characters
`?`	matches any single character
`[seq]`	matches any character in `seq`
`[!seq]`	matches any character not in `seq`

Parameters:

headers – Header name(s) to search for
root – The root directory to start searching from
recursive – if False search only root folder, if True descends top-down from the root. Defaults to False.

Returns:

The headers that have been found

Added in version v2.0.

spack.package.find_libraries(libraries: str | List[str], root: str, shared: bool = True, recursive: bool = False, runtime: bool = True, max_depth: int | None = None) → LibraryList[source]¶

Returns an iterable of full paths to libraries found in a root dir.

Accepts any glob characters accepted by fnmatch.fnmatch():

Pattern	Meaning
`*`	matches one or more characters
`?`	matches any single character
`[seq]`	matches any character in `seq`
`[!seq]`	matches any character not in `seq`

Parameters:

libraries – Library name(s) to search for
root – The root directory to start searching from
shared – if True searches for shared libraries, otherwise for static. Defaults to True.
recursive – if False search only root folder, if True descends top-down from the root. Defaults to False.
max_depth – if set, don’t search below this depth. Cannot be set if recursive is False
runtime – Windows only option, no-op elsewhere. If True, search for runtime shared libs (.DLL), otherwise, search for .Lib files. If shared is False, this has no meaning. Defaults to True.

Returns:

The libraries that have been found

Added in version v2.0.

spack.package.find_required_file(root: str, filename: str, expected: int = 1, recursive: bool = True) → str | List[str][source]¶

Find the required file(s) under the root directory.

Parameters:

root – root directory for the search
filename – name of the file being located
expected – expected number of files to be found under the directory (default is 1)
recursive – True if subdirectories are to be recursively searched, else False (default is True)

Returns: the path(s), relative to root, to the required file(s)

Raises:: Exception – SkipTest when number of files detected does not match expected

Added in version v2.0.

spack.package.find_system_libraries(libraries: str | List[str], shared: bool = True) → LibraryList[source]¶

Searches the usual system library locations for libraries.

Search order is as follows:

/lib64
/lib
/usr/lib64
/usr/lib
/usr/local/lib64
/usr/local/lib

Accepts any glob characters accepted by fnmatch.fnmatch():

Pattern	Meaning
`*`	matches one or more characters
`?`	matches any single character
`[seq]`	matches any character in `seq`
`[!seq]`	matches any character not in `seq`

Parameters:

libraries – Library name(s) to search for
shared – if True searches for shared libraries, otherwise for static. Defaults to True.

Returns:

The libraries that have been found

Added in version v2.0.

spack.package.fish_completion_path(root: str | Path) → Path[source]¶

Return standard path for fish completion scripts under root.

Parameters:: root – The prefix root under which to generate the path.
Returns:: Standard path for fish completion scripts under root.

Added in version v2.0.

spack.package.fix_darwin_install_name(path: str) → None[source]¶

Fix install name of dynamic libraries on Darwin to have full path.

There are two parts of this task:

Use install_name -id ... to change install name of a single lib
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.

Parameters:: path – directory in which .dylib files are located

Added in version v2.0.

spack.package.force_remove(*paths: str) → None[source]¶: Remove files without printing errors. Like rm -f, does NOT remove directories.

Added in version v2.0.

spack.package.force_symlink(src: str, dest: str) → None[source]¶: Create a symlink at dest pointing to src. Similar to ln -sf.

Added in version v2.0.

spack.package.get_cmake_prefix_path(pkg: PackageBase) → List[str][source]¶: Obtain the CMAKE_PREFIX_PATH entries for a package, based on the cmake_prefix_paths package attribute of direct build/test and transitive link dependencies.

Added in version v2.2.

spack.package.get_effective_jobs(jobs, parallel: bool = True, supports_jobserver: bool = False) → int | None[source]¶: Return the number of jobs, or None if supports_jobserver and a jobserver is detected.

Added in version v2.2.

spack.package.get_elf_compat(path: str) → Tuple[bool, bool, int][source]¶: Get a triplet (is_64_bit, is_little_endian, e_machine) from an ELF file, which can be used to see if two ELF files are compatible.

Added in version v2.2.

spack.package.get_escaped_text_output(filename: str) → List[str][source]¶

Retrieve and escape the expected text output from the file

Parameters:: filename – path to the file
Returns:: escaped text lines read from the file

Added in version v2.0.

spack.package.get_path_args_from_module_line(line)[source]¶: Added in version v2.2.

spack.package.get_user()[source]¶: Added in version v2.2.

spack.package.has_shebang(path) → bool[source]¶: Returns whether a path has a shebang line. Returns False if the file cannot be opened.

Added in version v2.2.

spack.package.host_platform()¶: Detect and return the platform for this machine or None if detection fails.

Added in version v2.2.

spack.package.inject_flags(name: str, flags: Iterable[str]) → Tuple[Iterable[str] | None, Iterable[str] | None, Iterable[str] | None]¶

This is the default value of spack.package_base.PackageBase.flag_handler, which tells Spack to inject compiler flags through the compiler wrappers, which means that the build system will not see them directly. This is typically a good default, but in rare case you may need to use env_flags() or build_system_flags() instead.

Example:

from spack.package import *

class MyPackage(MakefilePackage):
    flag_handler = inject_flags

Added in version v2.0.

spack.package.install(src: str, dest: str) → None[source]¶

Install the file(s) src to the file or directory dest.

Same as copy() with the addition of setting proper permissions on the installed file.

Parameters:

src – the file(s) to install
dest – the destination file or directory

Raises:

OSError – if src does not match any files or directories
ValueError – if src matches multiple files but dest is not a directory

Added in version v2.0.

spack.package.install_test_root(pkg: PackageBase) → str[source]¶: The install test root directory.

Added in version v2.0.

spack.package.install_tree(src: str, dest: str, symlinks: bool = True, ignore: Callable[[str], bool] | None = None)[source]¶

Recursively install an entire directory tree rooted at src.

Same as copy_tree() with the addition of setting proper permissions on the installed files and directories.

Parameters:

src – the directory to install
dest – the destination directory
symlinks – whether or not to preserve symlinks
ignore – function indicating which files to ignore

Raises:

OSError – if src does not match any files or directories
ValueError – if src is a parent directory of dest

Added in version v2.0.

spack.package.is_exe(path) → bool[source]¶: Returns True iff the specified path exists, is a regular file, and has executable permissions for the current process.

Added in version v2.0.

spack.package.is_system_path(path: str) → bool[source]¶: Returns True iff the argument is a system path.

Deprecated since version v2.0.

Added in version v2.2.

spack.package.join_path(prefix, *args) → str[source]¶: Alias for os.path.join()

Added in version v2.0.

spack.package.join_url(base: str, *components: str, resolve_href: bool = False, **kwargs) → str¶

Convenience wrapper around urllib.parse.urljoin(), with a few differences:

By default resolve_href=False, which makes the function like os.path.join(). For example https://example.com/a/b + c/d = https://example.com/a/b/c/d. If resolve_href=True, the behavior is how a browser would resolve the URL: https://example.com/a/c/d.
s3://, gs://, oci:// URLs are joined like http:// URLs.
It accepts multiple components for convenience. Note that components[1:] are treated as literal path components and appended to components[0] separated by slashes.

Added in version v2.2.

spack.package.keep_modification_time(*filenames: str) → Generator[None, None, None][source]¶

Context manager to keep the modification timestamps of the input files. Tolerates and has no effect on non-existent files and files that are deleted by the nested code.

Example:

with keep_modification_time("file1.txt", "file2.txt"):
    # do something that modifies file1.txt and file2.txt

Parameters:: *filenames – one or more files that must have their modification timestamps unchanged

Added in version v2.0.

spack.package.kernel_version() → StandardVersion[source]¶: Return the host’s kernel version as a StandardVersion object.

Added in version v2.2.

spack.package.libc_from_dynamic_linker(dynamic_linker: str) → Spec | None[source]¶: Get the libc spec from the dynamic linker path.

Added in version v2.2.

spack.package.license(license_identifier: str, checked_by: str | List[str] | None = None, when: str | bool | None = None)[source]¶

Declare the license(s) the software is distributed under.

Parameters:

license_identifiers – SPDX identifier specifying the license(s) the software is distributed under.
checked_by – string or list of strings indicating which github user checked the license (if any).
when – A spec specifying when the license applies.

Added in version v2.0.

spack.package.macos_version() → StandardVersion[source]¶

Get the current macOS version as a version object.

This has three mechanisms for determining the macOS version, which is used for spack identification (the os in the spec’s arch) and indirectly for setting the value of MACOSX_DEPLOYMENT_TARGET, which affects the minos value of the LC_BUILD_VERSION macho header. Mixing minos values can lead to lots of linker warnings, and using a consistent version (pinned to the major OS version) allows distribution across clients that might be slightly behind.

The version determination is made with three mechanisms in decreasing priority:

The MACOSX_DEPLOYMENT_TARGET variable overrides the actual operating system version, just like the value can be used to build for older macOS targets on newer systems. Spack currently will truncate this value when building packages, but at least the major version will be the same.
The system sw_vers command reports the actual operating system version.
The Python platform.mac_ver function is a fallback if the operating system identification fails, because some Python versions and/or installations report the OS on which Python was built rather than the one on which it is running.

Added in version v2.2.

spack.package.maintainers(*names: str)[source]¶

Declare the maintainers of a package.

Parameters:: names – GitHub username for the maintainer

Added in version v2.0.

spack.package.make_package_test_rpath(pkg: PackageBase, test_dir: str | Path) → None[source]¶

Establishes a temp Windows simulated rpath for the pkg in the testing directory so an executable can test the libraries/executables with proper access to dependent dlls.

Note: this is a no-op on all other platforms besides Windows

Parameters:

pkg – the package for which the rpath should be computed
test_dir – the testing directory in which we should construct an rpath

Added in version v2.2.

spack.package.makedirs(name [, mode=0o777][, exist_ok=False])[source]¶: Alias for os.makedirs()

Added in version v2.0.

spack.package.memoized(func)[source]¶

Decorator that caches the results of a function, storing them in an attribute of that function.

Example:

@memoized
def expensive_computation(x):
    # Some expensive computation
    return result

Added in version v2.2.

spack.package.microarchitecture_flags(spec: Spec, language: str) → str[source]¶

Get compiler flags for the spec’s microarchitecture.

Parameters:

spec – The spec defining the target microarchitecture and compiler.
language – The language ("c", "cxx", "fortran") used to select the appropriate compiler from the spec.

Example:

>>> spec.format("{target}")
'm1'
>>> spec["c"].format("{name}{@version}")
'apple-clang@17.0.0'
>>> microarchitecture_flags(spec, language="c")
'-mcpu=apple-m1'

Added in version v2.2.

spack.package.microarchitecture_flags_from_target(target: Microarchitecture, compiler: Spec) → str[source]¶

Get compiler flags for the spec’s microarchitecture. Similar to microarchitecture_flags(), but takes a target and compiler directly instead of a spec.

Parameters:

target – The target microarchitecture.
compiler – The spec defining the compiler.

Added in version v2.2.

spack.package.mkdir(path, mode=511, *, dir_fd=None)¶: Alias for os.mkdir()

Added in version v2.0.

spack.package.mkdirp(*paths: str, mode: int | None = None, group: str | int | None = None, default_perms: str | None = None)[source]¶

Creates a directory, as well as parent directories if needed.

Parameters:

paths – paths to create with mkdirp
mode – optional permissions to set on the created directory – use OS default if not provided
group – optional group for permissions of final created directory – use OS default if not provided. Only used if world write permissions are not set
default_perms – one of "parents" or "args". The default permissions that are set for directories that are not themselves an argument for mkdirp. "parents" means intermediate directories get the permissions of their direct parent directory, "args" means intermediate get the same permissions specified in the arguments to mkdirp – default value is "args"

Added in version v2.0.

spack.package.module_command(*args: str, module_template: str | None = None, module_src_cmd: str | None = None, environb: MutableMapping[bytes, bytes] | None = None)¶

Run the module shell function in a /bin/bash subprocess, and either collect its changes to environment variables and apply them in the current process (for module load, module swap, etc.), or return its output as a string (for module show, etc.).

This requires /bin/bash to be available on the system and awk to be in PATH.

Parameters:

args – Command line arguments for the module command.
environb – (Binary) environment variables dictionary. If not provided, the current process’s environment is modified.

Added in version v2.2.

spack.package.move(src, dst, copy_function=copy2)[source]¶: Alias for shutil.move()

Added in version v2.0.

spack.package.on_package_attributes(**attr_dict)[source]¶

Decorator: executes instance function only if object has attr values.

Executes the decorated method only if at the moment of calling the instance has attributes that are equal to certain values.

Parameters:: attr_dict (dict) – dictionary mapping attribute names to their required values

Added in version v2.0.

spack.package.parse_dynamic_linker(output: str)[source]¶: Parse -dynamic-linker /path/to/ld.so from compiler output

Added in version v2.2.

spack.package.parse_elf(f: BinaryIO, interpreter: bool = False, dynamic_section: bool = False, only_header: bool = False) → ElfFile[source]¶: Given a file handle f for an ELF file opened in binary mode, return an ElfFile object with the parsed contents.

Added in version v2.2.

Declare a patch to apply to package sources. A when spec can be provided to indicate that a particular patch should only be applied when the package’s spec meets certain conditions.

Example:

patch("foo.patch", when="@1.0.0:")
patch("https://example.com/foo.patch", sha256="...")

Parameters:

url_or_filename – url or relative filename of the patch
level – patch level (as in the patch shell command)
when – optional anonymous spec that specifies when to apply the patch
working_dir – dir to change to before applying
reverse – reverse the patch
sha256 – sha256 sum of the patch, used to verify the patch (only required for URL patches)
archive_sha256 – sha256 sum of the archive, if the patch is compressed (only required for compressed URL patches)

Added in version v2.0.

spack.package.path_contains_subdirectory(path: str, root: str) → bool[source]¶: Check if the path is a subdirectory of the root directory. Note: this is a symbolic check, and does not resolve symlinks.

Added in version v2.2.

spack.package.provides(*specs: str, when: Spec | str | bool | None = None)[source]¶

Declare that this package provides 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.

Parameters:

*specs – virtual specs provided by this package
when – condition when this provides clause needs to be considered

Added in version v2.0.

spack.package.pwd()¶: Alias for os.getcwd()

Added in version v2.0.

spack.package.readlink(path, *, dir_fd=None)¶: Alias for os.readlink() (with certain Windows-specific changes)

Added in version v2.2.

Declare that the package source and/or compiled binaries should not be redistributed.

By default, packages allow source/binary distribution (in mirrors/build caches resp.). This directive allows users to explicitly disable redistribution for specs.

Added in version v2.0.

spack.package.register_builder(build_system_name: str)[source]¶

Class decorator used to register the default builder for a given build system. The name corresponds to the build_system variant value of the package.

Example:

@register_builder("cmake")
class CMakeBuilder(BuilderWithDefaults):
    pass

Parameters:: build_system_name – name of the build system

Added in version v2.0.

spack.package.remove(path, *, dir_fd=None)¶: Alias for os.remove()

Added in version v2.0.

spack.package.remove_directory_contents(dir)[source]¶: Remove all contents of a directory.

Added in version v2.0.

spack.package.remove_linked_tree(path: str) → None[source]¶

Removes a directory and its contents.

If the directory is a symlink, follows the link and removes the real directory before removing the link.

This method will force-delete files on Windows

Parameters:: path – Directory to be removed

Added in version v2.0.

spack.package.removedirs(name)[source]¶: Alias for os.removedirs()

Added in version v2.0.

spack.package.rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)¶: Alias for os.rename() (with certain Windows-specific changes)

Added in version v2.0.

spack.package.requires(*requirement_specs: str, policy: str = 'one_of', when: str | None = None, msg: str | None = None)[source]¶

Declare that a spec must be satisfied for a package.

For instance, a package whose Fortran code can only be compiled with GCC can declare:

requires("%fortran=gcc")

A package that requires Apple-Clang on Darwin can declare instead:

requires("%apple-clang", when="platform=darwin", msg="Apple Clang is required on Darwin")

Parameters:

requirement_specs – spec expressing the requirement
policy – either "one_of" or "any_of". If "one_of", exactly one of the requirements must be satisfied. If "any_of", at least one of the requirements must be satisfied. Defaults to "one_of".
when – optional constraint that triggers the requirement. If None the requirement is applied unconditionally.
msg – optional user defined message

Added in version v2.0.

Declare 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.

Keyword Arguments:

name – name for the resource
when – condition defining when the resource is needed
destination – path, relative to the package stage area, to which resource should be moved
placement – optionally rename the expanded resource inside the destination directory

Added in version v2.0.

spack.package.rmtree(path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None)[source]¶: Alias for shutil.rmtree()

Added in version v2.0.

spack.package.run_after(phase: str, when: str | None = None)¶

Decorator to register a function for running after a given phase.

Example:

@run_after("install", when="@2:")
def install_missing_files(self):
    # Do something after the install phase for versions 2.x and above
    pass

Parameters:

phase – phase after which the function must run.
when – condition under which the function is run (if None, it is always run).

Added in version v2.0.

spack.package.run_before(phase: str, when: str | None = None)¶

Decorator to register a function for running before a given phase.

Example:

@run_before("build", when="@2:")
def patch_generated_source_file(pkg):
    # Do something before the build phase for versions 2.x and above
    pass

Parameters:

phase – phase before which the function must run.
when – condition under which the function is run (if None, it is always run).

Added in version v2.0.

spack.package.safe_remove(*files_or_dirs)[source]¶

Context manager to remove the files passed as input, but restore them in case any exception is raised in the context block.

Parameters:: *files_or_dirs – glob expressions for files or directories to be removed
Returns:: Dictionary that maps deleted files to their temporary copy within the context block.

Added in version v2.2.

spack.package.sbang_install_path()[source]¶: Location sbang is installed within the install tree.

Added in version v2.2.

spack.package.sbang_shebang_line()[source]¶

Full shebang line that should be prepended to files to use sbang.

The line returned does not have a final newline (caller should add it if needed).

This should be the only place in Spack that knows about what interpreter we use for sbang.

Added in version v2.2.

spack.package.set_env(**kwargs)[source]¶: Temporarily sets and restores environment variables. Variables can be set as keyword arguments to this function.

Note

If the goal is to set environment variables for a subprocess, it is strongly recommended to use the extra_env argument of spack.util.executable.Executable.__call__() instead of this function.

This function is intended to modify the current process’s environment (which is an unsafe operation in general).

Added in version v2.2.

spack.package.set_executable(path)[source]¶: Set the executable bit on a file or directory.

Added in version v2.0.

spack.package.set_install_permissions(path)[source]¶: Set appropriate permissions on the installed file.

Added in version v2.0.

spack.package.shared_library_suffix(spec: Spec) → str[source]¶: Return the shared library suffix for the given spec.

Added in version v2.2.

spack.package.static_library_suffix(spec: Spec) → str[source]¶: Return the static library suffix for the given spec.

Added in version v2.2.

spack.package.substitute_version_in_url(path: str, new_version) → str¶

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 example:

>>> substitute_version("https://www.hdfgroup.org/ftp/HDF/releases/HDF4.2.12/src/hdf-4.2.12.tar.gz", "2.3")
"https://www.hdfgroup.org/ftp/HDF/releases/HDF2.3/src/hdf-2.3.tar.gz"

Added in version v2.2.

spack.package.symlink(src, dst, target_is_directory=False, *, dir_fd=None)¶: Alias for os.symlink() (with certain Windows-specific changes)

Added in version v2.0.

spack.package.test_part(pkg: PackageBase, test_name: str, purpose: str, work_dir: str = '.', verbose: bool = False)[source]¶: Added in version v2.0.

spack.package.touch(path)[source]¶: Creates an empty file at the specified path.

Added in version v2.0.

class spack.package.tty[source]¶

Bases: object

Added in version v2.0.

debug(*args, level: int = 1, format: str = 'g', stream: IO[str] | None = None, **kwargs) → None¶: Print a debug message if the debug level is set.

error(*args, format: str = '*r', stream: IO[str] | None = None, **kwargs) → None¶: Print an error message.

info(*args, format: str = '*b', stream: IO[str] | None = None, wrap: bool = False, break_long_words: bool = False, countback: int = 3) → None¶: Print an informational message.

msg(*args: str, newline: bool = True) → None¶: Print a message to the console.

warn(*args, format: str = '*Y', stream: IO[str] | None = None, **kwargs) → None¶: Print a warning message.

Declare a variant for a package.

Packager can specify a default value as well as a text description.

Parameters:

name – Name of the variant
default – Default value for the variant, if not specified otherwise the default will be False for a boolean variant and ‘nothing’ for a multi-valued variant
description – Description of the purpose of the variant
values – Either a tuple of strings containing the allowed values, or a callable accepting one value and returning True if it is valid
multi – If False only one value per spec is allowed for this variant
validator – Optional group validator to enforce additional logic. It receives the package name, the variant name and a tuple of values and should raise an instance of SpackError if the group doesn’t meet the additional constraints
when – Optional condition on which the variant applies
sticky – The variant should not be changed by the concretizer to find a valid concrete spec

Raises:

spack.directives_meta.DirectiveError – If arguments passed to the directive are invalid

Added in version v2.0.

spack.package.ver(obj: VersionType | str | list | tuple | int | float) → VersionType[source]¶: Returns a ClosedOpenRange, StandardVersion, GitVersion, or VersionList from the argument.

Added in version v2.0.

Declare a version for a package with optional metadata for fetching its code.

Example:

version("2.1", sha256="...")
version("2.0", sha256="...", preferred=True)

Changed in version v2.3: The git_sparse_paths parameter was added.

Added in version v2.0.

class spack.package.when(condition: str | bool)[source]¶

Bases: object

This is a multi-purpose class, which can be used

As a context manager to group directives together that share the same when= argument.
As a decorator for defining multi-methods (multiple methods with the same name are defined, but the version that is called depends on the condition of the package’s spec)

As a context manager it groups directives together. It allows you to write:

with when("+nvptx"):
    conflicts("@:6", msg="NVPTX only supported from gcc 7")
    conflicts("languages=ada")
    conflicts("languages=brig")

instead of the more repetitive:

conflicts("@:6", when="+nvptx", msg="NVPTX only supported from gcc 7")
conflicts("languages=ada", when="+nvptx")
conflicts("languages=brig", when="+nvptx")

This context manager is composable both with nested when contexts and with other when= arguments in directives. For example:

with when("+foo"):
    with when("+bar"):
        depends_on("dependency", when="+baz")

is equilavent to:

depends_on("dependency", when="+foo +bar +baz")

As a decorator, it allows packages to declare multiple versions of methods like install() that depend on the package’s spec. For example:

class SomePackage(Package):
    ...

    def install(self, spec: Spec, prefix: Prefix):
        # Do default install

    @when("target=x86_64:")
    def install(self, spec: Spec, prefix: Prefix):
        # This will be executed instead of the default install if
        # the package's target is in the x86_64 family.

    @when("target=aarch64:")
    def install(self, spec: Spec, prefix: Prefix):
        # This will be executed if the package's target is in
        # the aarch64 family

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 architecture 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.
        pass

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

Note that the default version of decorated methods must always come first. Otherwise it will override all of the decorated versions. This is a limitation of the Python language.

Added in version v2.0.

spec: Spec | None¶

spack.package.which(*args: str, path: List[str] | str | None = None, required: Literal[True]) → Executable[source]¶

spack.package.which(*args: str, path: List[str] | str | None = None, required: bool = False) → Executable | None

Finds an executable in the path like command-line which.

If given multiple executables, returns the first one that is found. If no executables are found, returns None.

Parameters:

*args – one or more executables to search for
path – the path to search. Defaults to PATH
required – if set to True, raise an error if executable not found

Returns:

The first executable that is found in the path or None if not found.

Added in version v2.0.

spack.package.which_string(*args: str, path: List[str] | str | None = None, required: Literal[True]) → str[source]¶
spack.package.which_string(*args: str, path: List[str] | str | None = None, required: bool = False) → str | None: Like which(), but returns a string instead of an Executable.

Added in version v2.0.

spack.package.windows_sfn(path: PathLike)[source]¶

Returns 8.3 Filename (SFN) representation of path

8.3 Filenames (SFN or short filename) is a file naming convention used prior to Win95 that Windows still (and will continue to) support. This convention caps filenames at 8 characters, and most importantly does not allow for spaces in addition to other specifications. The scheme is generally the same as a normal Windows file scheme, but all spaces are removed and the filename is capped at 6 characters. The remaining characters are replaced with ~N where N is the number file in a directory that a given file represents i.e. Program Files and Program Files (x86) would be PROGRA~1 and PROGRA~2 respectively. Further, all file/directory names are all caps (although modern Windows is case insensitive in practice). Conversion is accomplished by fileapi.h GetShortPathNameW

Returns paths in 8.3 Filename form

Note: this method is a no-op on Linux

Parameters:: path – Path to be transformed into SFN (8.3 filename) format

Added in version v2.2.

spack.package.working_dir(dirname: str, *, create: bool = False)[source]¶

Context manager to change the current working directory to dirname.

Parameters:

dirname – the directory to change to
create – if True, create the directory if it does not exist

Example usage:

with working_dir("/path/to/dir"):
    # do something in /path/to/dir
    pass

Added in version v2.0.

spack.package.zsh_completion_path(root: str | Path) → Path[source]¶

Return standard path for zsh completion scripts under root.

Parameters:: root – The prefix root under which to generate the path.
Returns:: Standard path for zsh completion scripts under root.

Added in version v2.0.