diff options
| -rw-r--r-- | README.md | 67 |
1 files changed, 35 insertions, 32 deletions
@@ -1,51 +1,54 @@ -* Theory of config +# Configuration Library - * Make the defaults the same everywhere +## Theory of Operation - * There are two types of config files: +The core philosophy of this library is to standardize configuration handling with sensible, consistent defaults. - 1) A super simple ENV key:value file (config.proto defined in this package) - 2) A application defined <appname>.proto (.proto wherever you want to put it) +There are two types of configuration files: +1. A simple environment-style `KEY=VALUE` file (defined by `config.proto` in this package). +2. An application-specific Protobuf file (e.g., `<appname>.proto`). -* 1) Basic application config.proto information +--- - the application config.proto is loaded from, in order: +### 1. Basic Application Configuration - /usr/share/doc/appname/config.text - /etc/default/appname - ~/.config/appname/config.text +This configuration uses a simple, environment-style file for basic settings. The file is loaded from the following locations, in order of precedence (later files override earlier ones): - These files ONLY HAVE ENV LIKE KEY/VALUE Pairs +1. `/usr/share/doc/<appname>/config.text` +2. `/etc/default/<appname>` +3. `~/.config/<appname>/config.text` -* 2) application specific protobuf files +**Note:** These files **must** only contain `KEY=VALUE` pairs. - Application config files are always located in the same place - with the same name by default. +--- - For the application "forge" using forge.proto +### 2. Application-Specific Protobuf Configuration - ~/.config/forge/forge.text +This is for the application's main data structure, defined in its own `.proto` file. By default, these files are always located in a standard location. - To override these defaults, set the values in the 1) protobuf +For an application named `forge` using a `forge.proto` definition, the default file path is: -* notes from the code +- `~/.config/forge/forge.text` -``` -// Because you followed autogenpb's advice (you did follow it right?) you now -// win the automation lottery. -// -// for this .proto file, GetProtobufName(pb) returns "repos" -// Then, ConfigLoad(), ConfigSave(), CacheLoad() and CacheSave() -// all do exactly what is expected: -// -// Automatically work with the files: -// ~/.config/<appname>/repos.pb -// or -// ~/.cache/<appname/repos.pb -// +The default paths and filenames can be overridden by setting the appropriate values in the basic application config file (see #1 above). + +--- + +## Code Example & Notes + +The `autogenpb` tool provides powerful automation. If you follow its conventions, the configuration and cache management functions work seamlessly. + +For a `.proto` file containing the message `Repos`, the function `GetProtobufName(pb)` will return `"repos"`. + +Consequently, the standard functions `ConfigLoad()`, `ConfigSave()`, `CacheLoad()`, and `CacheSave()` will automatically handle the correct files without any extra code: + +- **Config:** `~/.config/<appname>/repos.pb` +- **Cache:** `~/.cache/<appname>/repos.pb` + +```protobuf // message Repos { // string uuid = 1; // string version = 2; // repeated Repo repos = 3; -``` +```
\ No newline at end of file |