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

Use console instead of shell syntax lexer, fixes #1634

Browse Source
This commit is contained in:
Adam J. Stewart 2016-08-26 16:41:00 -05:00
parent f856952728
commit 6795f4ca12
8 changed files with 949 additions and 981 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -8,15 +8,18 @@ The ``spack`` command has many *subcommands*. You'll only need a
small subset of them for typical usage. small subset of them for typical usage.
Note that Spack colorizes output. ``less -R`` should be used with Note that Spack colorizes output. ``less -R`` should be used with
Spack to maintain this colorization. E.g.:: Spack to maintain this colorization. E.g.:
spack find | less -R .. code-block:: console
It is recommend that the following be put in your ``.bashrc`` file:: $ spack find | less -R
It is recommend that the following be put in your ``.bashrc`` file:
.. code-block:: sh
alias less='less -R' alias less='less -R'
-------------------------- --------------------------
Listing available packages Listing available packages
-------------------------- --------------------------
@ -114,18 +117,18 @@ Installing and uninstalling
For example, To install the latest version of the ``mpileaks`` For example, To install the latest version of the ``mpileaks``
package, you might type this: package, you might type this:
.. code-block:: sh .. code-block:: console
$ spack install mpileaks $ spack install mpileaks
If `mpileaks` depends on other packages, Spack will install the If ``mpileaks`` depends on other packages, Spack will install the
dependencies first. It then fetches the ``mpileaks`` tarball, expands dependencies first. It then fetches the ``mpileaks`` tarball, expands
it, verifies that it was downloaded without errors, builds it, and it, verifies that it was downloaded without errors, builds it, and
installs it in its own directory under ``$SPACK_ROOT/opt``. You'll see installs it in its own directory under ``$SPACK_ROOT/opt``. You'll see
a number of messages from spack, a lot of build output, and a message a number of messages from spack, a lot of build output, and a message
that the packages is installed: that the packages is installed:
.. code-block:: sh .. code-block:: console
$ spack install mpileaks $ spack install mpileaks
==> Installing mpileaks ==> Installing mpileaks
@ -155,7 +158,7 @@ Building a specific version
Spack can also build *specific versions* of a package. To do this, Spack can also build *specific versions* of a package. To do this,
just add ``@`` after the package name, followed by a version: just add ``@`` after the package name, followed by a version:
.. code-block:: sh .. code-block:: console
$ spack install mpich@3.0.4 $ spack install mpich@3.0.4
@ -174,8 +177,8 @@ two configurations of the same version of a package, one built with boost
This can all be done on the command line using the *spec* syntax. This can all be done on the command line using the *spec* syntax.
Spack calls the descriptor used to refer to a particular package Spack calls the descriptor used to refer to a particular package
configuration a **spec**. In the commands above, ``mpileaks`` and configuration a **spec**. In the commands above, ``mpileaks`` and
``mpileaks@3.0.4``. We'll talk more about how you can use them to ``mpileaks@3.0.4`` are both valid *specs*. We'll talk more about how
customize an installation in :ref:`sec-specs`. you can use them to customize an installation in :ref:`sec-specs`.
.. _spack-uninstall: .. _spack-uninstall:
@ -183,53 +186,56 @@ customize an installation in :ref:`sec-specs`.
``spack uninstall`` ``spack uninstall``
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
To uninstall a package, type ``spack uninstall <package>``. This will ask the user for To uninstall a package, type ``spack uninstall <package>``. This will ask
confirmation, and in case will completely remove the directory in which the package was installed. the user for confirmation, and in case will completely remove the directory
in which the package was installed.
.. code-block:: sh .. code-block:: console
spack uninstall mpich $ spack uninstall mpich
If there are still installed packages that depend on the package to be If there are still installed packages that depend on the package to be
uninstalled, spack will refuse to uninstall it. uninstalled, spack will refuse to uninstall it.
To uninstall a package and every package that depends on it, you may give the To uninstall a package and every package that depends on it, you may give the
`--dependents` option. ``--dependents`` option.
.. code-block:: sh .. code-block:: console
spack uninstall --dependents mpich $ spack uninstall --dependents mpich
will display a list of all the packages that depend on `mpich` and, upon confirmation, will display a list of all the packages that depend on ``mpich`` and, upon
will uninstall them in the right order. confirmation, will uninstall them in the right order.
A line like A command like
.. code-block:: sh .. code-block:: console
spack uninstall mpich $ spack uninstall mpich
may be ambiguous, if multiple ``mpich`` configurations are installed. For example, if both may be ambiguous if multiple ``mpich`` configurations are installed.
``mpich@3.0.2`` and ``mpich@3.1`` are installed, ``mpich`` could refer For example, if both ``mpich@3.0.2`` and ``mpich@3.1`` are installed,
to either one. Because it cannot determine which one to uninstall, ``mpich`` could refer to either one. Because it cannot determine which
Spack will ask you either to provide a version number to remove the one to uninstall, Spack will ask you either to provide a version number
ambiguity or use the ``--all`` option to uninstall all of the matching packages. to remove the ambiguity or use the ``--all`` option to uninstall all of
the matching packages.
You may force uninstall a package with the `--force` option You may force uninstall a package with the ``--force`` option
.. code-block:: sh .. code-block:: console
spack uninstall --force mpich $ spack uninstall --force mpich
but you risk breaking other installed packages. In general, it is safer to remove dependent but you risk breaking other installed packages. In general, it is safer to
packages *before* removing their dependencies or use the `--dependents` option. remove dependent packages *before* removing their dependencies or use the
``--dependents`` option.
------------------------- -------------------------
Seeing installed packages 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 installed? but how do you figure out which are already installed?
.. _spack-find: .. _spack-find:
@ -244,7 +250,7 @@ of the same package with different specs.
Running ``spack find`` with no arguments lists installed packages: Running ``spack find`` with no arguments lists installed packages:
.. code-block:: sh .. code-block:: console
$ spack find $ spack find
==> 74 installed packages. ==> 74 installed packages.
@ -283,17 +289,18 @@ only shows the version of installed packages.
``spack find`` can filter the package list based on the package name, spec, or ``spack find`` can filter the package list based on the package name, spec, or
a number of properties of their installation status. For example, missing a number of properties of their installation status. For example, missing
dependencies of a spec can be shown with ``-m``, packages which were dependencies of a spec can be shown with ``--missing``, packages which were
explicitly installed with ``spack install <package>`` can be singled out with explicitly installed with ``spack install <package>`` can be singled out with
``-e`` and those which have been pulled in only as dependencies with ``-E``. ``--explicit`` and those which have been pulled in only as dependencies with
``--implicit``.
In some cases, there may be different configurations of the *same* In some cases, there may be different configurations of the *same*
version of a package installed. For example, there are two version of a package installed. For example, there are two
installations of of ``libdwarf@20130729`` above. We can look at them installations of ``libdwarf@20130729`` above. We can look at them
in more detail using ``spack find -d``, and by asking only to show in more detail using ``spack find --deps``, and by asking only to show
``libdwarf`` packages: ``libdwarf`` packages:
.. code-block:: sh .. code-block:: console
$ spack find --deps libdwarf $ spack find --deps libdwarf
==> 2 installed packages. ==> 2 installed packages.
@ -307,25 +314,25 @@ Now we see that the two instances of ``libdwarf`` depend on
*different* versions of ``libelf``: 0.8.12 and 0.8.13. This view can *different* versions of ``libelf``: 0.8.12 and 0.8.13. This view can
become complicated for packages with many dependencies. If you just become complicated for packages with many dependencies. If you just
want to know whether two packages' dependencies differ, you can use want to know whether two packages' dependencies differ, you can use
``spack find -l``: ``spack find --long``:
.. code-block:: sh .. code-block:: console
$ spack find -l libdwarf $ spack find --long libdwarf
==> 2 installed packages. ==> 2 installed packages.
-- linux-debian7-x86_64 / gcc@4.4.7 -------------------------------- -- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
libdwarf@20130729-d9b90962 libdwarf@20130729-b52fac98 libdwarf@20130729-d9b90962 libdwarf@20130729-b52fac98
Now the ``libwarf`` installs have hashes after their names. These are Now the ``libdwarf`` installs have hashes after their names. These are
hashes over all of the dependencies of each package. If the hashes hashes over all of the dependencies of each package. If the hashes
are the same, then the packages have the same dependency configuration. are the same, then the packages have the same dependency configuration.
If you want to know the path where each package is installed, you can If you want to know the path where each package is installed, you can
use ``spack find -p``: use ``spack find --paths``:
.. code-block:: sh .. code-block:: console
$ spack find -p $ spack find --paths
==> 74 installed packages. ==> 74 installed packages.
-- linux-debian7-x86_64 / gcc@4.4.7 -------------------------------- -- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
ImageMagick@6.8.9-10 /home/gamblin2/spack/opt/linux-debian7-x86_64/gcc@4.4.7/ImageMagick@6.8.9-10-4df950dd ImageMagick@6.8.9-10 /home/gamblin2/spack/opt/linux-debian7-x86_64/gcc@4.4.7/ImageMagick@6.8.9-10-4df950dd
@ -340,9 +347,9 @@ use ``spack find -p``:
And, finally, you can restrict your search to a particular package And, finally, you can restrict your search to a particular package
by supplying its name: by supplying its name:
.. code-block:: sh .. code-block:: console
$ spack find -p libelf $ spack find --paths libelf
-- linux-debian7-x86_64 / gcc@4.4.7 -------------------------------- -- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
libelf@0.8.11 /home/gamblin2/spack/opt/linux-debian7-x86_64/gcc@4.4.7/libelf@0.8.11 libelf@0.8.11 /home/gamblin2/spack/opt/linux-debian7-x86_64/gcc@4.4.7/libelf@0.8.11
libelf@0.8.12 /home/gamblin2/spack/opt/linux-debian7-x86_64/gcc@4.4.7/libelf@0.8.12 libelf@0.8.12 /home/gamblin2/spack/opt/linux-debian7-x86_64/gcc@4.4.7/libelf@0.8.12
@ -353,7 +360,7 @@ by supplying its name:
package. If you want to find only libelf versions greater than version package. If you want to find only libelf versions greater than version
0.8.12, you could say: 0.8.12, you could say:
.. code-block:: sh .. code-block:: console
$ spack find libelf@0.8.12: $ spack find libelf@0.8.12:
-- linux-debian7-x86_64 / gcc@4.4.7 -------------------------------- -- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
@ -362,17 +369,16 @@ package. If you want to find only libelf versions greater than version
Finding just the versions of libdwarf built with a particular version Finding just the versions of libdwarf built with a particular version
of libelf would look like this: of libelf would look like this:
.. code-block:: sh .. code-block:: console
$ spack find -l libdwarf ^libelf@0.8.12 $ spack find --long libdwarf ^libelf@0.8.12
==> 1 installed packages. ==> 1 installed packages.
-- linux-debian7-x86_64 / gcc@4.4.7 -------------------------------- -- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
libdwarf@20130729-d9b90962 libdwarf@20130729-d9b90962
We can also search for packages that have a certain attribute. For example, We can also search for packages that have a certain attribute. For example,
``spack find -l libdwarf +debug`` will show only installations of libdwarf ``spack find libdwarf +debug`` will show only installations of libdwarf
with the 'debug' compile-time option enabled, while ``spack find -l +debug`` with the 'debug' compile-time option enabled.
will find every installed package with a 'debug' compile-time option enabled.
The full spec syntax is discussed in detail in :ref:`sec-specs`. The full spec syntax is discussed in detail in :ref:`sec-specs`.
@ -385,7 +391,7 @@ Compiler configuration
Spack has the ability to build packages with multiple compilers and Spack has the ability to build packages with multiple compilers and
compiler versions. Spack searches for compilers on your machine 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: .. _spack-compilers:
@ -394,7 +400,9 @@ your path.
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
You can see which compilers spack has found by running ``spack You can see which compilers spack has found by running ``spack
compilers`` or ``spack compiler list``:: compilers`` or ``spack compiler list``:
.. code-block:: console
$ spack compilers $ spack compilers
==> Available compilers ==> Available compilers
@ -432,7 +440,9 @@ An alias for ``spack compiler find``.
If you do not see a compiler in this list, but you want to use it with If you do not see a compiler in this list, but you want to use it with
Spack, you can simply run ``spack compiler find`` with the path to Spack, you can simply run ``spack compiler find`` with the path to
where the compiler is installed. For example:: where the compiler is installed. For example:
.. code-block:: console
$ spack compiler find /usr/local/tools/ic-13.0.079 $ spack compiler find /usr/local/tools/ic-13.0.079
==> Added 1 new compiler to /Users/gamblin2/.spack/compilers.yaml ==> Added 1 new compiler to /Users/gamblin2/.spack/compilers.yaml
@ -441,7 +451,9 @@ where the compiler is installed. For example::
Or you can run ``spack compiler find`` with no arguments to force Or you can run ``spack compiler find`` with no arguments to force
auto-detection. This is useful if you do not know where compilers are auto-detection. This is useful if you do not know where compilers are
installed, but you know that new compilers have been added to your installed, but you know that new compilers have been added to your
``PATH``. For example, using dotkit, you might do this:: ``PATH``. For example, using dotkit, you might do this:
.. code-block:: console
$ module load gcc-4.9.0 $ module load gcc-4.9.0
$ spack compiler find $ spack compiler find
@ -458,7 +470,9 @@ This loads the environment module for gcc-4.9.0 to add it to
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
If you want to see specifics on a particular compiler, you can run If you want to see specifics on a particular compiler, you can run
``spack compiler info`` on it:: ``spack compiler info`` on it:
.. code-block:: console
$ spack compiler info intel@15 $ spack compiler info intel@15
intel@15.0.0: intel@15.0.0:
@ -466,9 +480,11 @@ If you want to see specifics on a particular compiler, you can run
cxx = /usr/local/bin/icpc-15.0.090 cxx = /usr/local/bin/icpc-15.0.090
f77 = /usr/local/bin/ifort-15.0.090 f77 = /usr/local/bin/ifort-15.0.090
fc = /usr/local/bin/ifort-15.0.090 fc = /usr/local/bin/ifort-15.0.090
modules = []
operating system = centos6
This shows which C, C++, and Fortran compilers were detected by Spack. This shows which C, C++, and Fortran compilers were detected by Spack.
Notice also that we didn\'t have to be too specific about the Notice also that we didn't have to be too specific about the
version. We just said ``intel@15``, and information about the only version. We just said ``intel@15``, and information about the only
matching Intel compiler was displayed. matching Intel compiler was displayed.
@ -480,9 +496,42 @@ If auto-detection fails, you can manually configure a compiler by
editing your ``~/.spack/compilers.yaml`` file. You can do this by running editing your ``~/.spack/compilers.yaml`` file. You can do this by running
``spack config edit compilers``, which will open the file in your ``$EDITOR``. ``spack config edit compilers``, which will open the file in your ``$EDITOR``.
Each compiler configuration in the file looks like this:: Each compiler configuration in the file looks like this:
.. code-block:: yaml
compilers:
- compiler:
modules = []
operating_system: centos6
paths:
cc: /usr/local/bin/icc-15.0.024-beta
cxx: /usr/local/bin/icpc-15.0.024-beta
f77: /usr/local/bin/ifort-15.0.024-beta
fc: /usr/local/bin/ifort-15.0.024-beta
spec: intel@15.0.0:
For compilers, like ``clang``, that do not support Fortran, put
``None`` for ``f77`` and ``fc``:
.. code-block:: yaml
paths:
cc: /usr/bin/clang
cxx: /usr/bin/clang++
f77: None
fc: None
spec: clang@3.3svn:
Once you save the file, the configured compilers will show up in the
list displayed by ``spack compilers``.
You can also add compiler flags to manually configured compilers. The
valid flags are ``cflags``, ``cxxflags``, ``fflags``, ``cppflags``,
``ldflags``, and ``ldlibs``. For example:
.. code-block:: yaml
...
compilers: compilers:
- compiler: - compiler:
modules = [] modules = []
@ -492,36 +541,9 @@ Each compiler configuration in the file looks like this::
cxx: /usr/local/bin/icpc-15.0.024-beta cxx: /usr/local/bin/icpc-15.0.024-beta
f77: /usr/local/bin/ifort-15.0.024-beta f77: /usr/local/bin/ifort-15.0.024-beta
fc: /usr/local/bin/ifort-15.0.024-beta fc: /usr/local/bin/ifort-15.0.024-beta
parameters:
spec: intel@15.0.0:
For compilers, like ``clang``, that do not support Fortran, put
``None`` for ``f77`` and ``fc``::
clang@3.3svn:
cc: /usr/bin/clang
cxx: /usr/bin/clang++
f77: None
fc: None
Once you save the file, the configured compilers will show up in the
list displayed by ``spack compilers``.
You can also add compiler flags to manually configured compilers. The
valid flags are ``cflags``, ``cxxflags``, ``fflags``, ``cppflags``,
``ldflags``, and ``ldlibs``. For example::
...
compilers:
- compiler:
...
intel@15.0.0:
cc: /usr/local/bin/icc-15.0.024-beta
cxx: /usr/local/bin/icpc-15.0.024-beta
f77: /usr/local/bin/ifort-15.0.024-beta
fc: /usr/local/bin/ifort-15.0.024-beta
cppflags: -O3 -fPIC cppflags: -O3 -fPIC
... spec: intel@15.0.0:
These flags will be treated by spack as if they were enterred from These flags will be treated by spack as if they were enterred from
the command line each time this compiler is used. The compiler wrappers the command line each time this compiler is used. The compiler wrappers
@ -541,10 +563,12 @@ Spack, that descriptor is called a *spec*. Spack uses specs to refer
to a particular build configuration (or configurations) of a package. to a particular build configuration (or configurations) of a package.
Specs are more than a package name and a version; you can use them to Specs are more than a package name and a version; you can use them to
specify the compiler, compiler version, architecture, compile options, specify the compiler, compiler version, architecture, compile options,
and dependency options for a build. In this section, we\'ll go over and dependency options for a build. In this section, we'll go over
the full syntax of specs. the full syntax of specs.
Here is an example of a much longer spec than we\'ve seen thus far:: Here is an example of a much longer spec than we've seen thus far:
.. code-block:: none
mpileaks @1.2:1.4 %gcc@4.7.5 +debug -qt arch=bgq_os ^callpath @1.1 %gcc@4.7.2 mpileaks @1.2:1.4 %gcc@4.7.5 +debug -qt arch=bgq_os ^callpath @1.1 %gcc@4.7.2
@ -638,7 +662,7 @@ of dependencies within a spec is that they appear *after* the root
package. For example, these two specs represent exactly the same package. For example, these two specs represent exactly the same
configuration: configuration:
.. code-block:: sh .. code-block:: none
mpileaks ^callpath@1.0 ^libelf@0.8.3 mpileaks ^callpath@1.0 ^libelf@0.8.3
mpileaks ^libelf@0.8.3 ^callpath@1.0 mpileaks ^libelf@0.8.3 ^callpath@1.0
@ -712,7 +736,7 @@ makes available. Variants can be specified using
a flexible parameter syntax ``name=<value>``. For example, a flexible parameter syntax ``name=<value>``. For example,
``spack install libelf debug=True`` will install libelf build with debug ``spack install libelf debug=True`` will install libelf build with debug
flags. The names of particular variants available for a package depend on flags. The names of particular variants available for a package depend on
what was provided by the package author. ``spack into <package>`` will what was provided by the package author. ``spack info <package>`` will
provide information on what build variants are available. provide information on what build variants are available.
For compatibility with earlier versions, variants which happen to be For compatibility with earlier versions, variants which happen to be
@ -723,7 +747,7 @@ compile time option for the libelf package.
Depending on the package a variant may have any default value. For Depending on the package a variant may have any default value. For
``libelf`` here, ``debug`` is ``False`` by default, and we turned it on ``libelf`` here, ``debug`` is ``False`` by default, and we turned it on
with ``debug=True`` or ``+debug``. If a package is ``True`` by default with ``debug=True`` or ``+debug``. If a variant is ``True`` by default
you can turn it off by either adding ``-name`` or ``~name`` to the spec. you can turn it off by either adding ``-name`` or ``~name`` to the spec.
There are two syntaxes here because, depending on context, ``~`` and There are two syntaxes here because, depending on context, ``~`` and
@ -774,9 +798,9 @@ command line. From within python files, the same spec would be specified
handles the quote symbols. handles the quote symbols.
The six compiler flags are injected in the order of implicit make commands The six compiler flags are injected in the order of implicit make commands
in gnu autotools. If all flags are set, the order is in GNU Autotools. If all flags are set, the order is
``$cppflags $cflags|$cxxflags $ldflags command $ldlibs`` for C and C++ and ``$cppflags $cflags|$cxxflags $ldflags <command> $ldlibs`` for C and C++ and
``$fflags $cppflags $ldflags command $ldlibs`` for fortran. ``$fflags $cppflags $ldflags <command> $ldlibs`` for Fortran.
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
Architecture specifiers Architecture specifiers
@ -786,14 +810,14 @@ The architecture can be specified by using the reserved
words ``target`` and/or ``os`` (``target=x86-64 os=debian7``). You can also words ``target`` and/or ``os`` (``target=x86-64 os=debian7``). You can also
use the triplet form of platform, operating system and processor. use the triplet form of platform, operating system and processor.
.. code-block:: sh .. code-block:: console
spack install libelf arch=cray_xc-CNL10-haswell $ spack install libelf arch=cray-CNL10-haswell
Users on non-Cray systems won't have to worry about specifying the architecture. Users on non-Cray systems won't have to worry about specifying the architecture.
Spack will autodetect what kind of operating system is on your machine as well Spack will autodetect what kind of operating system is on your machine as well
as the processor. For more information on how the architecture can be as the processor. For more information on how the architecture can be
used on Cray machines, check here :ref:`cray-support` used on Cray machines, see :ref:`cray-support`
.. _sec-virtual-dependencies: .. _sec-virtual-dependencies:
@ -848,21 +872,27 @@ Constraining virtual packages
When installing a package that depends on a virtual package, you can When installing a package that depends on a virtual package, you can
opt to specify the particular provider you want to use, or you can let opt to specify the particular provider you want to use, or you can let
Spack pick. For example, if you just type this:: Spack pick. For example, if you just type this:
spack install mpileaks .. code-block:: console
$ spack install mpileaks
Then spack will pick a provider for you according to site policies. Then spack will pick a provider for you according to site policies.
If you really want a particular version, say mpich, then you could If you really want a particular version, say ``mpich``, then you could
run this instead:: run this instead:
spack install mpileaks ^mpich .. code-block:: console
$ spack install mpileaks ^mpich
This forces spack to use some version of ``mpich`` for its This forces spack to use some version of ``mpich`` for its
implementation. As always, you can be even more specific and require implementation. As always, you can be even more specific and require
a particular ``mpich`` version:: a particular ``mpich`` version:
spack install mpileaks ^mpich@3 .. code-block:: console
$ spack install mpileaks ^mpich@3
The ``mpileaks`` package in particular only needs MPI-1 commands, so The ``mpileaks`` package in particular only needs MPI-1 commands, so
any MPI implementation will do. If another package depends on any MPI implementation will do. If another package depends on
@ -887,7 +917,7 @@ to be unique, Spack will replace the reference with the spec to which
it refers. Otherwise, it will prompt for a more qualified hash. 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 -f``. ``spack uninstall --force``.
.. _spack-providers: .. _spack-providers:
@ -937,15 +967,15 @@ distributions, this can be installed from the vendor's repository:
.. code-block:: sh .. code-block:: sh
yum install environment-modules # (Fedora/RHEL/CentOS) $ yum install environment-modules # (Fedora/RHEL/CentOS)
apt-get install environment-modules # (Ubuntu/Debian) $ apt-get install environment-modules # (Ubuntu/Debian)
If your Linux distribution does not have If your Linux distribution does not have
Environment Modules, you can get it with Spack: Environment Modules, you can get it with Spack:
.. code-block:: sh .. code-block:: console
spack install environment-modules $ spack install environment-modules
In this case to activate it automatically you need to add the following two In this case to activate it automatically you need to add the following two
lines to your ``.bashrc`` profile (or similar): lines to your ``.bashrc`` profile (or similar):
@ -972,7 +1002,8 @@ For ``bash`` or ``ksh``, run:
.. code-block:: sh .. code-block:: sh
. ${SPACK_ROOT}/share/spack/setup-env.sh export SPACK_ROOT=/path/to/spack
. $SPACK_ROOT/share/spack/setup-env.sh
For ``csh`` and ``tcsh`` run: For ``csh`` and ``tcsh`` run:
@ -995,8 +1026,8 @@ directories:
.. code-block:: sh .. code-block:: sh
${SPACK_ROOT}/share/spack/modules $SPACK_ROOT/share/spack/modules
${SPACK_ROOT}/share/spack/dotkit $SPACK_ROOT/share/spack/dotkit
The directories are automatically added to your ``MODULEPATH`` and The directories are automatically added to your ``MODULEPATH`` and
``DK_NODE`` environment variables when you enable Spack's `shell ``DK_NODE`` environment variables when you enable Spack's `shell
@ -1011,7 +1042,7 @@ If you have shell support enabled you should be able to run either
been installed. Here is sample output of those programs, showing lots been installed. Here is sample output of those programs, showing lots
of installed packages. of installed packages.
.. code-block:: sh .. code-block:: console
$ module avail $ module avail
@ -1028,7 +1059,7 @@ of installed packages.
libNBC@1.1.1%gcc@4.9.0-27912b7b sundials@2.5.0%gcc@4.9.0-27912b7b libNBC@1.1.1%gcc@4.9.0-27912b7b sundials@2.5.0%gcc@4.9.0-27912b7b
libdwarf@20130729%gcc@4.4.7-b52fac98 libdwarf@20130729%gcc@4.4.7-b52fac98
.. code-block:: sh .. code-block:: console
$ use -l spack $ use -l spack
@ -1054,13 +1085,13 @@ The names here should look familiar, they're the same ones from
``spack find``. You *can* use the names here directly. For example, ``spack find``. You *can* use the names here directly. For example,
you could type either of these commands to load the callpath module: you could type either of these commands to load the callpath module:
.. code-block:: sh .. code-block:: console
use callpath@1.0.1%gcc@4.4.7-5dce4318 $ use callpath@1.0.1%gcc@4.4.7-5dce4318
.. code-block:: sh .. code-block:: console
module load callpath@1.0.1%gcc@4.4.7-5dce4318 $ module load callpath@1.0.1%gcc@4.4.7-5dce4318
Neither of these is particularly pretty, easy to remember, or Neither of these is particularly pretty, easy to remember, or
easy to type. Luckily, Spack has its own interface for using modules easy to type. Luckily, Spack has its own interface for using modules
@ -1077,7 +1108,7 @@ And you can use the same shortened names you use everywhere else in
Spack. For example, this will add the ``mpich`` package built with Spack. For example, this will add the ``mpich`` package built with
``gcc`` to your path: ``gcc`` to your path:
.. code-block:: sh .. code-block:: console
$ spack install mpich %gcc@4.4.7 $ spack install mpich %gcc@4.4.7
@ -1090,15 +1121,15 @@ Spack. For example, this will add the ``mpich`` package built with
Or, similarly with modules, you could type: Or, similarly with modules, you could type:
.. code-block:: sh .. code-block:: console
$ spack load mpich %gcc@4.4.7 $ spack load mpich %gcc@4.4.7
These commands will add appropriate directories to your ``PATH``, These commands will add appropriate directories to your ``PATH``,
``MANPATH``, ``CPATH``, and ``LD_LIBRARY_PATH``. When you no longer want to use ``MANPATH``, ``CPATH``, and ``LD_LIBRARY_PATH``. When you no longer
a package, you can type unload or unuse similarly: want to use a package, you can type unload or unuse similarly:
.. code-block:: sh .. code-block:: console
$ spack unload mpich %gcc@4.4.7 # modules $ spack unload mpich %gcc@4.4.7 # modules
$ spack unuse mpich %gcc@4.4.7 # dotkit $ spack unuse mpich %gcc@4.4.7 # dotkit
@ -1116,7 +1147,7 @@ Ambiguous module names
If a spec used with load/unload or use/unuse is ambiguous (i.e. more If a spec used with load/unload or use/unuse is ambiguous (i.e. more
than one installed package matches it), then Spack will warn you: than one installed package matches it), then Spack will warn you:
.. code-block:: sh .. code-block:: console
$ spack load libelf $ spack load libelf
==> Error: Multiple matches for spec libelf. Choose one: ==> Error: Multiple matches for spec libelf. Choose one:
@ -1129,7 +1160,7 @@ identify one package. For example, above, the key differentiator is
that one ``libelf`` is built with the Intel compiler, while the other that one ``libelf`` is built with the Intel compiler, while the other
used ``gcc``. You could therefore just type: used ``gcc``. You could therefore just type:
.. code-block:: sh .. code-block:: console
$ spack load libelf %intel $ spack load libelf %intel
@ -1144,13 +1175,13 @@ and are placed in the following directories under the Spack root:
.. code-block:: sh .. code-block:: sh
${SPACK_ROOT}/share/spack/modules $SPACK_ROOT/share/spack/modules
${SPACK_ROOT}/share/spack/dotkit $SPACK_ROOT/share/spack/dotkit
The content that gets written in each module file can be customized in two ways: The content that gets written in each module file can be customized in two ways:
1. overriding part of the ``spack.Package`` API within a ``package.py`` #. overriding part of the ``spack.Package`` API within a ``package.py``
2. writing dedicated configuration files #. writing dedicated configuration files
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
Override ``Package`` API Override ``Package`` API
@ -1179,7 +1210,7 @@ RPATH.
Modules may be loaded recursively with the ``load`` command's Modules may be loaded recursively with the ``load`` command's
``--dependencies`` or ``-r`` argument: ``--dependencies`` or ``-r`` argument:
.. code-block:: sh .. code-block:: console
$ spack load --dependencies <spec> ... $ spack load --dependencies <spec> ...
@ -1195,7 +1226,7 @@ commands inside a shell script. By adding the ``--shell`` flag,
``spack module find`` may also be used to generate code that can be ``spack module find`` may also be used to generate code that can be
cut-and-pasted into a shell script. For example: cut-and-pasted into a shell script. For example:
.. code-block:: sh .. code-block:: console
$ spack module find tcl --dependencies --shell py-numpy git $ spack module find tcl --dependencies --shell py-numpy git
# bzip2@1.0.6%gcc@4.9.3=linux-x86_64 # bzip2@1.0.6%gcc@4.9.3=linux-x86_64
@ -1230,7 +1261,7 @@ cut-and-pasted into a shell script. For example:
module load git-2.8.0-rc2-gcc-4.9.3-3bib4hqtnv5xjjoq5ugt3inblt4xrgkd module load git-2.8.0-rc2-gcc-4.9.3-3bib4hqtnv5xjjoq5ugt3inblt4xrgkd
The script may be further edited by removing unnecessary modules. The script may be further edited by removing unnecessary modules.
This script may be directly executed in bash via This script may be directly executed in bash via:
.. code-block:: sh .. code-block:: sh
@ -1261,7 +1292,6 @@ overrides ``setup_dependent_environment`` in the following way:
.. code-block:: python .. code-block:: python
def setup_dependent_environment(self, spack_env, run_env, extension_spec): def setup_dependent_environment(self, spack_env, run_env, extension_spec):
# ...
if extension_spec.package.extends(self.spec): if extension_spec.package.extends(self.spec):
run_env.prepend_path('PYTHONPATH', os.path.join(extension_spec.prefix, self.site_packages_dir)) run_env.prepend_path('PYTHONPATH', os.path.join(extension_spec.prefix, self.site_packages_dir))
@ -1355,7 +1385,8 @@ modified by your dotkit modules. Then :
dotkit: dotkit:
all: all:
filter: filter:
environment_blacklist: ['CPATH', 'LIBRARY_PATH'] # Exclude changes to any of these variables # Exclude changes to any of these variables
environment_blacklist: ['CPATH', 'LIBRARY_PATH']
will generate dotkit module files that will not contain modifications to either will generate dotkit module files that will not contain modifications to either
``CPATH`` or ``LIBRARY_PATH`` and environment module files that instead will ``CPATH`` or ``LIBRARY_PATH`` and environment module files that instead will
@ -1448,15 +1479,12 @@ Running ``spack module refresh`` will remove the
``share/spack/modules`` and ``share/spack/dotkit`` directories, then ``share/spack/modules`` and ``share/spack/dotkit`` directories, then
regenerate all module and dotkit files from scratch: regenerate all module and dotkit files from scratch:
.. code-block:: sh .. code-block:: console
$ spack module refresh $ spack module refresh
==> Regenerating tcl module files. ==> Regenerating tcl module files.
==> Regenerating dotkit module files. ==> Regenerating dotkit module files.
.. _extensions:
---------------- ----------------
Filesystem Views Filesystem Views
---------------- ----------------
@ -1496,10 +1524,10 @@ built by Spack.
Views can be used for a variety of purposes including: Views can be used for a variety of purposes including:
- A central installation in a traditional layout, eg ``/usr/local`` maintained over time by the sysadmin. * A central installation in a traditional layout, eg ``/usr/local`` maintained over time by the sysadmin.
- A self-contained installation area which may for the basis of a top-level atomic versioning scheme, eg ``/opt/pro`` vs ``/opt/dev``. * A self-contained installation area which may for the basis of a top-level atomic versioning scheme, eg ``/opt/pro`` vs ``/opt/dev``.
- Providing an atomic and monolithic binary distribution, eg for delivery as a single tarball. * Providing an atomic and monolithic binary distribution, eg for delivery as a single tarball.
- Producing ephemeral testing or developing environments. * Producing ephemeral testing or developing environments.
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
Using Filesystem Views Using Filesystem Views
@ -1514,9 +1542,9 @@ The following example creates a filesystem view based
on an installed ``cmake`` package and then removes from the view the on an installed ``cmake`` package and then removes from the view the
files in the ``cmake`` package while retaining its dependencies. files in the ``cmake`` package while retaining its dependencies.
.. code-block:: sh .. code-block:: console
$ spack view -v symlink myview cmake@3.5.2 $ spack view --verbose symlink myview cmake@3.5.2
==> Linking package: "ncurses" ==> Linking package: "ncurses"
==> Linking package: "zlib" ==> Linking package: "zlib"
==> Linking package: "openssl" ==> Linking package: "openssl"
@ -1529,7 +1557,7 @@ files in the ``cmake`` package while retaining its dependencies.
captoinfo clear cpack ctest infotocap openssl tabs toe tset captoinfo clear cpack ctest infotocap openssl tabs toe tset
ccmake cmake c_rehash infocmp ncurses6-config reset tic tput ccmake cmake c_rehash infocmp ncurses6-config reset tic tput
$ spack view -v -d false rm myview cmake@3.5.2 $ spack view --verbose --dependencies false rm myview cmake@3.5.2
==> Removing package: "cmake" ==> Removing package: "cmake"
$ ls myview/bin/ $ ls myview/bin/
@ -1568,6 +1596,8 @@ particular, if two packages require the same sub-tree of dependencies,
removing one package (recursively) will remove its dependencies and removing one package (recursively) will remove its dependencies and
leave the other package broken. leave the other package broken.
.. _extensions:
--------------------------- ---------------------------
Extensions & Python support Extensions & Python support
--------------------------- ---------------------------
@ -1583,7 +1613,7 @@ Spack has support for this type of installation as well. In Spack,
a package that can live inside the prefix of another package is called a package that can live inside the prefix of another package is called
an *extension*. Suppose you have Python installed like so: an *extension*. Suppose you have Python installed like so:
.. code-block:: sh .. code-block:: console
$ spack find python $ spack find python
==> 1 installed packages. ==> 1 installed packages.
@ -1598,7 +1628,7 @@ an *extension*. Suppose you have Python installed like so:
You can find extensions for your Python installation like this: You can find extensions for your Python installation like this:
.. code-block:: sh .. code-block:: console
$ spack extensions python $ spack extensions python
==> python@2.7.8%gcc@4.4.7 arch=linux-debian7-x86_64-703c7a96 ==> python@2.7.8%gcc@4.4.7 arch=linux-debian7-x86_64-703c7a96
@ -1623,11 +1653,11 @@ You can find extensions for your Python installation like this:
The extensions are a subset of what's returned by ``spack list``, and The extensions are a subset of what's returned by ``spack list``, and
they are packages like any other. They are installed into their own they are packages like any other. They are installed into their own
prefixes, and you can see this with ``spack find -p``: prefixes, and you can see this with ``spack find --paths``:
.. code-block:: sh .. code-block:: console
$ spack find -p py-numpy $ spack find --paths py-numpy
==> 1 installed packages. ==> 1 installed packages.
-- linux-debian7-x86_64 / gcc@4.4.7 -------------------------------- -- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
py-numpy@1.9.1 /g/g21/gamblin2/src/spack/opt/linux-debian7-x86_64/gcc@4.4.7/py-numpy@1.9.1-66733244 py-numpy@1.9.1 /g/g21/gamblin2/src/spack/opt/linux-debian7-x86_64/gcc@4.4.7/py-numpy@1.9.1-66733244
@ -1635,7 +1665,7 @@ prefixes, and you can see this with ``spack find -p``:
However, even though this package is installed, you cannot use it However, even though this package is installed, you cannot use it
directly when you run ``python``: directly when you run ``python``:
.. code-block:: sh .. code-block:: console
$ spack load python $ spack load python
$ python $ python
@ -1659,14 +1689,14 @@ in your current shell.
For tcl modules: For tcl modules:
.. code-block:: sh .. code-block:: console
$ spack load python $ spack load python
$ spack load py-numpy $ spack load py-numpy
or, for dotkit: or, for dotkit:
.. code-block:: sh .. code-block:: console
$ spack use python $ spack use python
$ spack use py-numpy $ spack use py-numpy
@ -1690,7 +1720,7 @@ installation:
``spack activate`` ``spack activate``
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
.. code-block:: sh .. code-block:: console
$ spack activate py-numpy $ spack activate py-numpy
==> Activated extension py-setuptools@11.3.1%gcc@4.4.7 arch=linux-debian7-x86_64-3c74eb69 for python@2.7.8%gcc@4.4.7. ==> Activated extension py-setuptools@11.3.1%gcc@4.4.7 arch=linux-debian7-x86_64-3c74eb69 for python@2.7.8%gcc@4.4.7.
@ -1707,7 +1737,7 @@ once all dependencies were activated in the ``python`` installation,
If we run ``spack extensions`` again, we now see the three new If we run ``spack extensions`` again, we now see the three new
packages listed as activated: packages listed as activated:
.. code-block:: sh .. code-block:: console
$ spack extensions python $ spack extensions python
==> python@2.7.8%gcc@4.4.7 arch=linux-debian7-x86_64-703c7a96 ==> python@2.7.8%gcc@4.4.7 arch=linux-debian7-x86_64-703c7a96
@ -1756,7 +1786,7 @@ explicitly load their preferred version.
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 -f``:
.. code-block:: sh .. code-block:: console
$ spack activate -f py-numpy $ spack activate -f 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.
@ -1775,15 +1805,17 @@ several variants:
* ``spack deactivate <extension>`` will deactivate a single * ``spack deactivate <extension>`` will deactivate a single
extension. If another activated extension depends on this one, extension. If another activated extension depends on this one,
Spack will warn you and exit with an error. Spack will warn you and exit with an error.
* ``spack deactivate -f <extension>`` deactivates an extension * ``spack deactivate --force <extension>`` deactivates an extension
regardless of packages that depend on it. regardless of packages that depend on it.
* ``spack deactivate -a <extension>`` deactivates an extension and * ``spack deactivate --all <extension>`` deactivates an extension and
all of its dependencies. Use ``-f`` to disregard dependents. all of its dependencies. Use ``--force`` to disregard dependents.
* ``spack deactivate -a <extendee>`` deactivates *all* activated * ``spack deactivate --all <extendee>`` deactivates *all* activated
extensions of a package. For example, to deactivate *all* python extensions of a package. For example, to deactivate *all* python
extensions, use:: extensions, use:
spack deactivate -a python .. code-block:: console
$ spack deactivate --all python
----------------------- -----------------------
Filesystem requirements Filesystem requirements
@ -1796,7 +1828,7 @@ without ``flock`` support enabled. You can determine how your
filesystems are mounted with ``mount -p``. The output for a Lustre filesystems are mounted with ``mount -p``. The output for a Lustre
filesystem might look like this: filesystem might look like this:
.. code-block:: sh .. code-block:: console
$ mount -l | grep lscratch $ mount -l | grep lscratch
pilsner-mds1-lnet0@o2ib100:/lsd on /p/lscratchd type lustre (rw,nosuid,noauto,_netdev,lazystatfs,flock) pilsner-mds1-lnet0@o2ib100:/lsd on /p/lscratchd type lustre (rw,nosuid,noauto,_netdev,lazystatfs,flock)
@ -1808,7 +1840,7 @@ system administrator to enable ``flock``.
This issue typically manifests with the error below: This issue typically manifests with the error below:
.. code-block:: sh .. code-block:: console
$ ./spack find $ ./spack find
Traceback (most recent call last): Traceback (most recent call last):
@ -1817,7 +1849,7 @@ This issue typically manifests with the error below:
File "./spack", line 154,' in main File "./spack", line 154,' in main
return_val = command(parser, args) return_val = command(parser, args)
File "./spack/lib/spack/spack/cmd/find.py", line 170, in find File "./spack/lib/spack/spack/cmd/find.py", line 170, in find
specs = set(spack.installed_db.query(**q_args)) specs = set(spack.installed_db.query(\**q_args))
File "./spack/lib/spack/spack/database.py", line 551, in query File "./spack/lib/spack/spack/database.py", line 551, in query
with self.read_transaction(): with self.read_transaction():
File "./spack/lib/spack/spack/database.py", line 598, in __enter__ File "./spack/lib/spack/spack/database.py", line 598, in __enter__
@ -1832,12 +1864,7 @@ This issue typically manifests with the error below:
A nicer error message is TBD in future versions of Spack. A nicer error message is TBD in future versions of Spack.
<<<<<<< c36f13e44dae52086ca48e4f16b514642bc91106
.. _cray-support: .. _cray-support:
=======
.. _spack-cray:
>>>>>>> Fix #1604 and fix #1605, title underline problems
------------- -------------
Spack on Cray Spack on Cray
@ -1846,34 +1873,34 @@ Spack on Cray
Spack differs slightly when used on a Cray system. The architecture spec Spack differs slightly when used on a Cray system. The architecture spec
can differentiate between the front-end and back-end processor and operating system. can differentiate between the front-end and back-end processor and operating system.
For example, on Edison at NERSC, the back-end target processor For example, on Edison at NERSC, the back-end target processor
is \"Ivy Bridge\", so you can specify to use the back-end this way: is "Ivy Bridge", so you can specify to use the back-end this way:
.. code-block:: sh .. code-block:: console
spack install zlib target=ivybridge $ spack install zlib target=ivybridge
You can also use the operating system to build against the back-end: You can also use the operating system to build against the back-end:
.. code-block:: sh .. code-block:: console
spack install zlib os=CNL10 $ spack install zlib os=CNL10
Notice that the name includes both the operating system name and the major Notice that the name includes both the operating system name and the major
version number concatenated together. version number concatenated together.
Alternatively, if you want to build something for the front-end, Alternatively, if you want to build something for the front-end,
you can specify the front-end target processor. The processor for a login node you can specify the front-end target processor. The processor for a login node
on Edison is \"Sandy bridge\" so we specify on the command line like so: on Edison is "Sandy bridge" so we specify on the command line like so:
.. code-block:: sh .. code-block:: console
spack install zlib target=sandybridge $ spack install zlib target=sandybridge
And the front-end operating system is: And the front-end operating system is:
.. code-block:: sh .. code-block:: console
spack install zlib os=SuSE11 $ spack install zlib os=SuSE11
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
Cray compiler detection Cray compiler detection
@ -1888,27 +1915,27 @@ compiler wrapper names (i.e. cc, CC, ftn). During build time, Spack will load
the correct PrgEnv and compiler module and will call appropriate wrapper. the correct PrgEnv and compiler module and will call appropriate wrapper.
The compilers.yaml config file will also differ. There is a The compilers.yaml config file will also differ. There is a
modules section that is filled with the compiler\'s Programming Environment modules section that is filled with the compiler's Programming Environment
and module name. On other systems, this field is empty []:: and module name. On other systems, this field is empty []:
.. code-block:: yaml
...
- compiler: - compiler:
modules: modules:
- PrgEnv-intel - PrgEnv-intel
- intel/15.0.109 - intel/15.0.109
...
As mentioned earlier, the compiler paths will look different on a Cray system. As mentioned earlier, the compiler paths will look different on a Cray system.
Since most compilers are invoked using cc, CC and ftn, the paths for each Since most compilers are invoked using cc, CC and ftn, the paths for each
compiler are replaced with their respective Cray compiler wrapper names:: compiler are replaced with their respective Cray compiler wrapper names:
.. code-block:: yaml
...
paths: paths:
cc: cc cc: cc
cxx: CC cxx: CC
f77: ftn f77: ftn
fc: ftn fc: ftn
...
As opposed to an explicit path to the compiler executable. This allows Spack As opposed to an explicit path to the compiler executable. This allows Spack
to call the Cray compiler wrappers during build time. to call the Cray compiler wrappers during build time.
@ -1917,16 +1944,16 @@ For more on compiler configuration, check out :ref:`compiler-config`.
Spack sets the default Cray link type to dynamic, to better match other Spack sets the default Cray link type to dynamic, to better match other
other platforms. Individual packages can enable static linking (which is the other platforms. Individual packages can enable static linking (which is the
default outside of Spack on cray systems) using the -static flag. default outside of Spack on cray systems) using the ``-static`` flag.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Setting defaults and using Cray modules Setting defaults and using Cray modules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to use default compilers for each PrgEnv and also be able If you want to use default compilers for each PrgEnv and also be able
to load cray external modules, you will need to set up a packages.yaml. to load cray external modules, you will need to set up a ``packages.yaml``.
Here\'s an example of an external configuration for cray modules: Here's an example of an external configuration for cray modules:
.. code-block:: yaml .. code-block:: yaml
@ -1942,7 +1969,7 @@ environment variables, libraries, etc, that are brought into the environment
via module load. via module load.
You can set the default compiler that Spack can use for each compiler type. You can set the default compiler that Spack can use for each compiler type.
If you want to use the Cray defaults, then set them under *all:* in packages.yaml. If you want to use the Cray defaults, then set them under ``all:`` in packages.yaml.
In the compiler field, set the compiler specs in your order of preference. In the compiler field, set the compiler specs in your order of preference.
Whenever you build with that compiler type, Spack will concretize to that version. Whenever you build with that compiler type, Spack will concretize to that version.
@ -1987,7 +2014,7 @@ Getting Help
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
If you don't find what you need here, the ``help`` subcommand will If you don't find what you need here, the ``help`` subcommand will
print out out a list of *all* of ``spack``'s options and subcommands: print out out a list of *all* of spack's options and subcommands:
.. command-output:: spack help .. command-output:: spack help
@ -1996,5 +2023,5 @@ usage information for a particular subcommand:
.. command-output:: spack help install .. command-output:: spack help install
Alternately, you can use ``spack -h`` in place of ``spack help``, or Alternately, you can use ``spack --help`` in place of ``spack help``, or
``spack <subcommand> -h`` to get help on a particular subcommand. ``spack <subcommand> --help`` to get help on a particular subcommand.

18
lib/spack/docs/configuration.rst
View File

@ -10,7 +10,9 @@ Configuration
Temporary space Temporary space
--------------- ---------------
.. warning:: Temporary space configuration will eventually be moved to .. warning::
Temporary space configuration will eventually be moved to
configuration files, but currently these settings are in configuration files, but currently these settings are in
``lib/spack/spack/__init__.py`` ``lib/spack/spack/__init__.py``
@ -144,7 +146,7 @@ The preferred configuration can be controlled via the
Here's an example packages.yaml file that sets preferred packages: Here's an example packages.yaml file that sets preferred packages:
.. code-block:: sh .. code-block:: yaml
packages: packages:
opencv: opencv:
@ -205,15 +207,15 @@ supply ``-p`` to Spack on the command line, before any subcommands.
``spack -p`` output looks like this: ``spack -p`` output looks like this:
.. code-block:: sh .. code-block:: console
$ spack -p graph dyninst $ spack -p graph dyninst
o dyninst o dyninst
|\ \|\
| |\ \| \|\
| o | libdwarf \| o \| libdwarf
|/ / \|/ /
o | libelf o \| libelf
/ /
o boost o boost

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

@ -70,7 +70,9 @@ Directory Structure
------------------- -------------------
So that you can familiarize yourself with the project, we'll start So that you can familiarize yourself with the project, we'll start
with a high level view of Spack's directory structure:: with a high level view of Spack's directory structure:
.. code-block:: none
spack/ <- installation root spack/ <- installation root
bin/ bin/
@ -109,17 +111,14 @@ Spack is designed so that it could live within a `standard UNIX
directory hierarchy <http://linux.die.net/man/7/hier>`_, so ``lib``, directory hierarchy <http://linux.die.net/man/7/hier>`_, so ``lib``,
``var``, and ``opt`` all contain a ``spack`` subdirectory in case ``var``, and ``opt`` all contain a ``spack`` subdirectory in case
Spack is installed alongside other software. Most of the interesting Spack is installed alongside other software. Most of the interesting
parts of Spack live in ``lib/spack``. Files under ``var`` are created parts of Spack live in ``lib/spack``.
as needed, so there is no ``var`` directory when you initially clone
Spack from the repository.
Spack has *one* directory layout and there is no install process. Spack has *one* directory layout and there is no install process.
version and the source code. Most Python programs don't look like Most Python programs don't look like this (they use distutils, ``setup.py``,
this (they use distutils, ``setup.py``, etc.) but we wanted to make etc.) but we wanted to make Spack *very* easy to use. The simple layout
Spack *very* easy to use. The simple layout spares users from the spares users from the need to install Spack into a Python environment.
need to install Spack into a Python environment. Many users don't Many users don't have write access to a Python installation, and installing
have write access to a Python installation, and installing an entire an entire new instance of Python to bootstrap Spack would be very complicated.
new instance of Python to bootstrap Spack would be very complicated.
Users should not have to install install a big, complicated package to Users should not have to install install a big, complicated package to
use the thing that's supposed to spare them from the details of big, use the thing that's supposed to spare them from the details of big,
complicated packages. The end result is that Spack works out of the complicated packages. The end result is that Spack works out of the
@ -283,8 +282,7 @@ Spec objects
Package objects Package objects
--------------- ---------------
Most spack commands Most spack commands look something like this:
look something like this:
#. Parse an abstract spec (or specs) from the command line, #. Parse an abstract spec (or specs) from the command line,
#. *Normalize* the spec based on information in package files, #. *Normalize* the spec based on information in package files,
@ -295,7 +293,7 @@ look something like this:
The information in Package files is used at all stages in this The information in Package files is used at all stages in this
process. process.
Conceptually, packages are overloaded. They contain Conceptually, packages are overloaded. They contain:
------------- -------------
Stage objects Stage objects

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

