diff --git a/doc/src/03100-lib-rt.md b/doc/src/03100-lib-rt.md new file mode 100644 index 00000000..3053adeb --- /dev/null +++ b/doc/src/03100-lib-rt.md @@ -0,0 +1,73 @@ +# 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: `$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} + diff --git a/doc/src/06000-modules.md b/doc/src/06000-modules.md index 3e7a06ce..0edf2667 100644 --- a/doc/src/06000-modules.md +++ b/doc/src/06000-modules.md @@ -1,2 +1,20 @@ # Modules {#sec:modules} +A module is a functionality of the program. + +A module MAY store data in the store (@sec:thestore). +It MAY include user input in the data it stores in the store. +A module MUST HAVE a commandline interface, though a module always consists of +two parts: + +- A Library +- A Binary, which + * is executable by the user + * implements a commandline frontend to the libray of the module + +By definition, the Binary depends on the Library. +By definition, the Library depends on the libstore (@sec:libstore). + +A module MUST use the runtime library to implement the commandline +interface as defined in @sec:librt. +