You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: tutorial_basics.rst
+52-48Lines changed: 52 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,34 +8,34 @@
8
8
Basic Installation Tutorial
9
9
=========================================
10
10
11
-
This tutorial will guide you through the process of installing software using Spack.
12
-
We will first cover the ``spack install`` command, focusing on the power of the spec syntax and the flexibility it gives to users.
13
-
We will also cover the ``spack find`` command for viewing installed packages and the ``spack uninstall`` command for uninstalling them.
14
-
Finally, we will touch on how Spack manages compilers, especially as it relates to using Spack-built compilers within Spack.
15
-
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).
16
-
The provided output is all from an Ubuntu 22.04 Docker image.
11
+
This tutorial will provide a step-by-step guide for installing software with Spack.
12
+
We will begin by introducing the ``spack install`` command, highlighting the versatility of Spack’s spec syntax and the flexibility it offers users.
13
+
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.
14
+
15
+
Additionally, we will discuss how Spack manages compilers, with a particular focus on using Spack-built compilers within the Spack environment.
16
+
Throughout the tutorial, we will present complete command outputs; however, we will often emphasize only the most relevant sections or simply confirm successful execution.
17
+
All examples and outputs are based on an Ubuntu 22.04 Docker image.
17
18
18
19
.. _basics-tutorial-install:
19
20
20
21
----------------
21
22
Installing Spack
22
23
----------------
23
24
24
-
Spack works out of the box.
25
-
Simply clone Spack to get going.
26
-
We will clone Spack and immediately check out the most recent release, v0.23.
25
+
Spack is ready to use immediately after installation.
26
+
To get started, we simply clone the Spack repository and check out the latest release, v1.0.
27
27
28
28
.. literalinclude:: outputs/basics/clone.out
29
29
:language: console
30
30
31
-
Next, add Spack to your path.
32
-
Spack has some nice command line integration tools, so instead of simply prepending to your ``PATH`` variable, source the Spack setup script.
31
+
Next, we'll add Spack to our path.
32
+
Spack has some nice command line integration tools, so instead of simply prepending to our ``PATH`` variable, we'll source the Spack setup script.
33
33
34
34
.. code-block:: console
35
35
36
36
$ . share/spack/setup-env.sh
37
37
38
-
You're good to go!
38
+
And now we're good to go!
39
39
40
40
-----------------
41
41
What is in Spack?
@@ -49,8 +49,8 @@ The ``spack list`` command shows available packages.
49
49
50
50
51
51
The ``spack list`` command can also take a query string.
52
-
Spack automatically adds wildcards to both ends of the string, or you can add your own wildcards.
53
-
For example, we can view all available Python packages.
52
+
Spack automatically adds wildcards to both ends of the string, or we can add our own wildcards for more advanced searches.
53
+
For example, let's view all available Python packages.
54
54
55
55
.. literalinclude:: outputs/basics/list-py.out
56
56
:language: console
@@ -61,7 +61,7 @@ Installing Packages
61
61
-------------------
62
62
63
63
Installing a package with Spack is very simple.
64
-
To install a piece of software simply type,
64
+
To install a software package, type:
65
65
66
66
.. code-block:: console
67
67
@@ -72,33 +72,37 @@ Let's go ahead and install ``gmake``,
72
72
.. literalinclude:: outputs/basics/gmake.out
73
73
:language: console
74
74
75
-
You will see Spack installed ``gmake``, ``gcc-runtime``, and ``glibc``.
75
+
We see Spack installed ``gmake``, ``gcc-runtime``, and ``glibc``.
76
76
The ``glibc`` and ``gcc-runtime`` packages are automatically tracked by Spack to manage consistency requirements among compiler runtimes.
77
77
They do not represent separate software builds from source, but are records of the system's compiler runtime components Spack used for the install.
78
-
For the rest of this section, we will ignore these components and focus on the packages explicitly installed.
78
+
For the rest of this section, we'll ignore these components and focus on the packages explicitly installed.
79
79
80
80
Spack can install software either from source or from a binary cache.
81
81
Packages in the binary cache are signed with GPG for security.
82
-
For the tutorial we have prepared a binary cache so you don't have to wait on slow compilation from source.
83
-
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.
82
+
For this tutorial, we've prepared a binary cache so we don't have to wait for slow compilation from source.
83
+
84
+
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.
84
85
85
86
.. literalinclude:: outputs/basics/mirror.out
86
87
:language: console
87
88
88
-
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.
89
-
By default this will install the binary cached version if it exists and fall back on installing from source if it does not.
89
+
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.
90
+
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.
90
91
92
+
Now that we understand how Spack handles installations, let's explore how we can customize what gets installed.
91
93
Spack's "spec" syntax is the interface by which we can request specific configurations of a package.
92
-
The ``%`` sigil is used to specify compilers.
94
+
The ``%`` sigil is used to specify direct dependencies like a package's compiler.
95
+
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.
93
96
94
97
.. literalinclude:: outputs/basics/zlib-clang.out
95
98
:language: console
96
99
97
-
Note that this installation is located separately from the previous one.
98
-
We will discuss this in more detail later, but this is part of what allows Spack to support many versions of software packages.
100
+
Notice that this installation is located separately from the previous one.
101
+
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.
99
102
100
-
You can check for particular versions before requesting them.
101
-
We will use the ``spack versions`` command to see the available versions, and then install a different version of ``zlib-ng``.
103
+
Now that we've seen how Spack handles separate installations, let's explore this capability by installing multiple versions of the same package.
104
+
Before we install additional versions, we can check the versions available to us using the ```spack versions``` command.
105
+
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.
Spack accepts ``cppflags``, ``cflags``, ``cxxflags``, ``fflags``, ``ldflags``, and ``ldlibs`` parameters.
116
-
The values of these fields must be quoted on the command line if they include spaces.
117
-
These values are injected into the compilation commands automatically by the Spack compiler wrappers.
118
+
The spec syntax in Spack also supports compiler flags.
119
+
We can specify parameters such as ``cppflags``, ``cflags``, ``cxxflags``, ``fflags``, ``ldflags``, and ``ldlibs``.
120
+
If any of these values contain spaces, we'll need to enclose them in quotes on the command line.
121
+
Spack’s compiler wrappers will automatically inject these flags into the appropriate compilation commands.
118
122
119
123
.. literalinclude:: outputs/basics/zlib-O3.out
120
124
:language: console
121
125
122
-
The ``spack find`` command is used to query installed packages.
123
-
Note that some packages appear identical with the default output.
124
-
The ``-l`` flag shows the hash of each package, and the ``-f`` flag shows any non-empty compiler flags of those packages.
126
+
After installing packages, we can use the ``spack find`` command to query which packages are installed.
127
+
Notice that by default, some installed packages appear identical in the output.
128
+
To help distinguish between them, we can add the ``-l`` flag to display each package’s unique hash.
129
+
Additionally, if we include the ``-f`` flag, Spack will show any non-empty compiler flags that were used during installation.
125
130
126
131
.. literalinclude:: outputs/basics/find.out
127
132
:language: console
128
133
129
134
.. literalinclude:: outputs/basics/find-lf.out
130
135
:language: console
131
136
132
-
Spack generates a hash for each spec.
133
-
This hash is a function of the full provenance of the package, so any change to the spec affects the hash.
134
-
Spack uses this value to compare specs and to generate unique installation directories for every combinatorial version.
135
-
As we move into more complicated packages with software dependencies, we can see that Spack reuses existing packages to satisfy a dependency.
136
-
By default, Spack tries hard to reuse existing installations as dependencies, either from a local store or from configured remote binary caches.
137
-
This minimizes unwanted rebuilds of common dependencies, in particular if you update Spack frequently.
137
+
Spack generates a unique hash for each spec we define.
138
+
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.
139
+
Spack uses these hashes both to compare specs and to create unique installation directories for every possible configuration.
140
+
141
+
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.
142
+
By default, Spack prioritizes reusing installations that already exist, whether they are stored locally or available from configured remote binary caches.
143
+
This approach helps us avoid unnecessary rebuilds of common dependencies, which is especially valuable if we update Spack frequently.
138
144
139
145
.. literalinclude:: outputs/basics/tcl.out
140
146
:language: console
141
147
142
-
Dependencies can be explicitly requested using the ``^`` sigil.
143
-
Note that the spec syntax is recursive.
144
-
Anything we could specify about the top-level package, we can also specify about a dependency using ``^``.
148
+
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.
Packages can also be referred to from the command line by their package hash.
150
-
Using the ``spack find -lf`` command earlier we saw that the hash of our optimized installation of zlib-ng (``cflags="-O3"``) began with ``umrbkwv``.
151
-
We can now explicitly build with that package without typing the entire spec, by using the ``/`` sigil to refer to it by hash.
152
-
As with other tools like Git, you do not need to specify an *entire* hash on the command line.
153
-
You can specify just enough digits to identify a hash uniquely.
154
-
If a hash prefix is ambiguous (i.e., two or more installed packages share the prefix) then Spack will report an error.
153
+
We can also refer to packages from the command line by their package hash.
154
+
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``.
155
+
Instead of typing out the entire spec, we can now build explicitly with that package by using the ``/`` sigil followed by its hash.
156
+
157
+
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.
158
+
If the prefix we provide matches more than one installed package, Spack will report an error and prompt us to be more specific.
0 commit comments