@ -14,7 +14,7 @@ Simple package installation
Installing the default version of a package is simple. This will install Installing the default version of a package is simple. This will install
the latest version of the ``mpileaks`` package and all of its dependencies: the latest version of the ``mpileaks`` package and all of its dependencies:
.. code-block:: sh .. code-block:: console
$ spack install mpileaks $ spack install mpileaks
@ -26,7 +26,7 @@ Spack allows installation to be customized. Users can specify the
version, build compiler, compile-time options, and cross-compile version, build compiler, compile-time options, and cross-compile
platform, all on the command line. platform, all on the command line.
.. code-block:: sh .. code-block:: console
# Install a particular version by appending @ # Install a particular version by appending @
$ spack install mpileaks@1.1.2 $ spack install mpileaks@1.1.2
@ -59,7 +59,7 @@ customized extensively. Suppose that ``mpileaks`` depends indirectly
on ``libelf`` and ``libdwarf``. Using ``^``, users can add custom on ``libelf`` and ``libdwarf``. Using ``^``, users can add custom
configurations for the dependencies: configurations for the dependencies:
.. code-block:: sh .. code-block:: console
# Install mpileaks and link it with specific versions of libelf and libdwarf # Install mpileaks and link it with specific versions of libelf and libdwarf
$ spack install mpileaks@1.1.2 %gcc@4.7.3 +debug ^libelf@0.8.12 ^libdwarf@20130729+debug $ spack install mpileaks@1.1.2 %gcc@4.7.3 +debug ^libelf@0.8.12 ^libdwarf@20130729+debug
@ -91,7 +91,7 @@ in pure Python.
For example, this command: For example, this command:
.. code-block:: sh .. code-block:: console
$ spack create http://www.mr511.de/software/libelf-0.8.13.tar.gz $ spack create http://www.mr511.de/software/libelf-0.8.13.tar.gz
@ -101,16 +101,26 @@ creates a simple python file:
from spack import * from spack import *
class Libelf(Package): class Libelf(Package):
homepage = "http://www.example.com/" """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 = "http://www.mr511.de/software/libelf-0.8.13.tar.gz" url = "http://www.mr511.de/software/libelf-0.8.13.tar.gz"
version('0.8.13', '4136d7b4c04df68b686570afa26988ac') version('0.8.13', '4136d7b4c04df68b686570afa26988ac')
def install(self, prefix): # FIXME: Add dependencies if required.
configure("--prefix=%s" % prefix) # depends_on('foo')
def install(self, spec, prefix):
# FIXME: Modify the configure line to suit your build system here.
configure('--prefix={0}'.format(prefix))
# FIXME: Add logic to build and install here.
make() make()
make("install") make('install')
It doesn't take much python coding to get from there to a working It doesn't take much python coding to get from there to a working
package: package:

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

@ -9,7 +9,7 @@ Download
Getting spack is easy. You can clone it from the `github repository Getting spack is easy. You can clone it from the `github repository
<https://github.com/llnl/spack>`_ using this command: <https://github.com/llnl/spack>`_ using this command:
.. code-block:: sh .. code-block:: console
$ git clone https://github.com/llnl/spack.git $ git clone https://github.com/llnl/spack.git
@ -18,7 +18,7 @@ full path to this directory is in the ``SPACK_ROOT`` environment
variable. Add ``$SPACK_ROOT/bin`` to your path and you're ready to variable. Add ``$SPACK_ROOT/bin`` to your path and you're ready to
go: go:
.. code-block:: sh .. code-block:: console
$ export PATH=$SPACK_ROOT/bin:$PATH $ export PATH=$SPACK_ROOT/bin:$PATH
$ spack install libelf $ spack install libelf
@ -26,9 +26,10 @@ go:
For a richer experience, use Spack's `shell support For a richer experience, use Spack's `shell support
<http://software.llnl.gov/spack/basic_usage.html#environment-modules>`_: <http://software.llnl.gov/spack/basic_usage.html#environment-modules>`_:
.. code-block:: sh .. code-block:: console
# For bash users # For bash users
$ export SPACK_ROOT=/path/to/spack
$ . $SPACK_ROOT/share/spack/setup-env.sh $ . $SPACK_ROOT/share/spack/setup-env.sh
# For tcsh or csh users (note you must set SPACK_ROOT) # For tcsh or csh users (note you must set SPACK_ROOT)
@ -48,7 +49,7 @@ You may want to run it out of a prefix other than the git repository
you cloned. The ``spack bootstrap`` command provides this you cloned. The ``spack bootstrap`` command provides this
functionality. To install spack in a new directory, simply type: functionality. To install spack in a new directory, simply type:
.. code-block:: sh .. code-block:: console
$ spack bootstrap /my/favorite/prefix $ spack bootstrap /my/favorite/prefix

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

@ -28,7 +28,7 @@ Get spack from the `github repository
<https://github.com/llnl/spack>`_ and install your first <https://github.com/llnl/spack>`_ and install your first
package: package:
.. code-block:: sh .. code-block:: console
$ git clone https://github.com/llnl/spack.git $ git clone https://github.com/llnl/spack.git
$ cd spack/bin $ cd spack/bin

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

@ -11,7 +11,9 @@ mirror is a URL that points to a directory, either on the local
filesystem or on some server, containing tarballs for all of Spack's filesystem or on some server, containing tarballs for all of Spack's
packages. packages.
Here's an example of a mirror's directory structure:: Here's an example of a mirror's directory structure:
.. code-block:: none
mirror/ mirror/
cmake/ cmake/
@ -57,21 +59,9 @@ contains tarballs for each package, named after each package.
---------------- ----------------
Mirrors are managed with the ``spack mirror`` command. The help for Mirrors are managed with the ``spack mirror`` command. The help for
``spack mirror`` looks like this:: ``spack mirror`` looks like this:
$ spack mirror -h .. command-output:: spack help mirror
usage: spack mirror [-h] SUBCOMMAND ...
positional arguments:
SUBCOMMAND
create Create a directory to be used as a spack mirror, and fill
it with package archives.
add Add a mirror to Spack.
remove Remove a mirror by name.
list Print out available mirrors to the console.
optional arguments:
-h, --help show this help message and exit
The ``create`` command actually builds a mirror by fetching all of its The ``create`` command actually builds a mirror by fetching all of its
packages from the internet and checksumming them. packages from the internet and checksumming them.
@ -92,7 +82,7 @@ The command will iterate through all of Spack's packages and download
the safe ones into a directory structure like the one above. Here is the safe ones into a directory structure like the one above. Here is
what it looks like: what it looks like:
.. code-block:: bash .. code-block:: console
$ spack mirror create libelf libdwarf $ spack mirror create libelf libdwarf
==> Created new mirror in spack-mirror-2014-06-24 ==> Created new mirror in spack-mirror-2014-06-24
@ -134,7 +124,9 @@ Normally, ``spack mirror create`` downloads all the archives it has
checksums for. If you want to only create a mirror for a subset of checksums for. If you want to only create a mirror for a subset of
packages, you can do that by supplying a list of package specs on the packages, you can do that by supplying a list of package specs on the
command line after ``spack mirror create``. For example, this command line after ``spack mirror create``. For example, this
command:: command:
.. code-block:: console
$ spack mirror create libelf@0.8.12: boost@1.44: $ spack mirror create libelf@0.8.12: boost@1.44:
@ -146,7 +138,9 @@ Mirror files
^^^^^^^^^^^^ ^^^^^^^^^^^^
If you have a *very* large number of packages you want to mirror, you If you have a *very* large number of packages you want to mirror, you
can supply a file with specs in it, one per line:: can supply a file with specs in it, one per line:
.. code-block:: console
$ cat specs.txt $ cat specs.txt
libdwarf libdwarf
@ -168,7 +162,9 @@ your site.
Once you have a mirror, you need to let spack know about it. This is Once you have a mirror, you need to let spack know about it. This is
relatively simple. First, figure out the URL for the mirror. If it's relatively simple. First, figure out the URL for the mirror. If it's
a file, you can use a file URL like this one:: a file, you can use a file URL like this one:
.. code-block:: none
file:///Users/gamblin2/spack-mirror-2014-06-24 file:///Users/gamblin2/spack-mirror-2014-06-24
@ -180,7 +176,7 @@ web server, you could use a URL like this one:
Spack will use the URL as the root for all of the packages it fetches. Spack will use the URL as the root for all of the packages it fetches.
You can tell your Spack installation to use that mirror like this: You can tell your Spack installation to use that mirror like this:
.. code-block:: bash .. code-block:: console
$ spack mirror add local_filesystem file:///Users/gamblin2/spack-mirror-2014-06-24 $ spack mirror add local_filesystem file:///Users/gamblin2/spack-mirror-2014-06-24
@ -192,7 +188,9 @@ Each mirror has a name so that you can refer to it again later.
``spack mirror list`` ``spack mirror list``
--------------------- ---------------------
To see all the mirrors Spack knows about, run ``spack mirror list``:: To see all the mirrors Spack knows about, run ``spack mirror list``:
.. code-block:: console
$ spack mirror list $ spack mirror list
local_filesystem file:///Users/gamblin2/spack-mirror-2014-06-24 local_filesystem file:///Users/gamblin2/spack-mirror-2014-06-24
@ -203,7 +201,9 @@ To see all the mirrors Spack knows about, run ``spack mirror list``::
``spack mirror remove`` ``spack mirror remove``
----------------------- -----------------------
To remove a mirror by name:: To remove a mirror by name, run:
.. code-block:: console
$ spack mirror remove local_filesystem $ spack mirror remove local_filesystem
$ spack mirror list $ spack mirror list
@ -213,7 +213,9 @@ To remove a mirror by name::
Mirror precedence Mirror precedence
----------------- -----------------
Adding a mirror really adds a line in ``~/.spack/mirrors.yaml``:: Adding a mirror really adds a line in ``~/.spack/mirrors.yaml``:
.. code-block:: yaml
mirrors: mirrors:
local_filesystem: file:///Users/gamblin2/spack-mirror-2014-06-24 local_filesystem: file:///Users/gamblin2/spack-mirror-2014-06-24

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

File diff suppressed because it is too large Load Diff