diff options
| -rw-r--r-- | lib/spack/docs/basic_usage.rst | 75 | ||||
| -rw-r--r-- | lib/spack/docs/conf.py | 3 | ||||
| -rw-r--r-- | 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 @@ import sys, os 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 ------------------------- |