summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTodd Gamblin <tgamblin@llnl.gov>2015-04-14 15:11:01 -0700
committerTodd Gamblin <tgamblin@llnl.gov>2015-04-14 15:11:01 -0700
commit8b14a4620161af275335d97e981d4edcbe48868c (patch)
tree0fb7483b7d457fa2d9b80c66d50a3291fd1335fe
parent203fd861aa1ab3d29477fa9954717ad46890801f (diff)
downloadspack-8b14a4620161af275335d97e981d4edcbe48868c.tar.gz
spack-8b14a4620161af275335d97e981d4edcbe48868c.tar.bz2
spack-8b14a4620161af275335d97e981d4edcbe48868c.tar.xz
spack-8b14a4620161af275335d97e981d4edcbe48868c.zip
documentation updates
-rw-r--r--lib/spack/docs/basic_usage.rst69
-rw-r--r--lib/spack/docs/getting_started.rst31
-rw-r--r--lib/spack/docs/index.rst4
3 files changed, 57 insertions, 47 deletions
diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index ed79790bb9..0578f0c8db 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -3,18 +3,16 @@
Basic usage
=====================
-Spack is implemented as a single command (``spack``) with many
-*subcommands*. Only a small subset of commands is needed for typical
-usage.
+The ``spack`` command has many *subcommands*. You'll only need a
+small subset of them for typical usage.
Listing available packages
------------------------------
-The first thing you likely want to do with spack is to install some
-software. Before that, you need to know what's available. You can
-see available package names either using the :ref:`package-list`, or
-using the commands below.
+To install software with Spack, you need to know what software is
+available. You can see a list of available package names at the
+:ref:`package-list` webpage, or using the ``spack list`` command.
.. _spack-list:
@@ -43,54 +41,55 @@ To get more information on a particular package from `spack list`, use
.. command-output:: spack info mpich
-Most of the information is self-explanatory. *Safe versions* are
-versions that Spack has a checksum for, and Spack will use the
-checksum to ensure they downloaded without any errors or malicious
-attacks. :ref:`Dependencies <sec-specs>` and :ref:`virtual
-dependencies <sec-virtual-dependencies>`, are described in more detail
-later.
+Most of the information is self-explanatory. The *safe versions* are
+versions that Spack knows the checksum for, and it will use the
+checksum to verify that these versions download without errors or
+viruses.
+
+:ref:`Dependencies <sec-specs>` and :ref:`virtual dependencies
+<sec-virtual-dependencies>` are described in more detail later.
.. _spack-versions:
``spack versions``
~~~~~~~~~~~~~~~~~~~~~~~~
-To see *more* available versions of a package, run ``spack versions``,
-for example:
+To see *more* available versions of a package, run ``spack versions``.
+For example:
.. command-output:: spack versions libelf
-There are two sections in the output. *Safe versions* are ones that
-have already been checksummed. Spack goes a step further, though, and
-also shows you what versions are available out on the web---these are
-*remote versions*. Spack gets this information by scraping it
-directly from web pages. Depending on the package, Spack may or may
-not be able to find any remote versions.
+There are two sections in the output. *Safe versions* are versions
+for which Spack has a checksum on file. It can verify that these
+versions are downloaded correctly.
+
+In many cases, Spack can also show you what versions are available out
+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
------------------------------
-Now that you know how to list available packages and versions, you're
-ready to start installing things.
-
.. _spack-install:
``spack install``
~~~~~~~~~~~~~~~~~~~~~
``spack install`` will install any package shown by ``spack list``.
-To install the latest version of a package, along with all of its
-dependencies, simply give it a package name:
+For example, To install the latest version of the ``mpileaks``
+package, you might type this:
.. code-block:: sh
$ spack install mpileaks
-If `mpileaks` depends on other packages, Spack will install those
-first. It then fetches the tarball for ``mpileaks``, expands it,
-verifies that it was downloaded without errors, builds it, and
-installs it in its own directory under ``$SPACK_HOME/opt``. You'll see
+If `mpileaks` depends on other packages, Spack will install the
+dependencies first. It then fetches the ``mpileaks`` tarball, expands
+it, verifies that it was downloaded without errors, builds it, and
+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
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
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
-calls the descriptor used to refer to a particular package
-configuration a **spec**. In the command lines above, both
-``mpileaks`` and ``mpileaks@3.0.4`` are specs. Specs are described in
-detail in :ref:`sec-specs`.
+This can all be done on the command line using the *spec* syntax.
+Spack calls the descriptor used to refer to a particular package
+configuration a **spec**. In the commands above, ``mpileaks`` and
+``mpileaks@3.0.4``. We'll talk more about how you can use them to
+customize an installation in :ref:`sec-specs`.
.. _spack-uninstall:
diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst
index a28883259f..d958d9e74a 100644
--- a/lib/spack/docs/getting_started.rst
+++ b/lib/spack/docs/getting_started.rst
@@ -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
This will create a directory called ``spack``. We'll assume that the
-full path to this directory is in some environment called
-``SPACK_HOME``. Add ``$SPACK_HOME/bin`` to your path and you're ready
-to go:
+full path to this directory is in the ``SPACK_ROOT`` environment
+variable. Add ``$SPACK_ROOT/bin`` to your path and you're ready to
+go:
.. code-block:: sh
- $ export PATH=spack/bin:$PATH
+ $ export PATH=$SPACK_ROOT/bin:$PATH
$ spack install libelf
-In general, most of your interactions with Spack will be through the
-``spack`` command.
+For a richer experience, use Spack's `shell support
+<http://scalability-llnl.github.io/spack/basic_usage.html#environment-modules>`_:
+.. code-block:: sh
+
+ # 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``.
-Install
+Installation
--------------------
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
-This will install a new spack script in /my/favorite/prefix/bin, which
-you can use just like you would the regular spack script. Each copy
-of spack installs packages into its own ``$PREFIX/opt`` directory.
+This will install a new spack script in ``/my/favorite/prefix/bin``,
+which you can use just like you would the regular spack script. Each
+copy of spack installs packages into its own ``$PREFIX/opt``
+directory.
diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst
index 2382678cc3..97c8361421 100644
--- a/lib/spack/docs/index.rst
+++ b/lib/spack/docs/index.rst
@@ -18,8 +18,8 @@ configurations can coexist on the same system.
Most importantly, Spack is *simple*. It offers a simple *spec* syntax
so that users can specify versions and configuration options
concisely. Spack is also simple for package authors: package files
-are writtin in pure Python, and specs allow package authors to write a
-single build script for many different builds of the same package.
+are writtin in pure Python, and specs allow package authors to
+maintain a single file for many different builds of the same package.
See the :doc:`features` for examples and highlights.