From f5b650a06cddd447ad7a75330e9e9c6baf23ccc4 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Wed, 2 Oct 2013 15:32:45 -0400 Subject: Add documentation for lib/ * Add a bunch of man-pages * Add some comments to conf.sh * Add more information to librelib:usage() --- src/lib/blacklist.sh.3.ronn | 1 + src/lib/common.sh.3.ronn | 16 ++++ src/lib/conf.sh | 4 +- src/lib/conf.sh.3.ronn | 136 +++++++++++++++++++++++++++ src/lib/libreblacklist.1.ronn | 23 +++++ src/lib/librelib | 8 +- src/lib/librelib.1.ronn | 55 +++++++++++ src/lib/librelib.7.ronn | 50 ++++++++++ src/lib/libremessages.1.ronn | 209 ++++++++++++++++++++++++++++++++++++++++++ src/lib/messages.sh.3.ronn | 1 + 10 files changed, 500 insertions(+), 3 deletions(-) create mode 120000 src/lib/blacklist.sh.3.ronn create mode 100644 src/lib/common.sh.3.ronn create mode 100644 src/lib/conf.sh.3.ronn create mode 100644 src/lib/libreblacklist.1.ronn create mode 100644 src/lib/librelib.1.ronn create mode 100644 src/lib/librelib.7.ronn create mode 100644 src/lib/libremessages.1.ronn create mode 120000 src/lib/messages.sh.3.ronn 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 +# 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 $ and $, +`conf.sh` sets $ and $, which it then uses. + + * : + If $ is set, then $ is set to + that. Otherwise, $ is set to the value of $. + * : + If $ == $, then $ is set to the value + of $. Otherwise, it is set to the default home directory + of the user $. + +Further, `conf.sh` works with XDG; it sets and uses +$ and $ with the following values: + + * : + If it isn't already set, it is set to "$/.config" and + exported. + * : + If it isn't already set, it is set to "$/.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, +='abs' will identify `/etc/abs.conf` and `$/.abs.conf`. + +The routines you will likely actually use are: + + * `load_files` : + Loads the configuration files for , loading the files in + the correct order, and checking the appropriate environmental + variables. + * `check_vars` ...: + Checks to see if all of are defined. If any of them + aren't, it prints a message to configure them in the + configuration files for , 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` : + Lists (newline-separated) the configuration files that must be + considered for . Files listed later take precedence over + files listed earlier. + * `list_envvars` : + Lists (newline-separated) the environmental variables that take + precedence over the settings in the configuration files for + . For example, in `makepkg.conf`(8) (=makepkg), if the + 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` : + If is set, return it's value, considering environmental + variables. If it is not set, return . The printed + value is then trailed by a newline. + * `set_conf_makepkg` : + Set the variable equal to 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` []: + "Safely" loads a PKGBUILD. Everything that it would normally set + is unset first, $ is set according to `makepkg.conf`(5), + then the file is loaded. The file to be loaded is , 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/.conf" and + "$/libretools/.conf" + * `list_envvars` will give back an empty list. + +The rules for =(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)`
+`. libreblacklist`
+`libremessages` [-h] [...] + +## 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-", or it may be invoked on +the command line as "libreblacklist ". + +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)`
+`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)`
+`. libremessages`
+`libremessages` + +## 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 + + * `_` : + If `gettext` is available, calls `gettext`, otherwise just prints + the arguments given. + + * `in_array` ...: + Evaluates whether includes ; 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` ...: + 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` [...]: + Like `printf`(1), but `gettext`-aware, and automatically prints a + trailing newline. + + * `prose` [...]: + Takes a `printf`(1)-formatted string, collapses whitespace + (HTML-style), and then word-wraps it. + + * `bullet` [...]: + Similar to `prose`, but prints a bullet point before the first + line, and indents the remaining lines. + + * `flag` : + Print a flag and description formatted for `--help` text. For + example:
+ `flag '-N' 'Disable networking in the chroot'`
+ 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:
+ `flag "-C <$(_ FILE)>" 'Use this file instead of pacman.conf'`
+ 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` [...]: + Prints "plain" message in bold, indented with 4 spaces. + + * `msg` [...]: + Prints a top-level priority notification. + + * `msg2` [...]: + Prints a secondary notification. + + * `warning` [...]: + Prints a warning. + + * `error` [...]: + Prints an error message. + + * `stat_busy` [...]: + 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 $; `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 $ 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` []: + *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` [...]: + Exactly like `error`, but calls `cleanup` and calls `exit`(1) + with a status of 1. + +### LOCKFILE ROUTINES + + * `lock` [...]: + Opens (creating if nescessary) the file with file + descriptor 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 . + + * `slock` [...]: + 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` : + Closes file descriptor , releasing the lock opened on it. + +### MAKEPKG ROUTINES + +These routines relate to `makepkg`(8). + + * `get_full_version` []: + Inspects variables that are set, and prints the full version + spec, including if necessary, , and . By + default, it will print the information for , following + the normal rules for finding . If 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 to `libretools` unconditionally, +making it generally unsuitable for use outside of libretools. If you +override 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 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 -- cgit v1.2.2