From 58d6a8d3b6d9b6d07d96758c5ff84ee27090c035 Mon Sep 17 00:00:00 2001 From: Harmen Stoppels Date: Wed, 6 Aug 2025 12:18:05 +0200 Subject: [PATCH 1/2] add spec highlighting --- _static/css/custom.css | 4 ++ conf.py | 78 ++++++++++++++++++++++++++++++++ tutorial_basics.rst | 76 +++++++++++++++---------------- tutorial_binary_cache.rst | 6 +-- tutorial_configuration.rst | 18 ++++---- tutorial_developer_workflows.rst | 20 ++++---- tutorial_environments.rst | 27 ++++++----- tutorial_modules.rst | 11 +++-- tutorial_packaging.rst | 12 ++--- tutorial_scripting.rst | 2 +- tutorial_stacks.rst | 14 +++--- 11 files changed, 174 insertions(+), 94 deletions(-) diff --git a/_static/css/custom.css b/_static/css/custom.css index 091c2fffb5..2ae3d11b7c 100644 --- a/_static/css/custom.css +++ b/_static/css/custom.css @@ -43,3 +43,7 @@ div.version-switch select:hover { .toc-tree li.scroll-current>.reference { font-weight: normal; } + +.highlight .go { + color: #333; +} \ No newline at end of file diff --git a/conf.py b/conf.py index 89162683e9..4dfb2e85f8 100644 --- a/conf.py +++ b/conf.py @@ -20,6 +20,10 @@ from sphinx.domains.python import PythonDomain +from pygments.lexer import RegexLexer, default +from pygments.token import * + + # -- Spack customizations ----------------------------------------------------- # Add the Spack bin directory to the path so that we can use its output in docs. os.environ["SPACK_ROOT"] = os.path.abspath("_spack_root") @@ -29,9 +33,80 @@ os.environ["COLIFY_SIZE"] = "25x120" os.environ["COLUMNS"] = "120" +sys.path.insert(0, os.path.abspath("_spack_root/lib/spack/")) + # Enable todo items todo_include_todos = True +from spack.spec_parser import SpecTokens + + +class SpecLexer(RegexLexer): + """A custom lexer for Spack spec strings and spack commands.""" + + name = "Spack spec" + aliases = ["spec"] + filenames = [] + tokens = { + "root": [ + # Looks for `$ command`, which may need spec highlighting. + (r"^\$\s+", Generic.Prompt, "command"), + (r"#.*?\n", Comment.Single), + # Alternatively, we just get a literal spec string, so we move to spec mode. We just + # look ahead here, without consuming the spec string. + (r"(?=\S+)", Generic.Prompt, "spec"), + ], + "command": [ + # A spack install command is followed by a spec string, which we highlight. + ( + r"spack(?:\s+(?:-[eC]\s+\S+|--?\S+))*\s+(?:install|uninstall|spec|load|unload|find|info|list|versions|providers|mark|diff|add|develop)(?: +(?:--?\S+)?)*", + Text, + "spec", + ), + # Comment + (r"\s+#.*?\n", Comment.Single, "command_output"), + # Escaped newline should leave us in this mode + (r".*?\\\n", Text), + # Otherwise, it's the end of the command + (r".*?\n", Text, "command_output"), + ], + "command_output": [ + (r"^\$\s+", Generic.Prompt, "#pop"), # new command + (r"#.*?\n", Comment.Single), # comments + (r".*?\n", Generic.Output), # command output + ], + "spec": [ + # New line terminates the spec string + (r"\s*?$", Text, "#pop"), + # Dependency, with optional virtual assignment specifier + (SpecTokens.START_EDGE_PROPERTIES.regex, Name.Variable, "edge_properties"), + (SpecTokens.DEPENDENCY.regex, Name.Variable), + # versions + (SpecTokens.VERSION_HASH_PAIR.regex, Keyword.Pseudo), + (SpecTokens.GIT_VERSION.regex, Keyword.Pseudo), + (SpecTokens.VERSION.regex, Keyword.Pseudo), + # variants + (SpecTokens.PROPAGATED_BOOL_VARIANT.regex, Name.Function), + (SpecTokens.BOOL_VARIANT.regex, Name.Function), + (SpecTokens.PROPAGATED_KEY_VALUE_PAIR.regex, Name.Function), + (SpecTokens.KEY_VALUE_PAIR.regex, Name.Function), + # filename + (SpecTokens.FILENAME.regex, Text), + # Package name + (SpecTokens.FULLY_QUALIFIED_PACKAGE_NAME.regex, Name.Class), + (SpecTokens.UNQUALIFIED_PACKAGE_NAME.regex, Name.Class), + # DAG hash + (SpecTokens.DAG_HASH.regex, Text), + (SpecTokens.WS.regex, Text), + # Also stop at unrecognized tokens (without consuming them) + default("#pop"), + ], + "edge_properties": [ + (SpecTokens.KEY_VALUE_PAIR.regex, Name.Function), + (SpecTokens.END_EDGE_PROPERTIES.regex, Name.Variable, "#pop"), + ], + } + # # Disable duplicate cross-reference warnings. @@ -47,6 +122,7 @@ def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): def setup(sphinx): sphinx.add_domain(PatchedPythonDomain, override=True) + sphinx.add_lexer("spec", SpecLexer) # -- General configuration ----------------------------------------------------- @@ -143,6 +219,8 @@ def setup(sphinx): # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = "furo" +pygments_style = "default" +pygments_dark_style = "monokai" # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = ["_themes"] diff --git a/tutorial_basics.rst b/tutorial_basics.rst index 5061d18127..79b026bc78 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -75,7 +75,7 @@ To install a software package, type: Let's go ahead and install ``gmake``, .. literalinclude:: outputs/basics/gmake.out - :language: console + :language: spec You will see Spack installed ``gmake``, ``gcc``, ``gcc-runtime``, and ``glibc``. The ``glibc`` and ``gcc-runtime`` packages are automatically tracked by Spack to manage consistency requirements among compiler runtimes. @@ -108,7 +108,7 @@ 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 with the clang compiler. .. literalinclude:: outputs/basics/zlib-clang.out - :language: console + :language: spec 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. @@ -118,17 +118,17 @@ Before we install additional versions, we can check the versions available to us 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 + :language: spec The ``@`` sigil is used to specify versions. .. literalinclude:: outputs/basics/zlib-2.0.7.out - :language: console + :language: spec The spec syntax is recursive -- any syntax we can specify for the "root" package (``zlib-ng``) we can also use for a dependency. .. literalinclude:: outputs/basics/zlib-gcc-10.out - :language: console + :language: spec The spec syntax in Spack also supports compiler flags. We can specify parameters such as ``cppflags``, ``cflags``, ``cxxflags``, ``fflags``, ``ldflags``, and ``ldlibs``. @@ -136,7 +136,7 @@ If any of these values contain spaces, we'll need to enclose them in quotes on t Spack’s compiler wrappers will automatically inject these flags into the appropriate compilation commands. .. literalinclude:: outputs/basics/zlib-O3.out - :language: console + :language: spec 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. @@ -144,10 +144,10 @@ 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. .. literalinclude:: outputs/basics/find.out - :language: console + :language: spec .. literalinclude:: outputs/basics/find-lf.out - :language: console + :language: spec Spack generates a unique hash for each spec. 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. @@ -158,14 +158,14 @@ By default, Spack prioritizes reusing installations that already exist, whether 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 + :language: spec Sometimes it is simpler to specify dependencies without caring whether they are direct or transitive dependencies. To do that, use the ``^`` sigil. Note that a dependency specified by ``^`` is always applied to the root package, whereas a direct dependency specified by ``%`` is applied to either the root or any intervening dependency specified by ``^``. .. literalinclude:: outputs/basics/tcl-zlib-clang.out - :language: console + :language: spec 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``. @@ -175,20 +175,20 @@ Similar to tools like Git, we do not need to enter the entire hash on the comman 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 + :language: spec The ``spack find`` command can also take a ``-d`` flag, which can show dependency information. Note that each package has a top-level entry, even if it also appears as a dependency. .. literalinclude:: outputs/basics/find-ldf.out - :language: console + :language: spec Spack models the dependencies of packages as a directed acyclic graph (DAG). The ``spack find -d`` command shows the tree representation of that graph, which loses some dependency relationship information. We can also use the ``spack graph`` command to view the entire DAG as a graph. .. literalinclude:: outputs/basics/graph-tcl.out - :language: console + :language: spec Let's move on to slightly more complicated packages. HDF5 is a good example of a more complicated package, with an MPI dependency. @@ -197,12 +197,12 @@ We can check the install plan in advance to ensure it's what we want to install The ``spack spec`` command accepts the same spec syntax. .. literalinclude:: outputs/basics/hdf5-spec.out - :language: console + :language: spec Assuming we're happy with that configuration, we will now install it. .. literalinclude:: outputs/basics/hdf5.out - :language: console + :language: spec Spack packages can also have build options, called variants. Boolean variants can be specified using the ``+`` (enable) and ``~`` or ``-`` @@ -212,7 +212,7 @@ Variants (boolean or otherwise) can also be specified using the same syntax as c Here we can install HDF5 without MPI support. .. literalinclude:: outputs/basics/hdf5-no-mpi.out - :language: console + :language: spec We might also want to install HDF5 with a different MPI implementation. While ``mpi`` itself is a virtual package representing an interface, other packages can depend on such abstract interfaces. @@ -231,7 +231,7 @@ We call this "virtual assignment", and can be specified by ``%virtual=provider`` For example if we wanted to install hdf5 using GCC for the C and C++ components but Intel OneAPI for the Fortran compiler we could write: -.. code-block:: none +.. code-block:: spec hdf5 %c,cxx=gcc %fortran=oneapi @@ -240,7 +240,7 @@ We could use the same syntax for ``^mpi=mpich``, but there's no need because the This is also why we didn't care to specify which virtuals ``gcc`` and ``clang`` provided earlier when building simpler packages. .. literalinclude:: outputs/basics/hdf5-hl-mpi.out - :language: console + :language: spec .. note:: @@ -252,13 +252,13 @@ This is also why we didn't care to specify which virtuals ``gcc`` and ``clang`` We'll do a quick check in on what we have installed so far. .. literalinclude:: outputs/basics/find-ldf-2.out - :language: console + :language: spec HDF5 is more complicated than our basic example of zlib-ng and Tcl, but it's still within the realm of software that an experienced HPC user could reasonably expect to manually install given a bit of time. Now let's look at an even more complicated package. .. literalinclude:: outputs/basics/trilinos.out - :language: console + :language: spec Now we're starting to see the power of Spack. Depending on the spec, Trilinos can have over 30 direct dependencies, many of which have dependencies of their own. @@ -270,19 +270,19 @@ Every MPI dependency will be satisfied by the same configuration of MPI, etc. If we install Trilinos again specifying a dependency on our previous HDF5 built with MPICH: .. literalinclude:: outputs/basics/trilinos-hdf5.out - :language: console + :language: spec We see that every package in the Trilinos DAG that depends on MPI now uses MPICH. .. literalinclude:: outputs/basics/find-d-trilinos.out - :language: console + :language: spec As we discussed before, the ``spack find -d`` command shows the dependency information as a tree. While that is often sufficient, many complicated packages, including Trilinos, have dependencies that cannot be fully represented as a tree. Again, the ``spack graph`` command shows the full DAG of the dependency information. .. literalinclude:: outputs/basics/graph-trilinos.out - :language: console + :language: spec You can control how the output is displayed with a number of options. @@ -303,18 +303,18 @@ Earlier we installed many configurations each of zlib-ng and Tcl. Now we will go through and uninstall some of those packages that we didn't really need. .. literalinclude:: outputs/basics/find-d-tcl.out - :language: console + :language: spec .. literalinclude:: outputs/basics/find-zlib.out - :language: console + :language: spec We can uninstall packages by spec using the same syntax as install. .. literalinclude:: outputs/basics/uninstall-zlib.out - :language: console + :language: spec .. literalinclude:: outputs/basics/find-lf-zlib.out - :language: console + :language: spec We can also uninstall packages by referring only to their hash. @@ -323,19 +323,19 @@ 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 + :language: spec .. literalinclude:: outputs/basics/uninstall-r-needed.out - :language: console + :language: spec Spack will not uninstall packages that are not sufficiently 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 + :language: spec .. literalinclude:: outputs/basics/uninstall-specific.out - :language: console + :language: spec ----------------------------- Advanced ``spack find`` Usage @@ -348,17 +348,17 @@ The ``spack find`` command can accept what we call "anonymous specs." These are For example, ``spack find ^mpich`` will return every installed package that depends on MPICH, and ``spack find cflags="-O3"`` will return every package which was built with ``cflags="-O3"``. .. literalinclude:: outputs/basics/find-dep-mpich.out - :language: console + :language: spec .. literalinclude:: outputs/basics/find-O3.out - :language: console + :language: spec The ``find`` command can also show which packages were installed explicitly (rather than pulled in as a dependency) using the lowercase ``-x`` flag. The uppercase ``-X`` flag shows implicit installs only. The ``find`` command can also show the path to which a Spack package was installed using the ``-p`` flag. .. literalinclude:: outputs/basics/find-px.out - :language: console + :language: spec --------------------- Customizing Compilers @@ -375,22 +375,22 @@ Later in the tutorial we will discuss how to configure external compilers by han Spack can also use compilers built by Spack to compile later packages. .. literalinclude:: outputs/basics/install-gcc-12.1.0.out - :language: console + :language: spec .. literalinclude:: outputs/basics/compilers-2.out - :language: console + :language: spec Because this compiler is a newer version than the external compilers Spack knows about, it will be the new default compiler. We will discuss changing these defaults in a later section. We can check that this compiler is preferred by looking at the install plan for a package that isn't being reused from binary. .. literalinclude:: outputs/basics/spec-zziplib - :language: console + :language: spec For the test of the tutorial we will sometimes use this new compiler, and sometimes we want to demonstrate things without it. For now, we will uninstall it to avoid using it in the next section. .. literalinclude:: outputs/basics/compiler-uninstall.out - :language: console + :language: spec .. note:: diff --git a/tutorial_binary_cache.rst b/tutorial_binary_cache.rst index 5531401c3b..e7be55b6ec 100644 --- a/tutorial_binary_cache.rst +++ b/tutorial_binary_cache.rst @@ -17,7 +17,7 @@ Spack supports a range of storage backends, such as an ordinary filesystem, Amaz Before we configure a build cache, let's install the ``julia`` package, which is an interesting example because it has some non-trivial dependencies like ``llvm``, and features an interactive REPL that we can use to verify that the installation works. -.. code-block:: console +.. code-block:: spec $ mkdir ~/myenv && cd ~/myenv $ spack env create --with-view view . @@ -145,7 +145,7 @@ The easiest way to do this is to override the ``mirrors`` config section in the An "overwrite install" should be enough to show that the build cache is used (output will vary based on your specific configuration): -.. code-block:: console +.. code-block:: spec $ spack -e . install --overwrite julia ==> Fetching https://ghcr.io/v2//buildcache--/blobs/sha256:34f4aa98d0a2c370c30fbea169a92dd36978fc124ef76b0a6575d190330fda51 @@ -251,7 +251,7 @@ Let's add a simple text editor like ``vim`` to our previous environment next to You may want to change ``mirrors::`` to ``mirrors:`` in the ``spack.yaml`` file to avoid a source build of ``vim`` --- but a source build should be quick. -.. code-block:: console +.. code-block:: spec $ spack -e . install --add vim diff --git a/tutorial_configuration.rst b/tutorial_configuration.rst index cccaa69c2c..f48aa5d5e0 100644 --- a/tutorial_configuration.rst +++ b/tutorial_configuration.rst @@ -251,7 +251,7 @@ We can do this by adding creating a toolchain config: We are essentially saying "use Clang for c/c++, and use GCC for Fortran". You can use this new entry like so: -.. code-block:: console +.. code-block:: spec $ spack spec openblas %clang_gfortran @@ -292,7 +292,7 @@ Let's open our compilers configuration file again and add a compiler flag: We can test this out using the ``spack spec`` command to show how the spec is concretized: .. literalinclude:: outputs/config/0.compiler_flags.out - :language: console + :language: spec We can see that ``cppflags="-g"`` has been added to every node in the DAG. @@ -370,7 +370,7 @@ To illustrate how this works, suppose we want to change the preferences to prefe Currently, we prefer GCC and OpenMPI. .. literalinclude:: outputs/config/0.prefs.out - :language: console + :language: spec :emphasize-lines: 15 @@ -413,7 +413,7 @@ We see if we retry that we now get what we want without getting any more specifi .. Because of the configuration scoping we discussed earlier, this overrides the default settings just for these two items. .. literalinclude:: outputs/config/1.prefs.out - :language: console + :language: spec :emphasize-lines: 16 @@ -447,7 +447,7 @@ Instead, we'll update our config to force disable it: Note if you define ``require`` under ``all`` and ``hdf5``, you must reintroduce any requirements in ``hdf5``. .. literalinclude:: outputs/config/3.prefs.out - :language: console + :language: spec :emphasize-lines: 2 @@ -495,7 +495,7 @@ Finally, we set ``buildable: false`` to require that Spack not try to build its .. The weighting/preferences dont work quite the same so I skipped right to buildable:false .. literalinclude:: outputs/config/2.externals.out - :language: console + :language: spec This gets slightly more complicated with virtual dependencies. @@ -543,7 +543,7 @@ If you run this as-is, you'll notice Spack still hasn't built ``hdf5`` with our The concretizer has instead turned off ``mpi`` support in ``hdf5``. To debug this, we will force Spack to use ``hdf5+mpi``. -.. code-block:: console +.. code-block:: spec $ spack spec hdf5+mpi ==> Error: failed to concretize `hdf5+mpi` for the following reasons: @@ -654,7 +654,7 @@ One last setting that may be of interest to many users is the ability to customi By default, Spack installs all packages in parallel with the number of jobs equal to the number of cores on the node (up to a maximum of 16). For example, on a node with 16 cores, this will look like: -.. code-block:: console +.. code-block:: spec $ spack install --no-cache --verbose --overwrite --yes-to-all zlib ==> Installing zlib @@ -686,7 +686,7 @@ To limit the number of cores our build uses, set ``build_jobs`` like so: If we uninstall and reinstall zlib-ng, we see that it now uses only 2 cores: -.. code-block:: console +.. code-block:: spec $ spack install --no-cache --verbose --overwrite --yes-to-all zlib-ng ==> Installing zlib diff --git a/tutorial_developer_workflows.rst b/tutorial_developer_workflows.rst index c1748ab3b5..7b0d592422 100644 --- a/tutorial_developer_workflows.rst +++ b/tutorial_developer_workflows.rst @@ -142,7 +142,7 @@ First, we tell Spack that we'd like to check out the version of scr that we want In this case, it will be the 3.1.0 release that we want to write a patch for: .. literalinclude:: outputs/dev/develop-1.out - :language: console + :language: spec The ``spack develop`` command marks the package as being a "development" package in the ``spack.yaml``. This adds a special ``dev_path=`` attribute to the spec for the package, so Spack remembers where the source code for this package is located. @@ -237,17 +237,15 @@ When we're done developing, we simply tell Spack that it no longer needs to keep .. literalinclude:: outputs/dev/wrapup.out :language: console -------------------- Workflow Summary -------------------- +---------------- Use the ``spack develop`` command with an environment to make a reproducible build environment for your development workflow. Spack will set up all the dependencies for you and link all your packages together. Within a development environment, ``spack install`` works similarly to ``make`` in that it will check file times to rebuild the minimum number of Spack packages necessary to reflect the changes to your build. -------------------- Optional: Tips and Tricks -------------------- +------------------------- This section will cover some additional features that are useful additions to the core tutorial above. Many of these items are very useful to specific projects and developers. @@ -258,7 +256,7 @@ A list of the options for the ``spack develop`` can be viewed below: $ spack develop --help Source Code Management ----------- +---------------------- ``spack develop`` allows users to manipulate the source code locations The default behavior is to let Spack manage its location and cloning operations, but software developers often want more control over these. @@ -276,7 +274,7 @@ This allows developers to pre-clone the software or use preferred paths as they $ spack concretize -f Navigation and the Build Environment ----------- +------------------------------------ Diving into the build environment was introduced previously in the packaging section with the ``spack build-env scr -- bash`` command. This is a helpful function because it allows you to run commands inside the build environment. @@ -285,10 +283,10 @@ This command is particularly useful in developer environments—it allows develo The additional features of the install command are unnecessary when tightly iterating between building and testing a particular package. For example, the workflow modifying ``scr`` that we just went through can be simplified to: -.. code-block:: console +.. code-block:: spec $ spack build-env scr -- bash - # Shell wrappers didn't propagate to the subshell + # Shell wrappers did not propagate to the subshell $ source $SPACK_ROOT/share/spack/setup-env.sh # Lets look at navigation features $ spack cd --help @@ -305,14 +303,14 @@ For example, the workflow modifying ``scr`` that we just went through can be sim Working with the build environment and along with Spack navigation features provides a nice way to iterate quickly and navigate through the hash-heavy Spack directory structures. Combinatorics ------------- +------------- The final note we will look at in this tutorial will be the power of combinatoric development builds. There are many instances where developers want to see how a single set of changes affects multiple builds i.e. ``+cuda`` vs ``~cuda``, ``%gcc`` vs ``%clang``, ``build_type=Release`` vs ``build_type=Debug``, etc. Developers can achieve builds of both cases from a single ``spack install`` as long as the develop spec is generic enough to cover the packages' spec variations -.. code-block:: console +.. code-block:: spec # First we have to allow repeat specs in the environment $ spack config add concretizer:unify:false diff --git a/tutorial_environments.rst b/tutorial_environments.rst index 873987ec11..03d0d5fc12 100644 --- a/tutorial_environments.rst +++ b/tutorial_environments.rst @@ -145,7 +145,7 @@ Now that we understand how creation and activation work, let's go back to our `` Let's try the usual install commands we learned earlier: .. literalinclude:: outputs/environments/env-fail-install-1.out - :language: console + :language: spec Environments are special in that we must *add* specs to the an environment before we can install them. This additional step helps prevent us from accidentally modifying a shared environment when installing new software. @@ -153,7 +153,7 @@ Environments are special in that we must *add* specs to the an environment befor Let's try it: .. literalinclude:: outputs/environments/env-add-1.out - :language: console + :language: spec Now, ``tcl`` and ``trilinos`` have been registered as **root specs** in our environment. **Root specs** are packages that we've explicitly requested to be installed in an environment. @@ -226,7 +226,7 @@ Imagine we have two projects: Let's start by creating the ``myproject2`` environment and installing both ``scr`` and ``trilinos``: .. literalinclude:: outputs/environments/env-create-2.out - :language: console + :language: spec Now we have two environments with different package combinations: @@ -237,7 +237,7 @@ Now we have two environments with different package combinations: Now let's attempt to uninstall ``trilinos`` from ``myproject2`` and examine what happens: .. literalinclude:: outputs/environments/env-uninstall-1.out - :language: console + :language: spec Notice that ``trilinos`` won't be uninstalled because it's still referenced in ``myproject``. This safety feature prevents accidental removal of packages that other environments depend on. @@ -370,7 +370,7 @@ Creating an environment incrementally We can also add and install specs to an environment incrementally. For example: -.. code-block:: console +.. code-block:: spec $ spack install --add python $ spack install --add py-numpy@1.20 @@ -384,12 +384,12 @@ When you first install ``python`` in an environment, Spack will pick a recent ve If you then add ``py-numpy``, it may be in conflict with the ``python`` version already installed, and fail to concretize: .. literalinclude:: outputs/environments/incremental-1.out - :language: console + :language: spec The solution is to re-concretize the environment as a whole, which causes ``python`` to downgrade to a version compatible with ``py-numpy``: .. literalinclude:: outputs/environments/incremental-2.out - :language: console + :language: spec .. note:: There are other advantages to concretizing and installing an environment all at once: @@ -465,7 +465,7 @@ We also see that ``Hello world`` is output for each of the ranks and the version We can confirm the version of ``zlib`` used to build the program is in our environment using ``spack find``: .. literalinclude:: outputs/environments/myproject-zlib-ng-1.out - :language: console + :language: spec Note that the reported version *does* match that of our installation. @@ -547,7 +547,7 @@ This is because ``spack.lock`` was generated when we concretized the environment If we ``cat`` the ``spack.yaml`` file, we'll see the same specs and view options previously shown by ``spack config edit``: .. literalinclude:: outputs/environments/cat-config-1.out - :language: console + :language: spec ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -570,7 +570,7 @@ As we can see in the activation command, since the environment is independent, i Let's see what really happened with this command by listing the directory contents and looking at the configuration file: .. literalinclude:: outputs/environments/independent-create-2.out - :language: console + :language: spec Notice that Spack created a ``spack.yaml`` file in the *code* directory. @@ -625,7 +625,7 @@ You are free to add and remove specs just as you would outside of the environmen For example, let's add ``hdf5`` and look at our file: .. literalinclude:: outputs/environments/add-independent-1.out - :language: console + :language: spec Notice that ``spack add`` added the package to our active environment and it appears in the configuration file's spec list. @@ -640,7 +640,7 @@ Notice that ``spack add`` added the package to our active environment and it app Now use ``spack remove`` to remove the spec from the configuration: .. literalinclude:: outputs/environments/remove-independent-1.out - :language: console + :language: spec and we see that the spec *was* removed from the spec list of our environment. @@ -734,8 +734,7 @@ Clean-up The later sections of this tutorial are not designed to be run in whatever environment we happened to be in, so we will despacktivate now to avoid accidentally running in this environment later. -.. code-block:: - :language: console +.. code-block:: console spack env deactivate diff --git a/tutorial_modules.rst b/tutorial_modules.rst index 0a827764c3..aa163ed57d 100644 --- a/tutorial_modules.rst +++ b/tutorial_modules.rst @@ -49,7 +49,7 @@ Build a module tool The first thing that we need is the module tool itself. In this tutorial, we will use ``lmod`` because it can work with both hierarchical and non-hierarchical layouts. -.. code-block:: console +.. code-block:: spec $ spack install lmod @@ -69,6 +69,7 @@ Now we can re-source the setup file, and Spack modules will be put in our module .. FIXME: this needs bootstrap support for ``lmod`` .. FIXME: check the docs here, update them if necessary + If you need to install Lmod or Environment Modules, you can refer to the documentation `here `_. @@ -81,7 +82,7 @@ On first use, Spack scans the environment and automatically locates the compiler For this tutorial, however, we want to use ``gcc@12.3.0``. -.. code-block:: console +.. code-block:: spec $ spack install gcc@12.3.0 @@ -115,7 +116,7 @@ Build the software that will be used in the tutorial Finally, we will use Spack to install the packages used in the examples: -.. code-block:: console +.. code-block:: spec $ spack install netlib-scalapack ^openmpi ^openblas $ spack install netlib-scalapack ^mpich ^openblas @@ -165,7 +166,7 @@ Environment Modules This is the original modules tool. It can be installed with Spack using the following command: -.. code-block:: console +.. code-block:: spec $ spack install environment-modules @@ -180,7 +181,7 @@ Lmod Lmod is a module system written in Lua, originally created at the "Texas Advanced Computing Center" (TACC) by Robert McLay. You can get it with: -.. code-block:: console +.. code-block:: spec $ spack install lmod diff --git a/tutorial_packaging.rst b/tutorial_packaging.rst index dcc41ffe5c..2b89117b9f 100644 --- a/tutorial_packaging.rst +++ b/tutorial_packaging.rst @@ -258,7 +258,7 @@ Adding dependencies tells Spack that it must ensure those packages are installed Let's check that dependencies are effectively built when we try to install ``tutorial-mpileaks``: .. literalinclude:: outputs/packaging/install-mpileaks-2.out - :language: console + :language: spec .. note:: @@ -401,7 +401,7 @@ Since this is an ``AutotoolsPackage``, the arguments returned from the method wi Now let's try the build again: .. literalinclude:: outputs/packaging/install-mpileaks-3.out - :language: console + :language: spec Success! @@ -456,7 +456,7 @@ Also note that the value provided by the user is accessed by the entry's ``value Now run the installation again with the ``--verbose`` install option -- to get more output during the build -- and the new ``stackstart`` package option: .. literalinclude:: outputs/packaging/install-mpileaks-4.out - :language: console + :language: spec Notice the addition of the two stack start arguments in the configure command that appears at the end of the highlighted line after ``tutorial-mpileaks``' ``Executing phase: 'configure'``. @@ -492,7 +492,7 @@ Bring ``tutorial-mpileaks``' ``package.py`` file back up with the ``spack edit`` Since these are `build-time tests `_, we'll need to uninstall the package so we can re-run it with tests enabled: .. literalinclude:: outputs/packaging/install-mpileaks-5.out - :language: console + :language: spec Notice the installation fails due to the missing directory with the error: ``Error: InstallError: Install failed for tutorial-mpileaks. No such directory in prefix: shar``. @@ -507,7 +507,7 @@ Now let's properly fix the error: And try again: .. literalinclude:: outputs/packaging/install-mpileaks-6.out - :language: console + :language: spec Success! @@ -672,7 +672,7 @@ Before leaving this tutorial, let's ensure that our work does not interfere with Undo the work we've done here by entering the following commands: .. literalinclude:: outputs/packaging/cleanup.out - :language: console + :language: spec -------------------- More information diff --git a/tutorial_scripting.rst b/tutorial_scripting.rst index 228ec8f48d..85420ca806 100644 --- a/tutorial_scripting.rst +++ b/tutorial_scripting.rst @@ -52,7 +52,7 @@ Alternatively, we can get a serialized version of ``Spec`` objects in the `JSON` For example, to get attributes for all installations of ``zlib-ng``: .. literalinclude:: outputs/scripting/find-json.out - :language: console + :language: spec This command provides complete information about any spec of interest in a structured format. The output of ``spack find --json`` can be piped to JSON filtering tools like ``jq`` to extract specific information. diff --git a/tutorial_stacks.rst b/tutorial_stacks.rst index 27fd72f9d2..3f2f25a673 100644 --- a/tutorial_stacks.rst +++ b/tutorial_stacks.rst @@ -54,7 +54,7 @@ We can add from the command line a new compiler. We'll also disable the generation of views for the time being, as we'll come back to this topic later in the tutorial: .. literalinclude:: outputs/stacks/setup-1.out - :language: console + :language: spec What you should see on screen now is the following ``spack.yaml`` file: @@ -98,12 +98,12 @@ Now that we have a compiler ready, the next objective is to build software with We'll start by trying to add different versions of ``netlib-scalapack``, linked against different MPI implementations: .. literalinclude:: outputs/stacks/unify-0.out - :language: console + :language: spec If we try to concretize the environment, we'll get an error: .. literalinclude:: outputs/stacks/unify-1.out - :language: console + :language: spec The error message is quite verbose and complicated, but it ultimately gives a useful hint: @@ -166,7 +166,7 @@ Let's further expand our stack and consider also linking against different LAPAC We could, of course, add new specs explicitly: .. literalinclude:: outputs/stacks/unify-4.out - :language: console + :language: spec This way of proceeding, though, will become very tedious once more software is requested. The best way to express a cross-product like this in Spack is instead through a matrix: @@ -244,7 +244,7 @@ Concretize the environment and install the specs again: At this point, the environment contains only ``py-scipy ^openblas``. Verify it: .. literalinclude:: outputs/stacks/concretize-4.out - :language: console + :language: spec ^^^^^^^^^^^^^^^^^^^^^^^ Conditional definitions @@ -279,7 +279,7 @@ Different definitions of lists with the same name are concatenated, so we can de First, check what happens when we concretize and don't set any environment variable: .. literalinclude:: outputs/stacks/concretize-5.out - :language: console + :language: spec As we expected we are only using ``mpich`` as an MPI provider. To get ``openmpi`` back we need to set the appropriate environment variable: @@ -391,7 +391,7 @@ There we discuss the general architecture of module file generation in Spack and Let's start by adding ``lmod`` to the software installed with the system compiler: -.. code-block:: console +.. code-block:: spec $ spack add lmod%gcc@11 $ spack concretize From faf434d7fa49215047f0412836725d276661e09c Mon Sep 17 00:00:00 2001 From: Harmen Stoppels Date: Wed, 6 Aug 2025 12:26:17 +0200 Subject: [PATCH 2/2] bump .gitmodules --- .gitmodules | 2 +- _spack_root | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitmodules b/.gitmodules index d136edc0aa..234b02abaa 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,4 @@ [submodule "_spack_root"] path = _spack_root url = https://github.com/spack/spack.git - branch = releases/v0.23 + branch = releases/v1.0 diff --git a/_spack_root b/_spack_root index c6d4037758..73eaea13f3 160000 --- a/_spack_root +++ b/_spack_root @@ -1 +1 @@ -Subproject commit c6d4037758140fe15913c29e80cd1547f388ae51 +Subproject commit 73eaea13f381e3495299284856fd02a64e1d154c