summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTodd Gamblin <tgamblin@llnl.gov>2018-06-24 00:49:18 -0700
committerTodd Gamblin <tgamblin@llnl.gov>2018-07-21 14:04:18 -0700
commitb2f3b07ec02cf6db9f8fbab61f9d61b97e33c1c8 (patch)
treee080bce90ac651c08d05e52358c65127b9bb6822
parent331da779f8f7d2f57655868f27ac76446af85f81 (diff)
downloadspack-b2f3b07ec02cf6db9f8fbab61f9d61b97e33c1c8.tar.gz
spack-b2f3b07ec02cf6db9f8fbab61f9d61b97e33c1c8.tar.bz2
spack-b2f3b07ec02cf6db9f8fbab61f9d61b97e33c1c8.tar.xz
spack-b2f3b07ec02cf6db9f8fbab61f9d61b97e33c1c8.zip
docs: doucment `spack config blame`
-rw-r--r--lib/spack/docs/configuration.rst63
1 files changed, 59 insertions, 4 deletions
diff --git a/lib/spack/docs/configuration.rst b/lib/spack/docs/configuration.rst
index dd51d37d67..6d3744f78c 100644
--- a/lib/spack/docs/configuration.rst
+++ b/lib/spack/docs/configuration.rst
@@ -428,10 +428,20 @@ Seeing Spack's configuration
----------------------------
With so many scopes overriding each other, it can sometimes be difficult
-to understand what Spack's final configuration looks like. ``spack
-config get`` shows a fully merged configuration file, taking into account
-all scopes. For example, to see the fully merged ``config.yaml``, you
-can type:
+to understand what Spack's final configuration looks like.
+
+Spack provides two useful ways to view the final "merged" version of any
+configuration file: ``spack config get`` and ``spack config blame``.
+
+.. _cmd-spack-config-get:
+
+^^^^^^^^^^^^^^^^^^^^
+``spack config get``
+^^^^^^^^^^^^^^^^^^^^
+
+``spack config get`` shows a fully merged configuration file, taking into
+account all scopes. For example, to see the fully merged
+``config.yaml``, you can type:
.. code-block:: console
@@ -470,3 +480,48 @@ see how your scope will affect Spack's configuration:
.. code-block:: console
$ spack -C /path/to/my/scope config get packages
+
+
+.. _cmd-spack-config-blame:
+
+^^^^^^^^^^^^^^^^^^^^^^
+``spack config blame``
+^^^^^^^^^^^^^^^^^^^^^^
+
+``spack config blame`` functions much like ``spack config get``, but it
+shows exactly which configuration file each preference came from. If you
+do not know why Spack is behaving a certain way, this can help you track
+down the problem:
+
+.. code-block:: console
+
+ $ spack --insecure -C ./my-scope -C ./my-scope-2 config blame config
+ ==> Warning: You asked for --insecure. Will NOT check SSL certificates.
+ --- config:
+ _builtin debug: False
+ /home/myuser/spack/etc/spack/defaults/config.yaml:72 checksum: True
+ command_line verify_ssl: False
+ ./my-scope-2/config.yaml:2 dirty: False
+ _builtin build_jobs: 8
+ ./my-scope/config.yaml:2 install_tree: /path/to/some/tree
+ /home/myuser/spack/etc/spack/defaults/config.yaml:23 template_dirs:
+ /home/myuser/spack/etc/spack/defaults/config.yaml:24 - $spack/templates
+ /home/myuser/spack/etc/spack/defaults/config.yaml:28 directory_layout: ${ARCHITECTURE}/${COMPILERNAME}-${COMPILERVER}/${PACKAGE}-${VERSION}-${HASH}
+ /home/myuser/spack/etc/spack/defaults/config.yaml:32 module_roots:
+ /home/myuser/spack/etc/spack/defaults/config.yaml:33 tcl: $spack/share/spack/modules
+ /home/myuser/spack/etc/spack/defaults/config.yaml:34 lmod: $spack/share/spack/lmod
+ /home/myuser/spack/etc/spack/defaults/config.yaml:35 dotkit: $spack/share/spack/dotkit
+ /home/myuser/spack/etc/spack/defaults/config.yaml:49 build_stage:
+ /home/myuser/spack/etc/spack/defaults/config.yaml:50 - $tempdir
+ /home/myuser/spack/etc/spack/defaults/config.yaml:51 - /nfs/tmp2/$user
+ /home/myuser/spack/etc/spack/defaults/config.yaml:52 - $spack/var/spack/stage
+ /home/myuser/spack/etc/spack/defaults/config.yaml:57 source_cache: $spack/var/spack/cache
+ /home/myuser/spack/etc/spack/defaults/config.yaml:62 misc_cache: ~/.spack/cache
+ /home/myuser/spack/etc/spack/defaults/config.yaml:86 locks: True
+
+You can see above that the ``build_jobs`` and ``debug`` settings are
+built in and are not overridden by a configuration file. The
+``verify_ssl`` setting comes from the ``--insceure`` option on the
+command line. ``dirty`` and ``install_tree`` come from the command-line
+scopes ``./my-scope`` and ``./my-scope-2``, and all other configuration
+options come from the default configuration files that ship with Spack.