Skip to content

Commit f376de5

Browse files
Docs: Enforce consistent language in tutorials
I've updated the following tutorial files to use consistent language: - tutorial_configuration.rst - tutorial_developer_workflows.rst - tutorial_environments.rst - tutorial_modules.rst Changes include: - Replaced "you will" with "we will" - Replaced "you can" with "we can" - Replaced "your" with "our" (contextually) - Replaced "yourself" with "ourselves" - Replaced "the packager can" with "we can" - Ensured "let's" and its variants align with the "we will" tone. These changes should improve the readability and consistency of your tutorial documentation.
1 parent 02e002f commit f376de5

7 files changed

Lines changed: 310 additions & 310 deletions

tutorial_configuration.rst

Lines changed: 37 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
Configuration Tutorial
1111
======================
1212

13-
This tutorial will guide you through various configuration options that allow you to customize Spack's behavior with respect to software installation.
13+
This tutorial will guide us through various configuration options that allow us to customize Spack's behavior with respect to software installation.
1414
There are many different configuration sections.
1515
A partial list of some key configuration sections is provided below.
1616

@@ -34,7 +34,7 @@ A partial list of some key configuration sections is provided below.
3434
- Naming, location and additional configuration of Spack generated modules
3535

3636
The full list of sections can be viewed with ``spack config list``.
37-
For further education, we encourage you to explore the Spack `documentation on configuration files <https://spack.readthedocs.io/en/latest/configuration.html#configuration-files>`_.
37+
For further education, we encourage exploration of the Spack `documentation on configuration files <https://spack.readthedocs.io/en/latest/configuration.html#configuration-files>`_.
3838

3939
The principle goals of this section of the tutorial are:
4040

@@ -45,7 +45,7 @@ The principle goals of this section of the tutorial are:
4545
As such, we will primarily focus on the ``compilers`` and ``packages`` configuration sections in this portion of the tutorial.
4646

4747
We will explain this by first covering how to manipulate configurations from the command line and then show how this impacts the configuration file hierarchy.
48-
We will then move into compiler and package configurations to help you develop skills for getting the builds you want on your system.
48+
We will then move into compiler and package configurations to help develop skills for getting the builds we want on our system.
4949
Finally, we will give some brief attention to more generalized Spack configurations in the ``config`` section.
5050

5151
For all of these features, we will demonstrate how we build up a full configuration file.
@@ -56,9 +56,9 @@ The provided output is all from a server running Ubuntu version 22.04.
5656
Configuration from the command line
5757
-----------------------------------
5858

59-
You can run ``spack config blame [section]`` at any point in time to see what your current configuration is.
60-
If you omit the section, then spack will dump all the configurations settings to your screen.
61-
Let's go ahead and run this for the ``concretizer`` section.
59+
We can run ``spack config blame [section]`` at any point in time to see what our current configuration is.
60+
If we omit the section, then spack will dump all the configurations settings to our screen.
61+
We will go ahead and run this for the ``concretizer`` section.
6262

6363
.. code-block:: console
6464
@@ -90,7 +90,7 @@ This will make more sense after the next section which provides the definition o
9090
Configuration Scopes
9191
--------------------
9292

93-
Depending on your use case, you may want to provide configuration settings common to everyone on your team, or you may want to set default behaviors specific to a single user account.
93+
Depending on our use case, we may want to provide configuration settings common to everyone on our team, or we may want to set default behaviors specific to a single user account.
9494
Spack provides six configuration *scopes* to handle this customization.
9595
These scopes, in order of decreasing priority, are:
9696

@@ -111,11 +111,11 @@ These are useful for reference, but should never be directly edited.
111111
To override these settings, create new configuration files in any of the higher-priority configuration scopes.
112112

113113
A particular cluster may have multiple Spack installations associated with different projects.
114-
To provide settings common to all Spack installations, put your configuration files in ``/etc/spack``.
115-
To provide settings specific to a particular Spack installation, you can use the ``$SPACK_ROOT/etc/spack`` directory.
114+
To provide settings common to all Spack installations, put our configuration files in ``/etc/spack``.
115+
To provide settings specific to a particular Spack installation, we can use the ``$SPACK_ROOT/etc/spack`` directory.
116116

117-
For settings specific to a particular user, you will want to add configuration files to the ``~/.spack`` directory.
118-
When Spack first checked for compilers on your system, you may have noticed that it placed your compiler configuration in this directory.
117+
For settings specific to a particular user, we will want to add configuration files to the ``~/.spack`` directory.
118+
When Spack first checked for compilers on our system, we may have noticed that it placed our compiler configuration in this directory.
119119

