zhangyiss/spack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Consistent docs and usage of env mod methods (#3351)

Browse Source
This commit is contained in:
Adam J. Stewart
2017-03-15 00:26:44 -05:00
committed by Todd Gamblin
parent 560d28ac7f
commit dca4d2b15e
26 changed files with 123 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
lib/spack/docs/packaging_guide.rst
View File

@@ -1523,23 +1523,23 @@ properties to be used by dependents.
The function declaration should look like this:
.. code-block:: python
class Qt(Package):
...
def setup_dependent_environment(self, module, spec, dep_spec):
"""Dependencies of Qt find it using the QTDIR environment variable."""
os.environ['QTDIR'] = self.prefix
.. literalinclude:: ../../../var/spack/repos/builtin/packages/qt/package.py
:pyobject: Qt.setup_dependent_environment
:linenos:
Here, the Qt package sets the ``QTDIR`` environment variable so that
packages that depend on a particular Qt installation will find it.
The arguments to this function are:
* **module**: the module of the dependent package, where global
properties can be assigned.
* **spec**: the spec of the *dependency package* (the one the function is called on).
* **dep_spec**: the spec of the dependent package (i.e. dep_spec depends on spec).
* **spack_env**: List of environment modifications to be applied when
the dependent package is built within Spack.
* **run_env**: List of environment modifications to be applied when
the dependent package is run outside of Spack. These are added to the
resulting module file.
* **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``.
A good example of using these is in the Python package:
@@ -2805,11 +2805,8 @@ the one passed to install, only the MPI implementations all set some
additional properties on it to help you out. E.g., in mvapich2, you'll
find this:
.. code-block:: python
def setup_dependent_package(self, module, dep_spec):
self.spec.mpicc = join_path(self.prefix.bin, 'mpicc')
# … etc …
.. literalinclude:: ../../../var/spack/repos/builtin/packages/mvapich2/package.py
:pyobject: Mvapich2.setup_dependent_package
That code allows the mvapich2 package to associate an ``mpicc`` property
with the ``mvapich2`` node in the DAG, so that dependents can access it.

111
lib/spack/spack/package.py
View File

@@ -1393,32 +1393,29 @@ def module(self):
def setup_environment(self, spack_env, run_env):
"""Set up the compile and runtime environments for a package.
`spack_env` and `run_env` are `EnvironmentModifications`
objects. Package authors can call methods on them to alter
``spack_env`` and ``run_env`` are ``EnvironmentModifications``
objects. Package authors can call methods on them to alter
the environment within Spack and at runtime.
Both `spack_env` and `run_env` are applied within the build
process, before this package's `install()` method is called.
Both ``spack_env`` and ``run_env`` are applied within the build
process, before this package's ``install()`` method is called.
Modifications in `run_env` will *also* be added to the
Modifications in ``run_env`` will *also* be added to the
generated environment modules for this package.
Default implementation does nothing, but this can be
overridden if the package needs a particular environment.
Examples:
Example:
1. Qt extensions need `QTDIR` set.
Args:
spack_env (EnvironmentModifications): list of
modifications to be applied when this package is built
within Spack.
run_env (EnvironmentModifications): list of environment
changes to be applied when this package is run outside
of Spack.
1. Qt extensions need ``QTDIR`` set.
:param EnvironmentModifications spack_env: List of environment
modifications to be applied when this package is built
within Spack.
:param EnvironmentModifications run_env: List of environment
modifications to be applied when this package is run outside
of Spack. These are added to the resulting module file.
"""
pass
@@ -1431,32 +1428,26 @@ def setup_dependent_environment(self, spack_env, run_env, dependent_spec):
others that follow the extension model a way to implement
common environment or compile-time settings for dependencies.
By default, this delegates to ``self.setup_environment()``
This is useful if there are some common steps to installing
all extensions for a certain package.
Example:
1. Installing python modules generally requires
`PYTHONPATH` to point to the lib/pythonX.Y/site-packages
directory in the module's install prefix. This could
set that variable.
1. Installing python modules generally requires ``PYTHONPATH`` to point
to the ``lib/pythonX.Y/site-packages`` directory in the module's
install prefix. This method could be used to set that variable.
Args:
spack_env (EnvironmentModifications): list of
modifications to be applied when the dependent package
is bulit within Spack.
run_env (EnvironmentModifications): list of environment
changes to be applied when the dependent package is
run outside of Spack.
dependent_spec (Spec): The spec of the dependent package
about to be built. This allows the extendee (self) to
query the dependent's state. Note that *this*
package's spec is available as `self.spec`.
This is useful if there are some common steps to installing
all extensions for a certain package.
:param EnvironmentModifications spack_env: List of environment
modifications to be applied when the dependent package is
built within Spack.
:param EnvironmentModifications run_env: List of environment
modifications to be applied when the dependent package is
run outside of Spack. These are added to the resulting
module file.
:param Spec 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``.
"""
pass
@@ -1470,37 +1461,29 @@ def setup_dependent_package(self, module, dependent_spec):
its extensions. This is useful if there are some common steps
to installing all extensions for a certain package.
Example :
Examples:
1. Extensions often need to invoke the `python`
interpreter from the Python installation being
extended. This routine can put a 'python' Executable
object in the module scope for the extension package to
simplify extension installs.
1. Extensions often need to invoke the ``python`` interpreter
from the Python installation being extended. This routine
can put a ``python()`` Executable object in the module scope
for the extension package to simplify extension installs.
2. MPI compilers could set some variables in the
dependent's scope that point to `mpicc`, `mpicxx`,
etc., allowing them to be called by common names
regardless of which MPI is used.
2. MPI compilers could set some variables in the dependent's
scope that point to ``mpicc``, ``mpicxx``, etc., allowing
them to be called by common name regardless of which MPI is used.
3. BLAS/LAPACK implementations can set some variables
indicating the path to their libraries, since these
paths differ by BLAS/LAPACK implementation.
3. BLAS/LAPACK implementations can set some variables
indicating the path to their libraries, since these
paths differ by BLAS/LAPACK implementation.
Args:
module (module): The Python `module` object of the
dependent package. Packages can use this to set
module-scope variables for the dependent to use.
dependent_spec (Spec): The spec of the dependent package
about to be built. This allows the extendee (self) to
query the dependent's state. Note that *this*
package's spec is available as `self.spec`.
This is useful if there are some common steps to installing
all extensions for a certain package.
:param spack.package.PackageBase.module module: The Python ``module``
object of the dependent package. Packages can use this to set
module-scope variables for the dependent to use.
:param Spec 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``.
"""
pass