summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--lib/spack/docs/developer_guide.rst2
-rw-r--r--lib/spack/docs/packaging_guide.rst340
2 files changed, 172 insertions, 170 deletions
diff --git a/lib/spack/docs/developer_guide.rst b/lib/spack/docs/developer_guide.rst
index 1f0977b4de..969ed60b15 100644
--- a/lib/spack/docs/developer_guide.rst
+++ b/lib/spack/docs/developer_guide.rst
@@ -4,7 +4,7 @@ Developer Guide
=====================
This guide is intended for people who want to work on Spack itself.
-If you just want to develop pacakges, see the :ref:`packaging-guide`.
+If you just want to develop packages, see the :ref:`packaging-guide`.
It is assumed that you've read the :ref:`basic-usage` and
:ref:`packaging-guide` sections, and that you're familiar with the
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index 13785e25b7..439e9f8f63 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -27,178 +27,22 @@ be ubiquitous in the HPC community due to its use in numerical codes.
Second, it's a modern language and has many powerful features to help
make package writing easy.
-Finally, we've gone to great lengths to make it *easy* to create
-packages. The ``spack create`` command lets you generate a
-boilerplate package template from a tarball URL, and ideally you'll
-only need to run this once and slightly modify the boilerplate to get
-your package working.
-
-This section of the guide goes through the parts of a package, and
-then tells you how to make your own. If you're impatient, jump ahead
-to :ref:`spack-create`.
-
-Package Files
----------------------------
-
-It's probably easiest to learn about packages by looking at an
-example. Let's take a look at the ``libelf`` package:
-
-.. literalinclude:: ../../../var/spack/packages/libelf/package.py
- :lines: 25-
- :linenos:
-
-Directory Structure
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A Spack installation directory is structured like a standard UNIX
-install prefix (``bin``, ``lib``, ``include``, ``var``, ``opt``,
-etc.). Most of the code for Spack lives in ``$SPACK_ROOT/lib/spack``.
-Packages themselves live in ``$SPACK_ROOT/var/spack/packages``.
-
-If you ``cd`` to that directory, you will see directories for each
-package:
-
-.. command-output:: cd $SPACK_ROOT/var/spack/packages; ls
- :shell:
- :ellipsis: 10
-
-Each of these directories contains a file called ``package.py``. This
-file is where all the python code for a package goes. For example,
-the ``libelf`` package looks like this::
-
- $SPACK_ROOT/var/spack/packages/
- libelf/
- package.py
-
-Alongside the ``package.py`` file, a package may contain extra files (like
-patches) that it needs to build.
-
-
-Package Names
-~~~~~~~~~~~~~~~~~~
-
-Packages are named after the directory containing ``package.py``. So,
-``libelf``'s ``package.py`` lives in a directory called ``libelf``.
-The ``package.py`` file contains a class called ``Libelf``, which
-extends Spack's ``Package`` class. This is what makes it a Spack
-package. The **directory name** is what users need to provide on the
-command line. e.g., if you type any of these:
-
-.. code-block:: sh
-
- $ spack install libelf
- $ spack install libelf@0.8.13
-
-Spack sees the package name in the spec and looks for
-``libelf/package.py`` in ``var/spack/packages``. Likewise, if you say
-``spack install docbook-xml``, then Spack looks for
-``docbook-xml/package.py``.
-
-We use the directory name to packagers more freedom when naming their
-packages. Package names can contain letters, numbers, dashes, and
-underscores. You can name a package ``3proxy`` or ``_foo`` and Spack
-won't care -- it just needs to see that name in the package spec.
-These aren't valid Python module names, but we allow them in Spack and
-import ``package.py`` file dynamically.
-
-Package class names
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The **class name** (``Libelf`` in our example) is formed by converting
-words separated by `-` or ``_`` in the file name to camel case. If
-the name starts with a number, we prefix the class name with
-``_``. Here are some examples:
-
-================= =================
- Module Name Class Name
-================= =================
- ``foo_bar`` ``FooBar``
- ``docbook-xml`` ``DocbookXml``
- ``FooBar`` ``Foobar``
- ``3proxy`` ``_3proxy``
-================= =================
-
-The class name is needed by Spack to properly import a package, but
-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
-~~~~~~~~~~~~~~~~~~~~
-
-Just under the class name is a description of the ``libelf`` package.
-In Python, this is called a *docstring*: a multi-line, triple-quoted
-(``"""``) string that comes just after the definition of a class.
-Spack uses the docstring to generate the description of the package
-that is shown when you run ``spack info``. If you don't provide a
-description, Spack will just print "None" for the description.
-
-In addition to the package description, there are a few fields you'll
-need to fill out. They are as follows:
-
-``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`` (required)
- This is the URL where you can download a distribution tarball of
- the pacakge's source code.
-
-``versions`` (optional)
- This is a `dictionary
- <http://docs.python.org/2/tutorial/datastructures.html#dictionaries>`_
- mapping versions to MD5 hashes. Spack uses the hashes to checksum
- archives when it downloads a particular version.
-
-``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
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The last element of the ``libelf`` package is its ``install()``
-method. This is where the real work of installation happens, and
-it's the main part of the package you'll need to customize for each
-piece of software.
-
-.. literalinclude:: ../../../var/spack/packages/libelf/package.py
- :start-after: 0.8.12
- :linenos:
+Creating Packages
+----------------------------------
-``install`` takes a ``spec``: a description of how the package should
-be built, and a ``prefix``: the path to the directory where the
-software should be installed.
+Spack tries to make it *very* easy to create packages. The ``spack
+create`` command lets you generate a boilerplate package template from
+a tarball URL. In most cases, you'll only need to run this once, then
+slightly modify the boilerplate to get your package working.
-:ref:`Writing the install method <install-method>` is documented in
-detail later, but in general, the ``install()`` method should look
-familiar. ``libelf`` uses autotools, so the package first calls
-``configure``, passing the prefix and some other package-specific
-arguments. It then calls ``make`` and ``make install``.
+If ``spack create`` does not work for you, you can always use ``spack
+edit``. This section of the guide goes through the parts of a package,
+and then tells you how to make your own. If you're impatient, jump
+ahead to :ref:`spack-create`.
-Spack provides wrapper functions for ``configure`` and ``make`` so
-that you can call them in a similar way to how you'd call a shell
-comamnd. In reality, these are Python functions. Spack provides
-these functions to make writing packages more natural. See the section
-on :ref:`shell wrappers <shell-wrappers>`.
.. _spack-create:
-Creating Packages
-----------------------------------
-
``spack create``
~~~~~~~~~~~~~~~~~~~~~
@@ -212,9 +56,9 @@ All you need is the URL to a tarball you want to package:
$ spack create http://www.cmake.org/files/v2.8/cmake-2.8.12.1.tar.gz
-When you run this, Spack will look at the tarball URL, and it will try
-to figure out the name of the package to be created. It will also try
-to figure out what version strings for that package look like. Once
+When you run this, Spack looks at the tarball URL and tries to figure
+out the name of the package to be created. It will also try to
+determine out what version strings look like for this package. Once
that is done, it tries to find *additional* versions by spidering the
package's webpage. Spack then prompts you to tell it how many
versions you want to download and checksum.
@@ -411,6 +255,164 @@ syntax errors, or the ``import`` will fail. Use this once you've got
your package in working order.
+
+Package Files
+---------------------------
+
+It's probably easiest to learn about packages by looking at an
+example. Let's take a look at the ``libelf`` package:
+
+.. literalinclude:: ../../../var/spack/packages/libelf/package.py
+ :lines: 25-
+ :linenos:
+
+Directory Structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A Spack installation directory is structured like a standard UNIX
+install prefix (``bin``, ``lib``, ``include``, ``var``, ``opt``,
+etc.). Most of the code for Spack lives in ``$SPACK_ROOT/lib/spack``.
+Packages themselves live in ``$SPACK_ROOT/var/spack/packages``.
+
+If you ``cd`` to that directory, you will see directories for each
+package:
+
+.. command-output:: cd $SPACK_ROOT/var/spack/packages; ls
+ :shell:
+ :ellipsis: 10
+
+Each of these directories contains a file called ``package.py``. This
+file is where all the python code for a package goes. For example,
+the ``libelf`` package looks like this::
+
+ $SPACK_ROOT/var/spack/packages/
+ libelf/
+ package.py
+
+Alongside the ``package.py`` file, a package may contain extra files (like
+patches) that it needs to build.
+
+
+Package Names
+~~~~~~~~~~~~~~~~~~
+
+Packages are named after the directory containing ``package.py``. So,
+``libelf``'s ``package.py`` lives in a directory called ``libelf``.
+The ``package.py`` file contains a class called ``Libelf``, which
+extends Spack's ``Package`` class. This is what makes it a Spack
+package. The **directory name** is what users need to provide on the
+command line. e.g., if you type any of these:
+
+.. code-block:: sh
+
+ $ spack install libelf
+ $ spack install libelf@0.8.13
+
+Spack sees the package name in the spec and looks for
+``libelf/package.py`` in ``var/spack/packages``. Likewise, if you say
+``spack install docbook-xml``, then Spack looks for
+``docbook-xml/package.py``.
+
+We use the directory name to packagers more freedom when naming their
+packages. Package names can contain letters, numbers, dashes, and
+underscores. You can name a package ``3proxy`` or ``_foo`` and Spack
+lwon't care -- it just needs to see that name in the package spec.
+These aren't valid Python module names, but we allow them in Spack and
+import ``package.py`` file dynamically.
+
+Package class names
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The **class name** (``Libelf`` in our example) is formed by converting
+words separated by `-` or ``_`` in the file name to camel case. If
+the name starts with a number, we prefix the class name with
+``_``. Here are some examples:
+
+================= =================
+ Module Name Class Name
+================= =================
+ ``foo_bar`` ``FooBar``
+ ``docbook-xml`` ``DocbookXml``
+ ``FooBar`` ``Foobar``
+ ``3proxy`` ``_3proxy``
+================= =================
+
+The class name is needed by Spack to properly import a package, but
+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:
+
+Package metadata
+--------------------
+
+Under the class declaration is a *docstring* (as Python calls it)
+enclosed in triple-quotes (``"""``). Spack uses the docstring to
+generate the description of the package that is shown when you run
+``spack info``. If you don't provide a description, Spack will just
+print "None" for the description.
+
+In addition to the package description, there are a few fields you'll
+need to fill out. They are as follows:
+
+``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`` (required)
+ This is the URL where you can download a distribution tarball of
+ the pacakge's source code.
+
+``versions`` (optional)
+ This is a `dictionary
+ <http://docs.python.org/2/tutorial/datastructures.html#dictionaries>`_
+ mapping versions to MD5 hashes. Spack uses the hashes to checksum
+ archives when it downloads a particular version.
+
+``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
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The last element of the ``libelf`` package is its ``install()``
+method. This is where the real work of installation happens, and
+it's the main part of the package you'll need to customize for each
+piece of software.
+
+.. literalinclude:: ../../../var/spack/packages/libelf/package.py
+ :start-after: 0.8.12
+ :linenos:
+
+``install`` takes a ``spec``: a description of how the package should
+be built, and a ``prefix``: the path to the directory where the
+software should be installed.
+
+:ref:`Writing the install method <install-method>` is documented in
+detail later, but in general, the ``install()`` method should look
+familiar. ``libelf`` uses autotools, so the package first calls
+``configure``, passing the prefix and some other package-specific
+arguments. It then calls ``make`` and ``make install``.
+
+Spack provides wrapper functions for ``configure`` and ``make`` so
+that you can call them in a similar way to how you'd call a shell
+comamnd. In reality, these are Python functions. Spack provides
+these functions to make writing packages more natural. See the section
+on :ref:`shell wrappers <shell-wrappers>`.
+
+
Optional Package Attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~