Spack Settings (config.yaml)

Spack’s basic configuration options are set in config.yaml. You can see the default settings by looking at etc/spack/defaults/config.yaml:

# -------------------------------------------------------------------------
# This is the default spack configuration file.
#
# Settings here are versioned with Spack and are intended to provide
# sensible defaults out of the box. Spack maintainers should edit this
# file to keep it current.
#
# Users can override these settings by editing the following files.
#
# Per-spack-instance settings (overrides defaults):
#   $SPACK_ROOT/etc/spack/config.yaml
#
# Per-user settings (overrides default and site settings):
#   ~/.spack/config.yaml
# -------------------------------------------------------------------------
config:
  # This is the path to the root of the Spack install tree.
  # You can use $spack here to refer to the root of the spack instance.
  install_tree:
    root: $spack/opt/spack
    projections:
      all: "{architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}"
    # install_tree can include an optional padded length (int or boolean)
    # default is False (do not pad)
    # if padded_length is True, Spack will pad as close to the system max path
    # length as possible
    # if padded_length is an integer, Spack will pad to that many characters,
    # assuming it is higher than the length of the install_tree root.
    # padded_length: 128


  # Locations where templates should be found
  template_dirs:
    - $spack/share/spack/templates

  # Directory where licenses should be located
  license_dir: $spack/etc/spack/licenses

  # Temporary locations Spack can try to use for builds.
  #
  # Recommended options are given below.
  #
  # Builds can be faster in temporary directories on some (e.g., HPC) systems.
  # Specifying `$tempdir` will ensure use of the default temporary directory
  # (i.e., ``$TMP` or ``$TMPDIR``).
  #
  # Another option that prevents conflicts and potential permission issues is
  # to specify `$user_cache_path/stage`, which ensures each user builds in their
  # home directory.
  #
  # A more traditional path uses the value of `$spack/var/spack/stage`, which
  # builds directly inside Spack's instance without staging them in a
  # temporary space.  Problems with specifying a path inside a Spack instance
  # are that it precludes its use as a system package and its ability to be
  # pip installable.
  #
  # In Spack environment files, chaining onto existing system Spack
  # installations, the $env variable can be used to download, cache and build
  # into user-writable paths that are relative to the currently active
  # environment.
  #
  # In any case, if the username is not already in the path, Spack will append
  # the value of `$user` in an attempt to avoid potential conflicts between
  # users in shared temporary spaces.
  #
  # The build stage can be purged with `spack clean --stage` and
  # `spack clean -a`, so it is important that the specified directory uniquely
  # identifies Spack staging to avoid accidentally wiping out non-Spack work.
  build_stage:
    - $tempdir/$user/spack-stage
    - $user_cache_path/stage
  # - $spack/var/spack/stage

  # Directory in which to run tests and store test results.
  # Tests will be stored in directories named by date/time and package
  # name/hash.
  test_stage: $user_cache_path/test

  # Cache directory for already downloaded source tarballs and archived
  # repositories. This can be purged with `spack clean --downloads`.
  source_cache: $spack/var/spack/cache


  ## Directory where spack managed environments are created and stored
  # environments_root: $spack/var/spack/environments


  # Cache directory for miscellaneous files, like the package index.
  # This can be purged with `spack clean --misc-cache`
  misc_cache: $user_cache_path/cache


  # Timeout in seconds used for downloading sources etc. This only applies
  # to the connection phase and can be increased for slow connections or
  # servers. 0 means no timeout.
  connect_timeout: 10


  # If this is false, tools like curl that use SSL will not verify
  # certifiates. (e.g., curl will use use the -k option)
  verify_ssl: true


  # This is where custom certs for proxy/firewall are stored.
  # It can be a path or environment variable. To match ssl env configuration
  # the default is the environment variable SSL_CERT_FILE
  ssl_certs: $SSL_CERT_FILE


  # Suppress gpg warnings from binary package verification
  # Only suppresses warnings, gpg failure will still fail the install
  # Potential rationale to set True: users have already explicitly trusted the
  # gpg key they are using, and may not want to see repeated warnings that it
  # is self-signed or something of the sort.
  suppress_gpg_warnings: false


  # If set to true, Spack will always check checksums after downloading
  # archives. If false, Spack skips the checksum step.
  checksum: true


  # If set to true, Spack will fetch deprecated versions without warning.
  # If false, Spack will raise an error when trying to install a deprecated version.
  deprecated: false


  # If set to true, `spack install` and friends will NOT clean
  # potentially harmful variables from the build environment. Use wisely.
  dirty: false


  # The language the build environment will use. This will produce English
  # compiler messages by default, so the log parser can highlight errors.
  # If set to C, it will use English (see man locale).
  # If set to the empty string (''), it will use the language from the
  # user's environment.
  build_language: C


  # When set to true, concurrent instances of Spack will use locks to
  # avoid modifying the install tree, database file, etc. If false, Spack
  # will disable all locking, but you must NOT run concurrent instances
  # of Spack.  For filesystems that don't support locking, you should set
  # this to false and run one Spack at a time, but otherwise we recommend
  # enabling locks.
  locks: true

  # The default url fetch method to use.
  # If set to 'curl', Spack will require curl on the user's system
  # If set to 'urllib', Spack will use python built-in libs to fetch
  url_fetch_method: urllib

  # The maximum number of jobs to use for the build system (e.g. `make`), when
  # the -j flag is not given on the command line. Defaults to 16 when not set.
  # Note that the maximum number of jobs is limited by the number of cores
  # available, taking thread affinity into account when supported. For instance:
  # - With `build_jobs: 16` and 4 cores available `spack install` will run `make -j4`
  # - With `build_jobs: 16` and 32 cores available `spack install` will run `make -j16`
  # - With `build_jobs: 2` and 4 cores available `spack install -j6` will run `make -j6`
  # build_jobs: 16


  # If set to true, Spack will use ccache to cache C compiles.
  ccache: false

  # How long to wait to lock the Spack installation database. This lock is used
  # when Spack needs to manage its own package metadata and all operations are
  # expected to complete within the default time limit. The timeout should
  # therefore generally be left untouched.
  db_lock_timeout: 60


  # How long to wait when attempting to modify a package (e.g. to install it).
  # This value should typically be 'null' (never time out) unless the Spack
  # instance only ever has a single user at a time, and only if the user
  # anticipates that a significant delay indicates that the lock attempt will
  # never succeed.
  package_lock_timeout: null


  # Control how shared libraries are located at runtime on Linux. See the
  # the Spack documentation for details.
  shared_linking:
    # Spack automatically embeds runtime search paths in ELF binaries for their
    # dependencies. Their type can either be "rpath" or "runpath". For glibc, rpath is
    # inherited and has precedence over LD_LIBRARY_PATH; runpath is not inherited
    # and of lower precedence. DO NOT MIX these within the same install tree.
    type: rpath


    # (Experimental) Embed absolute paths of dependent libraries directly in ELF
    # binaries to avoid runtime search. This can improve startup time of
    # executables with many dependencies, in particular on slow filesystems.
    bind: false


  # Set to 'false' to allow installation on filesystems that doesn't allow setgid bit
  # manipulation by unprivileged user (e.g. AFS)
  allow_sgid: true

  # Whether to show status information during building and installing packages.
  # This gives information about Spack's current progress as well as the current
  # and total number of packages. Information is shown both in the terminal
  # title and inline.
  install_status: true

  # Number of seconds a buildcache's index.json is cached locally before probing
  # for updates, within a single Spack invocation. Defaults to 10 minutes.
  binary_index_ttl: 600

  flags:
    # Whether to keep -Werror flags active in package builds.
    keep_werror: 'none'

  # A mapping of aliases that can be used to define new commands. For instance,
  # `sp: spec -I` will define a new command `sp` that will execute `spec` with
  # the `-I` argument. Aliases cannot override existing commands.
  aliases:
    concretise: concretize
    containerise: containerize
    rm: remove

