summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--lib/spack/docs/basic_usage.rst538
-rw-r--r--lib/spack/docs/conf.py18
-rw-r--r--lib/spack/docs/features.rst58
-rw-r--r--lib/spack/docs/index.rst21
-rw-r--r--lib/spack/spack/architecture.py (renamed from lib/spack/spack/arch.py)0
-rw-r--r--lib/spack/spack/cmd/arch.py (renamed from lib/spack/spack/cmd/sys_type.py)6
-rw-r--r--lib/spack/spack/cmd/install.py2
-rw-r--r--lib/spack/spack/cmd/providers.py17
-rw-r--r--lib/spack/spack/cmd/versions.py3
-rw-r--r--lib/spack/spack/colify.py7
-rw-r--r--lib/spack/spack/concretize.py4
-rw-r--r--lib/spack/spack/globals.py1
-rw-r--r--lib/spack/spack/multi_function.py2
-rw-r--r--lib/spack/spack/packages/__init__.py1
-rw-r--r--lib/spack/spack/spec.py1
15 files changed, 512 insertions, 167 deletions
diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index 425fe0c288..ae591920db 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -1,25 +1,26 @@
Basic usage
=====================
-Nearly everything you do wtih spack will involve the ``spack``
-command. Like many well-known tools (``git``, ``cvs``, ``svn``,
-``yum``, ``port``, ``apt-get``, etc.), ``spack`` is generally called
-with a *subcommand* indicating the action you want to perform.
+Spack is implemented as a single command (``spack``) with many
+*subcommands*, much like ``git``, ``svn``, ``yum``, or ``apt-get``.
+Only a small subset of commands are needed for typical usage.
+
+This section covers a small set of subcommands that should cover most
+general use cases for Spack.
Getting Help
-----------------------
-
``spack help``
~~~~~~~~~~~~~~~~~~~~~~
-The first subcommand you should know is ``spack help``. Run with no
-arguments, it will give a list of all spack options and subcommands:
+The ``help`` subcommand will print out out a list of all of
+``spack``'s options and subcommands:
.. command-output:: spack help
-If you want help on the usage of a particular subcommand, you can pass
-it as an argument to ``spack help``:
+Adding an argument, e.g. ``spack help <subcommand>``, will print out
+usage information for a particular subcommand:
.. command-output:: spack help install
@@ -38,29 +39,54 @@ this: ``spack list`` and ``spack info``.
``spack list``
~~~~~~~~~~~~~~~~
-The ``spack list`` command does what you might expect. it prints out a
-list of all the available packages you can install. Use it like
-this:
+The ``spack list`` command prints out a list of all of the packages
+Spack can install:
.. command-output:: spack list
-The packages are listed by name in alphabetical order. If you just
-want to see *installed* packages, you should use ``spack list -i``
+The packages are listed by name in alphabetical order. To see a list of
+only the *installed* packages, use ``spack list -i``.
``spack info``
~~~~~~~~~~~~~~~~
-To get information on a particular package from the full list, you can
-run ``spack info <package name>``. e.g., for ``mpich``:
+To get information on a particular package from the full list, run
+``spack info <package name>``. For example, for ``mpich`` the output
+looks like this:
.. command-output:: spack info mpich
-This gives basic information about the package, such as where it can
-be downloaded, what other packages it depends on, virtual package
-information, and a text description, if one is available. We'll give
-more details on dependencies and virtual dependencies later in this
-guide.
+This includes basic information about the package: where to download
+it, its dependencies, virtual packages it provides (e.g. an MPI
+implementation will provide the MPI interface), and a text
+description, if one is available. :ref:`Dependencies
+<sec-specs>` and :ref:`virtual dependencies
+<sec-virtual-dependencies>` are described in more detail later.
+
+
+``spack versions``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To see available versions of a package, run ``spack versions``, for
+example:
+
+.. command-output:: spack versions libelf
+
+Since it has to manage many different software packages, Spack doesn't
+place many restrictions on what a package version has to look like.
+Packages like ``mpich`` use traditional version numbers like
+``3.0.4``. Other packages, like ``libdwarf`` use date-stamp versions
+like ``20130729``. Versions can contain numbers, letters, dashes,
+underscores, and periods.
+
+``spack compilers``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can see supported compilers by running ``spack compilers``. The
+output will depend on the platform you run it on.
+
+.. command-output:: spack compilers
Installing and uninstalling
@@ -69,165 +95,433 @@ Installing and uninstalling
``spack install``
~~~~~~~~~~~~~~~~~~~~~
-You can install any package from ``spack list``, using ``spack
-install``. In the simplest case, if you just want the latest version
-and you don't care about any configuration, you can just run ``spack
-install <package>``:
+``spack install`` will install any package that appears in the output
+of ``spack list``. To install the latest version of a pacakge and all
+of its dependencies, simply run ``spack install <package>``:
.. code-block:: sh
spack install mpileaks
-This will fetch the tarball for ``mpileaks``, expand it, verify that
-it was donwloaded without errors, build the package, and install it in
-its own directory in ``$SPACK_HOME/opt``. If the requested packages
-depends on other packages in order to build, then they will also be
-fetched and installed.
+Spack will fetch the tarball for ``mpileaks``, expand it, verify that
+it was donwloaded without errors, build it, and install it in its own
+directory under ``$SPACK_HOME/opt``. If the requested package depends
+on other packages in order to build, Spack fetches them as well, and
+installs them before it installs the requested package. Like the main
+package, each dependency is also installed in its own directory.
-Spack also allows you to ask for *specific* configurations of a
-package. For example, if you want to install something with a
-specific version, you can add ``@`` after the package name, followed
-by the version you want:
+Spack can also build *specific* configurations of a package. For
+example, to install something with a specific version, add ``@`` after
+the package name, followed by a version string:
.. code-block:: sh
spack install mpich@3.0.4
-You can install as many versions of the same pacakge as you want, and
-they will not interfere with each other. Spack installs each package
-into its own unique prefix. If you or another user links a library
-against soething you install using Spack, it will continue to work
-until you explicitly uninstall it.
-
-The version isn't all that you can customize on a spack command line.
-Spack can install many configurations, with different versions,
-compilers, compiler versions, compile-time options (variants), and
-even architectures (e.g., on a machine that requires cross-compiling).
-Spack is also unique in that it lets you customize the *dependencies*
-you build a package with. That is, you could have two 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.
-
-Spack calls the descriptor used to refer to a particular package
+Any number of configurations of the same package can be installed at
+once without interfering with each other. This is good for multi-user
+sites, as installing a version that one user needs will not disrupt
+existing installations for other users.
+
+In addition to version configuraitons, Spack can customize the
+compiler, compile-time options (variants), and platform (for cross
+compiles) of an installation. Spack is unique in that it can also
+configure the *dependencies* a package is built with. For example,
+two 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 and their syntax
-are covered in more detail in :ref:`sec-specs`.
-
-
+``mpileaks`` and ``mpileaks@3.0.4`` are specs. To customize
+additional properties, simply add more attributes to the spec. Specs
+and their syntax are covered in more detail in :ref:`sec-specs`.
``spack uninstall``
~~~~~~~~~~~~~~~~~~~~~
-To uninstall a package, just type ``spack uninstall <package>``. This
-will completely remove the directory in which the package was installed.
+To uninstall a package, type ``spack uninstall <package>``. This will
+completely remove the directory in which the package was installed.
.. code-block:: sh
spack uninstall mpich
-If there are other installed packages depend on the package you're
-uninstalling, spack will issue a warning to this effect. In general,
-you should remove the other packages *before* removing the package
-they depend on, or you risk breaking packages on your system. If you
-still want to remove the package without regard for its dependencies,
-you can run ``spack uninstall -f <package>`` to override Spack's
-warning.
+If there are other installed packages depend on the package to be
+uninstalled, spack will issue a warning. In general, it is safer to
+remove dependent packages *before* removing their dependencies. Not
+doing so risks breaking packages on your system. To remove a package
+without regard for its dependencies, run ``spack uninstall -f
+<package>`` to override the warning.
-If you have more than one version of the same package installed, spack
-may not be able to figure out which on eyou want uninstalled. For
-example, if you have both ``mpich@3.0.2`` and ``mpich@3.1`` installed,
-and you type ``spack uninstall mpich``, then Spack will not know which
-one you're referring to, and it will ask you to be more specific by
-providing a version to differentiate, For example, ``spack uninstall
-mpich@3.1`` is unambiguous.
+A line like ``spack uninstall mpich`` may be ambiguous, if multiple
+``mpich`` configurations are installed. For example, if both
+``mpich@3.0.2`` and ``mpich@3.1`` are installed, it could refer to
+either one, and Spack cannot determine which one to uninstall. Spack
+will ask you to provide a version number to remove any ambiguity. For
+example, ``spack uninstall mpich@3.1`` is unambiguous in the
+above scenario.
.. _sec-specs:
-Specs
+Specs & Dependencies
-------------------------
-Dependencies
--------------------------
+We now know that ``spack install`` and ``spack uninstall`` both take a
+package name with an optional version specifier. In Spack, that
+descriptor is called a *spec*. Spack uses specs to refer 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
+specify the compiler, compiler version, architecture, compile options,
+and dependency options for a build. In this section, we'll go over
+the full syntax of specs.
+
+Here is an example of a much longer spec than we've seen thus far::
+
+ mpileaks @1.2:1.4 %gcc@4.7.5 +debug -qt =bgqos_0 ^callpath @1.1 %gcc@4.7.2
+
+If provided to ``spack install``, this will install the ``mpileaks``
+library at some version between ``1.2`` and ``1.4`` (inclusive),,
+built using ``gcc`` at version 4.7.5 for the Blue Gene/Q architecture,
+with debug options enabled, and without Qt support. Additionally, it
+says to link it with the ``callpath`` library (which it depends on),
+and to build callpath with ``gcc`` 4.7.2. Most specs will not be as
+complicated as this one, but this is a good example of what is
+possible with specs.
+
+More formally, a spec consists of the following pieces:
+
+* Package name identifier (``mpileaks`` above)
+* ``@`` Optional version specifier (``@1.2:1.4``)
+* ``%`` Optional compiler specifier, with an optional compiler version
+ (``gcc`` or ``gcc@4.7.3``)
+* ``+`` or ``-`` or ``~`` Optional variant specifiers (``+debug``,
+ ``-qt``, or ``~qt``)
+* ``=`` Optional architecture specifier (``bgqos_0``)
+* ``^`` Dependency specs (``^callpath@1.1``)
+
+There are two things to notice here. One is that specs are
+recursively defined. That is, each dependency after ``^`` is a spec
+itself. The second is that Notice that everything is optional
+*except* for the initial package name identifier. Users can be as
+vague or as specific as they want about the details of building
+packages, and this makes spack good for beginners and experts alike.
+
+To really understand what's going on above, we need to think about how
+software is structured. An executable or a library (these are
+generally the artifacts produced by building software) depends on
+other libraries in order to run. We can represent the relationship
+between a package and its dependencies as a graph. Here is the full
+dependency graph for ``mpileaks``:
+
+.. graphviz::
+
+ digraph {
+ mpileaks -> mpich
+ mpileaks -> callpath -> mpich
+ callpath -> dyninst
+ dyninst -> libdwarf -> libelf
+ dyninst -> libelf
+ }
+
+Each box above is a package and each arrow represents a dependency on
+some other package. For example, we say that the package ``mpileaks``
+*depends on* ``callpath`` and ``mpich``. ``mpileaks`` also depends
+*indirectly* on ``dyninst``, ``libdwarf``, and ``libelf``, in that
+these libraries are dependencies of ``callpath``. To install
+``mpileaks``, Spack has to build all of these packages. Dependency
+graphs in Spack have to be acyclic, and the *depends on* relationship
+is directional, so this is a *directed, acyclic graph* or *DAG*.
+
+The package name identifier in the spec is the root of some dependency
+DAG, and the DAG itself is implicit. Spack knows the precise
+dependencies among packages, but users do not need to know the full
+DAG structure. Each ``^`` in the full spec refers to some dependency
+of the root package. Spack will raise an error if you supply a name
+after ``^`` that the root does not actually depend on (e.g. ``mpileaks
+^emacs@23.3``).
+
+Spack further simplifies things by only allowing one configuration of
+each package within any single build. Above, both ``mpileaks`` and
+``callpath`` depend on ``mpich``, but ``mpich`` appears only once in
+the DAG. You cannot build an ``mpileaks`` version that depends on one
+version of ``mpich`` *and* on a ``callpath`` version that depends on
+some *other* version of ``mpich``. In general, such a configuration
+would likely behave unexpectedly at runtime, and Spack enforces this
+to ensure a consistent runtime environment.
+
+
+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
+by simply writing ``mpileaks``. If she knows that ``mpileaks``
+indirectly uses ``dyninst`` and she wants a particular version of
+``dyninst``, then she can refer to ``mpileaks ^dyninst@8.1``. Spack
+will fill in the rest when it parses the spec; the user only needs to
+know package names and minimal details about their relationship.
+
+When spack prints out specs, it sorts package names alphabetically to
+normalize the way they are displayed, but users do not need to worry
+about this when they write specs. The only restriction on the order
+of dependencies within a spec is that they appear *after* the root
+package. For example, these two specs represent exactly the same
+configuration:
+
+.. code-block:: sh
+
+ mpileaks ^callpath@1.0 ^libelf@0.8.3
+ mpileaks ^libelf@0.8.3 ^callpath@1.0
+
+You can put all the same modifiers on dependency specs that you would
+put on the root spec. That is, you can specify their versions,
+compilers, variants, and architectures just like any other spec.
+Specifiers are associated with the nearest package name to their left.
+For example, above, ``@1.1`` and ``%gcc@4.7.2`` associates with the
+``callpath`` package, while ``@1.2:1.4``, ``%gcc@4.7.5``, ``+debug``,
+``-qt``, and ``=bgqos_0`` all associate with the ``mpileaks`` package.
+
+In the diagram above, ``mpileaks`` depends on ``mpich`` with an
+unspecified version, but packages can depend on other packages with
+*constraints* by adding more specifiers. For example, ``mpileaks``
+could depend on ``mpich@1.2:`` if it can only build with version
+``1.2`` or higher of ``mpich``.
+
+Below are more details about the specifiers that you can add to specs.
+
+Version specifier
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A version specifier comes somewhere after a package name and starts
+with ``@``. It can be a single version, e.g. ``@1.0``, ``@3``, or
+``@1.2a7``. Or, it can be a range of versions, such as ``@1.0:1.5``
+(all versions between ``1.0`` and ``1.5``, inclusive). Version ranges
+can be open, e.g. ``:3`` means any version up to and including ``3``.
+This would include ``3.4`` and ``3.4.2``. ``4.2:`` means any version
+above and including ``4.2``. Finally, a version specifier can be a
+set of arbitrary versions, such as ``@1.0,1.5,1.7`` (``1.0``, ``1.5``,
+or ``1.7``). When you supply such a specifier to ``spack install``,
+it constrains the set of versions that Spack will install.
+
+If the version spec is not provided, then Spack will choose one
+according to policies set for the particular spack installation. If
+the spec is ambiguous, i.e. it could match multiple versions, Spack
+will choose a version within the spec's constraints according to
+policies set for the particular Spack installation.
+
+Details about how versions are compared and how Spack determines if
+one version is less than another are discussed in the developer guide.
+
+
+Compiler specifier
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A compiler specifier comes somewhere after a package name and starts
+with ``%``. It tells Spack what compiler(s) a particular package
+should be built with. After the ``%`` should come the name of some
+registered Spack compiler. This might include ``gcc``, or ``intel``,
+but the specific compilers available depend on the site. You can run
+``spack compilers`` to get a list; more on this below.
+
+The compiler spec can be followed by an optional *compiler version*.
+A compiler version specifier looks exactly like a package version
+specifier. Version specifiers will associate with the nearest package
+name or compiler specifier to their left in the spec.
+
+If the compiler spec is omitted, Spack will choose a default compiler
+based on site policies.
+
+
+Variants
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Variants are named options associated with a particular package, and
+they can be turned on or off. For example, above, supplying
+``+debug`` causes ``mpileaks`` to be built with debug flags. The
+names of particular variants available for a package depend on what
+was provided by the package author. ``spack info <package>`` will
+provide information on what build variants are available.
+
+Depending on the package a variant may be on or off by default. For
+``mpileaks`` here, ``debug`` is off by default, and we turned it on
+with ``+debug``. If a package is on by default you can turn it off by
+either adding ``-name`` or ``~name`` to the spec.
+
+There are two syntaxes here because, depending on context, ``~`` and
+``-`` may mean different things. In most shells, the following will
+result in the shell performing home directory substitution:
+
+.. code-block:: sh
+
+ mpileaks ~debug # shell may try to substitute this!
+ mpileaks~debug # use this instead
+
+If there is a user called ``debug``, the ``~`` will be incorrectly
+expanded. In this situation, you would want to write ``mpileaks
+-debug``. However, ``-`` can be ambiguous when included after a
+package name without spaces:
+
+.. code-block:: sh
+
+ mpileaks-debug # wrong!
+ mpileaks -debug # right
+
+Spack allows the ``-`` character to be part of package names, so the
+above will be interpreted as a request for the ``mpileaks-debug``
+package, not a request for ``mpileaks`` built without ``debug``
+options. In this scenario, you should write ``mpileaks~debug`` to
+avoid ambiguity.
+
+When spack normalizes specs, it prints them out with no spaces and
+uses only ``~`` for disabled variants. We allow ``-`` and spaces on
+the command line is provided for convenience and legibility.
+
+
+Architecture specifier
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The architecture specifier starts with a ``=`` and also comes after
+some package name within a spec. It allows a user to specify a
+particular architecture for the package to be built. This is mostly
+used for architectures that need cross-compilation, and in most cases,
+users will not need to specify the architecture when they install a
+package.
+
+
+.. _sec-virtual-dependencies:
Virtual dependencies
-------------------------
-Versions, compilers, and architectures
-----------------------------------------
+The dependence graph for ``mpileaks`` we saw above wasn't *quite*
+accurate. ``mpileaks`` uses MPI, which is an interface that has many
+different implementations. Above, we showed ``mpileaks`` and
+``callpath`` depending on ``mpich``, which is one *particular*
+implementation of MPI. However, we could build either with another
+implementation, such as ``openmpi`` or ``mvapich``.
-``spack versions``
-~~~~~~~~~~~~~~~~~~~~~~~~
+Spack represents interfaces like this using *virtual dependencies*.
+The real dependency DAG for ``mpileaks`` looks like this:
-``spack compilers``
-~~~~~~~~~~~~~~~~~~~~~~~~
+.. graphviz::
-Architectures
-~~~~~~~~~~~~~~~~~~~~~~~~
+ digraph {
+ mpi [color=red]
+ mpileaks -> mpi
+ mpileaks -> callpath -> mpi
+ callpath -> dyninst
+ dyninst -> libdwarf -> libelf
+ dyninst -> libelf
+ }
+
+Notice that ``mpich`` has now been replaced with ``mpi``. There is no
+*real* MPI package, but some packages *provide* the MPI interface, and
+these packages can be substituted in for ``mpi`` when ``mpileaks`` is
+built.
+
+You can see what virtual packages a particular package provides by
+getting info on it:
+
+.. command-output:: spack info mpich
+ :ellipsis: 10
+
+Spack is unique in that its virtual packages can be versioned, just
+like regular packages. A particular version of a package may provide
+a particular version of a virtual package, and we can see above that
+``mpich`` versions ``1`` and above provide all interfaces up to ``1``,
+and ``mpich`` versions ``3`` and above provide ``mpi`` versions up to
+``3``. A package can *depend on* a particular 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 implementation that
+provides MPI-2 functions.
+
+``spack providers``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can see what packages provide a particular virtual package using
+``spack providers``. If you wanted to see what packages provide
+``mpi``, you would just run:
+
+.. command-output:: spack providers mpi
+
+And if you *only* wanted to see packages that provide MPI-2, you would
+add a version specifier to the spec:
+
+.. command-output:: spack providers mpi@2
-Spack's specs allow insatllations for multiple architectures to coexist
-within the same prefix. It is also intended to support multiple
-architecutres for cross-compilation.
+Notice that the package versions that provide insufficient MPI
+versions are now filtered out.
Package lifecycle
------------------------------
-The ``spack install`` command performs a number of tasks before it
-finally installs each package. It downloads an archive, expands it in
-a temporary directory, and only then performs the installation. Spack
-has several commands that allow finer-grained control over each of
-these stages of the build process.
+``spack install`` command performs a number of tasks before it finally
+installs each package. It downloads an archive, expands it in a
+temporary directory, and then performs the installation. Spack has
+several commands that allow finer-grained control over each stage of
+the build process.
``spack fetch``
~~~~~~~~~~~~~~~~~
-This is the first step of ``spack install``. It takes a spec and
-determines the correct download URL to use for the requested package
-version. It then downloads the archive, checks it against an MD5
-checksum, and stores it in a staging directory if the check was
-successful. The staging directory will be located under
-``$SPACK_HOME/var/spack``.
+The first step of ``spack install``. Takes a spec and determines the
+correct download URL to use for the requested package version, then
+downloads the archive, checks it against an MD5 checksum, and stores
+it in a staging directory if the check was successful. The staging
+directory will be located under ``$SPACK_HOME/var/spack``.
-If run after the archive has already been downloaded, ``spack fetch``
-is idempotent and will not download the archive again.
+When run after the archive has already been downloaded, ``spack
+fetch`` is idempotent and will not download the archive again.
``spack stage``
~~~~~~~~~~~~~~~~~
-This is the second step in installation after ``spack fetch``. It
-expands the downloaded archive in its temporary directory, where it
-will be built by ``spack install``. If the archive has already been
-expanded, then this command does nothing.
+The second step in ``spack install`` after ``spack fetch``. Expands
+the downloaded archive in its temporary directory, where it will be
+built by ``spack install``. Similar to ``fetch``, if the archive has
+already been expanded, ``stage`` is idempotent.
``spack clean``
~~~~~~~~~~~~~~~~~
-This command has several variations, each undoing one of the
-installation tasks. They are:
+There are several variations of ``spack clean``. With no arguments,
+``spack clean`` runs ``make clean`` in the expanded archive directory.
+This is useful if an attempted build failed, and something needs to be
+changed to get a package to build. If a particular package does not
+have a ``make clean`` target, this will do nothing.
+
+``spack clean -w / --work``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Deletes the entire build directory and re-expands it from the downloaded
+archive. This is useful if a package does not support a proper ``make clean``
+target.
+
+``spack clean -d / --dist``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Deletes the build directory *and* the downloaded archive. If
+``fetch``, ``stage``, or ``install`` are run again after this, the
+process will start from scratch, and the archive archive will be
+downloaded again. Useful if somehow a bad archive is downloaded
+accidentally and needs to be cleaned out of the staging area.
-``spack clean``
- Runs ``make clean`` in the expanded archive directory. This is useful
- if an attempted build failed, and something needs to be changed to get
- a package to build. If a particular package does not have a ``make clean``
- target, this will do nothing.
-
-``spack clean -w`` or ``spack clean --work``
- This deletes the entire build directory and re-expands it from the downloaded
- archive. This is useful if a package does not support a proper ``make clean``
- target.
-
-``spack clean -d`` or ``spack clean --dist``
- This deletes the build directory *and* the downloaded archive. If
- ``fetch``, ``stage``, or ``install`` are run again after this, the
- process will start from scratch, and the archive archive will be
- downloaded again. Useful if somehow a bad archive is downloaded
- accidentally and needs to be cleaned out of the staging area.
+``spack purge``
+~~~~~~~~~~~~~~~~~
+Cleans up *everything* in the build directory. You can use this to
+recover disk space if temporary files from interrupted or failed
+installs accumulate in the staging area.
+Dirty Installs
+--------------------
-``spack purge``
-~~~~~~~~~~~~~~~~~
+By default, ``spack install`` will delete the staging area once a
+pacakge has been successfully built and installed, *or* if an error
+occurs during the build. Use ``spack install --dirty`` or ``spack
+install -d`` to leave the build directory intact. This allows you to
+inspect the build directory and potentially fix the build. You can
+use ``purge`` or ``clean`` later to get rid of the unwanted temporary
+files.
diff --git a/lib/spack/docs/conf.py b/lib/spack/docs/conf.py
index 68b70f359f..1303503bd6 100644
--- a/lib/spack/docs/conf.py
+++ b/lib/spack/docs/conf.py
@@ -17,8 +17,17 @@ import sys, os
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('exts'))
+
+# Add the Spack bin directory to the path so that we can use its output in docs.
os.environ['PATH'] += os.pathsep + '../../../bin'
+# Set an environment variable so that colify will print output like it would to
+# a terminal.
+os.environ['COLIFY_TTY'] = 'true'
+os.environ['COLUMNS'] = '80'
+os.environ['LINES'] = '25'
+
+# Enable todo items
todo_include_todos = True
# -- General configuration -----------------------------------------------------
@@ -33,6 +42,15 @@ extensions = ['sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinxcontrib.programoutput']
+# Set default graphviz options
+graphviz_dot_args = [
+ '-Grankdir=LR', '-Gbgcolor=transparent',
+ '-Nshape=box', '-Nfontname=monaco', '-Nfontsize=10']
+
+# Get nice vector graphics
+graphviz_output_format = "svg"
+
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/lib/spack/docs/features.rst b/lib/spack/docs/features.rst
index 7039563698..27e821d3b2 100644
--- a/lib/spack/docs/features.rst
+++ b/lib/spack/docs/features.rst
@@ -1,16 +1,16 @@
Feature Overview
==================
-This is an overview of features that make Spack different from other
-`package managers <http://en.wikipedia.org/wiki/Package_management_system>`_
-and `port systems <http://en.wikipedia.org/wiki/Ports_collection>`_.
+This is a high-level overview of features that make Spack different
+from other `package managers
+<http://en.wikipedia.org/wiki/Package_management_system>`_ and `port
+systems <http://en.wikipedia.org/wiki/Ports_collection>`_.
Simple package installation
----------------------------
-Installing packages is easy with Spack when you just want the default
-version. This installs the latest version of mpileaks and all of its
-dependencies:
+Installing the default version of a package is simple. This will install
+the latest version of the ``mpileaks`` package and all of its dependencies:
.. code-block:: sh
@@ -19,29 +19,35 @@ dependencies:
Custom versions & configurations
-------------------------------------------
-If there's some aspect of your package that you want to customize, you
-can do that too.
+Spack allows installation to be customized. Users can specify the
+version, build compiler, compile-time options, and cross-compile
+platform, all on the command line.
.. code-block:: sh
# Install a particular version by appending @
$ spack install mpileaks@1.1.2
- # Or your favorite compiler (and its version), with %
+ # Specify a compiler (and its version), with %
$ spack install mpileaks@1.1.2 %gcc@4.7.3
- # Add some special compile-time options with +
+ # Add special compile-time options with +
$ spack install mpileaks@1.1.2 %gcc@4.7.3 +debug
# Cross-compile for a different architecture with =
$ spack install mpileaks@1.1.2 =bgqos_0
+Users can specify as many or few options as they care about. Spack
+will fill in the unspecified values with sensible defaults.
+
+
Customize dependencies
-------------------------------------
-You can customize package dependencies with ``^``. Suppose that
-``mpileaks`` depends indirectly on ``libelf`` and ``libdwarf``. Using
-``^``, you can add custom configurations for the dependencies, too.
+Spack is unique in that it allows *dependencies* of a particualr
+installation to be customized. Suppose that ``mpileaks`` depends
+indirectly on ``libelf`` and ``libdwarf``. Using ``^``, users can add
+custom configurations for the dependencies, as well:
.. code-block:: sh
@@ -52,24 +58,24 @@ You can customize package dependencies with ``^``. Suppose that
Non-destructive installs
-------------------------------------
-Spack installs every unique package configuration in its own prefix,
-so you can install as many different versions and configurations as
-you want. New installs will not break existing ones.
-
+Spack installs every unique package/dependency configuration into its
+own prefix, so new installs will not break existing ones.
Packages can peacefully coexist
-------------------------------------
-Spack uses ``RPATH`` everywhere, so users do not need to customize
-``LD_LIBRARY_PATH``. If you use a library or run a program, it will
-run the way you built it.
-
+Spack avoids library misconfiguration by using ``RPATH`` to link
+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
+manipulate ``LD_LIBRARY_PATH`` at runtime.
Creating packages is easy
-------------------------------------
-To create your own packages, give spack the tarball URL. Spack
-creates all the boilerplate for you.
+To create a new packages, all Spack needs is a URL for the source
+archive. The ``spack create`` command will create a boilerplate
+package file, and the package authors can fill in specific build steps
+in pure Python.
.. code-block:: sh
@@ -91,6 +97,6 @@ Creates ``mpileaks.py``:
make()
make("install")
-Packages are pure python, so you have complete freedom when writing
-build code. Spack also provides a number of feature that make it
-easier to write packages.
+Spack also provides wrapper functions around common commands like
+``configure``, ``make``, and ``cmake`` to make writing packages
+simple.
diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst
index 092d696983..b6c1e537fb 100644
--- a/lib/spack/docs/index.rst
+++ b/lib/spack/docs/index.rst
@@ -6,11 +6,22 @@
Spack Documentation
=================================
-Spack builds and installs software the way you want it. Other tools
-let you install the latest version once. Spack lets you install the
-versions you want, built with the compilers, libraries, and options
-you want. Spack is non-destructive; installing a new version does not
-break your old installs. See the :doc:`features` for more highlights.
+Spack is a package management tool designed to support multiple
+versions and configurations of software on a wide variety of platforms
+and environments. It was designed for large supercomputing centers,
+where many users and application teams share common installations of
+software on clusters with exotic architectures, using libraries that
+do not have a standard ABI. Spack is non-destructive: installing a
+new version does not break existing installations, so many
+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.
+
+See the :doc:`features` for examples and highlights.
Get spack and install your first package:
diff --git a/lib/spack/spack/arch.py b/lib/spack/spack/architecture.py
index c4914de1a0..c4914de1a0 100644
--- a/lib/spack/spack/arch.py
+++ b/lib/spack/spack/architecture.py
diff --git a/lib/spack/spack/cmd/sys_type.py b/lib/spack/spack/cmd/arch.py
index 7f57fb16ff..a6d4879fdc 100644
--- a/lib/spack/spack/cmd/sys_type.py
+++ b/lib/spack/spack/cmd/arch.py
@@ -1,9 +1,9 @@
import spack
-import spack.arch as arch
+import spack.architecture as architecture
-description = "Print the spack sys_type for this machine"
+description = "Print the architecture for this machine"
-def sys_type(parser, args):
+def arch(parser, args):
configured_sys_type = arch.get_sys_type_from_spack_globals()
if not configured_sys_type:
configured_sys_type = "autodetect"
diff --git a/lib/spack/spack/cmd/install.py b/lib/spack/spack/cmd/install.py
index 1af74e0f60..b3ad463988 100644
--- a/lib/spack/spack/cmd/install.py
+++ b/lib/spack/spack/cmd/install.py
@@ -12,7 +12,7 @@ def setup_parser(subparser):
action='store_true', dest='ignore_dependencies',
help="Do not try to install dependencies of requested packages.")
subparser.add_argument('-d', '--dirty', action='store_true', dest='dirty',
- help="Don't clean up partially completed build/installation on error.")
+ help="Don't clean up staging area when install completes.")
subparser.add_argument('packages', nargs=argparse.REMAINDER, help="specs of packages to install")
diff --git a/lib/spack/spack/cmd/providers.py b/lib/spack/spack/cmd/providers.py
new file mode 100644
index 0000000000..5546c7f312
--- /dev/null
+++ b/lib/spack/spack/cmd/providers.py
@@ -0,0 +1,17 @@
+import os
+import argparse
+
+import spack.cmd
+import spack.packages
+from spack.colify import colify
+
+description ="List packages that provide a particular virtual package"
+
+def setup_parser(subparser):
+ subparser.add_argument('vpkg_spec', metavar='VPACKAGE_SPEC', nargs=argparse.REMAINDER,
+ help='Find packages that provide this virtual package')
+
+
+def providers(parser, args):
+ for spec in spack.cmd.parse_specs(args.vpkg_spec):
+ colify(sorted(spack.packages.providers_for(spec)), indent=4)
diff --git a/lib/spack/spack/cmd/versions.py b/lib/spack/spack/cmd/versions.py
index d18b1c1265..3ceee0eca7 100644
--- a/lib/spack/spack/cmd/versions.py
+++ b/lib/spack/spack/cmd/versions.py
@@ -1,7 +1,4 @@
import os
-import re
-from subprocess import CalledProcessError
-
import spack.packages as packages
from spack.colify import colify
diff --git a/lib/spack/spack/colify.py b/lib/spack/spack/colify.py
index 0ab2159197..02c4003681 100644
--- a/lib/spack/spack/colify.py
+++ b/lib/spack/spack/colify.py
@@ -88,6 +88,11 @@ def config_uniform_cols(elts, console_cols, padding):
return config
+def isatty(ostream):
+ force = os.environ.get('COLIFY_TTY', 'false').lower() != 'false'
+ return force or ostream.isatty()
+
+
def colify(elts, **options):
# Get keyword arguments or set defaults
output = options.get("output", sys.stdout)
@@ -99,7 +104,7 @@ def colify(elts, **options):
if not elts:
return
- if not output.isatty():
+ if not isatty(output):
for elt in elts:
output.write("%s\n" % elt)
return
diff --git a/lib/spack/spack/concretize.py b/lib/spack/spack/concretize.py
index f29f33f144..029b6d0d03 100644
--- a/lib/spack/spack/concretize.py
+++ b/lib/spack/spack/concretize.py
@@ -9,7 +9,7 @@ or user preferences.
TODO: make this customizable and allow users to configure
concretization policies.
"""
-import spack.arch
+import spack.architecture
import spack.compilers
import spack.packages
import spack.spec
@@ -62,7 +62,7 @@ class DefaultConcretizer(object):
if spec.root.architecture:
spec.architecture = spec.root.architecture
else:
- spec.architecture = spack.arch.sys_type()
+ spec.architecture = spack.architecture.sys_type()
def concretize_compiler(self, spec):
diff --git a/lib/spack/spack/globals.py b/lib/spack/spack/globals.py
index a2a14cfad1..166c463cdf 100644
--- a/lib/spack/spack/globals.py
+++ b/lib/spack/spack/globals.py
@@ -1,6 +1,5 @@
import os
-import spack.arch as arch
from spack.version import Version
from spack.util.filesystem import *
from spack.util.executable import *
diff --git a/lib/spack/spack/multi_function.py b/lib/spack/spack/multi_function.py
index abceb156c0..30146b2139 100644
--- a/lib/spack/spack/multi_function.py
+++ b/lib/spack/spack/multi_function.py
@@ -12,7 +12,7 @@ of the dependencies of the package.
import sys
import functools
-import arch
+import spack.architecture
import spack.error as serr
class NoSuchVersionError(serr.SpackError):
diff --git a/lib/spack/spack/packages/__init__.py b/lib/spack/spack/packages/__init__.py
index 68a5f7978b..0fd22fa480 100644
--- a/lib/spack/spack/packages/__init__.py
+++ b/lib/spack/spack/packages/__init__.py
@@ -11,7 +11,6 @@ import spack.spec
import spack.tty as tty
from spack.util.filesystem import new_path
from spack.util.lang import list_modules
-import spack.arch as arch
# Valid package names can contain '-' but can't start with it.
valid_package_re = r'^\w[\w-]*$'
diff --git a/lib/spack/spack/spec.py b/lib/spack/spack/spec.py
index 17ef523f57..748fa9b36a 100644
--- a/lib/spack/spack/spec.py
+++ b/lib/spack/spack/spec.py
@@ -75,7 +75,6 @@ import spack.error
import spack.compilers
import spack.compilers.gcc
import spack.packages as packages
-import spack.arch as arch
from spack.version import *
from spack.color import *
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2024-11-02 18:01:59 +0000