Add documentation on build systems (#5015)

Spack provides a number of classes based on commonly-used build systems
that users can extend when writing packages; the classes provide functionality
to perform the actions relevant to the build system (e.g. running "configure" for
an Autotools-based package). This adds documentation for classes supporting the
following build systems:

* Makefile
* Autotools
* CMake
* QMake
* SCons
* Waf

This includes build systems for managing extensions of the following packages:

* Perl
* Python
* R
* Octave

This also adds documentation on implementing packages that use a custom build
system (e.g. Perl/CMake).

Spack also provides extendable classes which aggregate functionality for related
sets of packages, e.g. those using CUDA. Documentation is added for
CudaPackage.

1 files changed, 83 insertions, 0 deletions

diff --git a/lib/spack/docs/build_systems.rst b/lib/spack/docs/build_systems.rst
new file mode 100644
index 0000000000..562e5c9fd0
--- /dev/null
+++ b/lib/spack/docs/build_systems.rst
@@ -0,0 +1,83 @@
+
+.. _build-systems:
+
+=============
+Build Systems
+=============
+
+Spack defines a number of classes which understand how to use common
+`build systems  <https://en.wikipedia.org/wiki/List_of_build_automation_software>`_
+(Makefiles, CMake, etc.). Spack package definitions can inherit these
+classes in order to streamline their builds.
+
+This guide provides information specific to each particular build system.
+It assumes that you've read the :ref:`packaging-guide` and expands
+on these ideas for each distinct build system that Spack supports:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Make-based
+
+   build_systems/makefilepackage
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Make-incompatible
+
+   build_systems/sconspackage
+   build_systems/wafpackage
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Build-script generation
+
+   build_systems/autotoolspackage
+   build_systems/cmakepackage
+   build_systems/qmakepackage
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Language-specific
+
+   build_systems/octavepackage
+   build_systems/perlpackage
+   build_systems/pythonpackage
+   build_systems/rpackage
+   build_systems/rubypackage
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Other
+
+   build_systems/cudapackage
+   build_systems/intelpackage
+   build_systems/custompackage
+
+For reference, the :py:mod:`Build System API docs <spack.build_systems>`
+provide a list of build systems and methods/attributes that can be
+overridden. If you are curious about the implementation of a particular
+build system, you can view the source code by running:
+
+.. code-block:: console
+
+   $ spack edit --build-system autotools
+
+
+This will open up the ``AutotoolsPackage`` definition in your favorite
+editor. In addition, if you are working with a less common build system
+like QMake, SCons, or Waf, it may be useful to see examples of other
+packages. You can quickly find examples by running:
+
+.. code-block:: console
+
+   $ cd var/spack/repos/builtin/packages
+   $ grep -l QMakePackage */package.py
+
+
+You can then view these packages with ``spack edit``.
+
+This guide is intended to supplement the
+:py:mod:`Build System API docs <spack.build_systems>` with examples of
+how to override commonly used methods. It also provides rules of thumb
+and suggestions for package developers who are unfamiliar with a
+particular build system.