summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthew LeGendre <legendre1@llnl.gov>2016-11-12 07:45:50 -0800
committerTodd Gamblin <tgamblin@llnl.gov>2016-11-12 07:45:50 -0800
commit216d269f1d85b9e3aba43009ceda11035ee57430 (patch)
tree18e18e0dca81782f36377384f92234bdc4e03859
parent09470ec672a27a87a75c127d0c13a9945861da4a (diff)
downloadspack-216d269f1d85b9e3aba43009ceda11035ee57430.tar.gz
spack-216d269f1d85b9e3aba43009ceda11035ee57430.tar.bz2
spack-216d269f1d85b9e3aba43009ceda11035ee57430.tar.xz
spack-216d269f1d85b9e3aba43009ceda11035ee57430.zip
Add packaging tutorial to docs (#2315)
* Add packaging tutorial to docs * packaging tutorial: formatting
-rw-r--r--lib/spack/docs/index.rst10
-rw-r--r--lib/spack/docs/module_file_tutorial.rst6
-rw-r--r--lib/spack/docs/package_tutorial.rst463
-rw-r--r--lib/spack/docs/packaging_tutorial/0.package.py64
-rw-r--r--lib/spack/docs/packaging_tutorial/1.package.py49
-rw-r--r--lib/spack/docs/packaging_tutorial/2.package.py21
-rw-r--r--lib/spack/docs/packaging_tutorial/3.package.py17
-rw-r--r--lib/spack/docs/packaging_tutorial/4.package.py26
8 files changed, 651 insertions, 5 deletions
diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst
index daaeef1af6..dfce28c185 100644
--- a/lib/spack/docs/index.rst
+++ b/lib/spack/docs/index.rst
@@ -40,13 +40,12 @@ or refer to the full manual below.
.. toctree::
:maxdepth: 2
- :caption: Tutorials
+ :caption: Basics
features
getting_started
basic_usage
workflows
- module_file_tutorial
.. toctree::
:maxdepth: 2
@@ -62,6 +61,13 @@ or refer to the full manual below.
.. toctree::
:maxdepth: 2
+ :caption: Step-by-step
+
+ module_file_tutorial
+ package_tutorial
+
+.. toctree::
+ :maxdepth: 2
:caption: Contributing to Spack
contribution_guide
diff --git a/lib/spack/docs/module_file_tutorial.rst b/lib/spack/docs/module_file_tutorial.rst
index 3ffca487a0..83df756566 100644
--- a/lib/spack/docs/module_file_tutorial.rst
+++ b/lib/spack/docs/module_file_tutorial.rst
@@ -1,8 +1,8 @@
.. _module_tutorial:
-=======
-Modules
-=======
+=============================
+Module Configuration Tutorial
+=============================
This tutorial will guide you through the customization of both
content and naming of module files generated by Spack.
diff --git a/lib/spack/docs/package_tutorial.rst b/lib/spack/docs/package_tutorial.rst
new file mode 100644
index 0000000000..e955780345
--- /dev/null
+++ b/lib/spack/docs/package_tutorial.rst
@@ -0,0 +1,463 @@
+.. _package_tutorial:
+
+=========================
+Package Creation Tutorial
+=========================
+
+This tutorial will walk you through the steps behind building a simple
+package installation script. We'll focus building an mpileaks package,
+which is a MPI debugging tool. By creating a package file we're
+essentially giving Spack a recipe for how to build a particular piece of
+software. We're describing some of the software's dependencies, where to
+find the package, what commands and options are used to build the package
+from source, and more. Once we've specified a package's recipe, we can
+ask Spack to build that package in many different ways.
+
+This tutorial assumes you have a basic familiarity with some of the Spack
+commands, and that you have a working version of Spack installed. If
+not, we suggest looking at Spack's *Getting Started* guide. This
+tutorial also assumes you have at least a beginner's-level familiarity
+with Python.
+
+Also note that this document is a tutorial. It can help you get started
+with packaging, but is not intended to be complete. See Spack's
+:ref:`packaging-guide` for more complete documentation on this topic.
+
+---------------
+Getting Started
+---------------
+
+A few things before we get started:
+
+- We'll refer to the Spack installation location via the environment
+ variable ``SPACK_ROOT``. You should point ``SPACK_ROOT`` at wherever
+ you have Spack installed.
+- Add ``$SPACK_ROOT/bin`` to your ``PATH`` before you start.
+- Make sure your ``EDITOR`` environment variable is set to some text
+ editor you like.
+- We'll be writting Python code as part of this tutorial. You can find
+ successive versions of the Python code in
+ ``$SPACK_ROOT/lib/spack/docs/packaging_tutorial``.
+
+-------------------------
+Creating the Package File
+-------------------------
+
+Spack comes with a handy command to create a new package: ``spack create``
+
+This command is given the location of a package's source code, downloads
+the code, and sets up some basic packaging infrastructure for you. The
+mpileaks source code can be found on github, and here's what happens when
+we run ``spack create`` on it:
+
+.. code-block:: console
+
+ % spack create -f https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz
+ ==> This looks like a URL for mpileaks version 1.0
+ ==> Creating template for package mpileaks
+ ==> Downloading...
+ ==> Fetching https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz
+ ###################################################################################### 100.0%
+
+And Spack should spawn a text editor with this file:
+
+.. literalinclude:: packaging_tutorial/0.package.py
+ :start-after: # flake8: noqa
+ :language: python
+
+Spack has created this file in
+``$SPACK_ROOT/var/spack/repos/builtin/packages/mpileaks/package.py``. Take a
+moment to look over the file. There's a few placeholders that Spack has
+created, which we'll fill in as part of this tutorial:
+
+- We'll document some information about this package in the comments.
+- We'll fill in the dependency list for this package.
+- We'll fill in some of the configuration arguments needed to build this
+ package.
+
+For the moment, exit your editor and let's see what happens when we try
+to build this package:
+
+.. code-block:: console
+
+ % spack install mpileaks
+ ==> Installing mpileaks
+ ==> Using cached archive: /usr/workspace/wsa/legendre/spack/var/spack/cache/mpileaks/mpileaks-1.0.tar.gz
+ ==> Staging archive: /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-hufwhwpq5benv3sslie6ryflk5s6nm35/mpileaks-1.0.tar.gz
+ ==> Created stage in /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-hufwhwpq5benv3sslie6ryflk5s6nm35
+ ==> Ran patch() for mpileaks
+ ==> Building mpileaks [AutotoolsPackage]
+ ==> Executing phase : 'autoreconf'
+ ==> Executing phase : 'configure'
+ ==> Error: ProcessError: Command exited with status 1:
+ './configure' '--prefix=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/mpileaks-1.0-hufwhwpq5benv3sslie6ryflk5s6nm35'
+ /usr/workspace/wsa/legendre/spack/lib/spack/spack/build_systems/autotools.py:150, in configure:
+ 145 def configure(self, spec, prefix):
+ 146 """Runs configure with the arguments specified in `configure_args`
+ 147 and an appropriately set prefix
+ 148 """
+ 149 options = ['--prefix={0}'.format(prefix)] + self.configure_args()
+ >> 150 inspect.getmodule(self).configure(*options)
+
+ See build log for details:
+ /tmp/legendre/spack-stage/spack-stage-8HVzqu/mpileaks-1.0/spack-build.out
+
+This obviously didn't work; we need to fill in the package-specific
+information. Specifically, Spack didn't try to build any of mpileaks'
+dependencies, nor did it use the proper configure arguments. Let's start
+fixing things
+
+---------------------
+Package Documentation
+---------------------
+
+We can bring the ``package.py`` file back into our ``EDITOR`` with the
+``spack edit`` command:
+
+.. code-block:: console
+
+ % spack edit mpileaks
+
+Let's remove some of the ``TODO`` comments, and add links to the mpileaks
+homepage and document what mpileaks does. I'm also going to cut out the
+Copyright clause at this point to keep this tutorial document shorter,
+but you shouldn't do that normally. The results of these changes can be
+found in ``$SPACK_ROOT/lib/spack/docs/packaging_tutorial/1.package.py``
+and are below. Make these changes to your ``package.py``:
+
+.. literalinclude:: packaging_tutorial/1.package.py
+ :start-after: # flake8: noqa
+ :language: python
+
+We've filled in the comment that describes what this package does and
+added a link to the web site. That won't help us build yet, but it will
+allow Spack to provide some documentation on this package to other users:
+
+.. code-block:: console
+
+ % spack info mpileaks
+ AutotoolsPackage: mpileaks
+ Homepage: https://github.com/hpc/mpileaks
+
+ Safe versions:
+ 1.0 https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz
+
+ Variants:
+ None
+
+ Installation Phases:
+ autoreconf configure build install
+
+ Build Dependencies:
+ None
+
+ Link Dependencies:
+ None
+
+ Run Dependencies:
+ None
+
+ Virtual Packages:
+ None
+
+ Description:
+ Tool to detect and report MPI objects like MPI_Requests and
+ MPI_Datatypes
+
+As we fill in more information about this package the spack info command
+will become more informative. Now let's start making this package build.
+
+------------
+Dependencies
+------------
+
+The mpileaks packages depends on three other package: ``MPI``,
+``adept-utils``, and ``callpath``. Let's add those via the
+``depends_on`` command in our ``package.py`` (this version is in
+``$SPACK_ROOT/lib/spack/docs/packaging_tutorial/2.package.py``):
+
+.. literalinclude:: packaging_tutorial/2.package.py
+ :start-after: # flake8: noqa
+ :language: python
+
+Now when we go to build mpileaks, Spack will fetch and build these
+dependencies before building mpileaks. Note that the mpi dependency is a
+different kind of beast than the adept-utils and callpath dependencies;
+there is no mpi package available in Spack. Instead mpi is a virtual
+dependency. Spack may satisfy that dependency by installing packages
+such as ``openmpi`` or ``mvapich``. See the :ref:`packaging-guide` for more
+information on virtual dependencies.
+
+Now when we try to install this package a lot more happens:
+
+.. code-block:: console
+
+ % spack install mpileaks
+ ==> Installing mpileaks
+ ==> openmpi is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz
+ ==> callpath is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/callpath-1.0.2-zm4pf3gasgxeibyu2y262suktvaazube
+ ==> adept-utils is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/adept-utils-1.0.1-7p7ezxwtajdglj6cmojy2vybjct4j4jz
+ ==> Using cached archive: /usr/workspace/wsa/legendre/spack/var/spack/cache/mpileaks/mpileaks-1.0.tar.gz
+ ==> Already staged mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk in /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk
+ ==> Already patched mpileaks
+ ==> Building mpileaks [AutotoolsPackage]
+ ==> Executing phase : 'autoreconf'
+ ==> Executing phase : 'configure'
+ ==> Error: ProcessError: Command exited with status 1:
+ './configure' '--prefix=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk'
+ /usr/workspace/wsa/legendre/spack/lib/spack/spack/build_systems/autotools.py:150, in configure:
+ 145 def configure(self, spec, prefix):
+ 146 """Runs configure with the arguments specified in `configure_args`
+ 147 and an appropriately set prefix
+ 148 """
+ 149 options = ['--prefix={0}'.format(prefix)] + self.configure_args()
+ >> 150 inspect.getmodule(self).configure(*options)
+
+ See build log for details:
+ /tmp/legendre/spack-stage/spack-stage-7V5yyk/mpileaks-1.0/spack-build.out
+
+Note that this command may take a while to run and produce more output if
+you don't have an MPI already installed or configured in Spack.
+
+Now Spack has identified and made sure all of our dependencies have been
+built. It found the ``openmpi`` package that will satisfy our ``mpi``
+dependency, and the callpath and ``adept-utils`` package to satisfy our
+concrete dependencies.
+
+------------------------
+Debugging Package Builds
+------------------------
+
+Our ``mpileaks`` package is still not building. It may be obvious to
+many of you that we're still missing the configure options. But let's
+pretend we're not all intelligent developers and use this opportunity
+spend some time debugging. We a few options that can tell us about
+what's going wrong:
+
+As per the error message, Spack has given us a ``spack-build.out`` debug log:
+
+.. code-block:: console
+
+ ==> './configure' '--prefix=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk'
+ checking metadata... no
+ checking installation directory variables... yes
+ checking for a BSD-compatible install... /usr/bin/install -c
+ checking whether build environment is sane... yes
+ checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
+ checking for gawk... gawk
+ checking whether make sets $(MAKE)... yes
+ checking for gcc... /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc
+ checking for C compiler default output file name... a.out
+ checking whether the C compiler works... yes
+ checking whether we are cross compiling... no
+ checking for suffix of executables...
+ checking for suffix of object files... o
+ checking whether we are using the GNU C compiler... yes
+ checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc accepts -g... yes
+ checking for /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc option to accept ISO C89... none needed
+ checking for style of include used by make... GNU
+ checking dependency style of /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc... gcc3
+ checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc and cc understand -c and -o together... yes
+ checking whether we are using the GNU C++ compiler... yes
+ checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/g++ accepts -g... yes
+ checking dependency style of /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/g++... gcc3
+ checking for /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc... /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc
+ Checking whether /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc responds to '-showme:compile'... yes
+ configure: error: unable to locate ``adept-utils`` installation
+
+This gives us the output from the build, and it's fairly obvious that
+mpileaks isn't finding it's ``adept-utils`` package. Spack has
+automatically added the include and library directories of
+``adept-utils`` to the compiler's search path, but some packages like
+mpileaks can sometimes be picky and still want things spelled out on
+their command line. But let's continue to pretend we're not brilliant
+developers, and explore some other debugging paths:
+
+We can also enter the build area and try to manually run the build:
+
+.. code-block:: console
+
+ % spack env mpileaks tcsh
+ % spack cd mpileaks
+
+The ``spack env`` command spawned a new shell that contains the same
+environment that Spack used to build the mpileaks package (you can
+substitute tcsh for your favorite shell). The ``spack cd`` command
+changed our working dirctory to the last attempted build for mpileaks.
+From here we can manually re-run the build:
+
+.. code-block:: console
+
+ % ./configure
+ checking metadata... no
+ checking installation directory variables... yes
+ checking for a BSD-compatible install... /usr/bin/install -c
+ checking whether build environment is sane... yes
+ checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
+ checking for gawk... gawk
+ checking whether make sets $(MAKE)... yes
+ checking for gcc... /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc
+ checking for C compiler default output file name... a.out
+ checking whether the C compiler works... yes
+ checking whether we are cross compiling... no
+ checking for suffix of executables...
+ checking for suffix of object files... o
+ checking whether we are using the GNU C compiler... yes
+ checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc accepts -g... yes
+ checking for /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc option to accept ISO C89... none needed
+ checking for style of include used by make... GNU
+ checking dependency style of /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc... gcc3
+ checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc and cc understand -c and -o together... yes
+ checking whether we are using the GNU C++ compiler... yes
+ checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/g++ accepts -g... yes
+ checking dependency style of /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/g++... gcc3
+ checking for /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc... /usr/workspace/wsa /legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc
+ Checking whether /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc responds to '-showme:compile'... yes
+ configure: error: unable to locate adept-utils installation
+
+We're seeing the same error, but now we're in a shell where we can run
+the command ourselves and debug as needed. We could, for example, run
+``./configure --help`` to see what options we can use to specify
+dependencies.
+
+We can use the ``exit`` command to leave the shell spawned by ``spack
+env``.
+
+------------------------------
+Specifying Configure Arguments
+------------------------------
+
+Let's add the configure arguments to the mpileaks' ``package.py``. This
+version can be found in
+``$SPACK_ROOT/lib/spack/docs/packaging_tutorial/3.package.py``:
+
+.. literalinclude:: packaging_tutorial/3.package.py
+ :start-after: # flake8: noqa
+ :language: python
+
+This is all we need for working mpileaks! If we install now we'll see:
+
+.. code-block:: console
+
+ % spack install mpileaks
+ spack install mpileaks
+ ==> Installing mpileaks
+ ==> openmpi is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz
+ ==> callpath is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/callpath-1.0.2-zm4pf3gasgxeibyu2y262suktvaazube
+ ==> adept-utils is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/adept-utils-1.0.1-7p7ezxwtajdglj6cmojy2vybjct4j4jz
+ ==> Using cached archive: /usr/workspace/wsa/legendre/spack/var/spack/cache/mpileaks/mpileaks-1.0.tar.gz
+ ==> Already staged mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk in /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk
+ ==> Already patched mpileaks
+ ==> Building mpileaks [AutotoolsPackage]
+ ==> Executing phase : 'autoreconf'
+ ==> Executing phase : 'configure'
+ ==> Executing phase : 'build'
+ ==> Executing phase : 'install'
+ ==> Successfully installed mpileaks
+ Fetch: 0.00s. Build: 14.08s. Total: 14.08s.
+ [+] /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk
+
+We took a few shortcuts for this package that are worth highlighting.
+Spack automatically detected that mpileaks was an autotools-based package
+when we ran spack create. If this had been a CMake-based package we
+would have been filling in a ``cmake_args`` function instead of
+``configure_args``. If spack hadn't been able to detect the build
+system, we'd be filling in a generic install method that would manually
+be calling build commands, such as is found in the ``zlib`` package:
+
+.. code-block:: python
+
+ def install(self, spec, prefix):
+ configure('--prefix={0}'.format(prefix))
+ make()
+ make('install')
+
+--------
+Variants
+--------
+
+We have a successful mpileaks build, but let's take some time to improve
+it. ``mpileaks`` has a build-time option to truncate parts of the stack
+that it walks. Let's add a variant to allow users to set this when they
+build in Spack.
+
+To do this, we'll add a variant to our package, as per the following (see
+``$SPACK_ROOT/lib/spack/docs/packaging_tutorial/4.package.py``):
+
+.. literalinclude:: packaging_tutorial/4.package.py
+ :start-after: # flake8: noqa
+ :language: python
+
+We've added the variant ``stackstart``, and given it a default value of
+``0``. If we install now we can see the stackstart variant added to the
+configure line (output truncated for length):
+
+.. code-block:: console
+
+ % spack install --verbose mpileaks stackstart=4
+ ==> Installing mpileaks
+ ==> openmpi is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz
+ ==> callpath is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/callpath-1.0.2-zm4pf3gasgxeibyu2y262suktvaazube
+ ==> adept-utils is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/adept-utils-1.0.1-7p7ezxwtajdglj6cmojy2vybjct4j4jz
+ ==> Using cached archive: /usr/workspace/wsa/legendre/spack/var/spack/cache/mpileaks/mpileaks-1.0.tar.gz
+ ==> Staging archive: /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-otqo2opkhan5ksujt6tpmdftydrieig7/mpileaks-1.0.tar.gz
+ ==> Created stage in /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-otqo2opkhan5ksujt6tpmdftydrieig7
+ ==> Ran patch() for mpileaks
+ ==> Building mpileaks [AutotoolsPackage]
+ ==> Executing phase : 'autoreconf'
+ ==> Executing phase : 'configure'
+ ==> './configure' '--prefix=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/mpileaks-1.0-otqo2opkhan5ksujt6tpmdftydrieig7' '--with-adept-utils=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/adept-utils-1.0.1-7p7ezxwtajdglj6cmojy2vybjct4j4jz' '--with-callpath=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/callpath-1.0.2-zm4pf3gasgxeibyu2y262suktvaazube' '--with-stack-start-c=4' '--with-stack-start-fortran=4'
+
+---------------
+The Spec Object
+---------------
+
+This tutorial has glossed over a few important features, which weren't
+too relevant for mpleaks but may be useful for other packages. There
+were several places we references the ``self.spec`` object. This is a
+powerful class for querying information about what we're building. For
+example, you could use the spec to query information about how a
+package's dependencies were built, or what compiler was being used, or
+what version of a package is being installed. Full documentation can be
+found in the :ref:`packaging-guide`, but here's some quick snippets with
+common queries:
+
+- Am I building ``mpileaks`` version ``1.1`` or greater?
+
+.. code-block:: python
+
+ if self.spec.satisfies('@1.1:'):
+ # Do things needed for 1.1+
+
+- Is ``openmpi`` the MPI I'm building with?
+
+.. code-block:: python
+
+ if self.spec['mpi'].name == 'openmpi':
+ # Do openmpi things
+
+- Am I building with ``gcc`` version less than ``5.0.0``:
+
+.. code-block:: python
+
+ if self.spec.satisfies('%gcc@:5.0.0'):
+ # Add arguments specific to gcc's earlier than 5.0.0
+
+- Am I built with the ``debug`` variant:
+
+.. code-block:: python
+
+ if self.spec.satisfies('+debug'):
+ # Add -g option to configure flags
+
+- Is my ``dyninst`` dependency greater than version ``8.0``?
+
+.. code-block:: python
+
+ if self.spec['dyninst'].satisfies('@8.0:'):
+ # Use newest dyninst options
+
+More examples can be found in the thousands of packages already added to
+Spack in ``$SPACK_ROOT/var/spack/repos/builtin/packages``.
+
+Good Luck!
diff --git a/lib/spack/docs/packaging_tutorial/0.package.py b/lib/spack/docs/packaging_tutorial/0.package.py
new file mode 100644
index 0000000000..ad6fd4d077
--- /dev/null
+++ b/lib/spack/docs/packaging_tutorial/0.package.py
@@ -0,0 +1,64 @@
+# flake8: noqa
+##############################################################################
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
+# Produced at the Lawrence Livermore National Laboratory.
+#
+# This file is part of Spack.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# LLNL-CODE-647188
+#
+# For details, see https://github.com/llnl/spack
+# Please also see the LICENSE file for our notice and the LGPL.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
+# conditions of the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+##############################################################################
+#
+# This is a template package file for Spack. We've put "FIXME"
+# next to all the things you'll want to change. Once you've handled
+# them, you can save this file and test your package like this:
+#
+# spack install mpileaks
+#
+# You can edit this file again by typing:
+#
+# spack edit mpileaks
+#
+# See the Spack documentation for more information on packaging.
+# If you submit this package back to Spack as a pull request,
+# please first remove this boilerplate and all FIXME comments.
+#
+from spack import *
+
+
+class Mpileaks(AutotoolsPackage):
+ """FIXME: Put a proper description of your package here."""
+
+ # FIXME: Add a proper url for your package's homepage here.
+ homepage = "http://www.example.com"
+ url = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
+
+ version('1.0', '8838c574b39202a57d7c2d68692718aa')
+
+ # FIXME: Add dependencies if required.
+ # depends_on('m4', type='build')
+ # depends_on('autoconf', type='build')
+ # depends_on('automake', type='build')
+ # depends_on('libtool', type='build')
+ # depends_on('foo')
+
+ def configure_args(self):
+ # FIXME: Add arguments other than --prefix
+ # FIXME: If not needed delete the function
+ args = []
+ return args
diff --git a/lib/spack/docs/packaging_tutorial/1.package.py b/lib/spack/docs/packaging_tutorial/1.package.py
new file mode 100644
index 0000000000..afacf3bbe8
--- /dev/null
+++ b/lib/spack/docs/packaging_tutorial/1.package.py
@@ -0,0 +1,49 @@
+##############################################################################
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
+# Produced at the Lawrence Livermore National Laboratory.
+#
+# This file is part of Spack.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# LLNL-CODE-647188
+#
+# For details, see https://github.com/llnl/spack
+# Please also see the LICENSE file for our notice and the LGPL.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
+# conditions of the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+##############################################################################
+# flake8: noqa
+
+from spack import *
+
+
+class Mpileaks(AutotoolsPackage):
+ """Tool to detect and report MPI objects like MPI_Requests and MPI_Datatypes"""
+
+ homepage = "https://github.com/hpc/mpileaks"
+ url = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
+
+ version('1.0', '8838c574b39202a57d7c2d68692718aa')
+
+ # FIXME: Add dependencies if required.
+ # depends_on('m4', type='build')
+ # depends_on('autoconf', type='build')
+ # depends_on('automake', type='build')
+ # depends_on('libtool', type='build')
+ # depends_on('foo')
+
+ def configure_args(self):
+ # FIXME: Add arguments other than --prefix
+ # FIXME: If not needed delete the function
+ args = []
+ return args
diff --git a/lib/spack/docs/packaging_tutorial/2.package.py b/lib/spack/docs/packaging_tutorial/2.package.py
new file mode 100644
index 0000000000..f7000cd1b6
--- /dev/null
+++ b/lib/spack/docs/packaging_tutorial/2.package.py
@@ -0,0 +1,21 @@
+# flake8: noqa
+
+from spack import *
+
+class Mpileaks(AutotoolsPackage):
+ """Tool to detect and report MPI objects like MPI_Requests and MPI_Datatypes"""
+
+ homepage = "https://github.com/hpc/mpileaks"
+ url = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
+
+ version('1.0', '8838c574b39202a57d7c2d68692718aa')
+
+ depends_on('mpi')
+ depends_on('adept-utils')
+ depends_on('callpath')
+
+ def configure_args(self):
+ # FIXME: Add arguments other than --prefix
+ # FIXME: If not needed delete the function
+ args = []
+ return args
diff --git a/lib/spack/docs/packaging_tutorial/3.package.py b/lib/spack/docs/packaging_tutorial/3.package.py
new file mode 100644
index 0000000000..6e7e5e2f3c
--- /dev/null
+++ b/lib/spack/docs/packaging_tutorial/3.package.py
@@ -0,0 +1,17 @@
+# flake8: noqa
+
+class Mpileaks(AutotoolsPackage):
+ """Tool to detect and report MPI objects like MPI_Requests and MPI_Datatypes"""
+ homepage = "https://github.com/hpc/mpileaks"
+ url = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
+
+ version('1.0', '8838c574b39202a57d7c2d68692718aa')
+
+ depends_on('mpi')
+ depends_on('adept-utils')
+ depends_on('callpath')
+
+ def configure_args(self):
+ args = ['--with-adept-utils=%s' % self.spec['adept-utils'].prefix,
+ '--with-callpath=%s' % self.spec['callpath'].prefix]
+ return args
diff --git a/lib/spack/docs/packaging_tutorial/4.package.py b/lib/spack/docs/packaging_tutorial/4.package.py
new file mode 100644
index 0000000000..3294b86e25
--- /dev/null
+++ b/lib/spack/docs/packaging_tutorial/4.package.py
@@ -0,0 +1,26 @@
+# flake8: noqa
+
+from spack import *
+
+class Mpileaks(AutotoolsPackage):
+ """Tool to detect and report MPI objects like MPI_Requests and MPI_Datatypes"""
+
+ homepage = "https://github.com/hpc/mpileaks"
+ url = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
+
+ version('1.0', '8838c574b39202a57d7c2d68692718aa')
+
+ variant('stackstart', default=0, description='Specify the number of stack frames to truncate.')
+
+ depends_on('mpi')
+ depends_on('adept-utils')
+ depends_on('callpath')
+
+ def configure_args(self):
+ args = ['--with-adept-utils=%s' % self.spec['adept-utils'].prefix,
+ '--with-callpath=%s' % self.spec['callpath'].prefix]
+ stackstart = int(self.spec.variants['stackstart'].value)
+ if stackstart:
+ args.extend(['--with-stack-start-c=%s' % stackstart,
+ '--with-stack-start-fortran=%s' % stackstart])
+ return args