From c86b2860aa92f5312154a218c09c0e29963ff051 Mon Sep 17 00:00:00 2001 From: Harmen Stoppels Date: Tue, 20 May 2025 19:24:54 +0200 Subject: [PATCH] docs: fix a few typos (#50573) * docs: fix a few typos * fix a few issues in packaging_guide.rst * more fixes --- lib/spack/docs/basic_usage.rst | 2 +- lib/spack/docs/binary_caches.rst | 4 +-- lib/spack/docs/bootstrapping.rst | 6 ++--- lib/spack/docs/config_yaml.rst | 4 +-- lib/spack/docs/containers.rst | 6 ++--- lib/spack/docs/getting_started.rst | 2 +- lib/spack/docs/module_file_support.rst | 8 +++--- lib/spack/docs/packaging_guide.rst | 32 +++++++---------------- lib/spack/docs/replace_conda_homebrew.rst | 2 +- 9 files changed, 27 insertions(+), 39 deletions(-) diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst index f71f4fae81a..ff53561342f 100644 --- a/lib/spack/docs/basic_usage.rst +++ b/lib/spack/docs/basic_usage.rst @@ -276,7 +276,7 @@ remove dependent packages *before* removing their dependencies or use the Garbage collection ^^^^^^^^^^^^^^^^^^ -When Spack builds software from sources, if often installs tools that are needed +When Spack builds software from sources, it often installs tools that are needed just to build or test other software. These are not necessary at runtime. To support cases where removing these tools can be a benefit Spack provides the ``spack gc`` ("garbage collector") command, which will uninstall all unneeded packages: diff --git a/lib/spack/docs/binary_caches.rst b/lib/spack/docs/binary_caches.rst index f736fab75f0..5ec77fd8909 100644 --- a/lib/spack/docs/binary_caches.rst +++ b/lib/spack/docs/binary_caches.rst @@ -89,7 +89,7 @@ You can see that the mirror is added with ``spack mirror list`` as follows: spack-public https://spack-llnl-mirror.s3-us-west-2.amazonaws.com/ -At this point, you've create a buildcache, but spack hasn't indexed it, so if +At this point, you've created a buildcache, but Spack hasn't indexed it, so if you run ``spack buildcache list`` you won't see any results. You need to index this new build cache as follows: @@ -318,7 +318,7 @@ other system dependencies. However, they are still compatible with tools like ``skopeo``, ``podman``, and ``docker`` for pulling and pushing. .. note:: - The docker ``overlayfs2`` storage driver is limited to 128 layers, above which a + The Docker ``overlayfs2`` storage driver is limited to 128 layers, above which a ``max depth exceeded`` error may be produced when pulling the image. There are `alternative drivers `_. diff --git a/lib/spack/docs/bootstrapping.rst b/lib/spack/docs/bootstrapping.rst index 8a7bc1569fc..7f7a37f43cf 100644 --- a/lib/spack/docs/bootstrapping.rst +++ b/lib/spack/docs/bootstrapping.rst @@ -14,7 +14,7 @@ is an entire command dedicated to the management of every aspect of bootstrappin .. command-output:: spack bootstrap --help -Spack is configured to bootstrap its dependencies lazily by default; i.e. the first time they are needed and +Spack is configured to bootstrap its dependencies lazily by default; i.e., the first time they are needed and can't be found. You can readily check if any prerequisite for using Spack is missing by running: .. code-block:: console @@ -36,8 +36,8 @@ can't be found. You can readily check if any prerequisite for using Spack is mis In the case of the output shown above Spack detected that both ``clingo`` and ``gnupg`` are missing and it's giving detailed information on why they are needed and whether -they can be bootstrapped. The return code of this command summarizes the results, if any -dependencies are missing the return code is ``1``, otherwise ``0``. Running a command that +they can be bootstrapped. The return code of this command summarizes the results; if any +dependencies are missing, the return code is ``1``, otherwise ``0``. Running a command that concretizes a spec, like: .. code-block:: console diff --git a/lib/spack/docs/config_yaml.rst b/lib/spack/docs/config_yaml.rst index 54c659caf29..5a30309e1ac 100644 --- a/lib/spack/docs/config_yaml.rst +++ b/lib/spack/docs/config_yaml.rst @@ -148,8 +148,8 @@ this can expose you to attacks. Use at your own risk. ``ssl_certs`` -------------------- -Path to custom certificats for SSL verification. The value can be a -filesytem path, or an environment variable that expands to an absolute file path. +Path to custom certificates for SSL verification. The value can be a +filesystem path, or an environment variable that expands to an absolute file path. The default value is set to the environment variable ``SSL_CERT_FILE`` to use the same syntax used by many other applications that automatically detect custom certificates. diff --git a/lib/spack/docs/containers.rst b/lib/spack/docs/containers.rst index b0e1cb0e6f1..74af5d9a5cf 100644 --- a/lib/spack/docs/containers.rst +++ b/lib/spack/docs/containers.rst @@ -11,7 +11,7 @@ Container Images Spack :ref:`environments` can easily be turned into container images. This page outlines two ways in which this can be done: -1. By installing the environment on the host system, and copying the installations +1. By installing the environment on the host system and copying the installations into the container image. This approach does not require any tools like Docker or Singularity to be installed. 2. By generating a Docker or Singularity recipe that can be used to build the @@ -56,8 +56,8 @@ environment roots and its runtime dependencies. .. note:: - When using registries like GHCR and Docker Hub, the ``--oci-password`` flag is not - the password for your account, but a personal access token you need to generate separately. + When using registries like GHCR and Docker Hub, the ``--oci-password`` flag specifies not + the password for your account, but rather a personal access token you need to generate separately. The specified ``--base-image`` should have a libc that is compatible with the host system. For example if your host system is Ubuntu 20.04, you can use ``ubuntu:20.04``, ``ubuntu:22.04`` diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst index a0870ec86e4..011fbc85508 100644 --- a/lib/spack/docs/getting_started.rst +++ b/lib/spack/docs/getting_started.rst @@ -20,7 +20,7 @@ be present on the machine where Spack is run: :header-rows: 1 These requirements can be easily installed on most modern Linux systems; -on macOS, the Command Line Tools package is required, and a full XCode suite +on macOS, the Command Line Tools package is required, and a full Xcode suite may be necessary for some packages such as Qt and apple-gl. Spack is designed to run on HPC platforms like Cray. Not all packages should be expected to work on all platforms. diff --git a/lib/spack/docs/module_file_support.rst b/lib/spack/docs/module_file_support.rst index cfc32802938..cd392353a92 100644 --- a/lib/spack/docs/module_file_support.rst +++ b/lib/spack/docs/module_file_support.rst @@ -8,7 +8,7 @@ Modules (modules.yaml) ====================== -The use of module systems to manage user environment in a controlled way +The use of module systems to manage user environments in a controlled way is a common practice at HPC centers that is sometimes embraced also by individual programmers on their development machines. To support this common practice Spack integrates with `Environment Modules @@ -490,7 +490,7 @@ that are already in the Lmod hierarchy. .. note:: - Tcl and Lua modules also allow for explicit conflicts between modulefiles. + Tcl and Lua modules also allow for explicit conflicts between module files. .. code-block:: yaml @@ -513,7 +513,7 @@ that are already in the Lmod hierarchy. :meth:`~spack.spec.Spec.format` method. For Lmod and Environment Modules versions prior 4.2, it is important to - express the conflict on both modulefiles conflicting with each other. + express the conflict on both module files conflicting with each other. .. note:: @@ -550,7 +550,7 @@ that are already in the Lmod hierarchy. .. warning:: Consistency of Core packages - The user is responsible for maintining consistency among core packages, as ``core_specs`` + The user is responsible for maintaining consistency among core packages, as ``core_specs`` bypasses the hierarchy that allows Lmod to safely switch between coherent software stacks. .. warning:: diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst index daca27ecbd1..80bece5bbe3 100644 --- a/lib/spack/docs/packaging_guide.rst +++ b/lib/spack/docs/packaging_guide.rst @@ -179,7 +179,7 @@ Spack can be found at :ref:`package_class_structure`. .. code-block:: python - class Foo(CmakePackage): + class Foo(CMakePackage): def cmake_args(self): ... @@ -1212,7 +1212,7 @@ class-level tarball URL and VCS. For example: version("master", branch="master") version("12.12.1", md5="ecd4606fa332212433c98bf950a69cc7") version("12.10.1", md5="667333dbd7c0f031d47d7c5511fd0810") - version("12.8.1", "9f37f683ee2b427b5540db8a20ed6b15") + version("12.8.1", md5="9f37f683ee2b427b5540db8a20ed6b15") If a package contains both a ``url`` and ``git`` class-level attribute, Spack decides which to use based on the arguments to the ``version()`` @@ -1343,7 +1343,7 @@ Submodules version("1.0.1", tag="v1.0.1", submodules=True) - If a package has needs more fine-grained control over submodules, define + If a package needs more fine-grained control over submodules, define ``submodules`` to be a callable function that takes the package instance as its only argument. The function should return a list of submodules to be fetched. @@ -2308,31 +2308,19 @@ looks like this: parallel = False -Similarly, you can disable parallel builds only for specific make -commands, as ``libdwarf`` does: +You can also disable parallel builds only for specific make +invocation: .. code-block:: python - :emphasize-lines: 9, 12 + :emphasize-lines: 5 :linenos: class Libelf(Package): ... def install(self, spec, prefix): - configure("--prefix=" + prefix, - "--enable-shared", - "--disable-dependency-tracking", - "--disable-debug") - make() - - # The mkdir commands in libelf's install can fail in parallel make("install", parallel=False) -The first make will run in parallel here, but the second will not. If -you set ``parallel`` to ``False`` at the package level, then each call -to ``make()`` will be sequential by default, but packagers can call -``make(parallel=True)`` to override it. - Note that the ``--jobs`` option works out of the box for all standard build systems. If you are using a non-standard build system instead, you can use the variable ``make_jobs`` to extract the number of jobs specified @@ -2507,7 +2495,7 @@ necessary when there are breaking changes in the dependency that the package cannot handle. In Spack we often add forward compatibility bounds only at the time a new, breaking version of a dependency is released. As with backward compatibility, it is typical to see a list -of forward compatibility bounds in a package file as seperate lines: +of forward compatibility bounds in a package file as separate lines: .. code-block:: python @@ -3383,7 +3371,7 @@ the above attribute implementations: "/opt/spack/linux-fedora35-haswell/gcc-11.3.1/foo-1.0-ca3rczp5omy7dfzoqw4p7oc2yh3u7lt6/baz/lib/libFooBaz.so" ]) - # baz library directories in the baz subdirectory of the foo porefix + # baz library directories in the baz subdirectory of the foo prefix >>> spec["baz"].libs.directories [ "/opt/spack/linux-fedora35-haswell/gcc-11.3.1/foo-1.0-ca3rczp5omy7dfzoqw4p7oc2yh3u7lt6/baz/lib" @@ -5740,7 +5728,7 @@ running each executable, ``foo`` and ``bar``, as independent test parts. .. note:: The method name ``copy_test_files`` here is for illustration purposes. - You are free to use a name that is more suited to your package. + You are free to use a name that is better suited to your package. The key to copying files for stand-alone testing at build time is use of the ``run_after`` directive, which ensures the associated files are @@ -7249,7 +7237,7 @@ which are not, there is the `checked_by` parameter in the license directive: license("", when="", checked_by="") -When you have validated a github license, either when doing so explicitly or +When you have validated a package license, either when doing so explicitly or as part of packaging a new package, please set the `checked_by` parameter to your Github username to signal that the license has been manually verified. diff --git a/lib/spack/docs/replace_conda_homebrew.rst b/lib/spack/docs/replace_conda_homebrew.rst index 4ec5765c44f..77093036137 100644 --- a/lib/spack/docs/replace_conda_homebrew.rst +++ b/lib/spack/docs/replace_conda_homebrew.rst @@ -214,7 +214,7 @@ package versions, simply run the following commands: Running ``spack mark -i --all`` tells Spack to mark all of the existing packages within an environment as "implicitly" installed. This tells -spack's garbage collection system that these packages should be cleaned up. +Spack's garbage collection system that these packages should be cleaned up. Don't worry however, this will not remove your entire environment. Running ``spack install`` will reexamine your spack environment after