summaryrefslogtreecommitdiff
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
parent86ee0a5da2a3a02d291ae40c8570bcd97ff066de (diff)
Add documentation for lib/
* Add a bunch of man-pages * Add some comments to conf.sh * Add more information to librelib:usage()
l---------src/lib/blacklist.sh.3.ronn1
-rw-r--r--src/lib/common.sh.3.ronn16
-rw-r--r--src/lib/conf.sh4
-rw-r--r--src/lib/conf.sh.3.ronn136
-rw-r--r--src/lib/libreblacklist.1.ronn23
-rwxr-xr-xsrc/lib/librelib8
-rw-r--r--src/lib/librelib.1.ronn55
-rw-r--r--src/lib/librelib.7.ronn50
-rw-r--r--src/lib/libremessages.1.ronn209
l---------src/lib/messages.sh.3.ronn1
10 files changed, 500 insertions, 3 deletions
diff --git a/src/lib/blacklist.sh.3.ronn b/src/lib/blacklist.sh.3.ronn
new file mode 120000
index 0000000..9001445
--- /dev/null
+++ b/src/lib/blacklist.sh.3.ronn
@@ -0,0 +1 @@
+libreblacklist.1.ronn \ No newline at end of file
diff --git a/src/lib/common.sh.3.ronn b/src/lib/common.sh.3.ronn
new file mode 100644
index 0000000..2ec113c
--- /dev/null
+++ b/src/lib/common.sh.3.ronn
@@ -0,0 +1,16 @@
+common.sh -- common Bash routines from devtools
+===============================================
+
+## SYNPOSIS
+
+`. $(librelib common)`
+
+## DESCRIPTION
+
+In short, don't use this. Use `libremessages`(1) instead.
+`libremessages` uses this internally.
+
+## SEE ALSO
+
+ * librelib(7)
+ * libremessages(1)/messages.sh(3)
diff --git a/src/lib/conf.sh b/src/lib/conf.sh
index f96af26..c2904de 100644
--- a/src/lib/conf.sh
+++ b/src/lib/conf.sh
@@ -61,7 +61,7 @@ list_files() {
}
# Usage: list_envvars $slug
-# Lists the environmental variables that take precidence over the configuration
+# Lists the environmental variables that take precedence over the configuration
# files for $slug.
list_envvars() {
local slug=$1
@@ -133,6 +133,7 @@ check_vars() {
# makepkg configuration ########################################################
# Usage: get_conf_makepkg <var_name> <default_value>
+# Does not work with arrays
get_conf_makepkg() (
set +euE
local setting=$1
@@ -141,6 +142,7 @@ get_conf_makepkg() (
printf '%s\n' "${!setting:-${default}}"
)
+# Does not work with arrays
set_conf_makepkg() {
local key=$1
local val=$2
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)
diff --git a/src/lib/libreblacklist.1.ronn b/src/lib/libreblacklist.1.ronn
new file mode 100644
index 0000000..e44aa8d
--- /dev/null
+++ b/src/lib/libreblacklist.1.ronn
@@ -0,0 +1,23 @@
+libreblacklist(1) -- Tools for working with the your-freedom blacklist
+======================================================================
+
+## SYNPOSIS
+
+`. $(librelib blacklist)`<br>
+`. libreblacklist`<br>
+`libremessages` [-h] <COMMAND> [<ARGS>...]
+
+## DESCRIPTION
+
+`libreblacklist` is a set of tools for working with the your-freedom
+blacklist.
+
+It may be included into a `Bash`(1) program as a library, which will
+expose it's routines as "blacklist-<COMMAND>", or it may be invoked on
+the command line as "libreblacklist <COMMAND>".
+
+See `libremessages -h` for more information.
+
+## SEE ALSO
+
+librelib(7)
diff --git a/src/lib/librelib b/src/lib/librelib
index 2dc9314..a58f5d3 100755
--- a/src/lib/librelib
+++ b/src/lib/librelib
@@ -34,7 +34,8 @@ cmd=${0##*/}
usage() {
. libremessages
print 'Usage: . $(%s LIBRARY)' "$cmd"
- print "Finds a shell library file"
+ print 'Usage: %s -h' "$cmd"
+ print "Finds a Bash library file"
echo
prose "While some libraries can be sourced just by their name because
they are installed in PATH (like libremessages), some are not
@@ -45,7 +46,10 @@ usage() {
changed with the environmental variable LIBRETOOLS_LIBDIR.' "$default_libdir"
echo
print "Example usage:"
- printf ' . $(%s conf.sh)\n' "$cmd"
+ printf ' . $(%s conf)\n' "$cmd"
+ echo
+ print "Options:"
+ flag '-h' 'Show this message'
}
main() {
diff --git a/src/lib/librelib.1.ronn b/src/lib/librelib.1.ronn
new file mode 100644
index 0000000..42d8f15
--- /dev/null
+++ b/src/lib/librelib.1.ronn
@@ -0,0 +1,55 @@
+librelib(1) -- finds a Bash library file
+========================================
+
+## SYNOPSIS
+
+`. $(librelib LIBRARY)`<br>
+`librelib -h`
+
+## DESRIPTION
+
+`librelib` is a program to find a Bash(1) library file at run-time.
+This way, the path does not need to be hard-coded into the
+application; think of it as a sort of dynamic-linker for shell
+programs.
+
+There are several reasons for doing this, instead of hard-coding the
+path:
+
+ * The install path can change in the future without having to change
+ programs that use them.
+ * The install directory can be configured at runtime, by setting
+ `LIBRETOOLS_LIBDIR`, similar to `LD_PRELOAD` (this is used when
+ running the test suite).
+ * The naming scheme of a library can change (such as between
+ `libreNAME` and `NAME.sh` without changing programs that use it.
+
+By default, `librelib` looks in `/usr/lib/libretools`, but that can be
+changed by setting the `LIBRETOOLS_LIBDIR` environmental variable to
+the directory it should look in.
+
+When searching for a library, `librelib` first strips `libre` from the
+beginning of the name, and `.sh` from the end. This means that all of
+the following are equivalent:
+
+ . $(librelib messages)
+ . $(librelib messages.sh)
+ . $(librelib libremessages)
+ . $(librelib libremessages.sh)
+
+Once it has the 'base' name of the library it is looking for, it looks
+for a file with that 'base' name (allowing for, but not requiring
+`libre` to be prepended, or `.sh` to be appended) in whichever
+directory it is looking in.
+
+If it cannot find a suitable library file, it will print an error
+message to standard error, and exit with a code of 1.
+
+## Examples
+
+ . $(librelib messages)
+ . $(librelib conf)
+
+## SEE ALSO
+
+librelib(7)
diff --git a/src/lib/librelib.7.ronn b/src/lib/librelib.7.ronn
new file mode 100644
index 0000000..e030f6a
--- /dev/null
+++ b/src/lib/librelib.7.ronn
@@ -0,0 +1,50 @@
+librelib(7) -- Suite of Bash libraries
+======================================
+
+## SYNOPSIS
+
+Overview ot the librelib Bash library suite.
+
+## DESCRIPTION
+
+There are three parts to librelib:
+
+ 1. The `librelib`(1) executable.
+ 2. The non-executable libraries installed in `/usr/lib/libretools`
+ 3. The executable libraries installed in both `/usr/bin` and
+ `/usr/lib/libretools`.
+
+The `librelib` executable isn't very exciting, it just finds the
+libraries installed in `/usr/lib/libretools`. Think of it as a sort
+of dynamic-linker.
+
+The 'core' of librelib are the libraries installed in
+`/usr/lib/libretools`. These are `Bash`(1) libaries that may be sourced in
+Bash programs.
+
+Some of these libraries also make sense as stand-alone programs, where
+if they are invoked directly, the first argument is the library
+routine to be executed. For example, the `messages` library may be
+included, or executed:
+
+ . $(librelib messages)
+ msg2 "Foo was found: %s" "$foo"
+ # or
+ libremessages msg2 "Foo was found: %s" "$foo"
+
+The `blacklist` library is similar:
+
+ . $(librelib blacklist)
+ blacklist-update
+ # or
+ libreblacklist update
+
+
+
+## SEE ALSO
+
+ * librelib(1)
+ * libremessages(1)/messages.sh(3)
+ * libreblacklist(1)/blacklist.sh(3)
+ * conf.sh(3)
+ * common.sh(3)
diff --git a/src/lib/libremessages.1.ronn b/src/lib/libremessages.1.ronn
new file mode 100644
index 0000000..970b950
--- /dev/null
+++ b/src/lib/libremessages.1.ronn
@@ -0,0 +1,209 @@
+libremessages(1) -- common Bash routines
+========================================
+
+## SYNOPSIS
+
+`. $(librelib messages)`<br>
+`. libremessages`<br>
+`libremessages` <COMMAND>
+
+## DESCRIPTION
+
+`libremessages` is a shell library containing many common routines.
+The name is a bit of a misnomer, it mostly deals with printing
+messages, but also has other things.
+
+`libremessages` uses `common.sh`(3) internally for a large portion of
+it's functionality. The authors make no promises that functionality
+that is implemented in `libremessages` won't move into `common.sh` or
+vice-versa. So, it is recommended that you use `libremessages`, not
+`common.sh`.
+
+### STAND ALONE USAGE
+
+The "normal" way to use libremessages is to source it, then call the
+provided routines.
+
+However, if you call libremessages directly, the first argument is
+taken as a the function to call, and the remaining arguments are
+passed to it. The only cases where this doesn't work are the lockfile
+routines (`lock`, `slock`, and `lock_close`), because lockfiles are
+managed as file descriptors.
+
+### VARIABLES
+
+The following variables for printing terminal color codes are set:
+`ALL_OFF`, `BOLD`, `BLUE`, `GREEN`, `RED`, `YELLOW`. If standard
+error is not a terminal (see `isatty`(3)), they are set, but empty.
+They are marked as readonly, so it is an error to try to set them
+afterwords.
+
+### MESSAGE FORMAT
+
+All routines feed the message/format string through `gettext`(1), if
+it is available.
+
+The descriptions will frequently reference `printf`(1)--this isn't
+really that `printf`. The program described by the manual page
+`printf`(1) is probably the version from GNU coreutils, every time it
+is used here, it is `bash`(1)'s internal implementation; try running
+the command `help printf` from a Bash shell for more information.
+
+### GENERAL ROUTINES
+
+ * `_` <MESSAGE>:
+ If `gettext` is available, calls `gettext`, otherwise just prints
+ the arguments given.
+
+ * `in_array` <NEEDLE> <HAYSTACK>...:
+ Evaluates whether <HAYSTACK> includes <NEEDLE>; returns 0 if it
+ does, non-zero if it doesn't.
+
+ * `panic`:
+ For the times when you can't reasonably continue, similar to
+ "assert" in some languages.
+
+ * `term_title` <MESSAGE>...:
+ Joins all arguments with whitespace, and sets the terminal title
+ to that.
+
+### PROSE ROUTINES
+
+These routines print to standard output, ande are useful for printing
+word-wrapped prose.
+
+ * `print` <MESSAGE> [<ARGS>...]:
+ Like `printf`(1), but `gettext`-aware, and automatically prints a
+ trailing newline.
+
+ * `prose` <MESSAGE> [<ARGS>...]:
+ Takes a `printf`(1)-formatted string, collapses whitespace
+ (HTML-style), and then word-wraps it.
+
+ * `bullet` <MESSAGE> [<ARGS>...]:
+ Similar to `prose`, but prints a bullet point before the first
+ line, and indents the remaining lines.
+
+ * `flag` <FLAG> <DESCRIPTION>:
+ Print a flag and description formatted for `--help` text. For
+ example:<br>
+ `flag '-N' 'Disable networking in the chroot'`<br>
+ The description is fed through `gettext`, the flag is not, so if
+ part of the flag needs to be translated, you must do that
+ yourself:<br>
+ `flag "-C <$(_ FILE)>" 'Use this file instead of pacman.conf'`<br>
+ Newlines in the description are ignored; it is
+ whitespace-collapsed (so newlines are stripped), then it is
+ re-word-wrapped, in the same way as `prose` and `bullet`.
+
+### NOTIFICATION ROUTINES
+
+These routines print to standard error, and all take arguments in the
+same format as `printf`(1), except for `stat_done`, which doesn't take
+any arguments.
+
+ * `plain` <MESSAGE> [<ARGS>...]:
+ Prints "plain" message in bold, indented with 4 spaces.
+
+ * `msg` <MESSAGE> [<ARGS>...]:
+ Prints a top-level priority notification.
+
+ * `msg2` <MESSAGE> [<ARGS>...]:
+ Prints a secondary notification.
+
+ * `warning` <MESSAGE> [<ARGS>...]:
+ Prints a warning.
+
+ * `error` <MESSAGE> [<ARGS>...]:
+ Prints an error message.
+
+ * `stat_busy` <MESSAGE> [<ARGS>...]:
+ Prints a "working..." type message without a trailing newline.
+
+ * `stat_done`:
+ Prints a "done" type message to terminate `stat_busy`.
+
+### TEMPORARY DIRECTORY MANAGEMENT
+
+These are used by devtools, and not used within the rest of
+libretools.
+
+They work by creating and removing the directory referred to by the
+variable $<WORKDIR>; `libretools.conf`(5) uses the same variable to
+where the user saves all their work. If you aren't careful with
+these, you could end up deleting a lot of someone's work.
+
+ * `setup_workdir`:
+ Creates a temporary directory, and sets the environmental
+ variable $<WORKDIR> to it. Also sets traps for the signals INT,
+ QUIT, TERM and HUP to run `abort`; and EXIT to run `cleanup`
+ (see `signal`(7)).
+
+ * `cleanup` [<EXIT_STATUS>]:
+ *If* `setup_workdir` has been run, `rm -rf "$WORKDIR"`. If given
+ a numeric argument, it will then call `exit`(1) with that argument.
+
+ * `abort`:
+ Calls `msg` with the message "Aborting...", then calls
+ `cleanup 0`.
+
+ * `die` <MESSAGE> [<ARGS>...]:
+ Exactly like `error`, but calls `cleanup` and calls `exit`(1)
+ with a status of 1.
+
+### LOCKFILE ROUTINES
+
+ * `lock` <FD> <LOCKFILE> <MESSAGE> [<MSG_ARGS>...]:
+ Opens (creating if nescessary) the file <LOCKFILE> with file
+ descriptor <FD> in the current process, and gets an exclusive
+ lock on it. If another program already has a lock on the file,
+ and this program needs to wait for the lock to be release, then
+ it uses `stat_busy`/`stat_done` to print <MESSAGE>.
+
+ * `slock` <FD> <LOCKFILE> <MESSAGE> [<MSG_ARGS>...]:
+ Identical like `lock`, but opens a shared lock. This is also
+ known as a "read lock". Many programs can have a shared lock at
+ the same time, as long as no one has an exclusive lock on it.
+
+ * `lock_close` <FD>:
+ Closes file descriptor <FD>, releasing the lock opened on it.
+
+### MAKEPKG ROUTINES
+
+These routines relate to `makepkg`(8).
+
+ * `get_full_version` [<PKGNAME>]:
+ Inspects variables that are set, and prints the full version
+ spec, including <epoch> if necessary, <pkgver>, and <pkgrel>. By
+ default, it will print the information for <pkgbase>, following
+ the normal rules for finding <pkgbase>. If <PKGNAME> is given,
+ it will print the information for that sub-package. The versions
+ for different parts of a split package don't have to be the same!
+
+## BUGS
+
+libremessages sets <TEXTDOMAIN> to `libretools` unconditionally,
+making it generally unsuitable for use outside of libretools. If you
+override <TEXTDOMAIN> after loading the library, that should work, but
+you will also have to provide translations for libremessage's internal
+messages (such as "ERROR" or "Warning").
+
+Generating `.pot` files for the prose functions is a pain. The
+libretools Makefiles have rules to do it, but it might make sense to
+pull it into a separate program.
+
+`term_title` currently only knows about the terminals screen, tmux,
+xterm and rxvt (and their various <TERM> values;
+"rxvt-unicode-256color" is still rxvt).
+
+Also, I think `abort` calling `cleanup 1` would make more sense than
+`cleanup 0`.
+
+## SEE ALSO
+
+librelib(7), gettext(1), common.sh(3)
+
+Things that were mentioned:
+
+bash(1), exit(1), isatty(3), libretools.conf(5), makepkg(8),
+printf(1), signal(7)
diff --git a/src/lib/messages.sh.3.ronn b/src/lib/messages.sh.3.ronn
new file mode 120000
index 0000000..391ecbd
--- /dev/null
+++ b/src/lib/messages.sh.3.ronn
@@ -0,0 +1 @@
+libremessages.1.ronn \ No newline at end of file