From 36e6ef9fbd169ad05b09dab097025e33fa7c91ee Mon Sep 17 00:00:00 2001 From: Todd Gamblin Date: Mon, 6 Jan 2014 18:21:27 +0100 Subject: [PATCH] Packaging docs are mostly done. --- lib/spack/docs/packaging_guide.rst | 131 ++++++++++++++++++++--------- 1 file changed, 93 insertions(+), 38 deletions(-) diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst index 1e6b81e640..55f7391cd9 100644 --- a/lib/spack/docs/packaging_guide.rst +++ b/lib/spack/docs/packaging_guide.rst @@ -116,6 +116,7 @@ not for much else. In general, you won't have to remember this naming convention because ``spack create`` will generate a boilerplate class for you, and you can just fill in the blanks. +.. _metadata: Metadata ~~~~~~~~~~~~~~~~~~~~ @@ -130,26 +131,32 @@ a description, Spack will just print "None" for the description. In addition the package description, there are a few fields you'll need to fill out. They are as follows: -``homepage`` - This is the URL where you can learn about the package and get - information. It is displayed to users when they run ``spack info``. +``homepage`` (required) + This is the URL where you can learn about the package and get + information. It is displayed to users when they run ``spack info``. -``url`` - This is the URL where you can download a distribution tarball of - the pacakge's source code. +``url`` (required) + This is the URL where you can download a distribution tarball of + the pacakge's source code. -``versions`` - This is a `dictionary - `_ - mapping versions to MD5 hashes. Spack uses the hashes to checksum - archives when it downloads a particular version. +``versions`` (optional) + This is a `dictionary + `_ + mapping versions to MD5 hashes. Spack uses the hashes to checksum + archives when it downloads a particular version. -The homepage and URL are required fields, and ``versions`` is not -required but it's recommended. Spack will warn usrs if they try to -install a spec (e.g., ``libelf@0.8.10`` for which there is not a -checksum available. They can force it to download the new version and -install, but it's better to provide checksums so users don't have to -install from an unchecked archive. +``parallel`` (optional) + Whether make should be parallel by default. By default, this is + ``True``, and package authors need to call ``make(parallel=False)`` + to override. If you set this to ``False`` at the package level + then each call to ``make`` will be sequential by default, and users + will have to call ``make(parallel=True)`` to override it. + +``versions`` is optional but strongly recommended. Spack will warn +usrs if they try to install a version (e.g., ``libelf@0.8.10`` for +which there is not a checksum available. They can force it to +download the new version and install, but it's better to provide +checksums so users don't have to install from an unchecked archive. Install method @@ -1086,26 +1093,82 @@ method (the one without the ``@when`` decorator) will be called. Shell command wrappers ------------------------- -This allows spack to provide some special features, as well. For -example, in Spack, ``make`` is parallel by default. Spack figures out -the number of cores on your machine and passes and appropriate value -for ``-j`` to the ``make`` command. In a package file, you -can supply a keyword argument, ``parallel=False``, to disable parallel -make. We do it here to avoid some race conditions in ``libelf``\'s -``install`` target. The first call to ``make()``, which does not have -a keyword argument, will still build in parallel. +Recall the install method in ``libelf.py``: + +.. code-block:: python + + def install(self, spec, prefix): + configure("--prefix=" + prefix, + "--enable-shared", + "--disable-dependency-tracking", + "--disable-debug") + make() + + # The mkdir commands in libelf's install can fail in parallel + make("install", parallel=False) + +Normally in Python, you'd have to write something like this in order +to execute shell commands: + +.. code-block:: python + + import subprocess + subprocess.check_call('configure', '--prefix=' + prefix) + +We've tried to make this a bit easier by providing callable wrapper +objects for some shell commands. By default, ``configure``, +``cmake``, and ``make`` provided, so you can call them more naturally +in your package files. + +If you need other commands, you can use ``which`` to get them: + +.. code-block:: python + + sed = which('sed') + sed('s/foo/bar/', filename) + +The ``which`` function will search the ``PATH`` for the application. + +Callable wrappers also allow spack to provide some special features. +For example, in Spack, ``make`` is parallel by default, and Spack +figures out the number of cores on your machine and passes an +appropriate value for ``-j`` when it calls ``make`` (see the +``parallel`` package attribute under :ref:`metadata `). In +a package file, you can supply a keyword argument, ``parallel=False``, +to the ``make`` wrapper to disable parallel make. In the ``libelf`` +package, this allows us to avoid race conditions in the library's +build system. .. _pacakge-lifecycle: -Package lifecycle ------------------------------- +The package build process +--------------------------------- + +When you are building packages, you will likely not get things +completely right the first time. The ``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. +a temporary directory, and only then gives control to the package's +``install()`` method. If the build doesn't go as planned, you may +want to clean up the temporary directory, or if the package isn't +downloading properly, you might want to run *only* the ``fetch`` stage +of the build. +A typical package development cycle might look like this: + +.. code-block:: sh + + $ spack edit mypackage + $ spack install mypackage + ... build breaks! ... + $ spack clean mypackage + $ spack edit mypackage + $ spack install mypackage + ... repeat clean/install until install works ... + +Below are some commands that will allow you some finer-grained +controll over the install process. ``spack fetch`` ~~~~~~~~~~~~~~~~~ @@ -1168,11 +1231,3 @@ 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. - - - - - - -``spack graph`` -~~~~~~~~~~~~~~~~~~~~