summaryrefslogtreecommitdiff
path: root/src/lib/conf.sh.3.ronn
blob: 1b26a060c278b16d13717334b8b6bf6891e065b3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
conf.sh(3) -- easy loading of configuration files
=================================================

## SYNOPSIS

`. "$(librelib conf)"`

## DESCRIPTION

`conf.sh` is a Bash(1) library to easily load various configuration
files related to Arch Linux/Parabola(7) and libretools(7).

### VARIABLES

When loading configuration files in a program run with `sudo`(8), it
is often desirable to load the configuration files from the home
directory of the user who called `sudo`, instead of from /root.

To accommodate this, instead of using the usual $<USER> and $<HOME>,
`conf.sh` sets $<LIBREUSER> and $<LIBREHOME>, which it then uses.

   * <LIBREUSER>:
     If $<SUDO_USER> is set, then $<LIBREUSER> is set to
     that. Otherwise, $<LIBREUSER> is set to the value of $<USER>.
   * <LIBREHOME>:
     If $<LIBREUSER> == $<USER>, then $<LIBREHOME> is set to the value
     of $<HOME>.  Otherwise, it is set to the default home directory
     of the user $<LIBREUSER>.

Further, `conf.sh` works with XDG; it sets and uses
$<XDG_CONFIG_HOME> and $<XDG_CACHE_HOME> with the following values:

   * <XDG_CONFIG_HOME>:
     If it isn't already set, it is set to "$<LIBREHOME>/.config" and
     exported.
   * <XDG_CACHE_HOME>:
     If it isn't already set, it is set to "$<LIBREHOME>/.cache" and
     exported.

Note that only the XDG_* variables are exported.

### GENERIC ROUTINES

The following routines take a "slug" to refer to a group of
configuration files; that is the basename of the files.  For example,
<SLUG>='abs' will identify `/etc/abs.conf` and `$<LIBREHOME>/.abs.conf`.

The routines you will likely actually use are:

   * `load_files` <SLUG>:
     Loads the configuration files for <SLUG>, loading the files in
     the correct order, and checking the appropriate environmental
     variables.
   * `check_vars` <SLUG> <VARS>...:
     Checks to see if all of <VARS> are defined.  If any of them
     aren't, it prints a message telling the user to configure them in
     the configuration files for <SLUG>, and returns with a non-zero
     status.
   * `get_var` <SLUG> <VAR> <DEFAULT>:
     If <VAR> is set in the configuration for <SLUG>, print its
     value, considering environmental variables.  If it is not set,
     return <DEFAULT>.  This does NOT work for array variables.
   * `set_var` <SLUG> <VAR> <VALUE>:
     Set the variable <VAR> equal to <VALUE> in the configuration file
     for <SLUG> of highest precedence that already exists and is
     writable.  If no files fit this description, the routine does
     nothing and returns a non-zero exit status.  This does NOT work
     for array variables.

There are two more routines the above routines use internally that are
used internally by by the above routines.  You are unlikely to use
them directly, but they might be useful for debugging, or at least
describing behavior.

   * `list_files` <SLUG>:
     Lists (newline-separated) the configuration files that must be
     considered for <SLUG>.  Files listed later take precedence over
     files listed earlier.
   * `list_envvars` <SLUG>:
     Lists (newline-separated) the environmental variables that take
     precedence over the settings in the configuration files for
     <SLUG>.  For example, in `makepkg.conf`(8) (<SLUG>=makepkg), if the
     <PACKAGER> environmental variable is set, the value in the
     configuration file is ignored.

### PKGBUILD ROUTINES

These two routines deal with loading `PKGBUILD`(5) files.

   * `unset_PKGBUILD`:
     Unsets all variables and functions that might be set in a
     `PKGBUILD`(5) file, including those specific to `librefetch`(8).
   * `load_PKGBUILD` [<FILE>]:
     "Safely" loads a PKGBUILD.  Everything that it would normally set
     is unset first, $<CARCH> is set according to `makepkg.conf`(5),
     then the file is loaded.  The file to be loaded is <FILE>, or
     "./PKGBUILD" by default.  This isn't safe, security wise, in that
     the PKGBUILD is free to execute code.

### SLUGS

The differences in behavior for anything that takes a slug comes down
to the differences in the output for `list_files` and `list_envvars`.

The "known" slugs are "abs", "makepkg", "libretools", and anything
beginning with "xbs".  If anything else is given, then:

   * `list_files` will give back "/etc/libretools.d/<SLUG>.conf" and
     "$<XDG_CONFIG_HOME>/libretools/<SLUG>.conf"
   * `list_envvars` will give back an empty list.

The rules for <SLUG>=(abs|makepkg|libretools) are more easily
expressed in code than prose, so it is recommended that you look at
that.

## BUGS

`get_var` and `set_var` do not work with arrays.

## SEE ALSO

librelib(7)

abs.conf(5), makepkg.conf(5), libretools.conf(5), PKGBUILD(5)

chroot.conf(5), librefetch.conf(5)