|
|
.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
Spack Project Developers. See the top-level COPYRIGHT file for details.
SPDX-License-Identifier: (Apache-2.0 OR MIT)
.. _wafpackage:
---
Waf
---
Like SCons, Waf is a general-purpose build system that does not rely
on Makefiles to build software.
^^^^^^
Phases
^^^^^^
The ``WafBuilder`` and ``WafPackage`` base classes come with the following phases:
#. ``configure`` - configure the project
#. ``build`` - build the project
#. ``install`` - install the project
By default, these phases run:
.. code-block:: console
$ python waf configure --prefix=/path/to/installation/prefix
$ python waf build
$ python waf install
Each of these are standard Waf commands and can be found by running:
.. code-block:: console
$ python waf --help
Each phase provides a ``<phase>`` function that runs:
.. code-block:: console
$ python waf -j<jobs> <phase>
where ``<jobs>`` is the number of parallel jobs to build with. Each phase
also has a ``<phase_args>`` function that can pass arguments to this call.
All of these functions are empty. The ``configure`` phase
automatically adds ``--prefix=/path/to/installation/prefix``, so you
don't need to add that in the ``configure_args``.
^^^^^^^
Testing
^^^^^^^
``WafPackage`` also provides ``test`` and ``installtest`` methods,
which are run after the ``build`` and ``install`` phases, respectively.
By default, these phases do nothing, but you can override them to
run package-specific unit tests.
.. code-block:: python
def installtest(self):
with working_dir("test"):
pytest = which("py.test")
pytest()
^^^^^^^^^^^^^^^
Important files
^^^^^^^^^^^^^^^
Each Waf package comes with a custom ``waf`` build script, written in
Python. This script contains instructions to build the project.
The package also comes with a ``wscript`` file. This file is used to
override the default ``configure``, ``build``, and ``install`` phases
to customize the Waf project. It also allows developers to override
the default ``./waf --help`` message. Check this file to find useful
information about dependencies and the minimum versions that are
supported.
^^^^^^^^^^^^^^^^^^^^^^^^^
Build system dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^
``WafPackage`` does not require ``waf`` to build. ``waf`` is only
needed to create the ``./waf`` script. Since ``./waf`` is a Python
script, Python is needed to build the project. ``WafPackage`` adds
the following dependency automatically:
.. code-block:: python
depends_on("python@2.5:", type="build")
Waf only supports Python 2.5 and up.
^^^^^^^^^^^^^^^^^^^^^^^^
Passing arguments to waf
^^^^^^^^^^^^^^^^^^^^^^^^
As previously mentioned, each phase comes with a ``<phase_args>``
function that can be used to pass arguments to that particular
phase. For example, if you need to pass arguments to the build
phase, you can use:
.. code-block:: python
def build_args(self, spec, prefix):
args = []
if self.run_tests:
args.append("--test")
return args
A list of valid options can be found by running ``./waf --help``.
^^^^^^^^^^^^^^^^^^^^^^
External documentation
^^^^^^^^^^^^^^^^^^^^^^
For more information on the Waf build system, see:
https://waf.io/book/
|
