Allow for packages with multiple build-systems (#30738)

This commit extends the DSL that can be used in packages
to allow declaring that a package uses different build-systems
under different conditions.

It requires each spec to have a `build_system` single valued
variant. The variant can be used in many context to query, manipulate
or select the build system associated with a concrete spec.

The knowledge to build a package has been moved out of the
PackageBase hierarchy, into a new Builder hierarchy. Customization
of the default behavior for a given builder can be obtained by
coding a new derived builder in package.py.

The "run_after" and "run_before" decorators are now applied to
methods on the builder. They can also incorporate a "when="
argument to specify that a method is run only when certain
conditions apply.

For packages that do not define their own builder, forwarding logic
is added between the builder and package (methods not found in one
will be retrieved from the other); this PR is expected to be fully
backwards compatible with unmodified packages that use a single
build system.

17 files changed, 63 insertions, 413 deletions

diff --git a/lib/spack/docs/build_systems/autotoolspackage.rst b/lib/spack/docs/build_systems/autotoolspackage.rst
index d341d28d08..88fabc0c5d 100644
--- a/lib/spack/docs/build_systems/autotoolspackage.rst
+++ b/lib/spack/docs/build_systems/autotoolspackage.rst
@@ -5,9 +5,9 @@
 
 .. _autotoolspackage:
 
-----------------
-AutotoolsPackage
-----------------
+---------
+Autotools
+---------
 
 Autotools is a GNU build system that provides a build-script generator.
 By running the platform-independent ``./configure`` script that comes
@@ -17,7 +17,7 @@ with the package, you can generate a platform-dependent Makefile.
 Phases
 ^^^^^^
 
-The ``AutotoolsPackage`` base class comes with the following phases:
+The ``AutotoolsBuilder`` and ``AutotoolsPackage`` base classes come with the following phases:
 
 #. ``autoreconf`` - generate the configure script
 #. ``configure`` - generate the Makefiles
diff --git a/lib/spack/docs/build_systems/bundlepackage.rst b/lib/spack/docs/build_systems/bundlepackage.rst
index 8787dce546..7a826f5e17 100644
--- a/lib/spack/docs/build_systems/bundlepackage.rst
+++ b/lib/spack/docs/build_systems/bundlepackage.rst
@@ -5,9 +5,9 @@
 
 .. _bundlepackage:
 
--------------
-BundlePackage
--------------
+------
+Bundle
+------
 
 ``BundlePackage`` represents a set of packages that are expected to work well
 together, such as a collection of commonly used software libraries.  The
diff --git a/lib/spack/docs/build_systems/cmakepackage.rst b/lib/spack/docs/build_systems/cmakepackage.rst
index 9544a7df73..7a1db842de 100644
--- a/lib/spack/docs/build_systems/cmakepackage.rst
+++ b/lib/spack/docs/build_systems/cmakepackage.rst
@@ -5,9 +5,9 @@
 
 .. _cmakepackage:
 
-------------
-CMakePackage
-------------
+-----
+CMake
+-----
 
 Like Autotools, CMake is a widely-used build-script generator. Designed
 by Kitware, CMake is the most popular build system for new C, C++, and
@@ -21,7 +21,7 @@ whereas Autotools is Unix-only.
 Phases
 ^^^^^^
 
-The ``CMakePackage`` base class comes with the following phases:
+The ``CMakeBuilder`` and ``CMakePackage`` base classes come with the following phases:
 
 #. ``cmake`` - generate the Makefile
 #. ``build`` - build the package
@@ -130,8 +130,8 @@ Adding flags to cmake
 To add additional flags to the ``cmake`` call, simply override the
 ``cmake_args`` function. The following example defines values for the flags
 ``WHATEVER``, ``ENABLE_BROKEN_FEATURE``, ``DETECT_HDF5``, and ``THREADS`` with
-and without the :meth:`~spack.build_systems.cmake.CMakePackage.define` and
-:meth:`~spack.build_systems.cmake.CMakePackage.define_from_variant` helper functions:
+and without the :meth:`~spack.build_systems.cmake.CMakeBuilder.define` and
+:meth:`~spack.build_systems.cmake.CMakeBuilder.define_from_variant` helper functions:
 
 .. code-block:: python
 
diff --git a/lib/spack/docs/build_systems/luapackage.rst b/lib/spack/docs/build_systems/luapackage.rst
index 6332edfc20..fd70f90c49 100644
--- a/lib/spack/docs/build_systems/luapackage.rst
+++ b/lib/spack/docs/build_systems/luapackage.rst
@@ -5,11 +5,11 @@
 
 .. _luapackage:
 
-------------
-LuaPackage
-------------
+---
+Lua
+---
 
-LuaPackage is a helper for the common case of Lua packages that provide
+The ``Lua`` build-system is a helper for the common case of Lua packages that provide
 a rockspec file.  This is not meant to take a rock archive, but to build
 a source archive or repository that provides a rockspec, which should cover
 most lua packages. In the case a Lua package builds by Make rather than
@@ -19,7 +19,7 @@ luarocks, prefer MakefilePackage.
 Phases
 ^^^^^^
 
-The ``LuaPackage`` base class comes with the following phases:
+The ``LuaBuilder`` and `LuaPackage`` base classes come with the following phases:
 
 #. ``unpack`` - if using a rock, unpacks the rock and moves into the source directory
 #. ``preprocess`` - adjust sources or rockspec to fix build
diff --git a/lib/spack/docs/build_systems/makefilepackage.rst b/lib/spack/docs/build_systems/makefilepackage.rst
index c092432037..5a83d612fa 100644
--- a/lib/spack/docs/build_systems/makefilepackage.rst
+++ b/lib/spack/docs/build_systems/makefilepackage.rst
@@ -5,9 +5,9 @@
 
 .. _makefilepackage:
 
----------------
-MakefilePackage
----------------
+--------
+Makefile
+--------
 
 The most primitive build system a package can use is a plain Makefile.
 Makefiles are simple to write for small projects, but they usually
@@ -18,7 +18,7 @@ variables.
 Phases
 ^^^^^^
 
-The ``MakefilePackage`` base class comes with 3 phases:
+The ``MakefileBuilder`` and ``MakefilePackage`` base classes come with 3 phases:
 
 #. ``edit`` - edit the Makefile
 #. ``build`` - build the project
diff --git a/lib/spack/docs/build_systems/mavenpackage.rst b/lib/spack/docs/build_systems/mavenpackage.rst
index 94ce128d3a..d1237ce34c 100644
--- a/lib/spack/docs/build_systems/mavenpackage.rst
+++ b/lib/spack/docs/build_systems/mavenpackage.rst
@@ -5,9 +5,9 @@
 
 .. _mavenpackage:
 
-------------
-MavenPackage
-------------
+-----
+Maven
+-----
 
 Apache Maven is a general-purpose build system that does not rely
 on Makefiles to build software. It is designed for building and
@@ -17,7 +17,7 @@ managing and Java-based project.
 Phases
 ^^^^^^
 
-The ``MavenPackage`` base class comes with the following phases:
+The ``MavenBuilder`` and ``MavenPackage`` base classes come with the following phases:
 
 #. ``build`` - compile code and package into a JAR file
 #. ``install`` - copy to installation prefix
diff --git a/lib/spack/docs/build_systems/mesonpackage.rst b/lib/spack/docs/build_systems/mesonpackage.rst
index 5ca444dcb1..c32b2241bc 100644
--- a/lib/spack/docs/build_systems/mesonpackage.rst
+++ b/lib/spack/docs/build_systems/mesonpackage.rst
@@ -5,9 +5,9 @@
 
 .. _mesonpackage:
 
-------------
-MesonPackage
-------------
+-----
+Meson
+-----
 
 Much like Autotools and CMake, Meson is a build system.  But it is
 meant to be both fast and as user friendly as possible.  GNOME's goal
@@ -17,7 +17,7 @@ is to port modules to use the Meson build system.
 Phases
 ^^^^^^
 
-The ``MesonPackage`` base class comes with the following phases:
+The ``MesonBuilder`` and ``MesonPackage`` base classes come with the following phases:
 
 #. ``meson`` - generate ninja files
 #. ``build`` - build the project
diff --git a/lib/spack/docs/build_systems/multiplepackage.rst b/lib/spack/docs/build_systems/multiplepackage.rst
deleted file mode 100644
index 71751f0dbf..0000000000
--- a/lib/spack/docs/build_systems/multiplepackage.rst
+++ /dev/null
@@ -1,350 +0,0 @@
-.. Copyright 2013-2022 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)
-
-.. _multiplepackage:
-
-----------------------
-Multiple Build Systems
-----------------------
-
-Quite frequently, a package will change build systems from one version to the
-next. For example, a small project that once used a single Makefile to build
-may now require Autotools to handle the increased number of files that need to
-be compiled. Or, a package that once used Autotools may switch to CMake for
-Windows support. In this case, it becomes a bit more challenging to write a
-single build recipe for this package in Spack.
-
-There are several ways that this can be handled in Spack:
-
-#. Subclass the new build system, and override phases as needed (preferred)
-#. Subclass ``Package`` and implement ``install`` as needed
-#. Create separate ``*-cmake``, ``*-autotools``, etc. packages for each build system
-#. Rename the old package to ``*-legacy`` and create a new package
-#. Move the old package to a ``legacy`` repository and create a new package
-#. Drop older versions that only support the older build system
-
-Of these options, 1 is preferred, and will be demonstrated in this
-documentation. Options 3-5 have issues with concretization, so shouldn't be
-used. Options 4-5 also don't support more than two build systems. Option 6 only
-works if the old versions are no longer needed. Option 1 is preferred over 2
-because it makes it easier to drop the old build system entirely.
-
-The exact syntax of the package depends on which build systems you need to
-support. Below are a couple of common examples.
-
-^^^^^^^^^^^^^^^^^^^^^
-Makefile -> Autotools
-^^^^^^^^^^^^^^^^^^^^^
-
-Let's say we have the following package:
-
-.. code-block:: python
-
-   class Foo(MakefilePackage):
-       version("1.2.0", sha256="...")
-
-       def edit(self, spec, prefix):
-           filter_file("CC=", "CC=" + spack_cc, "Makefile")
-
-       def install(self, spec, prefix):
-           install_tree(".", prefix)
-
-
-The package subclasses from :ref:`makefilepackage`, which has three phases:
-
-#. ``edit`` (does nothing by default)
-#. ``build`` (runs ``make`` by default)
-#. ``install`` (runs ``make install`` by default)
-
-In this case, the ``install`` phase needed to be overridden because the
-Makefile did not have an install target. We also modify the Makefile to use
-Spack's compiler wrappers. The default ``build`` phase is not changed.
-
-Starting with version 1.3.0, we want to use Autotools to build instead.
-:ref:`autotoolspackage` has four phases:
-
-#. ``autoreconf`` (does not if a configure script already exists)
-#. ``configure`` (runs ``./configure --prefix=...`` by default)
-#. ``build`` (runs ``make`` by default)
-#. ``install`` (runs ``make install`` by default)
-
-If the only version we need to support is 1.3.0, the package would look as
-simple as:
-
-.. code-block:: python
-
-   class Foo(AutotoolsPackage):
-       version("1.3.0", sha256="...")
-
-       def configure_args(self):
-           return ["--enable-shared"]
-
-
-In this case, we use the default methods for each phase and only override
-``configure_args`` to specify additional flags to pass to ``./configure``.
-
-If we wanted to write a single package that supports both versions 1.2.0 and
-1.3.0, it would look something like:
-
-.. code-block:: python
-
-   class Foo(AutotoolsPackage):
-       version("1.3.0", sha256="...")
-       version("1.2.0", sha256="...", deprecated=True)
-
-       def configure_args(self):
-           return ["--enable-shared"]
-
-       # Remove the following once version 1.2.0 is dropped
-       @when("@:1.2")
-       def patch(self):
-           filter_file("CC=", "CC=" + spack_cc, "Makefile")
-
-       @when("@:1.2")
-       def autoreconf(self, spec, prefix):
-           pass
-
-       @when("@:1.2")
-       def configure(self, spec, prefix):
-           pass
-
-       @when("@:1.2")
-       def install(self, spec, prefix):
-           install_tree(".", prefix)
-
-
-There are a few interesting things to note here:
-
-* We added ``deprecated=True`` to version 1.2.0. This signifies that version
-  1.2.0 is deprecated and shouldn't be used. However, if a user still relies
-  on version 1.2.0, it's still there and builds just fine.
-* We moved the contents of the ``edit`` phase to the ``patch`` function. Since
-  ``AutotoolsPackage`` doesn't have an ``edit`` phase, the only way for this
-  step to be executed is to move it to the ``patch`` function, which always
-  gets run.
-* The ``autoreconf`` and ``configure`` phases become no-ops. Since the old
-  Makefile-based build system doesn't use these, we ignore these phases when
-  building ``foo@1.2.0``.
-* The ``@when`` decorator is used to override these phases only for older
-  versions. The default methods are used for ``foo@1.3:``.
-
-Once a new Spack release comes out, version 1.2.0 and everything below the
-comment can be safely deleted. The result is the same as if we had written a
-package for version 1.3.0 from scratch.
-
-^^^^^^^^^^^^^^^^^^
-Autotools -> CMake
-^^^^^^^^^^^^^^^^^^
-
-Let's say we have the following package:
-
-.. code-block:: python
-
-   class Bar(AutotoolsPackage):
-       version("1.2.0", sha256="...")
-
-       def configure_args(self):
-           return ["--enable-shared"]
-
-
-The package subclasses from :ref:`autotoolspackage`, which has four phases:
-
-#. ``autoreconf`` (does not if a configure script already exists)
-#. ``configure`` (runs ``./configure --prefix=...`` by default)
-#. ``build`` (runs ``make`` by default)
-#. ``install`` (runs ``make install`` by default)
-
-In this case, we use the default methods for each phase and only override
-``configure_args`` to specify additional flags to pass to ``./configure``.
-
-Starting with version 1.3.0, we want to use CMake to build instead.
-:ref:`cmakepackage` has three phases:
-
-#. ``cmake`` (runs ``cmake ...`` by default)
-#. ``build`` (runs ``make`` by default)
-#. ``install`` (runs ``make install`` by default)
-
-If the only version we need to support is 1.3.0, the package would look as
-simple as:
-
-.. code-block:: python
-
-   class Bar(CMakePackage):
-       version("1.3.0", sha256="...")
-
-       def cmake_args(self):
-           return [self.define("BUILD_SHARED_LIBS", True)]
-
-
-In this case, we use the default methods for each phase and only override
-``cmake_args`` to specify additional flags to pass to ``cmake``.
-
-If we wanted to write a single package that supports both versions 1.2.0 and
-1.3.0, it would look something like:
-
-.. code-block:: python
-
-   class Bar(CMakePackage):
-       version("1.3.0", sha256="...")
-       version("1.2.0", sha256="...", deprecated=True)
-
-       def cmake_args(self):
-           return [self.define("BUILD_SHARED_LIBS", True)]
-
-       # Remove the following once version 1.2.0 is dropped
-       def configure_args(self):
-           return ["--enable-shared"]
-
-       @when("@:1.2")
-       def cmake(self, spec, prefix):
-           configure("--prefix=" + prefix, *self.configure_args())
-
-
-There are a few interesting things to note here:
-
-* We added ``deprecated=True`` to version 1.2.0. This signifies that version
-  1.2.0 is deprecated and shouldn't be used. However, if a user still relies
-  on version 1.2.0, it's still there and builds just fine.
-* Since CMake and Autotools are so similar, we only need to override the
-  ``cmake`` phase, we can use the default ``build`` and ``install`` phases.
-* We override ``cmake`` to run ``./configure`` for older versions.
-  ``configure_args`` remains the same.
-* The ``@when`` decorator is used to override these phases only for older
-  versions. The default methods are used for ``bar@1.3:``.
-
-Once a new Spack release comes out, version 1.2.0 and everything below the
-comment can be safely deleted. The result is the same as if we had written a
-package for version 1.3.0 from scratch.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Multiple build systems for the same version
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-During the transition from one build system to another, developers often
-support multiple build systems at the same time. Spack can only use a single
-build system for a single version. To decide which build system to use for a
-particular version, take the following things into account:
-
-1. If the developers explicitly state that one build system is preferred over
-   another, use that one.
-2. If one build system is considered "experimental" while another is considered
-   "stable", use the stable build system.
-3. Otherwise, use the newer build system.
-
-The developer preference for which build system to use can change over time as
-a newer build system becomes stable/recommended.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Dropping support for old build systems
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When older versions of a package don't support a newer build system, it can be
-tempting to simply delete them from a package. This significantly reduces
-package complexity and makes the build recipe much easier to maintain. However,
-other packages or Spack users may rely on these older versions. The recommended
-approach is to first support both build systems (as demonstrated above),
-:ref:`deprecate <deprecate>` versions that rely on the old build system, and
-remove those versions and any phases that needed to be overridden in the next
-Spack release.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Three or more build systems
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In rare cases, a package may change build systems multiple times. For example,
-a package may start with Makefiles, then switch to Autotools, then switch to
-CMake. The same logic used above can be extended to any number of build systems.
-For example:
-
-.. code-block:: python
-
-   class Baz(CMakePackage):
-       version("1.4.0", sha256="...")  # CMake
-       version("1.3.0", sha256="...")  # Autotools
-       version("1.2.0", sha256="...")  # Makefile
-
-       def cmake_args(self):
-           return [self.define("BUILD_SHARED_LIBS", True)]
-
-       # Remove the following once version 1.3.0 is dropped
-       def configure_args(self):
-           return ["--enable-shared"]
-
-       @when("@1.3")
-       def cmake(self, spec, prefix):
-           configure("--prefix=" + prefix, *self.configure_args())
-
-       # Remove the following once version 1.2.0 is dropped
-       @when("@:1.2")
-       def patch(self):
-           filter_file("CC=", "CC=" + spack_cc, "Makefile")
-
-       @when("@:1.2")
-       def cmake(self, spec, prefix):
-           pass
-
-       @when("@:1.2")
-       def install(self, spec, prefix):
-           install_tree(".", prefix)
-
-
-^^^^^^^^^^^^^^^^^^^
-Additional examples
-^^^^^^^^^^^^^^^^^^^
-
-When writing new packages, it often helps to see examples of existing packages.
-Here is an incomplete list of existing Spack packages that have changed build
-systems before:
-
-================  =====================  ================
-Package           Previous Build System  New Build System
-================  =====================  ================
-amber             custom                 CMake
-arpack-ng         Autotools              CMake
-atk               Autotools              Meson
-blast             None                   Autotools
-dyninst           Autotools              CMake
-evtgen            Autotools              CMake
-fish              Autotools              CMake
-gdk-pixbuf        Autotools              Meson
-glib              Autotools              Meson
-glog              Autotools              CMake
-gmt               Autotools              CMake
-gtkplus           Autotools              Meson
-hpl               Makefile               Autotools
-interproscan      Perl                   Maven
-jasper            Autotools              CMake
-kahip             SCons                  CMake
-kokkos            Makefile               CMake
-kokkos-kernels    Makefile               CMake
-leveldb           Makefile               CMake
-libdrm            Autotools              Meson
-libjpeg-turbo     Autotools              CMake
-mesa              Autotools              Meson
-metis             None                   CMake
-mpifileutils      Autotools              CMake
-muparser          Autotools              CMake
-mxnet             Makefile               CMake
-nest              Autotools              CMake
-neuron            Autotools              CMake
-nsimd             CMake                  nsconfig
-opennurbs         Makefile               CMake
-optional-lite     None                   CMake
-plasma            Makefile               CMake
-preseq            Makefile               Autotools
-protobuf          Autotools              CMake
-py-pygobject      Autotools              Python
-singularity       Autotools              Makefile
-span-lite         None                   CMake
-ssht              Makefile               CMake
-string-view-lite  None                   CMake
-superlu           Makefile               CMake
-superlu-dist      Makefile               CMake
-uncrustify        Autotools              CMake
-================  =====================  ================
-
-Packages that support multiple build systems can be a bit confusing to write.
-Don't hesitate to open an issue or draft pull request and ask for advice from
-other Spack developers!
diff --git a/lib/spack/docs/build_systems/octavepackage.rst b/lib/spack/docs/build_systems/octavepackage.rst
index 9a81671db6..32e8cb61b3 100644
--- a/lib/spack/docs/build_systems/octavepackage.rst
+++ b/lib/spack/docs/build_systems/octavepackage.rst
@@ -5,9 +5,9 @@
 
 .. _octavepackage:
 
--------------
-OctavePackage
--------------
+------
+Octave
+------
 
 Octave has its own build system for installing packages.
 
@@ -15,7 +15,7 @@ Octave has its own build system for installing packages.
 Phases
 ^^^^^^
 
-The ``OctavePackage`` base class has a single phase:
+The ``OctaveBuilder`` and ``OctavePackage`` base classes have a single phase:
 
 #. ``install`` - install the package
 
diff --git a/lib/spack/docs/build_systems/perlpackage.rst b/lib/spack/docs/build_systems/perlpackage.rst
index be81ca6ce9..4e1f613c3b 100644
--- a/lib/spack/docs/build_systems/perlpackage.rst
+++ b/lib/spack/docs/build_systems/perlpackage.rst
@@ -5,9 +5,9 @@
 
 .. _perlpackage:
 
------------
-PerlPackage
------------
+----
+Perl
+----
 
 Much like Octave, Perl has its own language-specific
 build system.
@@ -16,7 +16,7 @@ build system.
 Phases
 ^^^^^^
 
-The ``PerlPackage`` base class comes with 3 phases that can be overridden:
+The ``PerlBuilder`` and ``PerlPackage`` base classes come with 3 phases that can be overridden:
 
 #. ``configure`` - configure the package
 #. ``build`` - build the package
diff --git a/lib/spack/docs/build_systems/qmakepackage.rst b/lib/spack/docs/build_systems/qmakepackage.rst
index 6e8bcef7cc..215d59536e 100644
--- a/lib/spack/docs/build_systems/qmakepackage.rst
+++ b/lib/spack/docs/build_systems/qmakepackage.rst
@@ -5,9 +5,9 @@
 
 .. _qmakepackage:
 
-------------
-QMakePackage
-------------
+-----
+QMake
+-----
 
 Much like Autotools and CMake, QMake is a build-script generator
 designed by the developers of Qt. In its simplest form, Spack's
@@ -29,7 +29,7 @@ variables or edit ``*.pro`` files to get things working properly.
 Phases
 ^^^^^^
 
-The ``QMakePackage`` base class comes with the following phases:
+The ``QMakeBuilder`` and ``QMakePackage`` base classes come with the following phases:
 
 #. ``qmake`` - generate Makefiles
 #. ``build`` - build the project
diff --git a/lib/spack/docs/build_systems/racketpackage.rst b/lib/spack/docs/build_systems/racketpackage.rst
index 8ba37ceeba..5e09ffca4a 100644
--- a/lib/spack/docs/build_systems/racketpackage.rst
+++ b/lib/spack/docs/build_systems/racketpackage.rst
@@ -5,9 +5,9 @@
 
 .. _racketpackage:
 
--------------
-RacketPackage
--------------
+------
+Racket
+------
 
 Much like Python, Racket packages and modules have their own special build system.
 To learn more about the specifics of Racket package system, please refer to the
@@ -17,7 +17,7 @@ To learn more about the specifics of Racket package system, please refer to the
 Phases
 ^^^^^^
 
-The ``RacketPackage`` base class provides an ``install`` phase that
+The ``RacketBuilder`` and ``RacketPackage`` base classes provides an ``install`` phase that
 can be overridden, corresponding to the use of:
 
 .. code-block:: console
diff --git a/lib/spack/docs/build_systems/rpackage.rst b/lib/spack/docs/build_systems/rpackage.rst
index 671af779b1..ebf2270e8e 100644
--- a/lib/spack/docs/build_systems/rpackage.rst
+++ b/lib/spack/docs/build_systems/rpackage.rst
@@ -19,7 +19,7 @@ new Spack packages for.
 Phases
 ^^^^^^
 
-The ``RPackage`` base class has a single phase:
+The ``RBuilder`` and ``RPackage`` base classes have a single phase:
 
 #. ``install`` - install the package
 
diff --git a/lib/spack/docs/build_systems/rubypackage.rst b/lib/spack/docs/build_systems/rubypackage.rst
index b64ac60b2f..5b6ec462a6 100644
--- a/lib/spack/docs/build_systems/rubypackage.rst
+++ b/lib/spack/docs/build_systems/rubypackage.rst
@@ -5,9 +5,9 @@
 
 .. _rubypackage:
 
------------
-RubyPackage
------------
+----
+Ruby
+----
 
 Like Perl, Python, and R, Ruby has its own build system for
 installing Ruby gems.
@@ -16,7 +16,7 @@ installing Ruby gems.
 Phases
 ^^^^^^
 
-The ``RubyPackage`` base class provides the following phases that
+The ``RubyBuilder`` and ``RubyPackage`` base classes provide the following phases that
 can be overridden:
 
 #. ``build`` - build everything needed to install
diff --git a/lib/spack/docs/build_systems/sconspackage.rst b/lib/spack/docs/build_systems/sconspackage.rst
index cea0408651..aea5dacfa7 100644
--- a/lib/spack/docs/build_systems/sconspackage.rst
+++ b/lib/spack/docs/build_systems/sconspackage.rst
@@ -5,9 +5,9 @@
 
 .. _sconspackage:
 
-------------
-SConsPackage
-------------
+-----
+SCons
+-----
 
 SCons is a general-purpose build system that does not rely on
 Makefiles to build software. SCons is written in Python, and handles
@@ -42,7 +42,7 @@ As previously mentioned, SCons allows developers to add subcommands like
    $ scons install
 
 
-To facilitate this, the ``SConsPackage`` base class provides the
+To facilitate this, the ``SConsBuilder`` and ``SconsPackage`` base classes provide the
 following phases:
 
 #. ``build`` - build the package
diff --git a/lib/spack/docs/build_systems/sippackage.rst b/lib/spack/docs/build_systems/sippackage.rst
index 5235015a92..3e77968e80 100644
--- a/lib/spack/docs/build_systems/sippackage.rst
+++ b/lib/spack/docs/build_systems/sippackage.rst
@@ -5,9 +5,9 @@
 
 .. _sippackage:
 
-----------
-SIPPackage
-----------
+---
+SIP
+---
 
 SIP is a tool that makes it very easy to create Python bindings for C and C++
 libraries. It was originally developed to create PyQt, the Python bindings for
@@ -22,7 +22,7 @@ provides support functions to the automatically generated code.
 Phases
 ^^^^^^
 
-The ``SIPPackage`` base class comes with the following phases:
+The ``SIPBuilder`` and ``SIPPackage`` base classes come with the following phases:
 
 #. ``configure`` - configure the package
 #. ``build`` - build the package
diff --git a/lib/spack/docs/build_systems/wafpackage.rst b/lib/spack/docs/build_systems/wafpackage.rst
index 54fcba98d0..f91479ce43 100644
--- a/lib/spack/docs/build_systems/wafpackage.rst
+++ b/lib/spack/docs/build_systems/wafpackage.rst
@@ -5,9 +5,9 @@
 
 .. _wafpackage:
 
-----------
-WafPackage
-----------
+---
+Waf
+---
 
 Like SCons, Waf is a general-purpose build system that does not rely
 on Makefiles to build software.
@@ -16,7 +16,7 @@ on Makefiles to build software.
 Phases
 ^^^^^^
 
-The ``WafPackage`` base class comes with the following phases:
+The ``WafBuilder`` and ``WafPackage`` base classes come with the following phases:
 
 #. ``configure`` - configure the project
 #. ``build`` - build the project