From dca4d2b15e6e78058d1ebdb244877470241f8f9c Mon Sep 17 00:00:00 2001 From: "Adam J. Stewart" Date: Wed, 15 Mar 2017 00:26:44 -0500 Subject: Consistent docs and usage of env mod methods (#3351) --- lib/spack/docs/packaging_guide.rst | 29 +++++----- lib/spack/spack/package.py | 113 ++++++++++++++++--------------------- 2 files changed, 61 insertions(+), 81 deletions(-) (limited to 'lib') diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst index 211e72158c..b794bb2581 100644 --- a/lib/spack/docs/packaging_guide.rst +++ b/lib/spack/docs/packaging_guide.rst @@ -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. diff --git a/lib/spack/spack/package.py b/lib/spack/spack/package.py index 8889de7576..80d65bd739 100644 --- a/lib/spack/spack/package.py +++ b/lib/spack/spack/package.py @@ -1393,32 +1393,29 @@ class PackageBase(object): 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: - - 1. Qt extensions need `QTDIR` set. - - Args: - spack_env (EnvironmentModifications): list of - modifications to be applied when this package is built - within Spack. + Example: - 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 @@ class PackageBase(object): 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. - - 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. + 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. + + :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 @@ class PackageBase(object): its extensions. This is useful if there are some common steps to installing all extensions for a certain package. - Example : - - 1. Extensions often need to invoke the `python` - interpreter from the Python installation being - extended. This routine can put a 'python' Executable - object in the module scope for the extension package to - simplify extension installs. - - 2. MPI compilers could set some variables in the - dependent's scope that point to `mpicc`, `mpicxx`, - etc., allowing them to be called by common names - regardless of which MPI is used. - - 3. BLAS/LAPACK implementations can set some variables - indicating the path to their libraries, since these - paths differ by BLAS/LAPACK implementation. + Examples: - Args: + 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. - module (module): The Python `module` object of the - dependent package. Packages can use this to set - module-scope variables for the dependent to use. + 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. - 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`. + 3. BLAS/LAPACK implementations can set some variables + indicating the path to their libraries, since these + paths differ by BLAS/LAPACK implementation. - 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 -- cgit v1.2.3-60-g2f50