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

Fix #1604 and fix #1605, title underline problems

Browse Source
This commit is contained in:
Adam J. Stewart 2016-08-23 17:03:29 -05:00
parent c36f13e44d
commit 2326355497
8 changed files with 411 additions and 277 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,13 +1,14 @@
.. _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
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 maintian this colorization. Eg:: Spack to maintain this colorization. E.g.::
spack find | less -R spack find | less -R
@ -16,8 +17,9 @@ It is recommend that the following be put in your ``.bashrc`` file::
alias less='less -R' alias less='less -R'
--------------------------
Listing available packages Listing available packages
------------------------------ --------------------------
To install software with Spack, you need to know what software is 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
@ -25,8 +27,9 @@ available. You can see a list of available package names at the
.. _spack-list: .. _spack-list:
^^^^^^^^^^^^^^
``spack list`` ``spack list``
~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^
The ``spack list`` command prints out a list of all of the packages The ``spack list`` command prints out a list of all of the packages
Spack can install: Spack can install:
@ -59,8 +62,9 @@ All packages whose names contain documentation case insensitive:
.. _spack-info: .. _spack-info:
^^^^^^^^^^^^^^
``spack info`` ``spack info``
~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^
To get more information on a particular package from `spack list`, use To get more information on a particular package from `spack list`, use
`spack info`. Just supply the name of a package: `spack info`. Just supply the name of a package:
@ -77,8 +81,9 @@ viruses.
.. _spack-versions: .. _spack-versions:
^^^^^^^^^^^^^^^^^^
``spack versions`` ``spack versions``
~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^
To see *more* available versions of a package, run ``spack versions``. To see *more* available versions of a package, run ``spack versions``.
For example: For example:
@ -95,14 +100,15 @@ by scraping it directly from package web pages. Depending on the
package and how its releases are organized, Spack may or may not be package and how its releases are organized, Spack may or may not be
able to find remote versions. able to find remote versions.
---------------------------
Installing and uninstalling Installing and uninstalling
------------------------------ ---------------------------
.. _spack-install: .. _spack-install:
^^^^^^^^^^^^^^^^^
``spack install`` ``spack install``
~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^
``spack install`` will install any package shown by ``spack list``. ``spack install`` will install any package shown by ``spack list``.
For example, To install the latest version of the ``mpileaks`` For example, To install the latest version of the ``mpileaks``
@ -142,8 +148,9 @@ that the packages is installed:
The last line, with the ``[+]``, indicates where the package is The last line, with the ``[+]``, indicates where the package is
installed. installed.
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Building a specific version 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:
@ -172,8 +179,9 @@ customize an installation in :ref:`sec-specs`.
.. _spack-uninstall: .. _spack-uninstall:
^^^^^^^^^^^^^^^^^^^
``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 the user for
confirmation, and in case will completely remove the directory in which the package was installed. confirmation, and in case will completely remove the directory in which the package was installed.
@ -216,17 +224,18 @@ You may force uninstall a package with the `--force` option
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 remove dependent
packages *before* removing their dependencies or use the `--dependents` option. 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 installed?
.. _spack-find: .. _spack-find:
^^^^^^^^^^^^^^
``spack find`` ``spack find``
~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^
``spack find`` shows the *specs* of installed packages. A spec is ``spack find`` shows the *specs* of installed packages. A spec is
like a name, but it has a version, compiler, architecture, and build like a name, but it has a version, compiler, architecture, and build
@ -367,11 +376,11 @@ 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`.
.. _compiler-config: .. _compiler-config:
----------------------
Compiler configuration 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
@ -380,8 +389,9 @@ your path.
.. _spack-compilers: .. _spack-compilers:
^^^^^^^^^^^^^^^^^^^
``spack compilers`` ``spack compilers``
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^
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``::
@ -408,15 +418,17 @@ how this is done is in :ref:`sec-specs`.
.. _spack-compiler-add: .. _spack-compiler-add:
^^^^^^^^^^^^^^^^^^^^^^
``spack compiler add`` ``spack compiler add``
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^
An alias for ``spack compiler find``. An alias for ``spack compiler find``.
.. _spack-compiler-find: .. _spack-compiler-find:
^^^^^^^^^^^^^^^^^^^^^^^
``spack compiler find`` ``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
@ -441,8 +453,9 @@ This loads the environment module for gcc-4.9.0 to add it to
.. _spack-compiler-info: .. _spack-compiler-info:
^^^^^^^^^^^^^^^^^^^^^^^
``spack compiler info`` ``spack compiler info``
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^
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::
@ -459,9 +472,9 @@ 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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Manual compiler configuration Manual compiler configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If auto-detection fails, you can manually configure a compiler by 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
@ -518,8 +531,9 @@ following section.
.. _sec-specs: .. _sec-specs:
--------------------
Specs & dependencies Specs & dependencies
------------------------- --------------------
We know that ``spack install``, ``spack uninstall``, and other We know that ``spack install``, ``spack uninstall``, and other
commands take a package name with an optional version specifier. In commands take a package name with an optional version specifier. In
@ -609,7 +623,6 @@ some *other* version of ``mpich``. In general, such a configuration
would likely behave unexpectedly at runtime, and Spack enforces this would likely behave unexpectedly at runtime, and Spack enforces this
to ensure a consistent runtime environment. to ensure a consistent runtime environment.
The point of specs is to abstract this full DAG from Spack users. If The point of specs is to abstract this full DAG from Spack users. If
a user does not care about the DAG at all, she can refer to mpileaks a user does not care about the DAG at all, she can refer to mpileaks
by simply writing ``mpileaks``. If she knows that ``mpileaks`` by simply writing ``mpileaks``. If she knows that ``mpileaks``
@ -646,8 +659,9 @@ could depend on ``mpich@1.2:`` if it can only build with version
Below are more details about the specifiers that you can add to specs. Below are more details about the specifiers that you can add to specs.
^^^^^^^^^^^^^^^^^
Version specifier Version specifier
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^
A version specifier comes somewhere after a package name and starts A version specifier comes somewhere after a package name and starts
with ``@``. It can be a single version, e.g. ``@1.0``, ``@3``, or with ``@``. It can be a single version, e.g. ``@1.0``, ``@3``, or
@ -669,9 +683,9 @@ policies set for the particular Spack installation.
Details about how versions are compared and how Spack determines if Details about how versions are compared and how Spack determines if
one version is less than another are discussed in the developer guide. one version is less than another are discussed in the developer guide.
^^^^^^^^^^^^^^^^^^
Compiler specifier Compiler specifier
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^
A compiler specifier comes somewhere after a package name and starts A compiler specifier comes somewhere after a package name and starts
with ``%``. It tells Spack what compiler(s) a particular package with ``%``. It tells Spack what compiler(s) a particular package
@ -688,9 +702,9 @@ name or compiler specifier to their left in the spec.
If the compiler spec is omitted, Spack will choose a default compiler If the compiler spec is omitted, Spack will choose a default compiler
based on site policies. based on site policies.
^^^^^^^^
Variants Variants
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^
Variants are named options associated with a particular package. They are Variants are named options associated with a particular package. They are
optional, as each package must provide default values for each variant it optional, as each package must provide default values for each variant it
@ -742,9 +756,9 @@ variants using the backwards compatibility syntax and uses only ``~``
for disabled boolean variants. We allow ``-`` and spaces on the command for disabled boolean variants. We allow ``-`` and spaces on the command
line is provided for convenience and legibility. line is provided for convenience and legibility.
^^^^^^^^^^^^^^
Compiler Flags Compiler Flags
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^
Compiler flags are specified using the same syntax as non-boolean variants, Compiler flags are specified using the same syntax as non-boolean variants,
but fulfill a different purpose. While the function of a variant is set by but fulfill a different purpose. While the function of a variant is set by
@ -764,9 +778,9 @@ 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
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^
The architecture can be specified by using the reserved 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
@ -781,11 +795,11 @@ 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, check here :ref:`cray-support`
.. _sec-virtual-dependencies: .. _sec-virtual-dependencies:
--------------------
Virtual dependencies Virtual dependencies
------------------------- --------------------
The dependence graph for ``mpileaks`` we saw above wasn't *quite* The dependence graph for ``mpileaks`` we saw above wasn't *quite*
accurate. ``mpileaks`` uses MPI, which is an interface that has many accurate. ``mpileaks`` uses MPI, which is an interface that has many
@ -828,9 +842,9 @@ version of a virtual package, e.g. if an application needs MPI-2
functions, it can depend on ``mpi@2:`` to indicate that it needs some functions, it can depend on ``mpi@2:`` to indicate that it needs some
implementation that provides MPI-2 functions. implementation that provides MPI-2 functions.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Constraining virtual packages 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
@ -857,8 +871,9 @@ any MPI implementation will do. If another package depends on
error. Likewise, if you try to plug in some package that doesn't error. Likewise, if you try to plug in some package that doesn't
provide MPI, Spack will raise an error. provide MPI, Spack will raise an error.
^^^^^^^^^^^^^^^^^^^^^^^^
Specifying Specs by Hash Specifying Specs by Hash
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^
Complicated specs can become cumbersome to enter on the command line, Complicated specs can become cumbersome to enter on the command line,
especially when many of the qualifications are necessary to especially when many of the qualifications are necessary to
@ -876,8 +891,9 @@ Note that this will not work to reinstall a depencency uninstalled by
.. _spack-providers: .. _spack-providers:
^^^^^^^^^^^^^^^^^^^
``spack providers`` ``spack providers``
~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^
You can see what packages provide a particular virtual package using You can see what packages provide a particular virtual package using
``spack providers``. If you wanted to see what packages provide ``spack providers``. If you wanted to see what packages provide
@ -895,6 +911,7 @@ versions are now filtered out.
.. _shell-support: .. _shell-support:
-------------------------------
Integration with module systems Integration with module systems
------------------------------- -------------------------------
@ -910,10 +927,9 @@ Spack provides some integration with
and `Dotkit <https://computing.llnl.gov/?set=jobs&page=dotkit>`_ to make and `Dotkit <https://computing.llnl.gov/?set=jobs&page=dotkit>`_ to make
it easier to use the packages it installed. it easier to use the packages it installed.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Installing Environment Modules Installing Environment Modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to use Spack's generated environment modules, you must have In order to use Spack's generated environment modules, you must have
installed the *Environment Modules* package. On many Linux installed the *Environment Modules* package. On many Linux
@ -931,7 +947,6 @@ Environment Modules, you can get it with Spack:
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):
@ -944,11 +959,12 @@ If you use a Unix shell other than ``bash``, modify the commands above
accordingly and source the appropriate file in accordingly and source the appropriate file in
``${MODULES_HOME}/Modules/init/``. ``${MODULES_HOME}/Modules/init/``.
.. TODO : Add a similar section on how to install dotkit ? .. TODO : Add a similar section on how to install dotkit ?
^^^^^^^^^^^^^^^^^^^^^^^^
Spack and module systems Spack and module systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^
You can enable shell support by sourcing some files in the You can enable shell support by sourcing some files in the
``/share/spack`` directory. ``/share/spack`` directory.
@ -986,9 +1002,9 @@ 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
support <shell-support_>`_. support <shell-support_>`_.
^^^^^^^^^^^^^^^^^^^^^^^
Using Modules & Dotkits Using Modules & Dotkits
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^
If you have shell support enabled you should be able to run either If you have shell support enabled you should be able to run either
``module avail`` or ``use -l spack`` to see what modules/dotkits have ``module avail`` or ``use -l spack`` to see what modules/dotkits have
@ -1093,8 +1109,9 @@ a package, you can type unload or unuse similarly:
only available if you have enabled Spack's shell support *and* you only available if you have enabled Spack's shell support *and* you
have dotkit or modules installed on your machine. have dotkit or modules installed on your machine.
^^^^^^^^^^^^^^^^^^^^^^
Ambiguous module names 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:
@ -1118,8 +1135,9 @@ used ``gcc``. You could therefore just type:
To identify just the one built with the Intel compiler. To identify just the one built with the Intel compiler.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Module files generation and customization Module files generation and customization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Environment Modules and Dotkit files are generated when packages are installed, Environment Modules and Dotkit files are generated when packages are installed,
and are placed in the following directories under the Spack root: and are placed in the following directories under the Spack root:
@ -1134,8 +1152,10 @@ 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`` 1. overriding part of the ``spack.Package`` API within a ``package.py``
2. writing dedicated configuration files 2. writing dedicated configuration files
^^^^^^^^^^^^^^^^^^^^^^^^
Override ``Package`` API Override ``Package`` API
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
There are currently two methods in ``spack.Package`` that may affect the content There are currently two methods in ``spack.Package`` that may affect the content
of module files: of module files:
@ -1145,9 +1165,9 @@ of module files:
"""Set up the compile and runtime environments for a package.""" """Set up the compile and runtime environments for a package."""
pass pass
"""""""""""""""""
Recursive Modules Recursive Modules
`````````````````` """""""""""""""""
In some cases, it is desirable to load not just a module, but also all In some cases, it is desirable to load not just a module, but also all
the modules it depends on. This is not required for most modules the modules it depends on. This is not required for most modules
@ -1165,8 +1185,9 @@ Modules may be loaded recursively with the ``load`` command's
More than one spec may be placed on the command line here. More than one spec may be placed on the command line here.
"""""""""""""""""""""""""""""""""
Module Commands for Shell Scripts Module Commands for Shell Scripts
`````````````````````````````````` """""""""""""""""""""""""""""""""
Although Spack is flexible, the ``module`` command is much faster. Although Spack is flexible, the ``module`` command is much faster.
This could become an issue when emitting a series of ``spack load`` This could become an issue when emitting a series of ``spack load``
@ -1215,9 +1236,9 @@ This script may be directly executed in bash via
source <( spack module find tcl --dependencies --shell py-numpy git ) source <( spack module find tcl --dependencies --shell py-numpy git )
^^^^^^^^^^^^^^^^^^^^^^^^^
Regenerating Module files Regenerating Module files
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python .. code-block:: python
@ -1230,6 +1251,7 @@ module file content for the package you are currently writing, the second
allows for modifications to your dependees module file. In both cases one allows for modifications to your dependees module file. In both cases one
needs to fill ``run_env`` with the desired list of environment modifications. needs to fill ``run_env`` with the desired list of environment modifications.
""""""""""""""""""""""""""""""""""""""""""""""""
Example : ``builtin/packages/python/package.py`` Example : ``builtin/packages/python/package.py``
"""""""""""""""""""""""""""""""""""""""""""""""" """"""""""""""""""""""""""""""""""""""""""""""""
@ -1246,6 +1268,7 @@ overrides ``setup_dependent_environment`` in the following way:
to insert the appropriate ``PYTHONPATH`` modifications in the module to insert the appropriate ``PYTHONPATH`` modifications in the module
files of python packages. files of python packages.
^^^^^^^^^^^^^^^^^^^
Configuration files Configuration files
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
@ -1275,8 +1298,10 @@ For each module system that can be enabled a finer configuration is possible:
The structure under the ``tcl`` and ``dotkit`` keys is almost equal, and will The structure under the ``tcl`` and ``dotkit`` keys is almost equal, and will
be showcased in the following by some examples. be showcased in the following by some examples.
"""""""""""""""""""""""""""""""""""""""
Select module files by spec constraints Select module files by spec constraints
""""""""""""""""""""""""""""""""""""""" """""""""""""""""""""""""""""""""""""""
Using spec syntax it's possible to have different customizations for different Using spec syntax it's possible to have different customizations for different
groups of module files. groups of module files.
@ -1316,6 +1341,7 @@ what will happen is that:
first, no matter where they appear in the configuration file. All the other first, no matter where they appear in the configuration file. All the other
spec constraints are instead evaluated top to bottom. spec constraints are instead evaluated top to bottom.
""""""""""""""""""""""""""""""""""""""""
Filter modifications out of module files Filter modifications out of module files
"""""""""""""""""""""""""""""""""""""""" """"""""""""""""""""""""""""""""""""""""
@ -1335,6 +1361,7 @@ 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
contain those modifications. contain those modifications.
"""""""""""""""""""""
Autoload dependencies Autoload dependencies
""""""""""""""""""""" """""""""""""""""""""
@ -1357,6 +1384,7 @@ dependencies.
``prerequisites`` that accepts the same values and will add ``prereq`` ``prerequisites`` that accepts the same values and will add ``prereq``
statements instead of automatically loading other modules. statements instead of automatically loading other modules.
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Blacklist or whitelist the generation of specific module files Blacklist or whitelist the generation of specific module files
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@ -1375,6 +1403,7 @@ A configuration file like:
will skip module file generation for anything that satisfies ``%gcc@4.4.7``, will skip module file generation for anything that satisfies ``%gcc@4.4.7``,
with the exception of specs that satisfy ``gcc`` or ``llvm``. with the exception of specs that satisfy ``gcc`` or ``llvm``.
""""""""""""""""""""""""""""""""""""""""""""""""
Customize the naming scheme and insert conflicts Customize the naming scheme and insert conflicts
"""""""""""""""""""""""""""""""""""""""""""""""" """"""""""""""""""""""""""""""""""""""""""""""""
@ -1400,6 +1429,7 @@ load two or more versions of the same software at the same time.
.. note:: .. note::
The ``conflict`` option is ``tcl`` specific The ``conflict`` option is ``tcl`` specific
^^^^^^^^^^^^^^^^^^^^^^^^^
Regenerating module files Regenerating module files
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
@ -1410,6 +1440,7 @@ new features.
.. _spack-module: .. _spack-module:
""""""""""""""""""""""""
``spack module refresh`` ``spack module refresh``
"""""""""""""""""""""""" """"""""""""""""""""""""
@ -1426,8 +1457,9 @@ regenerate all module and dotkit files from scratch:
.. _extensions: .. _extensions:
----------------
Filesystem Views Filesystem Views
------------------------------- ----------------
.. Maybe this is not the right location for this documentation. .. Maybe this is not the right location for this documentation.
@ -1469,8 +1501,9 @@ Views can be used for a variety of purposes including:
- 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
~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^
A filesystem view is created and packages are linked in by the ``spack A filesystem view is created and packages are linked in by the ``spack
view`` command's ``symlink`` and ``hardlink`` sub-commands. The view`` command's ``symlink`` and ``hardlink`` sub-commands. The
@ -1483,7 +1516,6 @@ files in the ``cmake`` package while retaining its dependencies.
.. code-block:: sh .. code-block:: sh
$ spack view -v symlink myview cmake@3.5.2 $ spack view -v symlink myview cmake@3.5.2
==> Linking package: "ncurses" ==> Linking package: "ncurses"
==> Linking package: "zlib" ==> Linking package: "zlib"
@ -1504,9 +1536,9 @@ files in the ``cmake`` package while retaining its dependencies.
captoinfo c_rehash infotocap openssl tabs toe tset captoinfo c_rehash infotocap openssl tabs toe tset
clear infocmp ncurses6-config reset tic tput clear infocmp ncurses6-config reset tic tput
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Limitations of Filesystem Views Limitations of Filesystem Views
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This section describes some limitations that should be considered in This section describes some limitations that should be considered in
using filesystems views. using filesystems views.
@ -1536,12 +1568,9 @@ 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 & Python support Extensions & Python support
------------------------------------ ---------------------------
Spack's installation model assumes that each package will live in its Spack's installation model assumes that each package will live in its
own install prefix. However, certain packages are typically installed own install prefix. However, certain packages are typically installed
@ -1563,8 +1592,9 @@ an *extension*. Suppose you have Python installed like so:
.. _spack-extensions: .. _spack-extensions:
^^^^^^^^^^^^^^^^^^^^
``spack extensions`` ``spack extensions``
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^
You can find extensions for your Python installation like this: You can find extensions for your Python installation like this:
@ -1618,8 +1648,9 @@ directly when you run ``python``:
ImportError: No module named numpy ImportError: No module named numpy
>>> >>>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Extensions & Environment Modules Extensions & Environment Modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are two ways to get ``numpy`` working in Python. The first is There are two ways to get ``numpy`` working in Python. The first is
to use :ref:`shell-support`. You can simply ``use`` or ``load`` the to use :ref:`shell-support`. You can simply ``use`` or ``load`` the
@ -1643,9 +1674,9 @@ or, for dotkit:
Now ``import numpy`` will succeed for as long as you keep your current Now ``import numpy`` will succeed for as long as you keep your current
session open. session open.
^^^^^^^^^^^^^^^^^^^^^
Activating Extensions Activating Extensions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^
It is often desirable to have certain packages *always* available as It is often desirable to have certain packages *always* available as
part of a Python installation. Spack offers a more permanent solution part of a Python installation. Spack offers a more permanent solution
@ -1655,8 +1686,9 @@ installation:
.. _spack-activate: .. _spack-activate:
^^^^^^^^^^^^^^^^^^
``spack activate`` ``spack activate``
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
.. code-block:: sh .. code-block:: sh
@ -1700,7 +1732,6 @@ packages listed as activated:
-- linux-debian7-x86_64 / gcc@4.4.7 -------------------------------- -- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
py-nose@1.3.4 py-numpy@1.9.1 py-setuptools@11.3.1 py-nose@1.3.4 py-numpy@1.9.1 py-setuptools@11.3.1
Now, when a user runs python, ``numpy`` will be available for import Now, when a user runs python, ``numpy`` will be available for import
*without* the user having to explicitly loaded. ``python@2.7.8`` now *without* the user having to explicitly loaded. ``python@2.7.8`` now
acts like a system Python installation with ``numpy`` installed inside acts like a system Python installation with ``numpy`` installed inside
@ -1718,8 +1749,10 @@ 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 -f``
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
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``:
@ -1730,8 +1763,9 @@ dependencies, you can use ``spack activate -f``:
.. _spack-deactivate: .. _spack-deactivate:
^^^^^^^^^^^^^^^^^^^^
``spack deactivate`` ``spack deactivate``
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
We've seen how activating an extension can be used to set up a default We've seen how activating an extension can be used to set up a default
version of a Python module. Obviously, you may want to change that at version of a Python module. Obviously, you may want to change that at
@ -1751,8 +1785,9 @@ several variants:
spack deactivate -a python spack deactivate -a python
-----------------------
Filesystem requirements Filesystem requirements
-------------------------- -----------------------
Spack currently needs to be run from a filesystem that supports Spack currently needs to be run from a filesystem that supports
``flock`` locking semantics. Nearly all local filesystems and recent ``flock`` locking semantics. Nearly all local filesystems and recent
@ -1797,11 +1832,16 @@ 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
----------------------------- -------------
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.
@ -1835,10 +1875,9 @@ And the front-end operating system is:
spack install zlib os=SuSE11 spack install zlib os=SuSE11
^^^^^^^^^^^^^^^^^^^^^^^
Cray compiler detection Cray compiler detection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^
Spack can detect compilers using two methods. For the front-end, we treat Spack can detect compilers using two methods. For the front-end, we treat
everything the same. The difference lies in back-end compiler detection. everything the same. The difference lies in back-end compiler detection.
@ -1880,8 +1919,9 @@ 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.
@ -1934,16 +1974,17 @@ if we want to build with intel compilers, use version 16.0.0.109. We add a spec
for each compiler type for each cray modules. This ensures that for each for each compiler type for each cray modules. This ensures that for each
compiler on our system we can use that external module. compiler on our system we can use that external module.
For more on external packages check out the section :ref:`sec-external_packages`. For more on external packages check out the section :ref:`sec-external_packages`.
------------
Getting Help Getting Help
----------------------- ------------
.. _spack-help: .. _spack-help:
^^^^^^^^^^^^^^
``spack help`` ``spack 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:

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

@ -1,12 +1,14 @@
.. _configuration: .. _configuration:
=============
Configuration Configuration
=================================== =============
.. _temp-space: .. _temp-space:
---------------
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
@ -55,8 +57,10 @@ directory is.
.. _sec-external_packages: .. _sec-external_packages:
-----------------
External Packages External Packages
---------------------------- -----------------
Spack can be configured to use externally-installed Spack can be configured to use externally-installed
packages rather than building its own packages. This may be desirable packages rather than building its own packages. This may be desirable
if machines ship with system packages, such as a customized MPI if machines ship with system packages, such as a customized MPI
@ -126,9 +130,9 @@ The ``buildable`` does not need to be paired with external packages.
It could also be used alone to forbid packages that may be It could also be used alone to forbid packages that may be
buggy or otherwise undesirable. buggy or otherwise undesirable.
--------------------------
Concretization Preferences Concretization Preferences
-------------------------------- --------------------------
Spack can be configured to prefer certain compilers, package Spack can be configured to prefer certain compilers, package
versions, depends_on, and variants during concretization. versions, depends_on, and variants during concretization.
@ -136,7 +140,6 @@ The preferred configuration can be controlled via the
``~/.spack/packages.yaml`` file for user configuations, or the ``~/.spack/packages.yaml`` file for user configuations, or the
``etc/spack/packages.yaml`` site configuration. ``etc/spack/packages.yaml`` site configuration.
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:: sh
@ -152,7 +155,6 @@ Here's an example packages.yaml file that sets preferred packages:
providers: providers:
mpi: [mvapich, mpich, openmpi] mpi: [mvapich, mpich, openmpi]
At a high level, this example is specifying how packages should be At a high level, this example is specifying how packages should be
concretized. The opencv package should prefer using gcc 4.9 and concretized. The opencv package should prefer using gcc 4.9 and
be built with debug options. The gperftools package should prefer version be built with debug options. The gperftools package should prefer version
@ -185,9 +187,9 @@ concretization rules. A provider lists a value that packages may
``depend_on`` (e.g, mpi) and a list of rules for fulfilling that ``depend_on`` (e.g, mpi) and a list of rules for fulfilling that
dependency. dependency.
---------
Profiling 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,
@ -195,8 +197,9 @@ supply ``-p`` to Spack on the command line, before any subcommands.
.. _spack-p: .. _spack-p:
^^^^^^^^^^^^
``spack -p`` ``spack -p``
~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^
``spack -p`` output looks like this: ``spack -p`` output looks like this:

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

@ -1,7 +1,8 @@
.. _developer_guide: .. _developer_guide:
===============
Developer Guide Developer Guide
===================== ===============
This guide is intended for people who want to work on Spack itself. This guide is intended for people who want to work on Spack itself.
If you just want to develop packages, see the :ref:`packaging-guide`. If you just want to develop packages, see the :ref:`packaging-guide`.
@ -11,8 +12,9 @@ It is assumed that you've read the :ref:`basic-usage` and
concepts discussed there. If you're not, we recommend reading those concepts discussed there. If you're not, we recommend reading those
first. first.
--------
Overview Overview
----------------------- --------
Spack is designed with three separate roles in mind: Spack is designed with three separate roles in mind:
@ -63,9 +65,9 @@ building the software off to the package object. The rest of this
document describes all the pieces that come together to make that document describes all the pieces that come together to make that
happen. happen.
-------------------
Directory Structure 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::
@ -123,15 +125,16 @@ 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
box: clone it and add ``bin`` to your PATH and you're ready to go. box: clone it and add ``bin`` to your PATH and you're ready to go.
--------------
Code Structure Code Structure
------------------------- --------------
This section gives an overview of the various Python modules in Spack, This section gives an overview of the various Python modules in Spack,
grouped by functionality. grouped by functionality.
^^^^^^^^^^^^^^^^^^^^^^^
Package-related modules Package-related modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^
:mod:`spack.package` :mod:`spack.package`
Contains the :class:`Package <spack.package.Package>` class, which Contains the :class:`Package <spack.package.Package>` class, which
@ -158,9 +161,9 @@ Package-related modules
decorator, which allows :ref:`multimethods <multimethods>` in decorator, which allows :ref:`multimethods <multimethods>` in
packages. packages.
^^^^^^^^^^^^^^^^^^^^
Spec-related modules Spec-related modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^
:mod:`spack.spec` :mod:`spack.spec`
Contains :class:`Spec <spack.spec.Spec>` and :class:`SpecParser Contains :class:`Spec <spack.spec.Spec>` and :class:`SpecParser
@ -208,9 +211,9 @@ Spec-related modules
Not yet implemented. Should eventually have architecture Not yet implemented. Should eventually have architecture
descriptions for cross-compiling. descriptions for cross-compiling.
^^^^^^^^^^^^^^^^^
Build environment Build environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^
:mod:`spack.stage` :mod:`spack.stage`
Handles creating temporary directories for builds. Handles creating temporary directories for builds.
@ -224,15 +227,17 @@ Build environment
Create more implementations of this to change the hierarchy and Create more implementations of this to change the hierarchy and
naming scheme in ``$spack_prefix/opt`` naming scheme in ``$spack_prefix/opt``
^^^^^^^^^^^^^^^^^
Spack Subcommands Spack Subcommands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^
:mod:`spack.cmd` :mod:`spack.cmd`
Each module in this package implements a Spack subcommand. See Each module in this package implements a Spack subcommand. See
:ref:`writing commands <writing-commands>` for details. :ref:`writing commands <writing-commands>` for details.
^^^^^^^^^^
Unit tests Unit tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^
:mod:`spack.test` :mod:`spack.test`
Implements Spack's test suite. Add a module and put its name in Implements Spack's test suite. Add a module and put its name in
@ -242,8 +247,9 @@ Unit tests
This is a fake package hierarchy used to mock up packages for This is a fake package hierarchy used to mock up packages for
Spack's test suite. Spack's test suite.
^^^^^^^^^^^^^
Other Modules Other Modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^
:mod:`spack.globals` :mod:`spack.globals`
Includes global settings for Spack. the default policy classes for Includes global settings for Spack. the default policy classes for
@ -269,13 +275,13 @@ Other Modules
:class:`SpackError <spack.error.SpackError>`, the base class for :class:`SpackError <spack.error.SpackError>`, the base class for
Spack's exception hierarchy. Spack's exception hierarchy.
------------
Spec objects Spec objects
------------------------- ------------
---------------
Package objects Package objects
------------------------- ---------------
Most spack commands Most spack commands
look something like this: look something like this:
@ -286,34 +292,37 @@ look something like this:
#. Instantiate a package based on the spec, and #. Instantiate a package based on the spec, and
#. Call methods (e.g., ``install()``) on the package object. #. Call methods (e.g., ``install()``) on the package object.
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
------------------------- -------------
.. _writing-commands: .. _writing-commands:
----------------
Writing commands Writing commands
------------------------- ----------------
----------
Unit tests Unit tests
------------------------- ----------
------------
Unit testing Unit testing
------------------------- ------------
------------------
Developer commands Developer commands
------------------------- ------------------
^^^^^^^^^^^^^
``spack doc`` ``spack doc``
~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^
^^^^^^^^^^^^^^
``spack test`` ``spack test``
~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^

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

@ -1,13 +1,15 @@
================
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
from other `package managers from other `package managers
<http://en.wikipedia.org/wiki/Package_management_system>`_ and `port <http://en.wikipedia.org/wiki/Package_management_system>`_ and `port
systems <http://en.wikipedia.org/wiki/Ports_collection>`_. systems <http://en.wikipedia.org/wiki/Ports_collection>`_.
---------------------------
Simple package installation 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:
@ -16,8 +18,9 @@ the latest version of the ``mpileaks`` package and all of its dependencies:
$ spack install mpileaks $ spack install mpileaks
--------------------------------
Custom versions & configurations Custom versions & configurations
------------------------------------------- --------------------------------
Spack allows installation to be customized. Users can specify the 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
@ -47,9 +50,9 @@ Users can specify as many or few options as they care about. Spack
will fill in the unspecified values with sensible defaults. The two listed will fill in the unspecified values with sensible defaults. The two listed
syntaxes for variants are identical when the value is boolean. syntaxes for variants are identical when the value is boolean.
----------------------
Customize dependencies Customize dependencies
------------------------------------- ----------------------
Spack allows *dependencies* of a particular installation to be Spack allows *dependencies* of a particular installation to be
customized extensively. Suppose that ``mpileaks`` depends indirectly customized extensively. Suppose that ``mpileaks`` depends indirectly
@ -61,23 +64,25 @@ configurations for the dependencies:
# 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
------------------------
Non-destructive installs Non-destructive installs
------------------------------------- ------------------------
Spack installs every unique package/dependency configuration into its Spack installs every unique package/dependency configuration into its
own prefix, so new installs will not break existing ones. own prefix, so new installs will not break existing ones.
-------------------------------
Packages can peacefully coexist Packages can peacefully coexist
------------------------------------- -------------------------------
Spack avoids library misconfiguration by using ``RPATH`` to link Spack avoids library misconfiguration by using ``RPATH`` to link
dependencies. When a user links a library or runs a program, it is dependencies. When a user links a library or runs a program, it is
tied to the dependencies it was built with, so there is no need to tied to the dependencies it was built with, so there is no need to
manipulate ``LD_LIBRARY_PATH`` at runtime. manipulate ``LD_LIBRARY_PATH`` at runtime.
-------------------------
Creating packages is easy Creating packages is easy
------------------------------------- -------------------------
To create a new packages, all Spack needs is a URL for the source To create a new packages, all Spack needs is a URL for the source
archive. The ``spack create`` command will create a boilerplate archive. The ``spack create`` command will create a boilerplate

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

@ -1,8 +1,10 @@
===============
Getting Started Getting Started
==================== ===============
--------
Download 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:
@ -35,8 +37,9 @@ For a richer experience, use Spack's `shell support
This automatically adds Spack to your ``PATH``. This automatically adds Spack to your ``PATH``.
------------
Installation Installation
-------------------- ------------
You don't need to install Spack; it's ready to run as soon as you You don't need to install Spack; it's ready to run as soon as you
clone it from git. clone it from git.

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

@ -3,8 +3,9 @@
You can adapt this file completely to your liking, but it should at least You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive. contain the root `toctree` directive.
===================
Spack Documentation Spack Documentation
================================= ===================
Spack is a package management tool designed to support multiple Spack is a package management tool designed to support multiple
versions and configurations of software on a wide variety of platforms versions and configurations of software on a wide variety of platforms
@ -36,8 +37,9 @@ package:
If you're new to spack and want to start using it, see :doc:`getting_started`, If you're new to spack and want to start using it, see :doc:`getting_started`,
or refer to the full manual below. or refer to the full manual below.
-----------------
Table of Contents Table of Contents
--------------------- -----------------
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
@ -54,6 +56,7 @@ Table of Contents
package_list package_list
API Docs <spack> API Docs <spack>
==================
Indices and tables Indices and tables
================== ==================

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

@ -1,7 +1,8 @@
.. _mirrors: .. _mirrors:
=======
Mirrors Mirrors
============================ =======
Some sites may not have access to the internet for fetching packages. Some sites may not have access to the internet for fetching packages.
These sites will need a local repository of tarballs from which they These sites will need a local repository of tarballs from which they
@ -51,8 +52,9 @@ contains tarballs for each package, named after each package.
.. _spack-mirror: .. _spack-mirror:
----------------
``spack mirror`` ``spack mirror``
---------------------------- ----------------
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::
@ -79,8 +81,9 @@ control the URL(s) from which Spack downloads its packages.
.. _spack-mirror-create: .. _spack-mirror-create:
-----------------------
``spack mirror create`` ``spack mirror create``
---------------------------- -----------------------
You can create a mirror using the ``spack mirror create`` command, assuming You can create a mirror using the ``spack mirror create`` command, assuming
you're on a machine where you can access the internet. you're on a machine where you can access the internet.
@ -89,7 +92,6 @@ 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:: bash
$ spack mirror create libelf libdwarf $ spack mirror create libelf libdwarf
@ -124,8 +126,9 @@ what it looks like:
Once this is done, you can tar up the ``spack-mirror-2014-06-24`` directory and Once this is done, you can tar up the ``spack-mirror-2014-06-24`` directory and
copy it over to the machine you want it hosted on. copy it over to the machine you want it hosted on.
^^^^^^^^^^^^^^^^^^^
Custom package sets Custom package sets
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^
Normally, ``spack mirror create`` downloads all the archives it has 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
@ -138,8 +141,9 @@ command::
Will create a mirror for libelf versions greater than or equal to Will create a mirror for libelf versions greater than or equal to
0.8.12 and boost versions greater than or equal to 1.44. 0.8.12 and boost versions greater than or equal to 1.44.
^^^^^^^^^^^^
Mirror files 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::
@ -158,8 +162,9 @@ your site.
.. _spack-mirror-add: .. _spack-mirror-add:
--------------------
``spack mirror add`` ``spack mirror add``
---------------------------- --------------------
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
@ -183,8 +188,9 @@ Each mirror has a name so that you can refer to it again later.
.. _spack-mirror-list: .. _spack-mirror-list:
---------------------
``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``::
@ -193,8 +199,9 @@ To see all the mirrors Spack knows about, run ``spack mirror list``::
.. _spack-mirror-remove: .. _spack-mirror-remove:
-----------------------
``spack mirror remove`` ``spack mirror remove``
---------------------------- -----------------------
To remove a mirror by name:: To remove a mirror by name::
@ -202,8 +209,9 @@ To remove a mirror by name::
$ spack mirror list $ spack mirror list
==> No mirrors configured. ==> No mirrors configured.
-----------------
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``::
@ -217,8 +225,9 @@ search the topmost mirror first and the bottom-most mirror last.
.. _caching: .. _caching:
-------------------
Local Default Cache Local Default Cache
---------------------------- -------------------
Spack caches resources that are downloaded as part of installs. The cache is Spack caches resources that are downloaded as part of installs. The cache is
a valid spack mirror: it uses the same directory structure and naming scheme a valid spack mirror: it uses the same directory structure and naming scheme

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

File diff suppressed because it is too large Load Diff