imag/doc/src/03100-lib-rt.md

# librt {#sec:librt}

The runtime library provides types and functions which MUST be used by the
modules to implement the commandline interface, configuration file parsing and
logging.

The runtime library provides basic functionality for configuration file parsing
and logging setup.
The runtime library also provides helper functions for building a commandline
interface.

## Configuration file {#sec:librt:cfg}

The runtime library SHOULD read the configuration file, if it can be found.
If the configuration file cannot be found, the following variables are set to
their default values as shown in @tbl:librt:cfg:defaultvalues.

| Variable       | Value                |
| :------------- | :------------------- |
| verbosity      | false                |
| debugging      | false                |
| store location | `$HOME/.imag/store/` |

Table: Default values for configuration if configuration file unavailable
{#tbl:librt:cfg:defaultvalues}

### Location of the configuration file {#sec:librt:cfg:location}

For the configuration file is searched at the following locations:

1. Path: `$runtimepath/config`
1. Path: `$runtimepath/config.toml`
1. Path: `$runtimepath/imagrc`
1. Path: `$runtimepath/imagrc.toml`
1. Path: `$HOME/.imag/config`
1. Path: `$HOME/.imag/config.toml`
1. Path: `$HOME/.imag/imagrc`
1. Path: `$HOME/.imag/imagrc.toml`
1. Path: `$XDG_CONFIG_DIR/imag/config`
1. Path: `$XDG_CONFIG_DIR/imag/config.toml`
1. Path: `$XDG_CONFIG_DIR/imag/imagrc`
1. Path: `$XDG_CONFIG_DIR/imag/imagrc.toml`
1. Path in the environment variable `$IMAG_CONFIG`

If neither of these configuration files are found, the program MUST USE the
default values for the minimum required variables
(@tbl:librt:cfg:defaultvalues).

### Contents of the configuration file {#sec:librt:cfg:contents}

The contents of the configuration file MUST BE encoded in Unicode UTF-8.
The contents of the configuration file are structured as TOML, regardless of the
file extension.

The configuration file contains several sections:

1. The `base` section, which contains basic variables
   (@tbl:librt:cfg:contents:base)
1. The `modules` section, which contains a section for each module.
1. The `store` section, which contains configuration on the behaviour of the
   store (@tbl:librt:cfg:contents:store)

| Variable       | Type    |
| :------------- | :------ |
| verbosity      | boolean |
| debugging      | boolean |
| store location | Path    |

Table: "Base" variables in the configuration file {#tbl:librt:cfg:contents:base}


| Variable  | Type    | Meaning                                          |
| :-------- | :------ | :----------------------------------------------- |
| git-vcs   | boolean | Whether the store is version controlled with git |

Table: "store" variables in the configuration file {#tbl:librt:cfg:contents:store}