summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--lib/spack/docs/tutorial_configuration.rst113
1 files changed, 54 insertions, 59 deletions
diff --git a/lib/spack/docs/tutorial_configuration.rst b/lib/spack/docs/tutorial_configuration.rst
index e7ef5b92cd..f9221be9b4 100644
--- a/lib/spack/docs/tutorial_configuration.rst
+++ b/lib/spack/docs/tutorial_configuration.rst
@@ -133,7 +133,7 @@ We will start by opening the compilers configuration file
.. code-block:: console
- spack config edit compilers
+ $ spack config edit compilers
.. code-block:: yaml
@@ -514,16 +514,37 @@ okay.
Concretized
--------------------------------
- hdf5@1.10.1%clang@3.8.0-2ubuntu4+cxx~debug~fortran~hl+mpi+pic~shared~szip~threadsafe arch=linux-ubuntu16.04-x86_64
- ^zlib@1.2.11%clang@3.8.0-2ubuntu4+pic~shared arch=linux-ubuntu16.04-x86_64
+ hdf5@1.10.1%gcc@5.4.0~cxx~debug~fortran~hl~mpi+pic+shared~szip~threadsafe arch=linux-ubuntu16.04-x86_64
+ ^zlib@1.2.8%gcc@5.4.0+optimize+pic~shared arch=linux-ubuntu16.04-x86_64
+
+
+You'll notice that Spack is now using the external zlib installation,
+but the compiler used to build zlib is now overriding our compiler
+preference of clang. If we explicitly specify clang:
+
+.. code-block:: console
+
+ $ spack spec hdf5 %clang
+ Input spec
+ --------------------------------
+ hdf5%clang
+
+ Normalized
+ --------------------------------
+ hdf5%clang
+ ^zlib@1.1.2:
+
+ Concretized
+ --------------------------------
+ hdf5@1.10.1%clang@3.8.0-2ubuntu4~cxx~debug~fortran~hl~mpi+pic+shared~szip~threadsafe arch=linux-ubuntu16.04-x86_64
+ ^zlib@1.2.11%clang@3.8.0-2ubuntu4+optimize+pic~shared arch=linux-ubuntu16.04-x86_64
-You'll notice that this did not use our external zlib. Why?
-Because Spack concretized zlib to a different Spec than the
-one we provided. There are two ways we could get Spack to
-build with our external zlib. One would be to explicitly ask
-for that spec on the command line. The other is to tell Spack
-it's not allowed to build its own zlib. We'll go with the latter.
+Spack concretizes to both hdf5 and zlib being built with clang.
+This has a side-effect of rebuilding zlib. If we want to force
+Spack to use the system zlib, we have two choices. We can either
+specify it on the command line, or we can tell Spack that it's
+not allowed to build its own zlib. We'll go with the latter.
.. code-block:: yaml
@@ -537,7 +558,7 @@ it's not allowed to build its own zlib. We'll go with the latter.
variants: ~mpi
zlib:
paths:
- zlib@1.2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64: /usr
+ zlib@1.2.8%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64: /usr
buildable: False
@@ -545,30 +566,6 @@ Now Spack will be forced to choose the external zlib.
.. code-block:: console
- $ spack spec hdf5
- Input spec
- --------------------------------
- hdf5
-
- Normalized
- --------------------------------
- hdf5
- ^zlib@1.1.2:
-
- Concretized
- --------------------------------
- hdf5@1.10.1%gcc@5.4.0+cxx~debug~fortran~hl+mpi+pic~shared~szip~threadsafe arch=linux-ubuntu16.04-x86_64
- ^zlib@1.2.11%gcc@5.4.0+pic+shared arch=linux-ubuntu16.04-x86_64
-
-
-Note that Spack now concretizes the entire DAG to use the gcc
-compiler. Because we did not specify a build using the clang compiler
-(only expressed a preference) Spack used the gcc compiler specified by
-the zlib spec. If we want to use clang for the rest of the build, we
-have to specify it.
-
-.. code-block:: console
-
$ spack spec hdf5 %clang
Input spec
--------------------------------
@@ -581,8 +578,8 @@ have to specify it.
Concretized
--------------------------------
- hdf5@1.10.1%clang@3.8.0-2ubuntu4+cxx~debug~fortran~hl+mpi+pic~shared~szip~threadsafe arch=linux-ubuntu16.04-x86_64
- ^zlib@1.2.11%gcc@5.4.0+pic+shared arch=linux-ubuntu16.04-x86_64
+ hdf5@1.10.1%clang@3.8.0-2ubuntu4~cxx~debug~fortran~hl~mpi+pic+shared~szip~threadsafe arch=linux-ubuntu16.04-x86_64
+ ^zlib@1.2.8%gcc@5.4.0+optimize+pic~shared arch=linux-ubuntu16.04-x86_64
This gets slightly more complicated with virtual dependencies. Suppose
@@ -601,7 +598,7 @@ of hdf5? Well, fortunately we have mpich installed on these systems.
variants: ~mpi
zlib:
paths:
- zlib@1.2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64: /usr
+ zlib@1.2.8%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64: /usr
buildable: False
mpich:
paths:
@@ -638,7 +635,7 @@ build with an alternate MPI implementation.
^util-macros@1.19.1%clang@3.8.0-2ubuntu4 arch=linux-ubuntu16.04-x86_64
^libxml2@2.9.4%clang@3.8.0-2ubuntu4~python arch=linux-ubuntu16.04-x86_64
^xz@5.2.3%clang@3.8.0-2ubuntu4 arch=linux-ubuntu16.04-x86_64
- ^zlib@1.2.11%gcc@5.4.0+optimize+pic+shared arch=linux-ubuntu16.04-x86_64
+ ^zlib@1.2.8%gcc@5.4.0+optimize+pic+shared arch=linux-ubuntu16.04-x86_64
We have only expressed a preference for mpich over other MPI
@@ -662,7 +659,7 @@ again.
variants: ~shared
zlib:
paths:
- zlib@1.2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64: /usr
+ zlib@1.2.8%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64: /usr
buildable: False
mpich:
paths:
@@ -699,17 +696,22 @@ providers for MPI we can try again.
--------------------------------
hdf5@1.10.1%clang@3.8.0-2ubuntu4+cxx~debug~fortran~hl+mpi+pic~shared~szip~threadsafe arch=linux-ubuntu16.04-x86_64
^mpich@3.2%gcc@5.4.0 device=ch3 +hydra netmod=tcp +pmi+romio~verbs arch=linux-ubuntu16.04-x86_64
- ^zlib@1.2.11%gcc@5.4.0+pic+shared arch=linux-ubuntu16.04-x86_64
+ ^zlib@1.2.8%gcc@5.4.0+pic+shared arch=linux-ubuntu16.04-x86_64
-Now that we have hdf5 configured to install exactly as we want it, we
-can install it. We've now minimized the command line effort necessary
-to get exactly the hdf5 installation we want, and we can now build
-hdf5 against our external installations of zlib and mpich.
-.. code-block:: console
+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. In addition to compiler and variant
+preferences, we can specify version preferences as well. Anything
+that you can specify on the command line can be specified in
+``packages.yaml`` with the exact same spec syntax.
- $ spack install hdf5 %clang
- ...
+.. warning::
+
+ Make sure to delete or move the ``packages.yaml`` you have been
+ editing up to this point. Otherwise, it will change the hashes
+ of your packages, leading to differences in the output of later
+ tutorial sections.
-----------------
@@ -757,11 +759,11 @@ the build environment with the ``dirty`` setting:
However, this is strongly discouraged, as it can pull unwanted libraries
into the build.
-One last setting that may be of interest to users building on a shared
-login node is the ability to customize the parallelism of Spack builds.
-By default, Spack installs all packages in parallel with the number of
-jobs equal to the number of cores on the node. For example, on a node
-with 36 cores, this will look like:
+One last setting that may be of interest to many users is the ability
+to customize the parallelism of Spack builds. By default, Spack
+installs all packages in parallel with the number of jobs equal to the
+number of cores on the node. For example, on a node with 36 cores,
+this will look like:
.. code-block:: console
@@ -839,10 +841,3 @@ If we uninstall and reinstall zlib, we see that it now uses only 4 cores:
Obviously, if you want to build everything in serial for whatever reason,
you would set ``build_jobs`` to 1.
-.. warning::
-
- At this point, make sure you delete or move the ``packages.yaml`` and
- ``config.yaml`` you have been editing up to this point. Otherwise, they
- will change the hashes of your packages, leading to differences in the
- output of later tutorial sections.
-