Skip to content

suggestions #430

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
haampie wants to merge 2 commits into from
Closed

suggestions #430

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d4c25af
jules wip
haampie May 27, 2025
98bb7f1
scripting
haampie May 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
195 changes: 99 additions & 96 deletions tutorial_advanced_packaging.rst
View file
Open in desktop

Large diffs are not rendered by default.

77 changes: 42 additions & 35 deletions tutorial_basics.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ output is all from an Ubuntu 22.04 Docker image.
Installing Spack
----------------

Spack works out of the box. Simply clone Spack to get going. We will
clone Spack and immediately check out the most recent release, v0.23.
Spack works out of the box. Simply clone Spack to get started. We will
clone Spack and immediately check out a recent stable release, v0.23 (note: the specific version is used to ensure consistency of output in this tutorial).

.. literalinclude:: outputs/basics/clone.out
:language: console
Expand Down Expand Up @@ -82,10 +82,10 @@ Let's go ahead and install ``gmake``,
You will see Spack installed ``gmake``, ``gcc-runtime``, and
``glibc``. The ``glibc`` and ``gcc-runtime`` packages are
automatically tracked by Spack to manage consistency requirements
among compiler runtimes. These do not represent separate installs from
source, but represent aspects of the compiler Spack used for the
install. For the rest of this section, we will ignore these components
and focus on the rest of the install.
among compiler runtimes. They don't represent separate software builds from
source but are records of the system's compiler runtime components that Spack
uses. For the rest of this section, we will ignore these internally tracked
components and focus on the packages explicitly installed.

Spack can install software either from source or from a binary
cache. Packages in the binary cache are signed with GPG for
Expand All @@ -104,16 +104,17 @@ tutorial from a binary cache using the same ``spack install``
command. By default this will install the binary cached version if it
exists and fall back on installing from source if it does not.

Spack's spec syntax is the interface by which we can request specific
configurations of the package. The ``%`` sigil is used to specify
Spack's "spec" syntax is the interface by which we can request specific
configurations of a package. The ``%`` sigil is used to specify
compilers.

.. literalinclude:: outputs/basics/zlib-clang.out
:language: console

Note that this installation is located separately from the previous
one. We will discuss this in more detail later, but this is part of what
allows Spack to support arbitrarily versioned software.
allows Spack to support software with many version and configuration combinations
simultaneously.

You can check for particular versions before requesting them. We will
use the ``spack versions`` command to see the available versions, and then
Expand All @@ -135,7 +136,7 @@ The spec syntax also includes compiler flags. Spack accepts
``cppflags``, ``cflags``, ``cxxflags``, ``fflags``, ``ldflags``, and
``ldlibs`` parameters. The values of these fields must be quoted on
the command line if they include spaces. These values are injected
into the compile line automatically by the Spack compiler wrappers.
into the compilation commands automatically by the Spack compiler wrappers.

.. literalinclude:: outputs/basics/zlib-O3.out
:language: console
Expand All @@ -158,7 +159,7 @@ installation directories for every combinatorial version. As we move into
more complicated packages with software dependencies, we can see that
Spack reuses existing packages to satisfy a dependency. By default, Spack
tries hard to reuse existing installations as dependencies, either from a local
store or from configured remote buildcaches. This minimizes unwanted rebuilds
store or from configured remote binary caches. This minimizes unwanted rebuilds
of common dependencies, in particular if you update Spack frequently.

.. literalinclude:: outputs/basics/tcl.out
Expand Down Expand Up @@ -193,7 +194,7 @@ even if it also appears as a dependency.

Let's move on to slightly more complicated packages. HDF5 is a
good example of a more complicated package, with an MPI dependency. If
we install it "out of the box," it will build with OpenMPI.
we install it with default settings, it will typically build with OpenMPI if no other MPI provider is specified.

.. literalinclude:: outputs/basics/hdf5.out
:language: console
Expand All @@ -209,17 +210,19 @@ Here we can install HDF5 without MPI support.
:language: console