These settings can be overridden in etc/spack/config.yaml or ~/.spack/config.yaml. See Configuration Scopes for details.

`install_tree:root`

The location where Spack will install packages and their dependencies. Default is $spack/opt/spack.

`install_hash_length` and `install_path_scheme`

The default Spack installation path can be very long and can create problems for scripts with hardcoded shebangs. Additionally, when using the Intel compiler, and if there is also a long list of dependencies, the compiler may segfault. If you see the following:

: internal error: ** The compiler has encountered an unexpected problem.
** Segmentation violation signal raised. **
Access violation or stack overflow. Please contact Intel Support for assistance.

it may be because variables containing dependency specs may be too long. There are two parameters to help with long path names. 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 {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 format() method. Using this parameter it is possible to use a different package layout or reduce the depth of the installation paths. For example

config:
  install_path_scheme: '{name}/{version}/{hash:7}'

would install packages into sub-directories using only the package name, version and a hash length of 7 characters.

When using either parameter to set the hash length it only affects the representation of the hash in the installation directory. You should be aware that the smaller the hash length the more likely naming conflicts will occur. These parameters are independent of those used to configure module names.

Warning

Modifying the installation hash length or path scheme after packages have been installed will prevent Spack from being able to find the old installation directories.

`build_stage`

Spack is designed to run out of a user home directory, and on many systems the home directory is a (slow) network file system. On most systems, building in a temporary file system is faster. Usually, there is also more space available in the temporary location than in the home directory. If the username is not already in the path, Spack will append the value of $user to the selected build_stage path.

Warning

We highly recommend specifying build_stage paths that distinguish between staging and other activities to ensure spack clean does not inadvertently remove unrelated files. Spack prepends spack-stage- to temporary staging directory names to reduce this risk. Using a combination of spack and or stage in each specified path, as shown in the default settings and documented examples, will add another layer of protection.

By default, Spack’s build_stage is configured like this:

build_stage:
 - $tempdir/$user/spack-stage
 - ~/.spack/stage

This can be an ordered list of paths that Spack should search when trying to find a temporary directory for the build stage. The list is searched in order, and Spack will use the first directory to which it has write access.

Specifying ~/.spack/stage first will ensure each user builds in their home directory. The historic Spack stage path $spack/var/spack/stage will build directly inside the Spack instance. See Config File Variables for more on $tempdir and $spack.

When Spack builds a package, it creates a temporary directory within the build_stage. After the package is successfully installed, Spack deletes the temporary directory it used to build. Unsuccessful builds are not deleted, but you can manually purge them with spack clean –stage.

Note

The build will fail if there is no writable directory in the build_stage list, where any user- and site-specific setting will be searched first.

`source_cache`

Location to cache downloaded tarballs and repositories. By default these are stored in $spack/var/spack/cache. These are stored indefinitely by default. Can be purged with spack clean –downloads.

`misc_cache`

Temporary directory to store long-lived cache files, such as indices of packages available in repositories. Defaults to ~/.spack/cache. Can be purged with spack clean –misc-cache.

`verify_ssl`

When set to true (default) Spack will verify certificates of remote hosts when making ssl connections. Set to false to disable, and tools like curl will use their --insecure options. Disabling 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. 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. When url_fetch_method:curl the config:ssl_certs should resolve to a single file. Spack will then set the environment variable CURL_CA_BUNDLE in the subprocess calling curl. If url_fetch_method:urllib then files and directories are supported i.e. config:ssl_certs:$SSL_CERT_FILE or config:ssl_certs:$SSL_CERT_DIR will work. In all cases the expanded path must be absolute for Spack to use the certificates. Certificates relative to an environment can be created by prepending the path variable with the Spack configuration variable``$env``.

`checksum`

When set to true, Spack verifies downloaded source code using a checksum, and will refuse to build packages that it cannot verify. Set to false to disable these checks. Disabling this can expose you to attacks. Use at your own risk.

`locks`

When set to true, concurrent instances of Spack will use locks to avoid modifying the install tree, database file, etc. If false, Spack will disable all locking, but you must not run concurrent instances of Spack. For file systems that don’t support locking, you should set this to false and run one Spack at a time, but otherwise we recommend enabling locks.

`dirty`

By default, Spack unsets variables in your environment that can change the way packages build. This includes LD_LIBRARY_PATH, CPATH, LIBRARY_PATH, DYLD_LIBRARY_PATH, and others.

By default, builds are clean, but on some machines, compilers and other tools may need custom LD_LIBRARY_PATH settings to run. You can set dirty to true to skip the cleaning step and make all builds “dirty” by default. Be aware that this will reduce the reproducibility of builds.

`build_jobs`

Unless overridden in a package or on the command line, Spack builds all packages in parallel. The default parallelism is equal to the number of cores available to the process, up to 16 (the default of build_jobs). For a build system that uses Makefiles, this spack install runs:

make -j<build_jobs>, when build_jobs is less than the number of cores available
make -j<ncores>, when build_jobs is greater or equal to the number of cores available

If you work on a shared login node or have a strict ulimit, it may be necessary to set the default to a lower value. By setting build_jobs to 4, for example, commands like spack install will run make -j4 instead of hogging every core. To build all software in serial, set build_jobs to 1.

Note that specifying the number of jobs on the command line always takes priority, so that spack install -j<n> always runs make -j<n>, even when that exceeds the number of cores available.

`ccache`

When set to true Spack will use ccache to cache compiles. This is useful specifically in two cases: (1) when using spack dev-build, and (2) when building the same package with many different variants. The default is false.

When enabled, Spack will look inside your PATH for a ccache executable and stop if it is not found. Some systems come with ccache, but it can also be installed using spack install ccache. ccache comes with reasonable defaults for cache size and location. (See the Configuration settings section of man ccache to learn more about the default settings and how to change them). Please note that we currently disable ccache’s hash_dir feature to avoid an issue with the stage directory (see https://github.com/spack/spack/pull/3761#issuecomment-294352232).

`shared_linking:type`

Control whether Spack embeds RPATH or RUNPATH attributes in ELF binaries so that they can find their dependencies. Has no effect on macOS. Two options are allowed:

rpath uses RPATH and forces the --disable-new-tags flag to be passed to the linker

runpath uses RUNPATH and forces the --enable-new-tags flag to be passed to the linker

RPATH search paths have higher precedence than LD_LIBRARY_PATH and ld.so will search for libraries in transitive RPATHs of parent objects.

RUNPATH search paths have lower precedence than LD_LIBRARY_PATH, and ld.so will ONLY search for dependencies in the RUNPATH of the loading object.

DO NOT MIX the two options within the same install tree.

`shared_linking:bind`

This is an experimental option that controls whether Spack embeds absolute paths to needed shared libraries in ELF executables and shared libraries on Linux. Setting this option to true has two advantages:

Improved startup time: when running an executable, the dynamic loader does not have to perform a search for needed libraries, they are loaded directly.
Reliability: libraries loaded at runtime are those that were linked to. This minimizes the risk of accidentally picking up system libraries.

In the current implementation, Spack sets the soname (shared object name) of libraries to their install path upon installation. This has two implications:

binding does not apply to libraries installed before the option was enabled;
toggling the option off does not prevent binding of libraries installed when the option was still enabled.

It is also worth noting that:

Applications relying on dlopen(3) will continue to work, even when they open a library by name. This is because RPATHs are retained in binaries also when bind is enabled.
LD_PRELOAD continues to work for the typical use case of overriding symbols, such as preloading a library with a more efficient malloc. However, the preloaded library will be loaded additionally to, instead of in place of another library with the same name — this can be problematic in very rare cases where libraries rely on a particular init or fini order.

Note

In some cases packages provide stub libraries that only contain an interface for linking, but lack an implementation for runtime. An example of this is libcuda.so, provided by the CUDA toolkit; it can be used to link against, but the library needed at runtime is the one installed with the CUDA driver. To avoid binding those libraries, they can be marked as non-bindable using a property in the package:

class Example(Package):
   non_bindable_shared_objects = ["libinterface.so"]

`install_status`

When set to true, Spack will show information about its current progress as well as the current and total package numbers. Progress is shown both in the terminal title and inline. Setting it to false will not show any progress information.

To work properly, this requires your terminal to reset its title after Spack has finished its work, otherwise Spack’s status information will remain in the terminal’s title indefinitely. Most terminals should already be set up this way and clear Spack’s status information.

`aliases`

Aliases can be used to define new Spack commands. They can be either shortcuts for longer commands or include specific arguments for convenience. For instance, if users want to use spack install’s -v argument all the time, they can create a new alias called inst that will always call install -v:

aliases:
  inst: install -v

Spack Settings (config.yaml)

install_tree:root

install_hash_length and install_path_scheme

build_stage

source_cache

misc_cache

verify_ssl

ssl_certs

checksum

locks

dirty

build_jobs

ccache

shared_linking:type

shared_linking:bind

install_status

aliases