Configuration File

In some cases, the user needs to pass specific parameters in the command line for each call. It may be needed to comply with a system’s constraints, or a repeated use of parameters, which can be bothersome to type for every command. For this reason, it is possible to update a selection of settings through a YAML configuration file, which is going to be read automatically at each call.

Configuration file locations

To have a configuration file be loaded by e4s-cl, it must be at one of these locations:

  1. A system-wide configuration in /etc/e4s-cl/e4s-cl.yaml

  2. An installation-centric configuration in <INSTALLDIR>/e4s-cl.yaml

  3. A user-only configuration in ~/.config/e4s-cl.yaml

Each level has a higher precedence over the above. You can override a system configuration by creating your own configuration file in the user location and setting the keys to your desired values.

Configuration options

The following options can be set in a configuration file:

Field

Description

Type

Default

container_directory

The path of the directory to bind e4s-cl files in.

Character string

/.e4s-cl

launcher_options

Command line options to append to the launcher when running a multi-process job.

List of string

[]

preload_root_libraries

Force preload of bound libraries. Useful if some of the libraries were compiled with RPATHs.

Boolean

True

disable_ranked_log

Disable generation of log files on a per-rank basis.

Boolean

False

e4s-cl will not run if the option value is malformed or its type cannot be understood. Any other key-value pair not supported by e4s-cl will be ignored.

Some configuration values can also be enabled on a per-module basis. They will be detailed on those modules’ documentation.

Command-line configuration management

You can read or update configuration values without editing YAML by using the config command. The list action prints the merged configuration, while set writes to the user configuration file.

# Show merged configuration
e4s-cl config list

# Read a single value
e4s-cl config get wi4mpi.install_directory

# Update user configuration
e4s-cl config set wi4mpi.install_directory /opt/wi4mpi

Configuration file template

Running e4s-cl with the --print-config option makes the program output a YAML document with all supported configuration fields and default values.

$ e4s-cl --print-config | tee ~/.config/e4s-cl.yaml
backends:
  apptainer:
    exec_options: []
    executable: ''
    options: []
  podman:
    executable: ''
    options: []
    run_options: []
  shifter:
    executable: ''
    options: []
  singularity:
    exec_options: []
    executable: ''
    options: []
  barebones:
    exec_options: []
    options: []
container_directory: /.e4s-cl
disable_ranked_log: true
launcher_options: []
preload_root_libraries: false
profile_list_columns: []