diff options
Diffstat (limited to 'lib/spack/docs/packaging_guide.rst')
| -rw-r--r-- | lib/spack/docs/packaging_guide.rst | 71 |
1 files changed, 37 insertions, 34 deletions
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst index 5adb996232..767a744baa 100644 --- a/lib/spack/docs/packaging_guide.rst +++ b/lib/spack/docs/packaging_guide.rst @@ -2032,55 +2032,58 @@ appear in the package file (or in this case, in the list). .. _setup-dependent-environment: -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``setup_dependent_environment()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Spack provides a mechanism for dependencies to provide variables that -can be used in their dependents' build. Any package can declare a -``setup_dependent_environment()`` function, and this function will be -called before the ``install()`` method of any dependent packages. -This allows dependencies to set up environment variables and other -properties to be used by dependents. - -The function declaration should look like this: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Influence how dependents are built or run +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Spack provides a mechanism for dependencies to influence the +environment of their dependents by overriding the +:meth:`setup_dependent_run_environment <spack.package.PackageBase.setup_dependent_run_environment>` +or the +:meth:`setup_dependent_build_environment <spack.package.PackageBase.setup_dependent_build_environment>` +methods. +The Qt package, for instance, uses this call: .. literalinclude:: _spack_root/var/spack/repos/builtin/packages/qt/package.py - :pyobject: Qt.setup_dependent_environment + :pyobject: Qt.setup_dependent_build_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: +to set the ``QTDIR`` environment variable so that packages +that depend on a particular Qt installation will find it. +Another good example of how a dependency can influence +the build environment of dependents is the Python package: -* **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``. +.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/python/package.py + :pyobject: Python.setup_dependent_build_environment + :linenos: -A good example of using these is in the Python package: +In the method above it is ensured that any package that depends on Python +will have the ``PYTHONPATH``, ``PYTHONHOME`` and ``PATH`` environment +variables set appropriately before starting the installation. To make things +even simpler the ``python setup.py`` command is also inserted into the module +scope of dependents by overriding a third method called +:meth:`setup_dependent_package <spack.package.PackageBase.setup_dependent_package>` +: .. literalinclude:: _spack_root/var/spack/repos/builtin/packages/python/package.py - :pyobject: Python.setup_dependent_environment + :pyobject: Python.setup_dependent_package :linenos: -The first thing that happens here is that the ``python`` command is -inserted into module scope of the dependent. This allows most python -packages to have a very simple install method, like this: +This allows most python packages to have a very simple install procedure, +like the following: .. code-block:: python def install(self, spec, prefix): - python('setup.py', 'install', '--prefix={0}'.format(prefix)) + setup_py('install', '--prefix={0}'.format(prefix)) + +Finally the Python package takes also care of the modifications to ``PYTHONPATH`` +to allow dependencies to run correctly: + +.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/python/package.py + :pyobject: Python.setup_dependent_run_environment + :linenos: -Python's ``setup_dependent_environment`` method also sets up some -other variables, creates a directory, and sets up the ``PYTHONPATH`` -so that dependent packages can find their dependencies at build time. .. _packaging_conflicts: |