documentation updates

This commit is contained in:
Todd Gamblin 2015-04-14 15:11:01 -07:00
parent 203fd861aa
commit 8b14a46201
3 changed files with 57 additions and 47 deletions

View File

@ -3,18 +3,16 @@
Basic usage Basic usage
===================== =====================
Spack is implemented as a single command (``spack``) with many The ``spack`` command has many *subcommands*. You'll only need a
*subcommands*. Only a small subset of commands is needed for typical small subset of them for typical usage.
usage.
Listing available packages Listing available packages
------------------------------ ------------------------------
The first thing you likely want to do with spack is to install some To install software with Spack, you need to know what software is
software. Before that, you need to know what's available. You can available. You can see a list of available package names at the
see available package names either using the :ref:`package-list`, or :ref:`package-list` webpage, or using the ``spack list`` command.
using the commands below.
.. _spack-list: .. _spack-list:
@ -43,54 +41,55 @@ To get more information on a particular package from `spack list`, use
.. command-output:: spack info mpich .. command-output:: spack info mpich
Most of the information is self-explanatory. *Safe versions* are Most of the information is self-explanatory. The *safe versions* are
versions that Spack has a checksum for, and Spack will use the versions that Spack knows the checksum for, and it will use the
checksum to ensure they downloaded without any errors or malicious checksum to verify that these versions download without errors or
attacks. :ref:`Dependencies <sec-specs>` and :ref:`virtual viruses.
dependencies <sec-virtual-dependencies>`, are described in more detail
later. :ref:`Dependencies <sec-specs>` and :ref:`virtual dependencies
<sec-virtual-dependencies>` are described in more detail later.
.. _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:
.. command-output:: spack versions libelf .. command-output:: spack versions libelf
There are two sections in the output. *Safe versions* are ones that There are two sections in the output. *Safe versions* are versions
have already been checksummed. Spack goes a step further, though, and for which Spack has a checksum on file. It can verify that these
also shows you what versions are available out on the web---these are versions are downloaded correctly.
*remote versions*. Spack gets this information by scraping it
directly from web pages. Depending on the package, Spack may or may In many cases, Spack can also show you what versions are available out
not be able to find any remote versions. on the web---these are *remote versions*. Spack gets this information
by scraping it directly from package web pages. Depending on the
package and how its releases are organized, Spack may or may not be
able to find remote versions.
Installing and uninstalling Installing and uninstalling
------------------------------ ------------------------------
Now that you know how to list available packages and versions, you're
ready to start installing things.
.. _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``.
To install the latest version of a package, along with all of its For example, To install the latest version of the ``mpileaks``
dependencies, simply give it a package name: package, you might type this:
.. code-block:: sh .. code-block:: sh
$ spack install mpileaks $ spack install mpileaks
If `mpileaks` depends on other packages, Spack will install those If `mpileaks` depends on other packages, Spack will install the
first. It then fetches the tarball for ``mpileaks``, expands it, dependencies first. It then fetches the ``mpileaks`` tarball, expands
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_HOME/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:
@ -139,11 +138,11 @@ an installation. Spack is unique in that it can also configure the
configurations of the same version of a package, one built with boost configurations of the same version of a package, one built with boost
1.39.0, and the other version built with version 1.43.0, can coexist. 1.39.0, and the other version built with version 1.43.0, can coexist.
This can all be done on the command line using special syntax. Spack This can all be done on the command line using the *spec* syntax.
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 command lines above, both configuration a **spec**. In the commands above, ``mpileaks`` and
``mpileaks`` and ``mpileaks@3.0.4`` are specs. Specs are described in ``mpileaks@3.0.4``. We'll talk more about how you can use them to
detail in :ref:`sec-specs`. customize an installation in :ref:`sec-specs`.
.. _spack-uninstall: .. _spack-uninstall:

View File

@ -12,20 +12,30 @@ Getting spack is easy. You can clone it from the `github repository
$ git clone https://github.com/scalability-llnl/spack.git $ git clone https://github.com/scalability-llnl/spack.git
This will create a directory called ``spack``. We'll assume that the This will create a directory called ``spack``. We'll assume that the
full path to this directory is in some environment called full path to this directory is in the ``SPACK_ROOT`` environment
``SPACK_HOME``. Add ``$SPACK_HOME/bin`` to your path and you're ready variable. Add ``$SPACK_ROOT/bin`` to your path and you're ready to
to go: go:
.. code-block:: sh .. code-block:: sh
$ export PATH=spack/bin:$PATH $ export PATH=$SPACK_ROOT/bin:$PATH
$ spack install libelf $ spack install libelf
In general, most of your interactions with Spack will be through the For a richer experience, use Spack's `shell support
``spack`` command. <http://scalability-llnl.github.io/spack/basic_usage.html#environment-modules>`_:
.. code-block:: sh
Install # For bash users
$ . $SPACK_ROOT/share/spack/setup-env.sh
# For tcsh or csh users (note you must set SPACK_ROOT)
$ setenv SPACK_ROOT /path/to/spack
$ source $SPACK_ROOT/share/spack/setup-env.csh
This automatically adds Spack to your ``PATH``.
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
@ -39,6 +49,7 @@ functionality. To install spack in a new directory, simply type:
$ spack bootstrap /my/favorite/prefix $ spack bootstrap /my/favorite/prefix
This will install a new spack script in /my/favorite/prefix/bin, which This will install a new spack script in ``/my/favorite/prefix/bin``,
you can use just like you would the regular spack script. Each copy which you can use just like you would the regular spack script. Each
of spack installs packages into its own ``$PREFIX/opt`` directory. copy of spack installs packages into its own ``$PREFIX/opt``
directory.

View File

@ -18,8 +18,8 @@ configurations can coexist on the same system.
Most importantly, Spack is *simple*. It offers a simple *spec* syntax Most importantly, Spack is *simple*. It offers a simple *spec* syntax
so that users can specify versions and configuration options so that users can specify versions and configuration options
concisely. Spack is also simple for package authors: package files concisely. Spack is also simple for package authors: package files
are writtin in pure Python, and specs allow package authors to write a are writtin in pure Python, and specs allow package authors to
single build script for many different builds of the same package. maintain a single file for many different builds of the same package.
See the :doc:`features` for examples and highlights. See the :doc:`features` for examples and highlights.