Configuration¶

Description¶

Exec-helper configuration files are written in the YAML 1.2 specification.

Mandatory keys¶

A valid configuration file must contain at least the following keys on the root level of the configuration file:

commands

The commands that are configured in the configuration file. It will either contain a list of commands or a list of the commands as keys with an explanation of the command as a value. These formats can not be used interchangeably.

<command-keys>

For every command defined under the commands key, the configuration must define this command as a key in the root of the configuration file. The value of the key must either be a registered plugin or another command.

<plugin-keys>

For at least every plugin that is used by a command key, configure the specifics of the plugin (if applicable).

Optional keys¶

Optionally the configuration file contains the following keys on the root level of the configuration file:

patterns: Patterns are parts of the configuration that will be replaced by its value when evaluated by exec-helper. The patterns keyword describes a list of patterns identified by their key. See the @ref exec-helper-config-patterns for more information about how to define a pattern.

additional-search-paths

An ordered list of additional search paths to use when searching for plugins. The search paths can be absolute or relative w.r.t. the parent path of the settings file in which these paths are defined.

Defining search paths is useful for extending exec-helper with your own custom plugins or for overwriting or extending the functionality in the provided plugins. See [exec-helper-custom-plugins](@ref exec-helper-custom-plugins)(5) for more information on writing a custom plugin.

The paths defined in this list take precedence over the system search paths for modules with the same name. A higher position in this list implicates higher precedence.

Working directory¶

Configured commands are executed from the so-called working directory. Executing commands in a different working directory will not affect your current working directory (e.g. when executing from a shell). Each separately configured command can be executed in a separate working directory.

The working directory is the directory that is associated with the first of the following lines whose requirement is met: 1. The working-dir configuration setting is configured for the specific command. The value of the working-dir configuration key can be an absolute path to the working directory or a relative one w.r.t. the directory of the considered configuration file. If the command should be executed in the actual working directory, use <working-dir> as the value in the configuration file. 2. The directory of the considered configuration file.

Paths¶

All relative paths in the configuration should be relative to the directory in which the configuration resides. While relative paths are convenient for users as they can freely choose the root directory of an application, some applications require an absolute path. In such case, use the ${PWD} environment variable (both POSIX and non-POSIX systems) to convert a relative path in your configuration into an absolute path for calling these particular applications.

Example configuration¶

commands:                       # The mandatory commands key
    build: Build the project    # A map of command keys with their explanation
    clean: Clean the project
    rebuild: Build + clean

patterns:                       # Declare the patterns for this configuration file
    COMPILER:                   # Declare the COMPILER pattern
        default-values:         # Default values to use for the pattern
            - g++
            - clang++
        short-option: c         # Declare values for this pattern by using the -c [VALUES] option when calling exec-helper
        long-option: compiler   # Declare values for this pattern by using the --compiler [VALUES] option when calling exec-helper
    MODE:                       # Declare the MODE pattern
        default-values:
            - debug
            - release
        short-option: m
        long-option: mode

additional-search-paths:
    - /tmp

# Define the commands listed under 'commands'
build:
    - command-line-command      # Use the command-line-command plugin when using the 'build' command

clean:
    - command-line-command      # Use the command-line-command plugin when using the 'clean' command

rebuild:
    - clean                     # Call the 'clean' command when calling the 'rebuild' command
    - build                     # Call the 'build' command when calling the 'rebuild' command

command-line-command:           # Configure the command-line-command
    patterns:                   # Define the default patterns to use
        - COMPILER
        - MODE

    command-line:               # Configure the execution when the specific command is not listed. Will be executed from the directory of this configuration file
        - echo
        - building
        - using
        - "{COMPILER}"          # This value will be replaced by the COMPILER pattern value
        - in
        - "{MODE}"              # This value will be replaced by the MODE pattern value
        - mode.
        - wd=$(pwd)             # This command will be executed in a subshell and replaced by its value before the actual command is executed

    clean:                      # Configure the execution of the build command
        patterns:               # Overwrite the parent patterns
            - MODE
            - EH_WORKING_DIR    # Use the EH_WORKING_DIR pattern
        command-line:
            - echo
            - cleaning
            - mode.
            - "{MODE}"          # This value will be replaced by the MODE pattern value
            - wd=$(pwd)
        working-dir: "{EH_WORKING_DIR}" # The command will be executed from the current working directory rather than from the directory of this configuration file