120120
Configuration settings can also be placed in a custom location, which is then specified on the command line via ``--config-scope``.
121121
An example use case is managing two sets of configurations, one for development and another for production preferences.
@@ -210,7 +210,7 @@ Compiler Configuration
210210
For most tasks, we can use Spack with the compilers auto-detected the first time Spack runs on a system.
211211
As discussed in the basic installation tutorial, we can also tell Spack where compilers are located using the ``spack compiler add`` command.
212212
However, in some circumstances, we want even more fine-grained control over the compilers available.
213-
This section will teach you how to exercise that control using the compilers configuration file.
213+
This section will teach us how to exercise that control using the compilers configuration file.
214214

215215
We will start by opening the compilers configuration file:
216216

@@ -219,7 +219,7 @@ We will start by opening the compilers configuration file:
219219
$ spack config edit compilers
220220
221221
222-
We start with no active environment, so this will open a ``compilers.yaml`` file for editing (you can also do this with an active environment):
222+
We start with no active environment, so this will open a ``compilers.yaml`` file for editing (we can also do this with an active environment):
223223

224224
.. code-block:: yaml
225225
@@ -286,7 +286,7 @@ We can do this by adding another entry to the ``compilers.yaml`` file:
286286
extra_rpaths: []
287287
288288
289-
Let's talk about the sections of this compiler entry that we've changed.
289+
We will talk about the sections of this compiler entry that we've changed.
290290
The biggest change we've made is to the ``paths`` section.
291291
This lists the paths to the compilers to use for each language/specification.
292292
In this case, we point to the Clang compiler for C/C++ and the gfortran compiler for both specifications of Fortran.
@@ -326,7 +326,7 @@ Spack provides configuration options for setting compiler flags every time a spe
326326
These flags become part of the package spec and therefore of the build provenance.
327327
As on the command line, the flags are set through the implicit build variables ``cflags``, ``cxxflags``, ``cppflags``, ``fflags``, ``ldflags``, and ``ldlibs``.
328328

329-
Let's open our compilers configuration file again and add a compiler flag:
329+
We will open our compilers configuration file again and add a compiler flag:
330330

331331
.. code-block:: yaml
332332
:emphasize-lines: 8-9
@@ -383,7 +383,7 @@ Any modules in the ``modules`` field of the compiler configuration will be loade
383383
...
384384
385385
The ``environment`` field of the compiler configuration is used for compilers that require environment variables to be set during build time.
386-
For example, if your Intel compiler suite requires the ``INTEL_LICENSE_FILE`` environment variable to point to the proper license server, you can set this in ``compilers.yaml`` as follows:
386+
For example, if our Intel compiler suite requires the ``INTEL_LICENSE_FILE`` environment variable to point to the proper license server, we can set this in ``compilers.yaml`` as follows:
387387

388388
.. code-block:: yaml
389389
@@ -441,8 +441,8 @@ Currently, we prefer GCC and OpenMPI.
441441
:emphasize-lines: 16
442442

443443

