From 4ff8766a2210736adbf1cd8c709e4d75d0114fa1 Mon Sep 17 00:00:00 2001
From: Todd Gamblin <tgamblin@llnl.gov>
Date: Wed, 25 Dec 2013 15:30:42 -0800
Subject: [PATCH] Starting on packaging docs.
---
lib/spack/docs/basic_usage.rst | 75 +----------------------
lib/spack/docs/conf.py | 3 +-
lib/spack/docs/packaging_guide.rst | 97 +++++++++++++++++++++++++++++-
3 files changed, 98 insertions(+), 77 deletions(-)
diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index 080a48cc76..fc2312134e 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -1,3 +1,5 @@
+.. _basic_usage:
+
Basic usage
=====================
@@ -564,76 +566,3 @@ add a version specifier to the spec:
Notice that the package versions that provide insufficient MPI
versions are now filtered out.
-
-
-Package lifecycle
-------------------------------
-
-``spack install`` command performs a number of tasks before it finally
-installs each package. It downloads an archive, expands it in a
-temporary directory, and then performs the installation. Spack has
-several commands that allow finer-grained control over each stage of
-the build process.
-
-
-``spack fetch``
-~~~~~~~~~~~~~~~~~
-
-The first step of ``spack install``. Takes a spec and determines the
-correct download URL to use for the requested package version, then
-downloads the archive, checks it against an MD5 checksum, and stores
-it in a staging directory if the check was successful. The staging
-directory will be located under ``$SPACK_HOME/var/spack``.
-
-When run after the archive has already been downloaded, ``spack
-fetch`` is idempotent and will not download the archive again.
-
-``spack stage``
-~~~~~~~~~~~~~~~~~
-
-The second step in ``spack install`` after ``spack fetch``. Expands
-the downloaded archive in its temporary directory, where it will be
-built by ``spack install``. Similar to ``fetch``, if the archive has
-already been expanded, ``stage`` is idempotent.
-
-``spack clean``
-~~~~~~~~~~~~~~~~~
-
-There are several variations of ``spack clean``. With no arguments,
-``spack clean`` runs ``make clean`` in the expanded archive directory.
-This is useful if an attempted build failed, and something needs to be
-changed to get a package to build. If a particular package does not
-have a ``make clean`` target, this will do nothing.
-
-``spack clean -w / --work``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Deletes the entire build directory and re-expands it from the downloaded
-archive. This is useful if a package does not support a proper ``make clean``
-target.
-
-``spack clean -d / --dist``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Deletes the build directory *and* the downloaded archive. If
-``fetch``, ``stage``, or ``install`` are run again after this, the
-process will start from scratch, and the archive archive will be
-downloaded again. Useful if somehow a bad archive is downloaded
-accidentally and needs to be cleaned out of the staging area.
-
-``spack purge``
-~~~~~~~~~~~~~~~~~
-
-Cleans up *everything* in the build directory. You can use this to
-recover disk space if temporary files from interrupted or failed
-installs accumulate in the staging area.
-
-
-Dirty Installs
-~~~~~~~~~~~~~~~~~~~
-
-By default, ``spack install`` will delete the staging area once a
-pacakge has been successfully built and installed, *or* if an error
-occurs during the build. Use ``spack install --dirty`` or ``spack
-install -d`` to leave the build directory intact. This allows you to
-inspect the build directory and potentially fix the build. You can
-use ``purge`` or ``clean`` later to get rid of the unwanted temporary
-files.
diff --git a/lib/spack/docs/conf.py b/lib/spack/docs/conf.py
index 1303503bd6..c690e43086 100644
--- a/lib/spack/docs/conf.py
+++ b/lib/spack/docs/conf.py
@@ -19,7 +19,8 @@
sys.path.insert(0, os.path.abspath('exts'))
# Add the Spack bin directory to the path so that we can use its output in docs.
-os.environ['PATH'] += os.pathsep + '../../../bin'
+os.environ['SPACK_ROOT'] = '../../..'
+os.environ['PATH'] += os.pathsep + '$SPACK_ROOT/bin'
# Set an environment variable so that colify will print output like it would to
# a terminal.
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index 371c85df4c..1c67416c82 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -1,19 +1,110 @@
Packaging Guide
=====================
+This guide is intended for developers or administrators who want to
+*package* their software so that Spack can install it. We assume that
+you have at least some familiarty with Python, and that you've read
+the :ref:`guide for regular users <basic_usage>`, especially the part
+about *specs*.
+
Package files
-------------------------
+There are two parts of Spack, a language for describing builds of
+software (*specs*), and *packages*: Python modules thatactually build
+the software. A package essentially takes a spec and implements it
+for a particular piece of software. It allows a developer to
+encapsulate build logic for different versions, compilers, and
+platforms in one place, and it is designed to make things easy for
+you, the packager, as much as possible.
-Dependencies
--------------------------
+Packages in spack live in ``$prefix/lib/spack/spack/packages``:
+.. command-output:: cd $SPACK_ROOT/lib/spack/spack/packages; ls *.py
+ :shell:
+ :ellipsis: 5
-Virtual dependencies
+
+Package lifecycle
+------------------------------
+
+``spack install`` command performs a number of tasks before it finally
+installs each package. It downloads an archive, expands it in a
+temporary directory, and then performs the installation. Spack has
+several commands that allow finer-grained control over each stage of
+the build process.
+
+
+``spack fetch``
+~~~~~~~~~~~~~~~~~
+
+The first step of ``spack install``. Takes a spec and determines the
+correct download URL to use for the requested package version, then
+downloads the archive, checks it against an MD5 checksum, and stores
+it in a staging directory if the check was successful. The staging
+directory will be located under ``$SPACK_HOME/var/spack``.
+
+When run after the archive has already been downloaded, ``spack
+fetch`` is idempotent and will not download the archive again.
+
+``spack stage``
+~~~~~~~~~~~~~~~~~
+
+The second step in ``spack install`` after ``spack fetch``. Expands
+the downloaded archive in its temporary directory, where it will be
+built by ``spack install``. Similar to ``fetch``, if the archive has
+already been expanded, ``stage`` is idempotent.
+
+``spack clean``
+~~~~~~~~~~~~~~~~~
+
+There are several variations of ``spack clean``. With no arguments,
+``spack clean`` runs ``make clean`` in the expanded archive directory.
+This is useful if an attempted build failed, and something needs to be
+changed to get a package to build. If a particular package does not
+have a ``make clean`` target, this will do nothing.
+
+``spack clean -w / --work``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Deletes the entire build directory and re-expands it from the downloaded
+archive. This is useful if a package does not support a proper ``make clean``
+target.
+
+``spack clean -d / --dist``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Deletes the build directory *and* the downloaded archive. If
+``fetch``, ``stage``, or ``install`` are run again after this, the
+process will start from scratch, and the archive archive will be
+downloaded again. Useful if somehow a bad archive is downloaded
+accidentally and needs to be cleaned out of the staging area.
+
+``spack purge``
+~~~~~~~~~~~~~~~~~
+
+Cleans up *everything* in the build directory. You can use this to
+recover disk space if temporary files from interrupted or failed
+installs accumulate in the staging area.
+
+
+Dirty Installs
+~~~~~~~~~~~~~~~~~~~
+
+By default, ``spack install`` will delete the staging area once a
+pacakge has been successfully built and installed, *or* if an error
+occurs during the build. Use ``spack install --dirty`` or ``spack
+install -d`` to leave the build directory intact. This allows you to
+inspect the build directory and potentially fix the build. You can
+use ``purge`` or ``clean`` later to get rid of the unwanted temporary
+files.
+
+
+
+Dependencies
-------------------------
+
Virtual dependencies
-------------------------
--
GitLab