From 31607dd994338cd98948dcbefb344aafa9db4dcd Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Tue, 3 Jun 2025 12:25:20 -0700 Subject: [PATCH 01/10] Rewriting the start of the basics tutorial --- tutorial_basics.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index 32ec1c95c1..40ce7974b4 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -8,12 +8,13 @@ Basic Installation Tutorial ========================================= -This tutorial will guide you through the process of installing software using Spack. -We will first cover the ``spack install`` command, focusing on the power of the spec syntax and the flexibility it gives to users. -We will also cover the ``spack find`` command for viewing installed packages and the ``spack uninstall`` command for uninstalling them. -Finally, we will touch on how Spack manages compilers, especially as it relates to using Spack-built compilers within Spack. -We will include full output from all of the commands demonstrated, although we will frequently call attention to only small portions of that output (or merely to the fact that it succeeded). -The provided output is all from an Ubuntu 22.04 Docker image. +This tutorial will provide a step-by-step guide for installing software with Spack. +We will begin by introducing the ``spack install`` command, highlighting the versatility of Spack’s spec syntax and the flexibility it offers users. +Next, we will demonstrate how to use the ``spack find`` command to view installed packages, as well as the ``spack uninstall`` command to remove them. + +Additionally, we will discuss how Spack manages compilers, with a particular focus on using Spack-built compilers within the Spack environment. +Throughout the tutorial, we will present complete command outputs; however, we will often emphasize only the most relevant sections or simply confirm successful execution. +All examples and outputs are based on an Ubuntu 22.04 Docker image. .. _basics-tutorial-install: @@ -21,15 +22,14 @@ The provided 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 is ready to use immediately after installation. +To get started, we simply clone the Spack repository and check out the latest release, v1.0. .. literalinclude:: outputs/basics/clone.out :language: console -Next, add Spack to your path. -Spack has some nice command line integration tools, so instead of simply prepending to your ``PATH`` variable, source the Spack setup script. +Next, we'll add Spack to our path. +Spack has some nice command-line integration tools, so instead of simply prepending to our ``PATH`` variable, let's source the Spack setup script. .. code-block:: console From 27c5f29ae1010d37bab9ff11ab9ff279defc73a6 Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Tue, 3 Jun 2025 12:45:15 -0700 Subject: [PATCH 02/10] Additional syntax improvements --- tutorial_basics.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index 40ce7974b4..2c442e64fb 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -29,13 +29,13 @@ To get started, we simply clone the Spack repository and check out the latest re :language: console Next, we'll add Spack to our path. -Spack has some nice command-line integration tools, so instead of simply prepending to our ``PATH`` variable, let's source the Spack setup script. +Spack has some nice command-line integration tools, so instead of simply prepending to our ``PATH`` variable, we'll source the Spack setup script. .. code-block:: console $ . share/spack/setup-env.sh -You're good to go! +And now we're good to go! ----------------- What is in Spack? @@ -49,8 +49,8 @@ The ``spack list`` command shows available packages. The ``spack list`` command can also take a query string. -Spack automatically adds wildcards to both ends of the string, or you can add your own wildcards. -For example, we can view all available Python packages. +Spack automatically adds wildcards to both ends of the string, or we can add our own wildcards for more advanced searches. +For example, let's view all available Python packages. .. literalinclude:: outputs/basics/list-py.out :language: console @@ -61,7 +61,7 @@ Installing Packages ------------------- Installing a package with Spack is very simple. -To install a piece of software simply type, +To install a software package type, .. code-block:: console @@ -72,21 +72,21 @@ Let's go ahead and install ``gmake``, .. literalinclude:: outputs/basics/gmake.out :language: console -You will see Spack installed ``gmake``, ``gcc-runtime``, and ``glibc``. +We 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. They do not represent separate software builds from source, but are records of the system's compiler runtime components Spack used for the install. -For the rest of this section, we will ignore these components and focus on the packages explicitly installed. +For the rest of this section, we'll ignore these 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 security. -For the tutorial we have prepared a binary cache so you don't have to wait on slow compilation from source. -To be able to install from the binary cache, we will need to configure Spack with the location of the binary cache and trust the GPG key that the binary cache was signed with. +For the tutorial we prepared a binary cache so we don't have to wait on slow compilation from source. +To enable installation from the binary cache, we'll need to configure Spack with the location of the cache and trust the GPG key that the cache was signed with. .. literalinclude:: outputs/basics/mirror.out :language: console -You'll learn more about configuring Spack later in the tutorial, but for now you will be able to install the rest of the packages in the 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. +We'll learn more about configuring Spack later in the tutorial, but for now we will be able to install the rest of the packages in the tutorial from the cache using the same ``spack install`` command. +By default this will install the binary cached version if it exists and fall back to install the package from source if it does not. Spack's "spec" syntax is the interface by which we can request specific configurations of a package. The ``%`` sigil is used to specify compilers. From f2b5f4a4a31661e7e1fc9d2acce81554b964f67f Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Tue, 3 Jun 2025 16:49:18 -0700 Subject: [PATCH 03/10] Additional syntax improvements --- tutorial_basics.rst | 68 +++++++++++++++++++++++++-------------------- 1 file changed, 38 insertions(+), 30 deletions(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index 2c442e64fb..e1a083aa8f 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -79,26 +79,30 @@ For the rest of this section, we'll ignore these components and focus on the pac Spack can install software either from source or from a binary cache. Packages in the binary cache are signed with GPG for security. -For the tutorial we prepared a binary cache so we don't have to wait on slow compilation from source. +For this tutorial, we've prepared a binary cache so we don't have to wait for slow compilation from source. + To enable installation from the binary cache, we'll need to configure Spack with the location of the cache and trust the GPG key that the cache was signed with. .. literalinclude:: outputs/basics/mirror.out :language: console -We'll learn more about configuring Spack later in the tutorial, but for now we will be able to install the rest of the packages in the tutorial from the cache using the same ``spack install`` command. -By default this will install the binary cached version if it exists and fall back to install the package from source if it does not. +We'll learn more about configuring Spack later in the tutorial, but for now we can install the rest of the packages in the tutorial from the cache using the same ```spack install``` command. +By default, this will install the binary cached version if it exists and fall back to installing the package from source if it does not. +Now that we understand how Spack handles installations, let's explore how we can customize what gets installed. Spack's "spec" syntax is the interface by which we can request specific configurations of a package. -The ``%`` sigil is used to specify compilers. +The ``%`` sigil is used to specify direct dependencies like a package's compiler. +For example, we can install zlib (a commonly used compression library), but instead of building it with the GCC compiler as we did for gmake previously, we'll install it with ``%clang`` to build it on top of the clang compiler. .. 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 many versions of software packages. +Notice that this installation is located separately from the previous one. +We'll explore this concept in more detail later, but this separation is fundamental to how Spack supports multiple configurations and versions of software packages simultaneously. -You can check for particular versions before requesting them. -We will use the ``spack versions`` command to see the available versions, and then install a different version of ``zlib-ng``. +Now that we've seen how Spack handles separate installations, let's explore this capability further by installing multiple versions of the same package. +Before we install additional versions, we can check what versions are available to us using the ```spack versions``` command. +Let's check what versions of zlib-ng are available, and then we'll install a different version to demonstrate Spack's flexibility in managing multiple package versions. .. literalinclude:: outputs/basics/versions-zlib.out :language: console @@ -111,17 +115,22 @@ The ``@`` sigil is used to specify versions, both of packages and of compilers. .. literalinclude:: outputs/basics/zlib-gcc-10.out :language: console -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 compilation commands automatically by the Spack compiler wrappers. +The spec syntax in Spack also supports compiler flags. +We can specify parameters such as ``cppflags``, ``cflags``, ``cxxflags``, ``fflags``, ``ldflags``, and ``ldlibs``. +If any of these values contain spaces, we'll need to enclose them in quotes on the command line. +Spack’s compiler wrappers will automatically inject these flags into the appropriate compilation commands. .. literalinclude:: outputs/basics/zlib-O3.out :language: console -The ``spack find`` command is used to query installed packages. -Note that some packages appear identical with the default output. -The ``-l`` flag shows the hash of each package, and the ``-f`` flag shows any non-empty compiler flags of those packages. +After installing packages, we can use the ``spack find`` command to query which packages are installed. +Notice that by default, some installed packages appear identical in the output. +To help distinguish between them, we can add the ``-l`` flag to display each package’s unique hash. +Additionally if we include the ``-f`` flag, Spack will show any non-empty compiler flags that were used during installation. + +We use the ``spack find`` command to query which packages are installed. +Note that, with the default output, some packages may appear identical. To distinguish between them, we can use the ``-l`` flag to display the hash of each package. +Additionally, if we include the ``-f`` flag, Spack will show any non-empty compiler flags that were used during installation. .. literalinclude:: outputs/basics/find.out :language: console @@ -129,29 +138,28 @@ The ``-l`` flag shows the hash of each package, and the ``-f`` flag shows any no .. literalinclude:: outputs/basics/find-lf.out :language: console -Spack generates a hash for each spec. -This hash is a function of the full provenance of the package, so any change to the spec affects the hash. -Spack uses this value to compare specs and to generate unique 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 binary caches. -This minimizes unwanted rebuilds of common dependencies, in particular if you update Spack frequently. +Spack generates a unique hash for each spec we define. +This hash reflects the complete provenance of the package, so any change to the spec—such as compiler version, build options, or dependencies—will result in a different hash. +Spack uses these hashes both to compare specs and to create unique installation directories for every possible configuration. + +As we work with more complex packages that have multiple software dependencies, we will see that Spack efficiently reuses existing packages to satisfy dependency requirements. +By default, Spack prioritizes reusing installations that already exist, whether they are stored locally or available from configured remote binary caches. +This approach helps us avoid unnecessary rebuilds of common dependencies, which is especially valuable if we update Spack frequently. .. literalinclude:: outputs/basics/tcl.out :language: console -Dependencies can be explicitly requested using the ``^`` sigil. -Note that the spec syntax is recursive. -Anything we could specify about the top-level package, we can also specify about a dependency using ``^``. +When we need to specify dependencies explicitly, we use the ``^`` sigil in the spec syntax. The syntax is recursive, meaning that anything we can specify for the top-level package can also be specified for a dependency using ``^``. This allows us to precisely control the configuration of both packages and their dependencies. .. literalinclude:: outputs/basics/tcl-zlib-clang.out :language: console -Packages can also be referred to from the command line by their package hash. -Using the ``spack find -lf`` command earlier we saw that the hash of our optimized installation of zlib-ng (``cflags="-O3"``) began with ``umrbkwv``. -We can now explicitly build with that package without typing the entire spec, by using the ``/`` sigil to refer to it by hash. -As with other tools like Git, you do not need to specify an *entire* hash on the command line. -You can specify just enough digits to identify a hash uniquely. -If a hash prefix is ambiguous (i.e., two or more installed packages share the prefix) then Spack will report an error. +We can also refer to packages from the command line by their package hash. +Earlier, when we used the ``spack find -lf`` command, we saw that the hash for our optimized installation of zlib-ng (with ``cflags="-O3"``) began with ``umrbkwv``. +Instead of typing out the entire spec, we can now build explicitly with that package by using the ``/`` sigil followed by its hash. + +Similar to tools like Git, we do not need to enter the entire hash on the command line—just enough digits to uniquely identify the package. +If the prefix we provide matches more than one installed package, Spack will report an error and prompt us to be more specific. .. literalinclude:: outputs/basics/tcl-zlib-hash.out :language: console From aed60997751e91b79c1eb8054dc0c46e53f0fd14 Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Tue, 3 Jun 2025 16:50:36 -0700 Subject: [PATCH 04/10] Fix style for sentences --- tutorial_basics.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index e1a083aa8f..abe6f37037 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -129,7 +129,8 @@ To help distinguish between them, we can add the ``-l`` flag to display each pac Additionally if we include the ``-f`` flag, Spack will show any non-empty compiler flags that were used during installation. We use the ``spack find`` command to query which packages are installed. -Note that, with the default output, some packages may appear identical. To distinguish between them, we can use the ``-l`` flag to display the hash of each package. +Note that, with the default output, some packages may appear identical. +To distinguish between them, we can use the ``-l`` flag to display the hash of each package. Additionally, if we include the ``-f`` flag, Spack will show any non-empty compiler flags that were used during installation. .. literalinclude:: outputs/basics/find.out From 0a64996a90eb7e54f41080b3a16c523d9895bea8 Mon Sep 17 00:00:00 2001 From: Alec Scott <19558067+alecbcs@users.noreply.github.com> Date: Tue, 3 Jun 2025 17:11:53 -0700 Subject: [PATCH 05/10] Update tutorial_basics.rst Co-authored-by: Caetano Melone --- tutorial_basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index abe6f37037..c818496b2d 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -100,7 +100,7 @@ For example, we can install zlib (a commonly used compression library), but inst Notice that this installation is located separately from the previous one. We'll explore this concept in more detail later, but this separation is fundamental to how Spack supports multiple configurations and versions of software packages simultaneously. -Now that we've seen how Spack handles separate installations, let's explore this capability further by installing multiple versions of the same package. +Now that we've seen how Spack handles separate installations, let's explore this capability by installing multiple versions of the same package. Before we install additional versions, we can check what versions are available to us using the ```spack versions``` command. Let's check what versions of zlib-ng are available, and then we'll install a different version to demonstrate Spack's flexibility in managing multiple package versions. From 697decc5899e1d14b34d374e57a6d3aea549969c Mon Sep 17 00:00:00 2001 From: Alec Scott <19558067+alecbcs@users.noreply.github.com> Date: Tue, 3 Jun 2025 17:13:13 -0700 Subject: [PATCH 06/10] Update tutorial_basics.rst Co-authored-by: Caetano Melone --- tutorial_basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index c818496b2d..95e441b5c3 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -101,7 +101,7 @@ Notice that this installation is located separately from the previous one. We'll explore this concept in more detail later, but this separation is fundamental to how Spack supports multiple configurations and versions of software packages simultaneously. Now that we've seen how Spack handles separate installations, let's explore this capability by installing multiple versions of the same package. -Before we install additional versions, we can check what versions are available to us using the ```spack versions``` command. +Before we install additional versions, we can check the versions available to us using the ```spack versions``` command. Let's check what versions of zlib-ng are available, and then we'll install a different version to demonstrate Spack's flexibility in managing multiple package versions. .. literalinclude:: outputs/basics/versions-zlib.out From b090f75d6ffe5cd8d8d062aea1a2345216f9f198 Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Tue, 3 Jun 2025 17:21:09 -0700 Subject: [PATCH 07/10] Command line not command-line --- tutorial_basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index 95e441b5c3..a4488ccc4b 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -29,7 +29,7 @@ To get started, we simply clone the Spack repository and check out the latest re :language: console Next, we'll add Spack to our path. -Spack has some nice command-line integration tools, so instead of simply prepending to our ``PATH`` variable, we'll source the Spack setup script. +Spack has some nice command line integration tools, so instead of simply prepending to our ``PATH`` variable, we'll source the Spack setup script. .. code-block:: console From c12167741e01d142904f8f8fbf8c95d0e4fb22b5 Mon Sep 17 00:00:00 2001 From: Alec Scott <19558067+alecbcs@users.noreply.github.com> Date: Tue, 3 Jun 2025 17:24:10 -0700 Subject: [PATCH 08/10] Update tutorial_basics.rst Co-authored-by: Caetano Melone --- tutorial_basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index a4488ccc4b..4aaed76578 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -61,7 +61,7 @@ Installing Packages ------------------- Installing a package with Spack is very simple. -To install a software package type, +To install a software package, type: .. code-block:: console From cda2d68eec3e73105c648a868fca8a5ab21de44b Mon Sep 17 00:00:00 2001 From: Alec Scott <19558067+alecbcs@users.noreply.github.com> Date: Tue, 3 Jun 2025 17:25:01 -0700 Subject: [PATCH 09/10] Update tutorial_basics.rst Co-authored-by: Caetano Melone --- tutorial_basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index 4aaed76578..d89cbb3386 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -126,7 +126,7 @@ Spack’s compiler wrappers will automatically inject these flags into the appro After installing packages, we can use the ``spack find`` command to query which packages are installed. Notice that by default, some installed packages appear identical in the output. To help distinguish between them, we can add the ``-l`` flag to display each package’s unique hash. -Additionally if we include the ``-f`` flag, Spack will show any non-empty compiler flags that were used during installation. +Additionally, if we include the ``-f`` flag, Spack will show any non-empty compiler flags that were used during installation. We use the ``spack find`` command to query which packages are installed. Note that, with the default output, some packages may appear identical. From e19cfeff7f318553b76e7d8e72412aa09499f0c5 Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Tue, 3 Jun 2025 17:26:48 -0700 Subject: [PATCH 10/10] Remove original text for rewrite --- tutorial_basics.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index d89cbb3386..9c9f7f80d3 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -128,11 +128,6 @@ Notice that by default, some installed packages appear identical in the output. To help distinguish between them, we can add the ``-l`` flag to display each package’s unique hash. Additionally, if we include the ``-f`` flag, Spack will show any non-empty compiler flags that were used during installation. -We use the ``spack find`` command to query which packages are installed. -Note that, with the default output, some packages may appear identical. -To distinguish between them, we can use the ``-l`` flag to display the hash of each package. -Additionally, if we include the ``-f`` flag, Spack will show any non-empty compiler flags that were used during installation. - .. literalinclude:: outputs/basics/find.out :language: console