zhangyiss/spack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix various documentation bugs (#1678)

Browse Source 
* 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 2016-10-06 04:49:44 -05:00 committed by Todd Gamblin
parent 7dc11472bf
commit 83a074eea6
8 changed files with 97 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
lib/spack/docs/basic_usage.rst
View File

@ -1,7 +1,7 @@
.. _basic-usage: .. _basic-usage:
=========== ===========
Basic usage Basic Usage
=========== ===========
The ``spack`` command has many *subcommands*. You'll only need a 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 $ 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 .. 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 available. You can see a list of available package names at the
:ref:`package-list` webpage, or using the ``spack list`` command. :ref:`package-list` webpage, or using the ``spack list`` command.
.. _spack-list: .. _cmd-spack-list:
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
``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: 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: 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`` ``spack info``
@ -82,7 +82,7 @@ viruses.
:ref:`Dependencies <sec-specs>` and :ref:`virtual dependencies :ref:`Dependencies <sec-specs>` and :ref:`virtual dependencies
<sec-virtual-dependencies>` are described in more detail later. <sec-virtual-dependencies>` are described in more detail later.
.. _spack-versions: .. _cmd-spack-versions:
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
``spack versions`` ``spack versions``
@ -107,7 +107,7 @@ able to find remote versions.
Installing and uninstalling Installing and uninstalling
--------------------------- ---------------------------
.. _spack-install: .. _cmd-spack-install:
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
``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 ``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`. you can use them to customize an installation in :ref:`sec-specs`.
.. _spack-uninstall: .. _cmd-spack-uninstall:
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
``spack uninstall`` ``spack uninstall``
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
To uninstall a package, type ``spack uninstall <package>``. This will ask 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. in which the package was installed.
.. code-block:: console .. code-block:: console
@ -285,7 +285,7 @@ Seeing installed packages
We know that ``spack list`` shows you the names of available packages, We know that ``spack list`` shows you the names of available packages,
but how do you figure out which are already installed? but how do you figure out which are already installed?
.. _spack-find: .. _cmd-spack-find:
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
``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 Note that this will not work to reinstall a depencency uninstalled by
``spack uninstall --force``. ``spack uninstall --force``.
.. _spack-providers: .. _cmd-spack-providers:
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
``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 -------------------------------- -- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
python@2.7.8 python@2.7.8
.. _spack-extensions: .. _cmd-spack-extensions:
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
``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 environment modules, you can *activate* the package within the Python
installation: installation:
.. _spack-activate: .. _cmd-spack-activate:
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
``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 can still get it by using environment modules, but they will have to
explicitly load their preferred version. explicitly load their preferred version.
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
``spack activate -f`` ``spack activate --force``
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
If, for some reason, you want to activate a package *without* its 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 .. 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. ==> 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`` ``spack deactivate``
@ -1622,7 +1622,7 @@ A nicer error message is TBD in future versions of Spack.
Getting Help Getting Help
------------ ------------
.. _spack-help: .. _cmd-spack-help:
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
``spack help`` ``spack help``

2
lib/spack/docs/conf.py
View File

@ -79,7 +79,7 @@
for filename in glob('*rst'): for filename in glob('*rst'):
with open(filename) as f: with open(filename) as f:
for line in f: for line in f:
match = re.match(r'.. _(spack-[^:]*)', line) match = re.match('.. _(cmd-spack-.*):', line)
if match: if match:
command_names.append(match.group(1).strip()) command_names.append(match.group(1).strip())

2
lib/spack/docs/developer_guide.rst
View File

@ -331,7 +331,7 @@ Profiling
Spack has some limited built-in support for profiling, and can report Spack has some limited built-in support for profiling, and can report
statistics using standard Python timing tools. To use this feature, 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: .. _spack-p:

2
lib/spack/docs/features.rst
View File

@ -1,5 +1,5 @@
================ ================
Feature overview Feature Overview
================ ================
This is a high-level overview of features that make Spack different This is a high-level overview of features that make Spack different

13
lib/spack/docs/getting_started.rst
View File

@ -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 automatically the first time it is run. It does this by inspecting
your ``PATH``. your ``PATH``.
.. _spack-compilers: .. _cmd-spack-compilers:
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
``spack compilers`` ``spack compilers``
@ -559,7 +559,7 @@ flags to the ``icc`` command:
.. code-block:: console .. 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... /home2/rpfische/spack2/opt/spack/linux-centos7-x86_64/gcc-4.9.3-iy4rw...
#. Set up ``compilers.yaml``, for example: #. 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``. #. 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 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 .. code-block:: console
$ spack -k install
$ spack --insecure 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. from websites and from git.
.. warning:: .. warning::
@ -810,7 +809,7 @@ or if environment modules don't work:
.. code-block:: console .. 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, External commands are used by Spack in two places: within core Spack,
@ -899,7 +898,7 @@ with Spack:
TMP=`tempfile` TMP=`tempfile`
echo >$TMP 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_VERSION=`ls -1 $MODULE_HOME/Modules | head -1`
${MODULE_HOME}/Modules/${MODULE_VERSION}/bin/add.modules <$TMP ${MODULE_HOME}/Modules/${MODULE_VERSION}/bin/add.modules <$TMP
cp .bashrc $TMP cp .bashrc $TMP

6
lib/spack/docs/mirrors.rst
View File

@ -52,7 +52,7 @@ contains tarballs for each package, named after each package.
not standardize on a particular compression algorithm, because this not standardize on a particular compression algorithm, because this
would potentially require expanding and re-compressing each archive. would potentially require expanding and re-compressing each archive.
.. _spack-mirror: .. _cmd-spack-mirror:
---------------- ----------------
``spack mirror`` ``spack mirror``
@ -148,7 +148,7 @@ can supply a file with specs in it, one per line:
boost@1.44: boost@1.44:
boost@1.39.0 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 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 like other mirrors). The mirror is maintained locally (within the Spack
installation directory) at :file:`var/spack/cache/`. It is always enabled (and installation directory) at :file:`var/spack/cache/`. It is always enabled (and
is always searched first when attempting to retrieve files for an installation) 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. be deleted manually without issue.
Caching includes retrieved tarball archives and source control repositories, but Caching includes retrieved tarball archives and source control repositories, but

62
lib/spack/docs/packaging_guide.rst
View File

@ -33,7 +33,7 @@ easy.
Creating & editing packages Creating & editing packages
--------------------------- ---------------------------
.. _spack-create: .. _cmd-spack-create:
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
``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 You do not *have* to download all of the versions up front. You can
always choose to download just one tarball initially, and run 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:: .. 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 $ 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 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``. ``package.py`` file for the package in ``var/spack/repos/builtin/packages``.
.. note:: .. note::
Spack can fetch packages from source code repositories, but, Spack can fetch packages from source code repositories, but,
``spack create`` will *not* currently create a boilerplate package ``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 and manually edit the ``version()`` directives to fetch from a
repo. See :ref:`vcs-fetch` for details. 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. Before going into details, we'll cover a few more basics.
.. _spack-edit: .. _cmd-spack-edit:
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
``spack edit`` ``spack edit``
@ -238,7 +238,7 @@ package:
.. code-block:: console .. code-block:: console
$ spack edit -f foo $ spack edit --force foo
Unlike ``spack create``, which infers names and versions, and which Unlike ``spack create``, which infers names and versions, and which
actually downloads the tarball and checksums it for you, ``spack edit 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 This section describes how packages need to be named, and where they
live in Spack's directory structure. In general, :ref:`spack-create` and live in Spack's directory structure. In general, :ref:`cmd-spack-create` and
:ref:`spack-edit` handle creating package files for you, so you can skip :ref:`cmd-spack-edit` handle creating package files for you, so you can skip
most of the details here. most of the details here.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -371,7 +371,7 @@ some examples:
================= ================= ================= =================
In general, you won't have to remember this naming convention because 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 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 released, is tedious. See ``spack checksum`` below for an automated
version of this process. version of this process.
.. _spack-checksum: .. _cmd-spack-checksum:
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
``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 ``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 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 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 Handling RPATHs
@ -1134,7 +1134,7 @@ dynamic loader where to find its dependencies at runtime. You may be
familiar with `LD_LIBRARY_PATH familiar with `LD_LIBRARY_PATH
<http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html>`_ <http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html>`_
on Linux or `DYLD_LIBRARY_PATH 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 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 loader where to find libraries. Unlike them, it is embedded in
the binary and not set in each user's environment. 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. source code.
Spack uses the tarball URL to extrapolate where to find other tarballs 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 this does not always work. This section covers ways you can tell
Spack to find tarballs elsewhere. 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 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 of the tarball in the ``url`` attribute. For example, for libelf, the
url is: 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 :ref:`configuration`. Sites using Spack can customize them to match
the preferences of their own users. the preferences of their own users.
.. _spack-spec: .. _cmd-spack-spec:
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
``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 see the environment that a package will build with, or
if you want to run commands in that environment to test them out, you 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. below.
.. _compiler-wrappers: .. _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 Below are some commands that will allow you some finer-grained
control over the install process. control over the install process.
.. _spack-fetch: .. _cmd-spack-fetch:
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
``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 When run after the archive has already been downloaded, ``spack
fetch`` is idempotent and will not download the archive again. fetch`` is idempotent and will not download the archive again.
.. _spack-stage: .. _cmd-spack-stage:
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
``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 built by ``spack install``. Similar to ``fetch``, if the archive has
already been expanded, ``stage`` is idempotent. already been expanded, ``stage`` is idempotent.
.. _spack-patch: .. _cmd-spack-patch:
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
``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 apply cleanly on some previous run, then it will restage the entire
package before patching. package before patching.
.. _spack-restage: .. _cmd-spack-restage:
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
``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 #. If the source was checked out from a repository, this deletes the
build directory and checks it out again. build directory and checks it out again.
.. _spack-clean: .. _cmd-spack-clean:
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
``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 ``fetch``, ``stage``, or ``install`` are run again after this, Spack's
build process will start from scratch. build process will start from scratch.
.. _spack-purge: .. _cmd-spack-purge:
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
``spack purge`` ``spack purge``
@ -2996,7 +2996,7 @@ to get rid of the install prefix before you build again:
Graphing dependencies Graphing dependencies
--------------------- ---------------------
.. _spack-graph: .. _cmd-spack-graph:
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
``spack graph`` ``spack graph``
@ -3056,7 +3056,7 @@ For ``csh`` and ``tcsh`` run:
``spack cd`` will then be available. ``spack cd`` will then be available.
.. _spack-cd: .. _cmd-spack-cd:
^^^^^^^^^^^^ ^^^^^^^^^^^^
``spack cd`` ``spack cd``
@ -3081,14 +3081,14 @@ build it:
directory containing the expanded ``libelf`` source code. There are a directory containing the expanded ``libelf`` source code. There are a
number of other places you can cd to in the spack directory hierarchy: 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 Some of these change directory into package-specific locations (stage
directory, install directory, package directory) and others change to 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. the main python source directory of your spack install.
.. _spack-env: .. _cmd-spack-env:
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
``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 This will cd to the build directory and then run ``configure`` in the
package's build environment. package's build environment.
.. _spack-location: .. _cmd-spack-location:
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
``spack location`` ``spack location``
@ -3129,13 +3129,13 @@ cd'ing to it. In bash, this:
.. code-block:: console .. code-block:: console
$ cd $(spack location -b <spec>) $ cd $(spack location --build-dir <spec>)
is the same as: is the same as:
.. code-block:: console .. code-block:: console
$ spack cd -b <spec> $ spack cd --build-dir <spec>
``spack location`` is intended for use in scripts or makefiles that ``spack location`` is intended for use in scripts or makefiles that
need to know where packages are installed. e.g., in a makefile you need to know where packages are installed. e.g., in a makefile you
@ -3143,7 +3143,7 @@ might write:
.. code-block:: makefile .. code-block:: makefile
DWARF_PREFIX = $(spack location -i libdwarf) DWARF_PREFIX = $(spack location --install-dir libdwarf)
CXXFLAGS += -I$DWARF_PREFIX/include CXXFLAGS += -I$DWARF_PREFIX/include
CXXFLAGS += -L$DWARF_PREFIX/lib CXXFLAGS += -L$DWARF_PREFIX/lib

68
lib/spack/docs/workflows.rst
View File

@ -183,7 +183,6 @@ of usage:
.. code-block:: sh .. code-block:: sh
#!/bin/sh #!/bin/sh
#
compilers=( compilers=(
%gcc %gcc
@ -218,10 +217,6 @@ of usage:
done done
done done
------------------------------ ------------------------------
Running Binaries from Packages 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! 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 In many cases, nothing more is needed because Spack builds binaries
with RPATHs. Spack installation directories may be found with ``spack with RPATHs. Spack installation directories may be found with ``spack
location -i`` commands. For example: location --install-dir`` commands. For example:
.. code-block:: console .. 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 /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 This gives the root of the Spack package; relevant binaries may be
@ -249,7 +244,7 @@ found within it. For example:
.. code-block:: console .. 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: Standard UNIX tools can find binaries as well. For example:
@ -650,9 +645,9 @@ environments:
Administrators might find things easier to maintain without the Administrators might find things easier to maintain without the
added "heavyweight" state of a view. added "heavyweight" state of a view.
============================== ------------------------------
Developing Software with Spack Developing Software with Spack
============================== ------------------------------
For any project, one needs to assemble an For any project, one needs to assemble an
environment of that application's dependencies. You might consider 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 how this process works by example, assuming the software you are
creating is called ``mylib``. creating is called ``mylib``.
^^^^^^^^^^^^^^^^^^^^^
---------------------
Write the CMake Build Write the CMake Build
--------------------- ^^^^^^^^^^^^^^^^^^^^^
For now, the techniques in this section only work for CMake-based For now, the techniques in this section only work for CMake-based
projects, although they could be easily extended to other build projects, although they could be easily extended to other build
@ -770,9 +764,9 @@ The ``CMakeLists.txt`` file should be written as normal. A few caveats:
.. _write-the-spack-package: .. _write-the-spack-package:
----------------------- ^^^^^^^^^^^^^^^^^^^^^^^
Write the Spack Package Write the Spack Package
----------------------- ^^^^^^^^^^^^^^^^^^^^^^^
The Spack package also needs to be written, in tandem with setting up 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 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 not used in development. Don't worry if you don't have any, or if
they are behind a firewall. they are behind a firewall.
---------------- ^^^^^^^^^^^^^^^^
Build with Spack Build with Spack
---------------- ^^^^^^^^^^^^^^^^
Now that you have a Spack package, you can use Spack to find its Now that you have a Spack package, you can use Spack to find its
dependencies automatically. For example: dependencies automatically. For example:
@ -894,11 +888,9 @@ into Git or downloading tarballs.
problems in our experience, as long as your project sets problems in our experience, as long as your project sets
RPATHs as shown above. You DO use RPATHs, right? RPATHs as shown above. You DO use RPATHs, right?
^^^^^^^^^^^^^^^^^^^^
--------------------
Build Other Software Build Other Software
-------------------- ^^^^^^^^^^^^^^^^^^^^
Now that you've built ``mylib`` with Spack, you might want to build Now that you've built ``mylib`` with Spack, you might want to build
another package that depends on it --- for example, ``myapp``. This another package that depends on it --- for example, ``myapp``. This
@ -924,9 +916,9 @@ for example:
.. _release-your-software: .. _release-your-software:
--------------------- ^^^^^^^^^^^^^^^^^^^^^
Release Your Software Release Your Software
--------------------- ^^^^^^^^^^^^^^^^^^^^^
You are now ready to release your software as a tarball with a 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 numbered version, and a Spack package that can build it. If you're
@ -969,11 +961,9 @@ hosted on GitHub, this process will be a bit easier.
Spack concretization will always prefer numbered version to Spack concretization will always prefer numbered version to
non-numeric versions. Users will only get it if they ask for it. non-numeric versions. Users will only get it if they ask for it.
^^^^^^^^^^^^^^^^^^^^^^^^
------------------------
Distribute Your Software Distribute Your Software
------------------------ ^^^^^^^^^^^^^^^^^^^^^^^^
Once you've released your software, other people will want to build 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 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 systems. The :ref:`getting_started` section should cover this, but
there could always be issues. there could always be issues.
------------------- ^^^^^^^^^^^^^^^^^^^
Other Build Systems Other Build Systems
------------------- ^^^^^^^^^^^^^^^^^^^
``spack setup`` currently only supports CMake-based builds, in ``spack setup`` currently only supports CMake-based builds, in
packages that subclass ``CMakePackage``. The intent is that this 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 directly in the user's ``PYTHONPATH``. Then, edits in source files
are immediately available to run without any install process at all! are immediately available to run without any install process at all!
---------- ^^^^^^^^^^
Conclusion Conclusion
---------- ^^^^^^^^^^
The ``spack setup`` development workflow provides better automation, The ``spack setup`` development workflow provides better automation,
flexibility and safety than workflows relying on environment modules 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 integrate Spack explicitly in their workflow. Not all users are
willing to do this. willing to do this.
================== ------------------
Upstream Bug Fixes Upstream Bug Fixes
================== ------------------
It is not uncommon to discover a bug in an upstream project while 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 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 procedure to work around and ultimately resolve these bugs, while not
delaying the Spack user's main goal. delaying the Spack user's main goal.
----------------- ^^^^^^^^^^^^^^^^^
Buggy New Version Buggy New Version
----------------- ^^^^^^^^^^^^^^^^^
Sometimes, the old version of a package works fine, but a 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 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@:1.9', when='@:1.10.0')
depends_on('hdf5', when='@1.10.1:') depends_on('hdf5', when='@1.10.1:')
---------------- ^^^^^^^^^^^^^^^^
No Version Works No Version Works
---------------- ^^^^^^^^^^^^^^^^
Sometimes, *no* existing versions of a dependency work for a build. Sometimes, *no* existing versions of a dependency work for a build.
This typically happens when developing a new project: only then does 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 bugfix, then the unofficial ``version()`` line should be removed
from the Spack package. from the Spack package.
------- ^^^^^^^
Patches Patches
------- ^^^^^^^
Spack's source patching mechanism provides another way to fix bugs in Spack's source patching mechanism provides another way to fix bugs in
upstream projects. This has advantages and disadvantages compared to the procedures above. upstream projects. This has advantages and disadvantages compared to the procedures above.