Basic Settings¶

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: $spack/opt/spack


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


  # Default directory layout
  install_path_scheme: "${ARCHITECTURE}/${COMPILERNAME}-${COMPILERVER}/${PACKAGE}-${VERSION}-${HASH}"


  # Locations where different types of modules should be installed.
  module_roots:
    tcl:    $spack/share/spack/modules
    lmod:   $spack/share/spack/lmod


  # 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 `~/.spack/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 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
    - ~/.spack/stage
  # - $spack/var/spack/stage


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


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


  # 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


  # 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 attempt to build any compiler on the spec
  # that is not already available. If set to False, Spack will only use
  # compilers already configured in compilers.yaml
  install_missing_compilers: 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 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 maximum number of jobs to use when running `make` in parallel,
  # always limited by the number of cores available. For instance:
  # - If set to 16 on a 4 cores machine `spack install` will run `make -j4`
  # - If set to 16 on a 18 cores machine `spack install` will run `make -j16`
  # If not set, Spack will use all available cores up to 16.
  # 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: 3


  # 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 whether Spack embeds RPATH or RUNPATH attributes in ELF binaries.
  # Has no effect on macOS. DO NOT MIX these within the same install tree.
  # See the Spack documentation for details.
  shared_linking: 'rpath'

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

`install_tree`¶

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.

`module_roots`¶

Controls where Spack installs generated module files. You can customize the location for each type of module. e.g.:

module_roots:
  tcl:    $spack/share/spack/modules
  lmod:   $spack/share/spack/lmod

See Modules for details.

`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.

`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 on your machine, up to 16. Parallelism cannot exceed the number of cores available on the host. For a build system that uses Makefiles, this means running:

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

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.

`ccache`¶

When set to true Spack will use ccache to cache compiles. This is useful specifically in two cases: (1) when using spack setup, 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/LLNL/spack/pull/3761#issuecomment-294352232).

`shared_linking`¶

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.

Basic Settings¶

install_tree¶

install_hash_length and install_path_scheme¶

module_roots¶

build_stage¶

source_cache¶

misc_cache¶

verify_ssl¶

checksum¶

locks¶

dirty¶

build_jobs¶

ccache¶

shared_linking¶