We might also want to install HDF5 with a different MPI
implementation. While MPI is not a package itself, packages can depend on
abstract interfaces like MPI. Spack handles these through "virtual
dependencies." A package, such as HDF5, can depend on the MPI
interface. Other packages (``openmpi``, ``mpich``, ``mvapich2``, etc.)
provide the MPI interface. Any of these providers can be requested for
an MPI dependency. For example, we can build HDF5 with MPI support
provided by MPICH by specifying a dependency on ``mpich``. Spack also
supports versioning of virtual dependencies. A package can depend on the
MPI interface at version 3, and provider packages specify what version of
the interface *they* provide. The partial spec ``^mpi@3`` can be satisfied
by any of several providers.
implementation. While ``mpi`` itself is a virtual package representing an
interface, other packages can depend on such abstract interfaces. Spack
handles these through "virtual dependencies." A package, such as HDF5, can
depend on the ``mpi`` virtual package (the interface). Actual MPI implementation
packages (like ``openmpi``, ``mpich``, ``mvapich2``, etc.) "provide" this
virtual package. Any of these providers can be requested to satisfy an MPI
dependency. For example, we can build HDF5 with MPI support provided by
MPICH by specifying a dependency on ``mpich`` (e.g., ``hdf5 ^mpich``).
Spack also supports versioning of virtual dependencies. A package can depend
on the MPI interface at version 3 (e.g., ``hdf5 ^mpi@3``), and provider
packages specify what version of the interface *they* provide. The partial
spec ``^mpi@3`` can be satisfied by any of several MPI implementation packages
that provide MPI version 3.

.. literalinclude:: outputs/basics/hdf5-hl-mpi.out
:language: console
Expand All @@ -246,7 +249,7 @@ Now let's look at an even more complicated package.
:language: console

Now we're starting to see the power of Spack. Trilinos in its default
configuration has 23 top level dependencies, many of which have
configuration has 23 direct dependencies, many of which have
dependencies of their own. Installing more complex packages can take
days or weeks even for an experienced user. Although we've done a
binary installation for the tutorial, a source installation of
Expand Down Expand Up @@ -312,8 +315,10 @@ We can uninstall packages by spec using the same syntax as install.

We can also uninstall packages by referring only to their hash.

We can use either ``-f`` (force) or ``-R`` (remove dependents as well) to
remove packages that are required by another installed package.
We can use either the ``--force`` (or ``-f``) flag or the ``--dependents`` (or ``-R``)
flag to remove packages that are required by another installed package.
Use ``--force`` to remove just the specified package, leaving dependents broken.
Use ``--dependents`` to remove the specified package and all of its dependents.

.. literalinclude:: outputs/basics/uninstall-needed.out
:language: console
Expand All @@ -322,8 +327,9 @@ remove packages that are required by another installed package.
:language: console

Spack will not uninstall packages that are not sufficiently
specified. The ``-a`` (all) flag can be used to uninstall multiple
packages at once.
specified (i.e., if the spec is ambiguous and matches multiple installed packages).
The ``--all`` (or ``-a``) flag can be used to uninstall all packages matching
an ambiguous spec.

.. literalinclude:: outputs/basics/uninstall-ambiguous.out
:language: console
Expand Down Expand Up @@ -365,16 +371,16 @@ Customizing Compilers
---------------------

Spack manages a list of available compilers on the system, detected
automatically from the user's ``PATH`` variable. The ``spack
compilers`` command is an alias for the command ``spack compiler list``.
automatically from the user's ``PATH`` variable. The ``spack compilers``
command is an alias for ``spack compiler list``.

.. literalinclude:: outputs/basics/compilers.out
:language: console

The compilers are maintained in a YAML file. Later in the tutorial you
will learn how to configure compilers by hand for special cases. Spack
also has tools to add compilers, and compilers built with Spack can be
added to the configuration.
The compilers are maintained in a YAML file (``compilers.yaml``). Later in the
tutorial, you will learn how to configure compilers manually for special
cases. Spack also has tools to add compilers, and compilers built with Spack
can be added to the Spack compiler configuration.

.. literalinclude:: outputs/basics/install-gcc-12.1.0.out
:language: console
Expand All @@ -384,7 +390,8 @@ added to the configuration.

We can add GCC to Spack as an available compiler using the ``spack
compiler add`` command. This will allow future packages to build with
``gcc@12.3.0``. To avoid having to copy and paste GCC's path, we can use
this compiler (e.g., ``gcc@12.1.0`` as shown in the example output).
To avoid having to copy and paste GCC's path, we can use
``spack location -i`` to get the installation prefix.

.. literalinclude:: outputs/basics/compiler-add-location.out
Expand Down
Loading