diff options
| -rw-r--r-- | lib/spack/docs/basic_usage.rst | 115 | ||||
| -rw-r--r-- | lib/spack/docs/config_yaml.rst | 11 | ||||
| -rw-r--r-- | lib/spack/docs/module_file_support.rst | 2 |
3 files changed, 119 insertions, 9 deletions
diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst index 8748762fa0..d2aad69d3b 100644 --- a/lib/spack/docs/basic_usage.rst +++ b/lib/spack/docs/basic_usage.rst @@ -334,6 +334,10 @@ Packages are divided into groups according to their architecture and compiler. Within each group, Spack tries to keep the view simple, and only shows the version of installed packages. +"""""""""""""""""""""""""""""""" +Viewing more metadata +"""""""""""""""""""""""""""""""" + ``spack find`` can filter the package list based on the package name, spec, or a number of properties of their installation status. For example, missing dependencies of a spec can be shown with ``--missing``, packages which were @@ -391,8 +395,8 @@ use ``spack find --paths``: callpath@1.0.2 ~/spack/opt/linux-debian7-x86_64/gcc@4.4.7/callpath@1.0.2-5dce4318 ... -And, finally, you can restrict your search to a particular package -by supplying its name: +You can restrict your search to a particular package by supplying its +name: .. code-block:: console @@ -402,6 +406,10 @@ by supplying its name: libelf@0.8.12 ~/spack/opt/linux-debian7-x86_64/gcc@4.4.7/libelf@0.8.12 libelf@0.8.13 ~/spack/opt/linux-debian7-x86_64/gcc@4.4.7/libelf@0.8.13 +"""""""""""""""""""""""""""""""" +Spec queries +"""""""""""""""""""""""""""""""" + ``spack find`` actually does a lot more than this. You can use *specs* to query for specific configurations and builds of each package. If you want to find only libelf versions greater than version @@ -429,6 +437,109 @@ with the 'debug' compile-time option enabled. The full spec syntax is discussed in detail in :ref:`sec-specs`. + +"""""""""""""""""""""""""""""""" +Machine-readable output +"""""""""""""""""""""""""""""""" + +If you only want to see very specific things about installed packages, +Spack has some options for you. ``spack find --format`` can be used to +output only specific fields: + +.. code-block:: console + + $ spack find --format "{name}-{version}-{hash}" + autoconf-2.69-icynozk7ti6h4ezzgonqe6jgw5f3ulx4 + automake-1.16.1-o5v3tc77kesgonxjbmeqlwfmb5qzj7zy + bzip2-1.0.6-syohzw57v2jfag5du2x4bowziw3m5p67 + bzip2-1.0.8-zjny4jwfyvzbx6vii3uuekoxmtu6eyuj + cmake-3.15.1-7cf6onn52gywnddbmgp7qkil4hdoxpcb + ... + +or: + +.. code-block:: console + + $ spack find --format "{hash:7}" + icynozk + o5v3tc7 + syohzw5 + zjny4jw + 7cf6onn + ... + +This uses the same syntax as described in documentation for +:meth:`~spack.spec.Spec.format` -- you can use any of the options there. +This is useful for passing metadata about packages to other command-line +tools. + +Alternately, if you want something even more machine readable, you can +output each spec as JSON records using ``spack find --json``. This will +output metadata on specs and all dependencies as json: + +.. code-block:: console + + $ spack find --json sqlite@3.28.0 + [ + { + "name": "sqlite", + "hash": "3ws7bsihwbn44ghf6ep4s6h4y2o6eznv", + "version": "3.28.0", + "arch": { + "platform": "darwin", + "platform_os": "mojave", + "target": "x86_64" + }, + "compiler": { + "name": "clang", + "version": "10.0.0-apple" + }, + "namespace": "builtin", + "parameters": { + "fts": true, + "functions": false, + "cflags": [], + "cppflags": [], + "cxxflags": [], + "fflags": [], + "ldflags": [], + "ldlibs": [] + }, + "dependencies": { + "readline": { + "hash": "722dzmgymxyxd6ovjvh4742kcetkqtfs", + "type": [ + "build", + "link" + ] + } + } + }, + ... + ] + +You can use this with tools like `jq <https://stedolan.github.io/jq/>`_ to quickly create JSON records +structured the way you want: + +.. code-block:: console + + $ spack find --json sqlite@3.28.0 | jq -C '.[] | { name, version, hash }' + { + "name": "sqlite", + "version": "3.28.0", + "hash": "3ws7bsihwbn44ghf6ep4s6h4y2o6eznv" + } + { + "name": "readline", + "version": "7.0", + "hash": "722dzmgymxyxd6ovjvh4742kcetkqtfs" + } + { + "name": "ncurses", + "version": "6.1", + "hash": "zvaa4lhlhilypw5quj3akyd3apbq5gap" + } + .. _sec-specs: -------------------- diff --git a/lib/spack/docs/config_yaml.rst b/lib/spack/docs/config_yaml.rst index ef3ad1d03a..ef5d7b65be 100644 --- a/lib/spack/docs/config_yaml.rst +++ b/lib/spack/docs/config_yaml.rst @@ -36,14 +36,13 @@ to help with that. Firstly, the ``install_hash_length`` parameter can set the length of the hash in the installation path from 1 to 32. The default path uses the full 32 characters. -Secondly, it is -also possible to modify the entire installation scheme. By default -Spack uses +Secondly, it is also possible to modify the entire installation +scheme. By default Spack uses ``{architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}`` where the tokens that are available for use in this directive are the -same as those understood by the ``Spec.format`` method. Using this parameter it -is possible to use a different package layout or reduce the depth of -the installation paths. For example +same as those understood by the :meth:`~spack.spec.Spec.format` +method. Using this parameter it is possible to use a different package +layout or reduce the depth of the installation paths. For example .. code-block:: yaml diff --git a/lib/spack/docs/module_file_support.rst b/lib/spack/docs/module_file_support.rst index 85221dd2f8..8fcb38d81f 100644 --- a/lib/spack/docs/module_file_support.rst +++ b/lib/spack/docs/module_file_support.rst @@ -545,7 +545,7 @@ most likely via the ``+blas`` variant specification. base directory of the same module, effectively preventing the possibility to load two or more versions of the same software at the same time. The tokens that are available for use in this directive are the same understood by - the ``Spec.format`` method. + the :meth:`~spack.spec.Spec.format` method. .. note:: |