# Copyright Spack Project Developers. See COPYRIGHT file for details.
#
# SPDX-License-Identifier: (Apache-2.0 OR MIT)
"""This package contains directives that can be used within a package.
Directives are functions that can be called inside a package
definition to modify the package, for example::
class OpenMpi(Package):
depends_on("hwloc")
provides("mpi")
...
``provides`` and ``depends_on`` are spack directives.
The available directives are:
* ``build_system``
* ``conflicts``
* ``depends_on``
* ``extends``
* ``license``
* ``patch``
* ``provides``
* ``resource``
* ``variant``
* ``version``
* ``requires``
* ``redistribute``
They're implemented as functions that return a NamedTuple holding the arguments, which is
later called with a package class::
@directive("example")
def example_directive(arg1, arg2):
return _Example(arg1, arg2)
class _Example(NamedTuple):
arg1: int
arg2: int
def __call__(self, pkg):
arg1, arg2 = self
# modify pkg.example based on arg1 and arg2
"""
import collections
import collections.abc
import os
import re
import warnings
from typing import Any, Callable, Dict, List, NamedTuple, Optional, Sequence, Tuple, Type, Union
import spack.deptypes as dt
import spack.error
import spack.fetch_strategy
import spack.package_base
import spack.patch
import spack.spec
import spack.util.crypto
import spack.util.tty.color
import spack.variant
from spack.dependency import Dependency, intern_dependency
from spack.directives_meta import DirectiveError, directive, get_spec
from spack.resource import Resource
from spack.spec import EMPTY_SPEC
from spack.version import StandardVersion, VersionChecksumError, VersionError
__all__ = [
"DirectiveError",
"version",
"conditional",
"conflicts",
"depends_on",
"extends",
"maintainers",
"license",
"provides",
"patch",
"variant",
"resource",
"build_system",
"requires",
"redistribute",
"can_splice",
]
_patch_order_index = 0
SpecType = str
DepType = Union[Tuple[str, ...], str]
WhenType = Optional[Union[spack.spec.Spec, str, bool]]
PackageType = Type[spack.package_base.PackageBase]
PatchesType = Union["_Patch", str, List[Union["_Patch", str]]]
def _make_when_spec(value: Union[WhenType, Tuple[str, ...]]) -> Optional[spack.spec.Spec]:
"""Create a ``Spec`` that indicates when a directive should be applied.
Directives with ``when`` specs, e.g.:
patch('foo.patch', when='@4.5.1:')
depends_on('mpi', when='+mpi')
depends_on('readline', when=sys.platform() != 'darwin')
are applied conditionally depending on the value of the ``when``
keyword argument. Specifically:
1. If the ``when`` argument is ``True``, the directive is always applied
2. If it is ``False``, the directive is never applied
3. If it is a ``Spec`` string, it is applied when the package's
concrete spec satisfies the ``when`` spec.
The first two conditions are useful for the third example case above.
It allows package authors to include directives that are conditional
at package definition time, in additional to ones that are evaluated
as part of concretization.
Arguments:
value: a conditional Spec, constant ``bool``, or None if not supplied
value indicating when a directive should be applied. It can also be a tuple of when
conditions (as strings) to be combined together.
"""
# This branch is never taken, but our WhenType type annotation allows it, so handle it too.
if isinstance(value, spack.spec.Spec):
return value
if isinstance(value, tuple):
assert value, "when stack cannot be empty"
# avoid a copy when there's only one condition
if len(value) == 1:
return get_spec(value[0])
combined_spec = _WHEN_STACK_CACHE.get(value)
if combined_spec is None:
# reduce the when-stack to a single spec by combining all constraints.
combined_spec = spack.spec.Spec(value[0])
for cond in value[1:]:
combined_spec._constrain_symbolically(get_spec(cond))
_WHEN_STACK_CACHE[value] = combined_spec
return combined_spec
# Unsatisfiable conditions are discarded by the caller, and never
# added to the package class
if value is False:
return None
# If there is no constraint, the directive should always apply;
# represent this by returning the unconstrained `Spec()`, which is
# always satisfied.
if value is None or value is True:
return EMPTY_SPEC
# This is conditional on the spec
return get_spec(value)
#: Nested `with when(...)` blocks reduce to the same spec over and over. Combined when-specs are
#: only ever used as keys of the package class dictionaries, like the single-condition ones
#: `get_spec` shares.
_WHEN_STACK_CACHE: Dict[Tuple[str, ...], spack.spec.Spec] = {}
SubmoduleCallback = Callable[[spack.package_base.PackageBase], Union[str, List[str], bool]]
[docs]
@directive("versions", supports_when=False)
def version(
ver: Union[str, int],
# this positional argument is deprecated, use sha256=... instead
checksum: Optional[str] = None,
*,
# generic version options
preferred: Optional[bool] = None,
deprecated: Optional[bool] = None,
no_cache: Optional[bool] = None,
# url fetch options
url: Optional[str] = None,
extension: Optional[str] = None,
expand: Optional[bool] = None,
fetch_options: Optional[dict] = None,
# url archive verification options
md5: Optional[str] = None,
sha1: Optional[str] = None,
sha224: Optional[str] = None,
sha256: Optional[str] = None,
sha384: Optional[str] = None,
sha512: Optional[str] = None,
# git fetch options
git: Optional[str] = None,
commit: Optional[str] = None,
tag: Optional[str] = None,
branch: Optional[str] = None,
get_full_repo: Optional[bool] = None,
git_sparse_paths: Optional[
Union[List[str], Callable[[spack.package_base.PackageBase], List[str]]]
] = None,
submodules: Union[SubmoduleCallback, Optional[bool]] = None,
submodules_delete: Optional[bool] = None,
# other version control
svn: Optional[str] = None,
hg: Optional[str] = None,
cvs: Optional[str] = None,
revision: Optional[str] = None,
date: Optional[str] = None,
):
"""Declare a version for a package with optional metadata for fetching its code.
Example::
version("2.1", sha256="...")
version("2.0", sha256="...", preferred=True)
.. versionchanged:: v2.3
The ``git_sparse_paths`` parameter was added.
"""
kwargs: dict = {
key: value
for key, value in (
("sha256", sha256),
("sha384", sha384),
("sha512", sha512),
("preferred", preferred),
("deprecated", deprecated),
("expand", expand),
("url", url),
("extension", extension),
("no_cache", no_cache),
("fetch_options", fetch_options),
("git", git),
("svn", svn),
("hg", hg),
("cvs", cvs),
("get_full_repo", get_full_repo),
("git_sparse_paths", git_sparse_paths),
("branch", branch),
("submodules", submodules),
("submodules_delete", submodules_delete),
("commit", commit),
("tag", tag),
("revision", revision),
("date", date),
("md5", md5),
("sha1", sha1),
("sha224", sha224),
("checksum", checksum),
)
if value is not None
}
return _Version(ver, kwargs)
class _Version(NamedTuple):
ver: Union[str, int]
kwargs: dict
def __call__(self, pkg: PackageType) -> None:
ver, kwargs = self
if (
(any(s in kwargs for s in spack.util.crypto.hashes) or "checksum" in kwargs)
and hasattr(pkg, "has_code")
and not pkg.has_code
):
raise VersionChecksumError(
f"{pkg.name}: Checksums not allowed in no-code packages (see '{ver}' version)."
)
if not isinstance(ver, (int, str)):
raise VersionError(
f"{pkg.name}: declared version '{ver!r}' in package should be a string or int."
)
version = StandardVersion.from_string(str(ver))
# Store kwargs for the package to later with a fetch_strategy.
pkg.versions[version] = kwargs
[docs]
@directive("conflicts")
def conflicts(conflict_spec: SpecType, when: WhenType = None, msg: Optional[str] = None):
"""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")
Args:
conflict_spec: constraint defining the known conflict
when: optional condition that triggers the conflict
msg: optional user defined message
"""
return _Conflicts(conflict_spec, when, msg)
class _Conflicts(NamedTuple):
conflict_spec: SpecType
when: WhenType
msg: Optional[str]
def __call__(self, pkg: PackageType) -> None:
conflict_spec, when, msg = self
# If when is not specified the conflict always holds
when_spec = _make_when_spec(when)
if not when_spec:
return
# Save in a list the conflicts and the associated custom messages
conflict_spec_list = pkg.conflicts.setdefault(when_spec, [])
msg_with_name = f"{pkg.name}: {msg}" if msg is not None else msg
conflict_spec_list.append((get_spec(conflict_spec), msg_with_name))
[docs]
@directive("dependencies", can_patch_dependencies=True)
def depends_on(
spec: SpecType,
when: WhenType = None,
type: DepType = dt.DEFAULT_TYPES,
*,
patches: Optional[PatchesType] = None,
):
"""Declare a dependency on another package.
Example::
depends_on("hwloc@2:", when="@1:", type="link")
Args:
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 :py:func:`patch` directive, a
``str`` to be passed to ``patch``, or a list of these
"""
return _DependsOn(spec, when, type, patches)
class _DependsOn(NamedTuple):
spec: Union[str, spack.spec.Spec]
when: WhenType = None
type: DepType = dt.DEFAULT_TYPES
patches: Optional[PatchesType] = None
def __call__(self, pkg: PackageType) -> None:
spec, when, type, patches = self
spec = get_spec(spec) if isinstance(spec, str) else spec
when_spec = _make_when_spec(when)
if not when_spec:
return
if not spec.name:
raise DependencyError(
f"Invalid dependency specification in package '{pkg.name}':", str(spec)
)
if pkg.name == spec.name:
raise CircularReferenceError(f"Package '{pkg.name}' cannot depend on itself.")
depflag = dt.canonicalize(type)
# call this patches here for clarity -- we want patch to be a list,
# but the caller doesn't have to make it one.
# Note: we cannot check whether a package is virtual in a directive
# because directives are run as part of class instantiation, and specs
# instantiate the package class as part of the `virtual` check.
# To be technical, specs only instantiate the package class as part of the
# virtual check if the provider index hasn't been created yet.
# TODO: There could be a cache warming strategy that would allow us to
# ensure `Spec.virtual` is a valid thing to call in a directive.
# For now, we comment out the following check to allow for virtual packages
# with package files.
# if patches and spec.virtual:
# raise DependencyPatchError("Cannot patch a virtual dependency.")
# a single patch, given as a filename or as the result of the patch directive, stands for a
# one-element list. _Patch is a tuple, so it has to be matched before the list check.
patch_list: Sequence[Union[_Patch, str]]
if patches is None:
patch_list = ()
elif isinstance(patches, (str, _Patch)):
patch_list = (patches,)
else:
patch_list = patches
# this is where we actually add the dependency to this package
deps_by_name = pkg.dependencies.setdefault(when_spec, {})
dependency = deps_by_name.get(spec.name)
edges = spec.edges_to_dependencies()
if edges and not all(x.direct for x in edges):
raise DirectiveError(
f"the '^' sigil cannot be used in 'depends_on' directives. Please reformulate "
f"the directive below as multiple directives:\n\n"
f'\tdepends_on("{spec}", when="{when_spec}")\n'
)
if not dependency:
dependency = Dependency(spec, depflag=depflag)
else:
merged_spec = dependency.spec.copy()
merged_spec.constrain(spec, deps=False)
# an existing Dependency may be shared with other packages, so build a new one
merged = Dependency(merged_spec, depflag=dependency.depflag | depflag)
merged.patches = dependency.patches
dependency = merged
deps_by_name[spec.name] = dependency
# apply patches to the dependency
for patch in patch_list:
if isinstance(patch, str):
patch = _Patch(patch)
assert isinstance(patch, _Patch), f"Invalid patch argument: {patch!r}"
patch(pkg, dependency)
if dependency.patches is None:
deps_by_name[spec.name] = intern_dependency(dependency)
[docs]
@directive("disable_redistribute")
def redistribute(
source: Optional[bool] = None, binary: Optional[bool] = None, when: WhenType = None
):
"""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.
"""
return _Redistribute(source, binary, when)
class _Redistribute(NamedTuple):
source: Optional[bool]
binary: Optional[bool]
when: WhenType
def __call__(self, pkg: PackageType) -> None:
source, binary, when = self
if source is None and binary is None:
return
elif (source is True) or (binary is True):
raise DirectiveError(
"Source/binary distribution are true by default, they can only be "
"explicitly disabled."
)
if source is None:
source = True
if binary is None:
binary = True
when_spec = _make_when_spec(when)
if not when_spec:
return
if source is False:
max_constraint = get_spec(f"{pkg.name}@{when_spec.versions}")
if not max_constraint.satisfies(when_spec):
raise DirectiveError("Source distribution can only be disabled for versions")
if when_spec in pkg.disable_redistribute:
disable = pkg.disable_redistribute[when_spec]
if not source:
disable.source = True
if not binary:
disable.binary = True
else:
pkg.disable_redistribute[when_spec] = spack.package_base.DisableRedistribute(
source=not source, binary=not binary
)
[docs]
@directive(("extendees", "dependencies"), can_patch_dependencies=True)
def extends(
spec: str,
when: WhenType = None,
type: DepType = ("build", "run"),
*,
patches: Optional[PatchesType] = None,
):
"""Same as :func:`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
:func:`depends_on` where the default is ``("build", "link")``."""
return _Extends(spec, when, type, patches)
class _Extends(NamedTuple):
spec: str
when: WhenType
type: DepType
patches: Optional[PatchesType]
def __call__(self, pkg: PackageType) -> None:
spec, when, type, patches = self
when_spec = _make_when_spec(when)
if not when_spec:
return
dep_spec = get_spec(spec)
_DependsOn(dep_spec, when=when, type=type, patches=patches)(pkg)
# When extending python, also add a dependency on python-venv. This is done so that
# Spack environment views are Python virtual environments.
if dep_spec.name == "python" and not pkg.name == "python-venv":
_DependsOn("python-venv", when=when, type=("build", "run"))(pkg)
pkg.extendees[dep_spec.name] = (dep_spec, when_spec)
[docs]
@directive(("provided", "provided_together"))
def provides(*specs: SpecType, when: WhenType = None):
"""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.
Args:
*specs: virtual specs provided by this package
when: condition when this provides clause needs to be considered
"""
return _Provides(specs, when)
class _Provides(NamedTuple):
specs: Tuple[SpecType, ...]
when: WhenType
def __call__(self, pkg: PackageType) -> None:
specs, when = self
when_spec = _make_when_spec(when)
if not when_spec:
return
spec_objs = [get_spec(x) for x in specs]
spec_names = [x.name for x in spec_objs]
if len(spec_names) > 1:
pkg.provided_together.setdefault(when_spec, []).append(set(spec_names))
for provided_spec in spec_objs:
if pkg.name == provided_spec.name:
raise CircularReferenceError(f"Package '{pkg.name}' cannot provide itself.")
pkg.provided.setdefault(when_spec, set()).add(provided_spec)
[docs]
@directive("splice_specs")
def can_splice(
target: SpecType, *, when: SpecType, match_variants: Union[None, str, List[str]] = None
):
"""Declare whether the package is ABI-compatible with another package and thus can be spliced
into concrete versions of that package.
Args:
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 ``*``.
"""
return _CanSplice(target, when, match_variants)
class _CanSplice(NamedTuple):
target: SpecType
when: SpecType
match_variants: Union[None, str, List[str]]
def __call__(self, pkg: PackageType) -> None:
target, when, match_variants = self
when_spec = _make_when_spec(when)
if isinstance(match_variants, str) and match_variants != "*":
raise ValueError(
"* is the only valid string for match_variants "
"if looking to provide a single variant, use "
f"[{match_variants}] instead"
)
if when_spec is None:
return
pkg.splice_specs[when_spec] = (get_spec(target), match_variants)
[docs]
@directive("patches")
def patch(
url_or_filename: str,
level: int = 1,
when: WhenType = None,
working_dir: str = ".",
reverse: bool = False,
sha256: Optional[str] = None,
archive_sha256: Optional[str] = None,
) -> "_Patch":
"""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="...")
Args:
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)
"""
return _Patch(url_or_filename, level, when, working_dir, reverse, sha256, archive_sha256)
class _Patch(NamedTuple):
url_or_filename: str
level: int = 1
when: WhenType = None
working_dir: str = "."
reverse: bool = False
sha256: Optional[str] = None
archive_sha256: Optional[str] = None
def __call__(self, pkg: PackageType, dependency: Optional[Dependency] = None) -> None:
"""``pkg`` is the package that declares the patch; the patch file is looked up in its
directory. The patch is added to ``dependency`` when set, otherwise to ``pkg`` itself."""
url_or_filename, level, when, working_dir, reverse, sha256, archive_sha256 = self
target: Union[PackageType, Dependency] = pkg if dependency is None else dependency
if hasattr(pkg, "has_code") and not pkg.has_code:
raise UnsupportedPackageDirective(
"Patches are not allowed in {0}: package has no code.".format(pkg.name)
)
when_spec = _make_when_spec(when)
if not when_spec:
return
# If this spec is identical to some other, then append this
# patch to the existing list.
if target.patches is None:
target.patches = {}
cur_patches = target.patches.setdefault(when_spec, [])
global _patch_order_index
ordering_key = (pkg.name, _patch_order_index)
_patch_order_index += 1
patch: spack.patch.Patch
if "://" in url_or_filename:
if sha256 is None:
raise ValueError("patch() with a url requires a sha256")
patch = spack.patch.UrlPatch(
pkg,
url_or_filename,
level,
working_dir=working_dir,
reverse=reverse,
ordering_key=ordering_key,
sha256=sha256,
archive_sha256=archive_sha256,
)
else:
patch = spack.patch.FilePatch(
pkg, url_or_filename, level, working_dir, reverse, ordering_key=ordering_key
)
cur_patches.append(patch)
[docs]
def conditional(*values: Union[str, bool], when: Optional[WhenType] = None):
"""Conditional values that can be used in variant declarations."""
# _make_when_spec returns None when the condition is statically false.
when = _make_when_spec(when)
return spack.variant.ConditionalVariantValues(
spack.variant.ConditionalValue(x, when=when) for x in values
)
[docs]
@directive("variants")
def variant(
name: str,
default: Optional[Union[bool, str, Tuple[str, ...]]] = None,
description: str = "",
values: Optional[Union[collections.abc.Sequence, Callable[[Any], bool]]] = None,
multi: Optional[bool] = None,
validator: Optional[Callable[[str, str, Tuple[Any, ...]], None]] = None,
when: Optional[Union[str, bool]] = None,
sticky: bool = False,
):
"""Declare a variant for a package.
Packager can specify a default value as well as a text description.
Args:
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
"""
return _Variant(name, default, description, values, multi, validator, when, sticky)
def _format_error(msg, pkg, name):
msg += " @*r{{[{0}, variant '{1}']}}"
return spack.util.tty.color.colorize(msg.format(pkg.name, name))
class _Variant(NamedTuple):
name: str
default: Optional[Union[bool, str, Tuple[str, ...]]]
description: str
values: Optional[Union[collections.abc.Sequence, Callable[[Any], bool]]]
multi: Optional[bool]
validator: Optional[Callable[[str, str, Tuple[Any, ...]], None]]
when: Optional[Union[str, bool]]
sticky: bool
def __call__(self, pkg: PackageType) -> None:
name, default, description, values, multi, validator, when, sticky = self
if not (
default is None
or type(default) in (bool, str)
or (type(default) is tuple and all(type(x) is str for x in default))
):
if isinstance(default, (list, tuple)):
did_you_mean = f"default={','.join(str(x) for x in default)!r}"
else:
did_you_mean = f"default={str(default)!r}"
warnings.warn(
f"default value for variant '{name}' is not a boolean or string: "
f"default={default!r}. Did you mean {did_you_mean}?",
stacklevel=3,
category=spack.error.SpackAPIWarning,
)
if name in spack.variant.RESERVED_NAMES:
raise DirectiveError(
_format_error(f"The name '{name}' is reserved by Spack", pkg, name)
)
# Ensure we have a sequence of allowed variant values, or a
# predicate for it.
if values is None:
if (
default in (True, False)
or type(default) is str
and default.upper() in ("TRUE", "FALSE")
):
values = (True, False)
else:
values = lambda x: True
# The object defining variant values might supply its own defaults for
# all the other arguments. Ensure we have no conflicting definitions
# in place.
for argument, value in (("default", default), ("multi", multi), ("validator", validator)):
# TODO: we can consider treating 'default' differently from other
# TODO: attributes and let a packager decide whether to use the fluent
# TODO: interface or the directive argument
if hasattr(values, argument) and value is not None:
raise DirectiveError(
_format_error(
f"Remove specification of {argument} argument: it is handled "
"by an attribute of the 'values' argument",
pkg,
name,
)
)
# Allow for the object defining the allowed values to supply its own
# default value and group validator, say if it supports multiple values.
default = getattr(values, "default", default)
validator = getattr(values, "validator", validator)
multi = getattr(values, "multi", bool(multi))
# Here we sanitize against a default value being either None
# or the empty string, as the former indicates that a default
# was not set while the latter will make the variant unparsable
# from the command line
if isinstance(default, tuple):
default = ",".join(default)
if default is None or default == "":
if default is None:
msg = "either a default was not explicitly set, or 'None' was used"
else:
msg = "the default cannot be an empty string"
raise DirectiveError(_format_error(msg, pkg, name))
description = str(description).strip()
when_spec = _make_when_spec(when)
if not re.match(spack.spec.IDENTIFIER_RE, name):
raise DirectiveError("variant", f"Invalid variant name in {pkg.name}: '{name}'")
# variants are stored by condition then by name (so only the last variant of a
# given name takes precedence *per condition*).
# NOTE: variant defaults and values can conflict if when conditions overlap.
variants_by_name = pkg.variants.setdefault(when_spec, {}) # type: ignore[arg-type]
variants_by_name[name] = spack.variant.Variant(
name=name,
default=default,
description=description,
values=values,
multi=multi,
validator=validator,
sticky=sticky,
precedence=pkg.num_variant_definitions(),
)
[docs]
@directive("resources")
def resource(
*,
name: Optional[str] = None,
destination: str = "",
placement: Optional[str] = None,
when: WhenType = None,
# additional kwargs are as for `version()`
**kwargs,
):
"""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
"""
return _Resource(name, destination, placement, when, kwargs)
class _Resource(NamedTuple):
name: Optional[str]
destination: str
placement: Optional[str]
when: WhenType
kwargs: dict
def __call__(self, pkg: PackageType) -> None:
name, destination, placement, when, kwargs = self
when_spec = _make_when_spec(when)
if not when_spec:
return
# Check if the path is relative
if os.path.isabs(destination):
msg = "The destination keyword of a resource directive can't be an absolute path.\n"
msg += f"\tdestination : '{destination}\n'"
raise RuntimeError(msg)
# Check if the path falls within the main package stage area
test_path = "stage_folder_root"
# Normalized absolute path
normalized_destination = os.path.normpath(os.path.join(test_path, destination))
if test_path not in normalized_destination:
msg = "Destination of a resource must be within the package stage directory.\n"
msg += f"\tdestination : '{destination}'\n"
raise RuntimeError(msg)
resources = pkg.resources.setdefault(when_spec, [])
resources.append(
Resource(name, spack.fetch_strategy.from_kwargs(**kwargs), destination, placement)
)
[docs]
def build_system(*values, **kwargs):
"""Define the build system used by the package. This defines the ``build_system`` variant.
Example::
build_system("cmake", "autotools", "meson", default="cmake")
"""
default = kwargs.get("default", None) or values[0]
return variant(
"build_system",
values=tuple(values),
description="Build systems supported by the package",
default=default,
multi=False,
)
[docs]
@directive(dicts=())
def maintainers(*names: str):
"""Declare the maintainers of a package.
Args:
names: GitHub username for the maintainer
"""
return _Maintainers(names)
class _Maintainers(NamedTuple):
names: Tuple[str, ...]
def __call__(self, pkg: PackageType) -> None:
(names,) = self
maintainers = set(pkg.maintainers)
maintainers.update(names)
pkg.maintainers = sorted(maintainers)
[docs]
@directive("licenses")
def license(
license_identifier: str,
checked_by: Optional[Union[str, List[str]]] = None,
when: Optional[Union[str, bool]] = None,
):
"""Declare the license(s) the software is distributed under.
Args:
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.
"""
return _License(license_identifier, when)
class _License(NamedTuple):
license_identifier: str
when: Optional[Union[str, bool]]
def __call__(self, pkg: PackageType) -> None:
license_identifier, when = self
# If when is not specified the license always holds
when_spec = _make_when_spec(when)
if not when_spec:
return
for other_when_spec in pkg.licenses:
if when_spec.intersects(other_when_spec):
when_message = ""
if when_spec != EMPTY_SPEC:
when_message = f"when {when_spec}"
other_when_message = ""
if other_when_spec != EMPTY_SPEC:
other_when_message = f"when {other_when_spec}"
err_msg = (
f"{pkg.name} is specified as being licensed as {license_identifier} "
f"{when_message}, but it is also specified as being licensed under "
f"{pkg.licenses[other_when_spec]} {other_when_message}, which conflict."
)
raise OverlappingLicenseError(err_msg)
pkg.licenses[when_spec] = license_identifier
[docs]
@directive("requirements")
def requires(
*requirement_specs: str,
policy: str = "one_of",
when: Optional[str] = None,
msg: Optional[str] = None,
):
"""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")
Args:
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
"""
return _Requires(requirement_specs, policy, when, msg)
class _Requires(NamedTuple):
requirement_specs: Tuple[str, ...]
policy: str
when: Optional[str]
msg: Optional[str]
def __call__(self, pkg: PackageType) -> None:
requirement_specs, policy, when, msg = self
if policy not in ("one_of", "any_of"):
err_msg = (
f"the 'policy' argument of the 'requires' directive in {pkg.name} is set "
f"to a wrong value (only 'one_of' or 'any_of' are allowed)"
)
raise DirectiveError(err_msg)
when_spec = _make_when_spec(when)
if not when_spec:
return
# Save in a list the requirements and the associated custom messages
requirement_list = pkg.requirements.setdefault(when_spec, [])
msg_with_name = f"{pkg.name}: {msg}" if msg is not None else msg
requirements = tuple(get_spec(s) for s in requirement_specs)
requirement_list.append((requirements, policy, msg_with_name))
class DependencyError(DirectiveError):
"""This is raised when a dependency specification is invalid."""
class CircularReferenceError(DependencyError):
"""This is raised when something depends on itself."""
class DependencyPatchError(DirectiveError):
"""Raised for errors with patching dependencies."""
class UnsupportedPackageDirective(DirectiveError):
"""Raised when an invalid or unsupported package directive is specified."""
class OverlappingLicenseError(DirectiveError):
"""Raised when two licenses are declared that apply on overlapping specs."""