From 8b14a4620161af275335d97e981d4edcbe48868c Mon Sep 17 00:00:00 2001 From: Todd Gamblin Date: Tue, 14 Apr 2015 15:11:01 -0700 Subject: documentation updates --- lib/spack/docs/basic_usage.rst | 69 +++++++++++++++++++------------------- lib/spack/docs/getting_started.rst | 31 +++++++++++------ lib/spack/docs/index.rst | 4 +-- 3 files changed, 57 insertions(+), 47 deletions(-) (limited to 'lib') 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 ` and :ref:`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 ` and :ref:`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 +`_: +.. 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. -- cgit v1.2.3-70-g09d2