libeconf: README.md Source File

libeconf 0.7.1

README.md
Go to the documentation of this file.
1 # libeconf
2
3 **libeconf** is a highly flexible and configurable library to parse and
4 manage key=value configuration files.
5 It reads configuration file snippets from different directories and builds
6 the final configuration file for the application from it.
7
8 The first file is the vendor provided configuration file places in /usr/_vendordir_/_project_.
9 Optionally, /run/_project_ is also supported for ephemeral overrides.
10
11 *Defining _project_ sub directory is optional.*
12
13 There are two methods of overriding this vendor settings: Copy the file from
14 /usr/_vendordir_/_project_ to /etc/_project_ and modify the settings (see *Example 1*).
15
16 Alternatively, a directory named _file_._suffix_.d/ within /etc/_project_ can be created,
17 with drop-in files in the form _name_._suffix_ (see *Example 2*).
18
19 These files contain only the changes of the specific settings the user is
20 interested in.
21 There can be several such drop-in files, they are processed in
22 lexicographic order of their filename.
23
24 The first method is useful to override the complete configuration file with an
25 own one, the vendor supplied configuration is ignored.
26
27 So, if /etc/_project_/_example_._suffix_ exists, /usr/_vendor_/_project_/_example_._suffix_
28 and /run/_project_/_example_._suffix_ will not be read.
29 The disadvantage is, that changes of the vendor configuration file, due e.g.
30 an package update, are ignored and the user has to manually merge them.
31
32 The other method will continue to use /usr/_vendor_/_project_/_example_._suffix_ as base
33 configuration file and merge all changes from /etc/_project_/_example_._suffix_.d/*._suffix_.
34 So the user will automatically get improvements of the vendor, with the drawback,
35 that they could be incompatible with the user made changes.
36
37 If there is a file with the same name in /usr/_vendor_/_project_/_example_._suffix_.d/ and
38 in /etc/_project_/_example_._suffix_.d/*._suffix_., the file in /usr/_project_/_vendor_/_example_._suffix_.d/
39 will completely ignored.
40
41 To disable a configuration file supplied by the vendor, the recommended way is to place
42 a symlink to /dev/null in the configuration directory in /etc/_project_/, with the same filename
43 as the vendor configuration file.
44
45 Optionally, schemes with only drop-ins and without a ‘main’ configuration file will be supported too. In such
46 schemes many drop-ins are loaded from a common directory in each hierarchy.
47 For example, /usr/lib/_project_.d/*, /run/_project_.d/* and /etc/_project_.d/c.conf are all loaded and parsed
48 in this scheme.
49
50 **Example 1**
51
52 If a /etc/_example_._suffix_ file exists:
53
54 * /etc/_example_._suffix_
55 * /usr/_vendor_/_project_/_example_._suffix_.d/*._suffix_
56 * /run/_project_/_example_._suffix_.d/*._suffix_
57 * /etc/_project_/_example_._suffix_.d/*._suffix_
58
59 **Example 2**
60
61 The list of files and directories read if **no** /etc/_example_._suffix_ file
62 exists:
63
64 * /usr/_vendor_/_project_/_example_._suffix_ if no /run/_project_/_example_._suffix_ exist
65 * /usr/_vendor_/_project_/_example_._suffix_.d/*._suffix_
66 * /run/_project_/_example_._suffix_.d/*._suffix_
67 * /etc/_project_/_example_._suffix_.d/*._suffix_
68
69 The libeconf library fulfills all requirements defined by the **Linux Userspace API (UAPI) Group**
70 chapter "Configuration Files Specification".
71 See: :https://uapi-group.org/specifications/specs/configuration_files_specification/
72
73 ## API
74
75 The API is written in plain C. The description can be found here :https://opensuse.github.io/libeconf/
76
77 ## Bindings for other languages
78
79 - [Python](https://github.com/openSUSE/libeconf/blob/v0.7.0/bindings/python3/) ([Documentation](https://github.com/openSUSE/libeconf/blob/v0.6.0/bindings/python3/docs/python-libeconf.3)
80 - [C#](https://github.com/openSUSE/libeconf/blob/v0.7.0/bindings/csharp/) ([Documentation](https://github.com/openSUSE/libeconf/blob/v0.6.0/bindings/csharp/docs/README.md))