Fix various documentation bugs (#1678)
* Fix various documentation bugs * Keep long option names, but don't include in Command Index * Use long option name * Explicitly designate sections to be listed in the Command Index * Consistent menu bar titles
This commit is contained in:
Adam J. Stewart
Todd Gamblin
parent
7dc11472bf
commit
83a074eea6
@ -1,7 +1,7 @@
|
||||
.. _basic-usage:
|
||||
|
||||
===========
|
||||
Basic usage
|
||||
Basic Usage
|
||||
===========
|
||||
|
||||
The ``spack`` command has many *subcommands*. You'll only need a
|
||||
@ -14,7 +14,7 @@ Spack to maintain this colorization. E.g.:
|
||||
|
||||
$ spack find | less -R
|
||||
|
||||
It is recommend that the following be put in your ``.bashrc`` file:
|
||||
It is recommended that the following be put in your ``.bashrc`` file:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
@ -28,7 +28,7 @@ To install software with Spack, you need to know what software is
|
||||
available. You can see a list of available package names at the
|
||||
:ref:`package-list` webpage, or using the ``spack list`` command.
|
||||
|
||||
.. _spack-list:
|
||||
.. _cmd-spack-list:
|
||||
|
||||
^^^^^^^^^^^^^^
|
||||
``spack list``
|
||||
@ -57,13 +57,13 @@ All packages whose names start with a capital M:
|
||||
|
||||
All packages whose names or descriptions contain Documentation:
|
||||
|
||||
.. command-output:: spack list -d Documentation
|
||||
.. command-output:: spack list --search-description Documentation
|
||||
|
||||
All packages whose names contain documentation case insensitive:
|
||||
|
||||
.. command-output:: spack list -d documentation
|
||||
.. command-output:: spack list --search-description documentation
|
||||
|
||||
.. _spack-info:
|
||||
.. _cmd-spack-info:
|
||||
|
||||
^^^^^^^^^^^^^^
|
||||
``spack info``
|
||||
@ -82,7 +82,7 @@ viruses.
|
||||
:ref:`Dependencies <sec-specs>` and :ref:`virtual dependencies
|
||||
<sec-virtual-dependencies>` are described in more detail later.
|
||||
|
||||
.. _spack-versions:
|
||||
.. _cmd-spack-versions:
|
||||
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
``spack versions``
|
||||
@ -107,7 +107,7 @@ able to find remote versions.
|
||||
Installing and uninstalling
|
||||
---------------------------
|
||||
|
||||
.. _spack-install:
|
||||
.. _cmd-spack-install:
|
||||
|
||||
^^^^^^^^^^^^^^^^^
|
||||
``spack install``
|
||||
@ -180,14 +180,14 @@ configuration a **spec**. In the commands above, ``mpileaks`` and
|
||||
``mpileaks@3.0.4`` are both valid *specs*. We'll talk more about how
|
||||
you can use them to customize an installation in :ref:`sec-specs`.
|
||||
|
||||
.. _spack-uninstall:
|
||||
.. _cmd-spack-uninstall:
|
||||
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
``spack uninstall``
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To uninstall a package, type ``spack uninstall <package>``. This will ask
|
||||
the user for confirmation, and in case will completely remove the directory
|
||||
the user for confirmation before completely removing the directory
|
||||
in which the package was installed.
|
||||
|
||||
.. code-block:: console
|
||||
@ -285,7 +285,7 @@ Seeing installed packages
|
||||
We know that ``spack list`` shows you the names of available packages,
|
||||
but how do you figure out which are already installed?
|
||||
|
||||
.. _spack-find:
|
||||
.. _cmd-spack-find:
|
||||
|
||||
^^^^^^^^^^^^^^
|
||||
``spack find``
|
||||
@ -798,7 +798,7 @@ it refers. Otherwise, it will prompt for a more qualified hash.
|
||||
Note that this will not work to reinstall a depencency uninstalled by
|
||||
``spack uninstall --force``.
|
||||
|
||||
.. _spack-providers:
|
||||
.. _cmd-spack-providers:
|
||||
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
``spack providers``
|
||||
@ -1373,7 +1373,7 @@ an *extension*. Suppose you have Python installed like so:
|
||||
-- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
|
||||
python@2.7.8
|
||||
|
||||
.. _spack-extensions:
|
||||
.. _cmd-spack-extensions:
|
||||
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
``spack extensions``
|
||||
@ -1467,7 +1467,7 @@ for this case. Instead of requiring users to load particular
|
||||
environment modules, you can *activate* the package within the Python
|
||||
installation:
|
||||
|
||||
.. _spack-activate:
|
||||
.. _cmd-spack-activate:
|
||||
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
``spack activate``
|
||||
@ -1532,19 +1532,19 @@ into the same prefix. Users who want a different version of a package
|
||||
can still get it by using environment modules, but they will have to
|
||||
explicitly load their preferred version.
|
||||
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
``spack activate -f``
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
``spack activate --force``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If, for some reason, you want to activate a package *without* its
|
||||
dependencies, you can use ``spack activate -f``:
|
||||
dependencies, you can use ``spack activate --force``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ spack activate -f py-numpy
|
||||
$ spack activate --force py-numpy
|
||||
==> Activated extension py-numpy@1.9.1%gcc@4.4.7 arch=linux-debian7-x86_64-66733244 for python@2.7.8%gcc@4.4.7.
|
||||
|
||||
.. _spack-deactivate:
|
||||
.. _cmd-spack-deactivate:
|
||||
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
``spack deactivate``
|
||||
@ -1622,7 +1622,7 @@ A nicer error message is TBD in future versions of Spack.
|
||||
Getting Help
|
||||
------------
|
||||
|
||||
.. _spack-help:
|
||||
.. _cmd-spack-help:
|
||||
|
||||
^^^^^^^^^^^^^^
|
||||
``spack help``
|
||||
|
||||
@ -79,7 +79,7 @@
|
||||
for filename in glob('*rst'):
|
||||
with open(filename) as f:
|
||||
for line in f:
|
||||
match = re.match(r'.. _(spack-[^:]*)', line)
|
||||
match = re.match('.. _(cmd-spack-.*):', line)
|
||||
if match:
|
||||
command_names.append(match.group(1).strip())
|
||||
|
||||
|
||||
@ -331,7 +331,7 @@ Profiling
|
||||
|
||||
Spack has some limited built-in support for profiling, and can report
|
||||
statistics using standard Python timing tools. To use this feature,
|
||||
supply ``-p`` to Spack on the command line, before any subcommands.
|
||||
supply ``--profile`` to Spack on the command line, before any subcommands.
|
||||
|
||||
.. _spack-p:
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
================
|
||||
Feature overview
|
||||
Feature Overview
|
||||
================
|
||||
|
||||
This is a high-level overview of features that make Spack different
|
||||
|
||||
@ -135,7 +135,7 @@ compiler versions. Spack searches for compilers on your machine
|
||||
automatically the first time it is run. It does this by inspecting
|
||||
your ``PATH``.
|
||||
|
||||
.. _spack-compilers:
|
||||
.. _cmd-spack-compilers:
|
||||
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
``spack compilers``
|
||||
@ -559,7 +559,7 @@ flags to the ``icc`` command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ spack location -i gcc
|
||||
$ spack location --install-dir gcc
|
||||
/home2/rpfische/spack2/opt/spack/linux-centos7-x86_64/gcc-4.9.3-iy4rw...
|
||||
|
||||
#. Set up ``compilers.yaml``, for example:
|
||||
@ -761,14 +761,13 @@ by installing a new version of ``git`` and ``openssl``:
|
||||
#. Add the output of ``spack module loads git`` to your ``.bahsrc``.
|
||||
|
||||
If this doesn't work, it is also possible to disable checking of SSL
|
||||
certificates by using either of:
|
||||
certificates by using:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ spack -k install
|
||||
$ spack --insecure install
|
||||
|
||||
Using ``-k/--insecure`` makes Spack disable SSL checking when fetching
|
||||
Using ``--insecure`` makes Spack disable SSL checking when fetching
|
||||
from websites and from git.
|
||||
|
||||
.. warning::
|
||||
@ -810,7 +809,7 @@ or if environment modules don't work:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ export PATH=`spack location -i curl`/bin:$PATH
|
||||
$ export PATH=`spack location --install-dir curl`/bin:$PATH
|
||||
|
||||
|
||||
External commands are used by Spack in two places: within core Spack,
|
||||
@ -899,7 +898,7 @@ with Spack:
|
||||
|
||||
TMP=`tempfile`
|
||||
echo >$TMP
|
||||
MODULE_HOME=`spack location -i environment-modules`
|
||||
MODULE_HOME=`spack location --install-dir environment-modules`
|
||||
MODULE_VERSION=`ls -1 $MODULE_HOME/Modules | head -1`
|
||||
${MODULE_HOME}/Modules/${MODULE_VERSION}/bin/add.modules <$TMP
|
||||
cp .bashrc $TMP
|
||||
|
||||
@ -52,7 +52,7 @@ contains tarballs for each package, named after each package.
|
||||
not standardize on a particular compression algorithm, because this
|
||||
would potentially require expanding and re-compressing each archive.
|
||||
|
||||
.. _spack-mirror:
|
||||
.. _cmd-spack-mirror:
|
||||
|
||||
----------------
|
||||
``spack mirror``
|
||||
@ -148,7 +148,7 @@ can supply a file with specs in it, one per line:
|
||||
boost@1.44:
|
||||
boost@1.39.0
|
||||
...
|
||||
$ spack mirror create -f specs.txt
|
||||
$ spack mirror create --file specs.txt
|
||||
...
|
||||
|
||||
This is useful if there is a specific suite of software managed by
|
||||
@ -237,7 +237,7 @@ as other Spack mirrors (so it can be copied anywhere and referenced with a URL
|
||||
like other mirrors). The mirror is maintained locally (within the Spack
|
||||
installation directory) at :file:`var/spack/cache/`. It is always enabled (and
|
||||
is always searched first when attempting to retrieve files for an installation)
|
||||
but can be cleared with :ref:`purge <spack-purge>`; the cache directory can also
|
||||
but can be cleared with :ref:`purge <cmd-spack-purge>`; the cache directory can also
|
||||
be deleted manually without issue.
|
||||
|
||||
Caching includes retrieved tarball archives and source control repositories, but
|
||||
|
||||
@ -33,7 +33,7 @@ easy.
|
||||
Creating & editing packages
|
||||
---------------------------
|
||||
|
||||
.. _spack-create:
|
||||
.. _cmd-spack-create:
|
||||
|
||||
^^^^^^^^^^^^^^^^
|
||||
``spack create``
|
||||
@ -81,7 +81,7 @@ Spack will automatically download the number of tarballs you specify
|
||||
|
||||
You do not *have* to download all of the versions up front. You can
|
||||
always choose to download just one tarball initially, and run
|
||||
:ref:`spack checksum <spack-checksum>` later if you need more.
|
||||
:ref:`cmd-spack-checksum` later if you need more.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -93,14 +93,14 @@ always choose to download just one tarball initially, and run
|
||||
$ spack create --name cmake http://www.cmake.org/files/v2.8/cmake-2.8.12.1.tar.gz
|
||||
|
||||
If it fails entirely, you can get minimal boilerplate by using
|
||||
:ref:`spack-edit-f`, or you can manually create a directory and
|
||||
:ref:`spack edit --force <spack-edit-f>`, or you can manually create a directory and
|
||||
``package.py`` file for the package in ``var/spack/repos/builtin/packages``.
|
||||
|
||||
.. note::
|
||||
|
||||
Spack can fetch packages from source code repositories, but,
|
||||
``spack create`` will *not* currently create a boilerplate package
|
||||
from a repository URL. You will need to use :ref:`spack-edit-f`
|
||||
from a repository URL. You will need to use :ref:`spack edit --force <spack-edit-f>`
|
||||
and manually edit the ``version()`` directives to fetch from a
|
||||
repo. See :ref:`vcs-fetch` for details.
|
||||
|
||||
@ -198,7 +198,7 @@ The rest of the tasks you need to do are as follows:
|
||||
|
||||
Before going into details, we'll cover a few more basics.
|
||||
|
||||
.. _spack-edit:
|
||||
.. _cmd-spack-edit:
|
||||
|
||||
^^^^^^^^^^^^^^
|
||||
``spack edit``
|
||||
@ -238,7 +238,7 @@ package:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ spack edit -f foo
|
||||
$ spack edit --force foo
|
||||
|
||||
Unlike ``spack create``, which infers names and versions, and which
|
||||
actually downloads the tarball and checksums it for you, ``spack edit
|
||||
@ -271,8 +271,8 @@ Naming & directory structure
|
||||
----------------------------
|
||||
|
||||
This section describes how packages need to be named, and where they
|
||||
live in Spack's directory structure. In general, :ref:`spack-create` and
|
||||
:ref:`spack-edit` handle creating package files for you, so you can skip
|
||||
live in Spack's directory structure. In general, :ref:`cmd-spack-create` and
|
||||
:ref:`cmd-spack-edit` handle creating package files for you, so you can skip
|
||||
most of the details here.
|
||||
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -371,7 +371,7 @@ some examples:
|
||||
================= =================
|
||||
|
||||
In general, you won't have to remember this naming convention because
|
||||
:ref:`spack-create` and :ref:`spack-edit` handle the details for you.
|
||||
:ref:`cmd-spack-create` and :ref:`cmd-spack-edit` handle the details for you.
|
||||
|
||||
-----------------
|
||||
Trusted Downloads
|
||||
@ -590,7 +590,7 @@ Doing this for lots of files, or whenever a new package version is
|
||||
released, is tedious. See ``spack checksum`` below for an automated
|
||||
version of this process.
|
||||
|
||||
.. _spack-checksum:
|
||||
.. _cmd-spack-checksum:
|
||||
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
``spack checksum``
|
||||
@ -1120,7 +1120,7 @@ function gives you some benefits. First, spack ensures that the
|
||||
``patch()`` function is run once per code checkout. That means that
|
||||
if you run install, hit ctrl-C, and run install again, the code in the
|
||||
patch function is only run once. Also, you can tell Spack to run only
|
||||
the patching part of the build using the :ref:`spack-patch` command.
|
||||
the patching part of the build using the :ref:`cmd-spack-patch` command.
|
||||
|
||||
---------------
|
||||
Handling RPATHs
|
||||
@ -1134,7 +1134,7 @@ dynamic loader where to find its dependencies at runtime. You may be
|
||||
familiar with `LD_LIBRARY_PATH
|
||||
<http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html>`_
|
||||
on Linux or `DYLD_LIBRARY_PATH
|
||||
<https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/dyld.1.html>`
|
||||
<https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/dyld.1.html>`_
|
||||
on Mac OS X. RPATH is similar to these paths, in that it tells
|
||||
the loader where to find libraries. Unlike them, it is embedded in
|
||||
the binary and not set in each user's environment.
|
||||
@ -1191,7 +1191,7 @@ information about the package, and to determine where to download its
|
||||
source code.
|
||||
|
||||
Spack uses the tarball URL to extrapolate where to find other tarballs
|
||||
of the same package (e.g. in `spack checksum <spack-checksum_>`_, but
|
||||
of the same package (e.g. in :ref:`cmd-spack-checksum`, but
|
||||
this does not always work. This section covers ways you can tell
|
||||
Spack to find tarballs elsewhere.
|
||||
|
||||
@ -1202,7 +1202,7 @@ Spack to find tarballs elsewhere.
|
||||
^^^^^^^^^^^^
|
||||
|
||||
When spack tries to find available versions of packages (e.g. with
|
||||
`spack checksum <spack-checksum_>`_), it spiders the parent directory
|
||||
:ref:`cmd-spack-checksum`), it spiders the parent directory
|
||||
of the tarball in the ``url`` attribute. For example, for libelf, the
|
||||
url is:
|
||||
|
||||
@ -1859,7 +1859,7 @@ explicitly. Concretization policies are discussed in more detail in
|
||||
:ref:`configuration`. Sites using Spack can customize them to match
|
||||
the preferences of their own users.
|
||||
|
||||
.. _spack-spec:
|
||||
.. _cmd-spack-spec:
|
||||
|
||||
^^^^^^^^^^^^^^
|
||||
``spack spec``
|
||||
@ -2092,7 +2092,7 @@ discover its dependencies.
|
||||
|
||||
If you want to see the environment that a package will build with, or
|
||||
if you want to run commands in that environment to test them out, you
|
||||
can use the :ref:`spack env <spack-env>` command, documented
|
||||
can use the :ref:`cmd-spack-env` command, documented
|
||||
below.
|
||||
|
||||
.. _compiler-wrappers:
|
||||
@ -2871,7 +2871,7 @@ A typical package workflow might look like this:
|
||||
Below are some commands that will allow you some finer-grained
|
||||
control over the install process.
|
||||
|
||||
.. _spack-fetch:
|
||||
.. _cmd-spack-fetch:
|
||||
|
||||
^^^^^^^^^^^^^^^
|
||||
``spack fetch``
|
||||
@ -2886,7 +2886,7 @@ 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:
|
||||
.. _cmd-spack-stage:
|
||||
|
||||
^^^^^^^^^^^^^^^
|
||||
``spack stage``
|
||||
@ -2897,7 +2897,7 @@ 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-patch:
|
||||
.. _cmd-spack-patch:
|
||||
|
||||
^^^^^^^^^^^^^^^
|
||||
``spack patch``
|
||||
@ -2911,7 +2911,7 @@ this step if they have been. If Spack discovers that patches didn't
|
||||
apply cleanly on some previous run, then it will restage the entire
|
||||
package before patching.
|
||||
|
||||
.. _spack-restage:
|
||||
.. _cmd-spack-restage:
|
||||
|
||||
^^^^^^^^^^^^^^^^^
|
||||
``spack restage``
|
||||
@ -2927,7 +2927,7 @@ Does this in one of two ways:
|
||||
#. If the source was checked out from a repository, this deletes the
|
||||
build directory and checks it out again.
|
||||
|
||||
.. _spack-clean:
|
||||
.. _cmd-spack-clean:
|
||||
|
||||
^^^^^^^^^^^^^^^
|
||||
``spack clean``
|
||||
@ -2938,7 +2938,7 @@ expanded/checked out source code *and* any downloaded archive. If
|
||||
``fetch``, ``stage``, or ``install`` are run again after this, Spack's
|
||||
build process will start from scratch.
|
||||
|
||||
.. _spack-purge:
|
||||
.. _cmd-spack-purge:
|
||||
|
||||
^^^^^^^^^^^^^^^
|
||||
``spack purge``
|
||||
@ -2996,7 +2996,7 @@ to get rid of the install prefix before you build again:
|
||||
Graphing dependencies
|
||||
---------------------
|
||||
|
||||
.. _spack-graph:
|
||||
.. _cmd-spack-graph:
|
||||
|
||||
^^^^^^^^^^^^^^^
|
||||
``spack graph``
|
||||
@ -3056,7 +3056,7 @@ For ``csh`` and ``tcsh`` run:
|
||||
|
||||
``spack cd`` will then be available.
|
||||
|
||||
.. _spack-cd:
|
||||
.. _cmd-spack-cd:
|
||||
|
||||
^^^^^^^^^^^^
|
||||
``spack cd``
|
||||
@ -3081,14 +3081,14 @@ build it:
|
||||
directory containing the expanded ``libelf`` source code. There are a
|
||||
number of other places you can cd to in the spack directory hierarchy:
|
||||
|
||||
.. command-output:: spack cd -h
|
||||
.. command-output:: spack cd --help
|
||||
|
||||
Some of these change directory into package-specific locations (stage
|
||||
directory, install directory, package directory) and others change to
|
||||
core spack locations. For example, ``spack cd -m`` will take you to
|
||||
core spack locations. For example, ``spack cd --module-dir`` will take you to
|
||||
the main python source directory of your spack install.
|
||||
|
||||
.. _spack-env:
|
||||
.. _cmd-spack-env:
|
||||
|
||||
^^^^^^^^^^^^^
|
||||
``spack env``
|
||||
@ -3117,7 +3117,7 @@ provide them after the spec argument to ``spack env``:
|
||||
This will cd to the build directory and then run ``configure`` in the
|
||||
package's build environment.
|
||||
|
||||
.. _spack-location:
|
||||
.. _cmd-spack-location:
|
||||
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
``spack location``
|
||||
@ -3129,13 +3129,13 @@ cd'ing to it. In bash, this:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd $(spack location -b <spec>)
|
||||
$ cd $(spack location --build-dir <spec>)
|
||||
|
||||
is the same as:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ spack cd -b <spec>
|
||||
$ spack cd --build-dir <spec>
|
||||
|
||||
``spack location`` is intended for use in scripts or makefiles that
|
||||
need to know where packages are installed. e.g., in a makefile you
|
||||
@ -3143,7 +3143,7 @@ might write:
|
||||
|
||||
.. code-block:: makefile
|
||||
|
||||
DWARF_PREFIX = $(spack location -i libdwarf)
|
||||
DWARF_PREFIX = $(spack location --install-dir libdwarf)
|
||||
CXXFLAGS += -I$DWARF_PREFIX/include
|
||||
CXXFLAGS += -L$DWARF_PREFIX/lib
|
||||
|
||||
|
||||
@ -79,7 +79,7 @@ The following set is not consistent:
|
||||
curl@7.50.1%gcc@5.3.0 arch=linux-SuSE11-x86_64
|
||||
^openssl@system%gcc@5.3.0 arch=linux-SuSE11-x86_64
|
||||
^zlib@1.2.8%gcc@5.3.0 arch=linux-SuSE11-x86_64
|
||||
zlib@1.2.7%gcc@5.3.0 arch=linux-SuSE11-x86_64
|
||||
zlib@1.2.7%gcc@5.3.0 arch=linux-SuSE11-x86_64
|
||||
|
||||
The compatibility of a set of installed packages determines what may
|
||||
be done with it. It is always possible to ``spack load`` any set of
|
||||
@ -153,7 +153,7 @@ preferred versions and variants to use for packages. For example:
|
||||
|
||||
|
||||
This approach will work as long as you are building packages for just
|
||||
one application.
|
||||
one application.
|
||||
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
Multiple Applications
|
||||
@ -183,7 +183,6 @@ of usage:
|
||||
.. code-block:: sh
|
||||
|
||||
#!/bin/sh
|
||||
#
|
||||
|
||||
compilers=(
|
||||
%gcc
|
||||
@ -218,10 +217,6 @@ of usage:
|
||||
done
|
||||
done
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
------------------------------
|
||||
Running Binaries from Packages
|
||||
------------------------------
|
||||
@ -237,11 +232,11 @@ Find and Run
|
||||
The simplest way to run a Spack binary is to find it and run it!
|
||||
In many cases, nothing more is needed because Spack builds binaries
|
||||
with RPATHs. Spack installation directories may be found with ``spack
|
||||
location -i`` commands. For example:
|
||||
location --install-dir`` commands. For example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ spack location -i cmake
|
||||
$ spack location --install-dir cmake
|
||||
/home/me/spack2/opt/spack/linux-SuSE11-x86_64/gcc-5.3.0/cmake-3.6.0-7cxrynb6esss6jognj23ak55fgxkwtx7
|
||||
|
||||
This gives the root of the Spack package; relevant binaries may be
|
||||
@ -249,7 +244,7 @@ found within it. For example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ CMAKE=`spack location -i cmake`/bin/cmake
|
||||
$ CMAKE=`spack location --install-dir cmake`/bin/cmake
|
||||
|
||||
|
||||
Standard UNIX tools can find binaries as well. For example:
|
||||
@ -650,9 +645,9 @@ environments:
|
||||
Administrators might find things easier to maintain without the
|
||||
added "heavyweight" state of a view.
|
||||
|
||||
==============================
|
||||
------------------------------
|
||||
Developing Software with Spack
|
||||
==============================
|
||||
------------------------------
|
||||
|
||||
For any project, one needs to assemble an
|
||||
environment of that application's dependencies. You might consider
|
||||
@ -700,10 +695,9 @@ can be seamlessly integrated into the Spack ecosystem. We will show
|
||||
how this process works by example, assuming the software you are
|
||||
creating is called ``mylib``.
|
||||
|
||||
|
||||
---------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
Write the CMake Build
|
||||
---------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
For now, the techniques in this section only work for CMake-based
|
||||
projects, although they could be easily extended to other build
|
||||
@ -731,7 +725,7 @@ The ``CMakeLists.txt`` file should be written as normal. A few caveats:
|
||||
|
||||
# when building, don't use the install RPATH already
|
||||
# (but later on when installing)
|
||||
SET(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE)
|
||||
SET(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE)
|
||||
|
||||
# add the automatically determined parts of the RPATH
|
||||
# which point to directories outside the build tree to the install RPATH
|
||||
@ -770,9 +764,9 @@ The ``CMakeLists.txt`` file should be written as normal. A few caveats:
|
||||
|
||||
.. _write-the-spack-package:
|
||||
|
||||
-----------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Write the Spack Package
|
||||
-----------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The Spack package also needs to be written, in tandem with setting up
|
||||
the build (for example, CMake). The most important part of this task
|
||||
@ -838,9 +832,9 @@ used for development:
|
||||
not used in development. Don't worry if you don't have any, or if
|
||||
they are behind a firewall.
|
||||
|
||||
----------------
|
||||
^^^^^^^^^^^^^^^^
|
||||
Build with Spack
|
||||
----------------
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Now that you have a Spack package, you can use Spack to find its
|
||||
dependencies automatically. For example:
|
||||
@ -894,11 +888,9 @@ into Git or downloading tarballs.
|
||||
problems in our experience, as long as your project sets
|
||||
RPATHs as shown above. You DO use RPATHs, right?
|
||||
|
||||
|
||||
|
||||
--------------------
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
Build Other Software
|
||||
--------------------
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Now that you've built ``mylib`` with Spack, you might want to build
|
||||
another package that depends on it --- for example, ``myapp``. This
|
||||
@ -924,9 +916,9 @@ for example:
|
||||
|
||||
.. _release-your-software:
|
||||
|
||||
---------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
Release Your Software
|
||||
---------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You are now ready to release your software as a tarball with a
|
||||
numbered version, and a Spack package that can build it. If you're
|
||||
@ -952,7 +944,7 @@ hosted on GitHub, this process will be a bit easier.
|
||||
==> Found 1 versions of mylib
|
||||
0.1.2 https://github.com/citibeth/mylib/tarball/v0.1.2
|
||||
|
||||
How many would you like to checksum? (default is 5, q to abort)
|
||||
How many would you like to checksum? (default is 5, q to abort)
|
||||
==> Downloading...
|
||||
==> Trying to fetch from https://github.com/citibeth/mylib/tarball/v0.1.2
|
||||
######################################################################## 100.0%
|
||||
@ -969,11 +961,9 @@ hosted on GitHub, this process will be a bit easier.
|
||||
Spack concretization will always prefer numbered version to
|
||||
non-numeric versions. Users will only get it if they ask for it.
|
||||
|
||||
|
||||
|
||||
------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Distribute Your Software
|
||||
------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Once you've released your software, other people will want to build
|
||||
it; and you will need to tell them how. In the past, that has meant a
|
||||
@ -1012,9 +1002,9 @@ Spack is the best way to install it:
|
||||
systems. The :ref:`getting_started` section should cover this, but
|
||||
there could always be issues.
|
||||
|
||||
-------------------
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
Other Build Systems
|
||||
-------------------
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``spack setup`` currently only supports CMake-based builds, in
|
||||
packages that subclass ``CMakePackage``. The intent is that this
|
||||
@ -1028,9 +1018,9 @@ Python Distutils is another popular build system that should get
|
||||
directly in the user's ``PYTHONPATH``. Then, edits in source files
|
||||
are immediately available to run without any install process at all!
|
||||
|
||||
----------
|
||||
^^^^^^^^^^
|
||||
Conclusion
|
||||
----------
|
||||
^^^^^^^^^^
|
||||
|
||||
The ``spack setup`` development workflow provides better automation,
|
||||
flexibility and safety than workflows relying on environment modules
|
||||
@ -1049,9 +1039,9 @@ or filesystem views. However, it has some drawbacks:
|
||||
integrate Spack explicitly in their workflow. Not all users are
|
||||
willing to do this.
|
||||
|
||||
==================
|
||||
------------------
|
||||
Upstream Bug Fixes
|
||||
==================
|
||||
------------------
|
||||
|
||||
It is not uncommon to discover a bug in an upstream project while
|
||||
trying to build with Spack. Typically, the bug is in a package that
|
||||
@ -1059,9 +1049,9 @@ serves a dependency to something else. This section describes
|
||||
procedure to work around and ultimately resolve these bugs, while not
|
||||
delaying the Spack user's main goal.
|
||||
|
||||
-----------------
|
||||
^^^^^^^^^^^^^^^^^
|
||||
Buggy New Version
|
||||
-----------------
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sometimes, the old version of a package works fine, but a new version
|
||||
is buggy. For example, it was once found that `Adios did not build
|
||||
@ -1092,9 +1082,9 @@ procedure is:
|
||||
depends_on('hdf5@:1.9', when='@:1.10.0')
|
||||
depends_on('hdf5', when='@1.10.1:')
|
||||
|
||||
----------------
|
||||
^^^^^^^^^^^^^^^^
|
||||
No Version Works
|
||||
----------------
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Sometimes, *no* existing versions of a dependency work for a build.
|
||||
This typically happens when developing a new project: only then does
|
||||
@ -1183,9 +1173,9 @@ of ``py-proj/package.py`` is instructive here:
|
||||
bugfix, then the unofficial ``version()`` line should be removed
|
||||
from the Spack package.
|
||||
|
||||
-------
|
||||
^^^^^^^
|
||||
Patches
|
||||
-------
|
||||
^^^^^^^
|
||||
|
||||
Spack's source patching mechanism provides another way to fix bugs in
|
||||
upstream projects. This has advantages and disadvantages compared to the procedures above.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user