444-
Let's override these default preferences in an environment.
445-
When you have an activated environment, you can edit the associated configuration with ``spack config edit`` (you don't have to provide a section name):
444+
We will override these default preferences in an environment.
445+
When we have an activated environment, we can edit the associated configuration with ``spack config edit`` (we don't have to provide a section name):
446446

447447
.. code-block:: console
448448
@@ -453,10 +453,10 @@ When you have an activated environment, you can edit the associated configuratio
453453
454454
.. warning::
455455

456-
You will get exactly the same effects if you make these changes
457-
without using an environment, but you must delete the
456+
We will get exactly the same effects if we make these changes
457+
without using an environment, but we must delete the
458458
associated ``packages.yaml`` file after the config tutorial or
459-
the commands you run in later tutorial sections will not
459+
the commands we run in later tutorial sections will not
460460
produce the same output (because they weren't run with the
461461
configuration changes made here)
462462

@@ -521,7 +521,7 @@ Spack has a ``spack external find`` command that can automatically discover and
521521
This works for many common build dependencies, but it's also important to know how to do this manually for packages that Spack cannot yet detect.
522522

523523
On these systems, we have a pre-installed curl.
524-
Let's tell Spack about this package and where it can be found:
524+
We will tell Spack about this package and where it can be found:
525525

526526
.. code-block:: yaml
527527
:emphasize-lines: 11-14
@@ -550,7 +550,7 @@ We don't know exactly which variants it was built with, but that's okay.
550550
:language: console
551551

552552

553-
You'll notice that Spack is now using the external Curl installation, but the compiler used to build Curl is now overriding our compiler preference of clang.
553+
We'll notice that Spack is now using the external Curl installation, but the compiler used to build Curl is now overriding our compiler preference of clang.
554554
If we explicitly specify Clang:
555555

556556
.. literalinclude:: outputs/config/1.externals.out
@@ -653,16 +653,16 @@ The alternative is to try to find a version of ``hdf5`` which doesn't have this
653653

654654
By configuring most of our package preferences in ``packages.yaml``, we can cut down on the amount of work we need to do when specifying a spec on the command line.
655655
In addition to compiler and variant preferences, we can specify version preferences as well.
656-
Except for specifying dependencies via ``^``, anything that you can specify on the command line can be specified in ``packages.yaml`` with the exact same spec syntax.
656+
Except for specifying dependencies via ``^``, anything that we can specify on the command line can be specified in ``packages.yaml`` with the exact same spec syntax.
657657

658658
^^^^^^^^^^^^^^^^^^^^^^^^
659659
Installation permissions
660660
^^^^^^^^^^^^^^^^^^^^^^^^
661661

662662
The ``packages`` configuration also controls the default permissions to use when installing a package.
663-
You'll notice that by default, the installation prefix will be world-readable but only user-writable.
663+
We'll notice that by default, the installation prefix will be world-readable but only user-writable.
664664

665-
Let's say we need to install ``converge``, a licensed software package.
665+
We will say we need to install ``converge``, a licensed software package.
666666
Since a specific research group, ``fluid_dynamics``, pays for this license, we want to ensure that only members of this group can access the software.
667667
We can do this like so:
668668

@@ -697,7 +697,7 @@ High-level Config
697697

698698
In addition to compiler and package settings, Spack allows customization of several high-level settings.
699699
These settings are managed in the ``config`` section (in ``config.yaml`` when stored as an individual file outside of an environment).
700-
You can see the default settings by running:
700+
We can see the default settings by running:
701701

702702
.. code-block:: console
703703
@@ -708,10 +708,10 @@ You can see the default settings by running:
708708
:language: yaml
709709

710710

711-
As you can see, many of the directories Spack uses can be customized.
712-
For example, you can tell Spack to install packages to a prefix outside of the ``$SPACK_ROOT`` hierarchy.
713-
Module files can be written to a central location if you are using multiple Spack instances.
714-
If you have a fast scratch file system, you can run builds from this file system with the following ``config.yaml``:
711+
As we can see, many of the directories Spack uses can be customized.
712+
For example, we can tell Spack to install packages to a prefix outside of the ``$SPACK_ROOT`` hierarchy.
713+
Module files can be written to a central location if we are using multiple Spack instances.
714+
If we have a fast scratch file system, we can run builds from this file system with the following ``config.yaml``:
715715

716716
.. code-block:: yaml
717717
@@ -758,9 +758,9 @@ For example, on a node with 16 cores, this will look like:
758758
[+] /home/user/spack/opt/spack/linux-ubuntu22.04-x86_64/gcc-11.3.0/zlib-1.2.12-fntvsj6xevbz5gyq7kfa4xg7oxnaolxs
759759
760760
761-
As you can see, we are building with all 16 cores on the node.
762-
If you are on a shared login node, this can slow down the system for other users.
763-
If you have a strict ulimit or restriction on the number of available licenses, you may not be able to build at all with this many cores.
761+
As we can see, we are building with all 16 cores on the node.
762+
If we are on a shared login node, this can slow down the system for other users.
763+
If we have a strict ulimit or restriction on the number of available licenses, we may not be able to build at all with this many cores.
764764
To limit the number of cores our build uses, set ``build_jobs`` like so:
765765

766766
.. code-block:: console
@@ -790,7 +790,7 @@ If we uninstall and reinstall zlib-ng, we see that it now uses only 2 cores:
790790
[+] /home/user/spack/opt/spack/linux-ubuntu22.04...
791791
792792
793-
Obviously, if you want to build everything in serial for whatever reason, you would set ``build_jobs`` to 1.
793+
Obviously, if we want to build everything in serial for whatever reason, we would set ``build_jobs`` to 1.
794794

795795
Last, we'll unset ``concretizer:reuse:false`` since we'll want to enable concretizer reuse for the rest of this tutorial.
796796

@@ -800,7 +800,7 @@ Last, we'll unset ``concretizer:reuse:false`` since we'll want to enable concret
800800
801801
.. warning::
802802

803-
If you do not do this step, the rest of the tutorial will not reuse binaries!
803+
If we do not do this step, the rest of the tutorial will not reuse binaries!
804804

805805
----------
806806
Conclusion
@@ -811,4 +811,4 @@ Spack has many more configuration files, including ``modules.yaml``, which will
811811
For more detailed documentation on Spack's many configuration settings, see `the configuration section <https://spack.readthedocs.io/en/latest/configuration.html>`_ of Spack's main documentation.
812812

813813
For examples of how other sites configure Spack, see https://github.com/spack/spack-configs.
814-
If you use Spack at your site and want to share your config files, feel free to submit a pull request!
814+
If we use Spack at our site and want to share our config files, feel free to submit a pull request!

0 commit comments

Comments
 (0)