summaryrefslogtreecommitdiff
path: root/src/lib/conf.sh.3.ronn
diff options
context:
space:
mode:
authorLuke Shumaker <LukeShu@sbcglobal.net>2013-10-02 15:32:45 -0400
committerLuke Shumaker <LukeShu@sbcglobal.net>2013-10-02 15:32:45 -0400
commitf5b650a06cddd447ad7a75330e9e9c6baf23ccc4 (patch)
tree8be9f443b7056a9c08beb37fce490e99d1ea26a1 /src/lib/conf.sh.3.ronn
parent86ee0a5da2a3a02d291ae40c8570bcd97ff066de (diff)
Add documentation for lib/
* Add a bunch of man-pages * Add some comments to conf.sh * Add more information to librelib:usage()
Diffstat (limited to 'src/lib/conf.sh.3.ronn')
-rw-r--r--src/lib/conf.sh.3.ronn136
1 files changed, 136 insertions, 0 deletions
diff --git a/src/lib/conf.sh.3.ronn b/src/lib/conf.sh.3.ronn
new file mode 100644
index 0000000..a2bc862
--- /dev/null
+++ b/src/lib/conf.sh.3.ronn
@@ -0,0 +1,136 @@
+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).
+
+I recommend reading the source yourself--it is mostly
+self-explanatory, and is shorter than this document.
+
+### 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 to configure them in the
+ configuration files for <SLUG>, and returns with a non-zero
+ status.
+
+There are also two more routines that are used internally by
+the above. You are unlikely to use them directly, but they might
+be useful for debugging.
+
+ * `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.
+
+### MAKEPKG.CONF ROUTINES
+
+These two routines exist to get and set individual variables in
+`makepkg.conf`(). See the output of `list_files makepkg` for exactly
+what set of files that refers to.
+
+These routines do NOT work with array settings.
+
+ * `get_conf_makepkg` <VAR> <DEFAULT>:
+ If <VAR> is set, return it's value, considering environmental
+ variables. If it is not set, return <DEFAULT>. The printed
+ value is then trailed by a newline.
+ * `set_conf_makepkg` <VAR> <VALUE>:
+ Set the variable <VAR> equal to <VALUE> in the configuration file
+ 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.
+
+### 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", and "libretools". 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_conf_makepkg` and `set_conf_makepkg` 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)