diff --git a/doc/src/03100-lib-rt.md b/doc/src/03100-lib-rt.md index 67e6f10d..3053adeb 100644 --- a/doc/src/03100-lib-rt.md +++ b/doc/src/03100-lib-rt.md @@ -9,3 +9,65 @@ 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: `$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} +