From 6a5233bc4e0e53ea1dba8e1b7659159dbe9c039b Mon Sep 17 00:00:00 2001 From: Caetano Melone Date: Tue, 3 Jun 2025 09:37:05 -0700 Subject: [PATCH 1/5] add note about spack help --spec --- outputs/basics/help-spec.out | 34 ++++++++++++++++++++++++++++++++++ tutorial_basics.rst | 7 +++++++ 2 files changed, 41 insertions(+) create mode 100644 outputs/basics/help-spec.out diff --git a/outputs/basics/help-spec.out b/outputs/basics/help-spec.out new file mode 100644 index 0000000000..a801a353b8 --- /dev/null +++ b/outputs/basics/help-spec.out @@ -0,0 +1,34 @@ +usage: spack spec [-hlLNtU] [-I | --no-install-status] [-y | -j | --format FORMAT] [-c {nodes,edges,paths}] [--reuse] [--fresh-roots] [--deprecated] ... + +show what would be installed, given a spec + +positional arguments: + specs one or more package specs + +options: + --format FORMAT print concrete spec with the specified format string + --no-install-status do not show install status annotations + -I, --install-status show install status of packages + [+] installed [^] installed in an upstream + - not installed [-] missing dep of installed package + -L, --very-long show full dependency hashes as well as versions + -N, --namespaces show fully qualified package names + -c, --cover {nodes,edges,paths} + how extensively to traverse the DAG (default: nodes) + -h, --help show this help message and exit + -j, --json print concrete spec as JSON + -l, --long show dependency hashes as well as versions + -t, --types show dependency types + -y, --yaml print concrete spec as YAML + +concretizer arguments: + --deprecated allow concretizer to select deprecated versions + --fresh-roots, --reuse-deps + concretize with fresh roots and reused dependencies + --reuse reuse installed packages/buildcaches when possible + -U, --fresh do not reuse installed deps; build newest configuration + +when an environment is active and no specs are provided, the environment root specs are used instead + +for further documentation regarding the spec syntax, see: + spack help --spec \ No newline at end of file diff --git a/tutorial_basics.rst b/tutorial_basics.rst index 8e51f5584e..77b5d5e9a0 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -342,3 +342,10 @@ We can also remove compilers from our configuration using ``spack compiler remov .. literalinclude:: outputs/basics/compiler-remove.out :language: console + +.. note :: + +The spec syntax may be confusing for new users. Spack can provide information about commands you run frequently. For instance, ``spack help --spec``: + + .. literalinclude:: outputs/basics/help-spec.out + :language: console From 30138864b45f689c48a601f39299b8a23b0c49fc Mon Sep 17 00:00:00 2001 From: Caetano Melone Date: Tue, 3 Jun 2025 09:41:18 -0700 Subject: [PATCH 2/5] fix .. note:: --- tutorial_basics.rst | 8 ++++---- tutorial_binary_cache.rst | 18 +++++++++--------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index 77b5d5e9a0..2216e68c3e 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -343,9 +343,9 @@ We can also remove compilers from our configuration using ``spack compiler remov .. literalinclude:: outputs/basics/compiler-remove.out :language: console -.. note :: +.. note:: -The spec syntax may be confusing for new users. Spack can provide information about commands you run frequently. For instance, ``spack help --spec``: + The spec syntax may be confusing for new users. Spack can provide information about commands you run frequently. For instance, ``spack help --spec``: - .. literalinclude:: outputs/basics/help-spec.out - :language: console + .. literalinclude:: outputs/basics/help-spec.out + :language: console diff --git a/tutorial_binary_cache.rst b/tutorial_binary_cache.rst index b0025357ca..b3fdef9f25 100644 --- a/tutorial_binary_cache.rst +++ b/tutorial_binary_cache.rst @@ -60,10 +60,10 @@ The build cache name, `buildcache-${USER}-${HOSTNAME}`, is a suggestion; you can oci://ghcr.io//buildcache-${USER}-${HOSTNAME} -.. note :: +.. note:: -We talk about mirrors and build caches almost interchangeably, because every build cache is a binary mirror. -Source mirrors exist too, which we will not cover in this tutorial. + We talk about mirrors and build caches almost interchangeably, because every build cache is a binary mirror. + Source mirrors exist too, which we will not cover in this tutorial. Your ``spack.yaml`` file should now contain the following: @@ -111,15 +111,15 @@ The location of the pushed package, when referred to as an OCI image, will be: look very similar to a container image --- we will get to that in a bit. -.. note :: +.. note:: -Binaries pushed to GitHub packages are ``private`` by default, which means you need a token to download them. -You can change the visibility to ``public`` by going to GitHub Packages from your GitHub account, selecting the ``buildcache`` package, go to ``package settings``, and change the visibility to ``public`` in the ``Danger Zone`` section. -This page can also be directly accessed by going to + Binaries pushed to GitHub packages are ``private`` by default, which means you need a token to download them. + You can change the visibility to ``public`` by going to GitHub Packages from your GitHub account, selecting the ``buildcache`` package, go to ``package settings``, and change the visibility to ``public`` in the ``Danger Zone`` section. + This page can also be directly accessed by going to - .. code-block:: text + .. code-block:: text - https://github.com/users//packages/container/buildcache/settings + https://github.com/users//packages/container/buildcache/settings ------------------------------- From b934ae503bcd230b68ee18898c8e066b2670b6a5 Mon Sep 17 00:00:00 2001 From: Caetano Melone Date: Tue, 3 Jun 2025 09:44:37 -0700 Subject: [PATCH 3/5] indent doesn't need to be so large --- tutorial_basics.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index 2216e68c3e..3c886c27da 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -347,5 +347,5 @@ We can also remove compilers from our configuration using ``spack compiler remov The spec syntax may be confusing for new users. Spack can provide information about commands you run frequently. For instance, ``spack help --spec``: - .. literalinclude:: outputs/basics/help-spec.out - :language: console + .. literalinclude:: outputs/basics/help-spec.out + :language: console From ad829f41d9f07adfebad51d8d6383ec520b8aae7 Mon Sep 17 00:00:00 2001 From: Caetano Melone Date: Tue, 3 Jun 2025 12:33:58 -0700 Subject: [PATCH 4/5] fix the help text output --- outputs/basics/help-spec.out | 94 +++++++++++++++++++++++------------- 1 file changed, 60 insertions(+), 34 deletions(-) diff --git a/outputs/basics/help-spec.out b/outputs/basics/help-spec.out index a801a353b8..2faa1f9649 100644 --- a/outputs/basics/help-spec.out +++ b/outputs/basics/help-spec.out @@ -1,34 +1,60 @@ -usage: spack spec [-hlLNtU] [-I | --no-install-status] [-y | -j | --format FORMAT] [-c {nodes,edges,paths}] [--reuse] [--fresh-roots] [--deprecated] ... - -show what would be installed, given a spec - -positional arguments: - specs one or more package specs - -options: - --format FORMAT print concrete spec with the specified format string - --no-install-status do not show install status annotations - -I, --install-status show install status of packages - [+] installed [^] installed in an upstream - - not installed [-] missing dep of installed package - -L, --very-long show full dependency hashes as well as versions - -N, --namespaces show fully qualified package names - -c, --cover {nodes,edges,paths} - how extensively to traverse the DAG (default: nodes) - -h, --help show this help message and exit - -j, --json print concrete spec as JSON - -l, --long show dependency hashes as well as versions - -t, --types show dependency types - -y, --yaml print concrete spec as YAML - -concretizer arguments: - --deprecated allow concretizer to select deprecated versions - --fresh-roots, --reuse-deps - concretize with fresh roots and reused dependencies - --reuse reuse installed packages/buildcaches when possible - -U, --fresh do not reuse installed deps; build newest configuration - -when an environment is active and no specs are provided, the environment root specs are used instead - -for further documentation regarding the spec syntax, see: - spack help --spec \ No newline at end of file +spec expression syntax: + + package [constraints] [^dependency [constraints] ...] + + package any package from 'spack list', or + /hash unique prefix or full hash of + installed package + + constraints: + versions: + @version single version + @min:max version range (inclusive) + @min: version or higher + @:max up to version (inclusive) + @=version exact version + + compilers: + %compiler build with + %compiler@version build with specific compiler version + %compiler@min:max specific version range (see above) + + compiler flags: + cflags="flags" cppflags, cflags, cxxflags, + fflags, ldflags, ldlibs + == propagate flags to package dependencies + + variants: + +variant enable + -variant or ~variant disable + variant=value set non-boolean to + variant=value1,value2,value3 set multi-value values + ++, --, ~~, == propagate variants to package dependencies + + architecture variants: + platform=platform linux, darwin, freebsd, windows + os=operating_system specific + target=target specific processor + arch=platform-os-target shortcut for all three above + + dependencies: + ^dependency [constraints] specify constraints on dependencies + ^/hash build with a specific installed + dependency + + examples: + hdf5 any hdf5 configuration + hdf5 @1.10.1 hdf5 version 1.10.1 + hdf5 @1.8: hdf5 1.8 or higher + hdf5 @1.8: %gcc hdf5 1.8 or higher built with gcc + hdf5 +mpi hdf5 with mpi enabled + hdf5 ~mpi hdf5 with mpi disabled + hdf5 ++mpi hdf5 with mpi enabled and propagates + hdf5 ~~mpi hdf5 with mpi disabled and propagates + hdf5 +mpi ^mpich hdf5 with mpi, using mpich + hdf5 +mpi ^openmpi@1.7 hdf5 with mpi, using openmpi 1.7 + boxlib dim=2 boxlib built for 2 dimensions + libdwarf %intel ^libelf%gcc + libdwarf, built with intel compiler, linked to libelf built with gcc + mvapich2 fabrics=psm,mrail,sock %gcc + mvapich2, built with gcc compiler, with support for multiple fabrics \ No newline at end of file From d4888774cd0d11c276a36c0b9f3a21388d3913c0 Mon Sep 17 00:00:00 2001 From: Caetano Melone Date: Tue, 3 Jun 2025 17:26:10 -0700 Subject: [PATCH 5/5] break up sentences --- tutorial_basics.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tutorial_basics.rst b/tutorial_basics.rst index 3c886c27da..1689621539 100644 --- a/tutorial_basics.rst +++ b/tutorial_basics.rst @@ -345,7 +345,9 @@ We can also remove compilers from our configuration using ``spack compiler remov .. note:: - The spec syntax may be confusing for new users. Spack can provide information about commands you run frequently. For instance, ``spack help --spec``: + The spec syntax may be confusing for new users. + Spack can provide information about commands you run frequently. + For instance, see the output of ``spack help --spec``: .. literalinclude:: outputs/basics/help-spec.out :language: console