aboutsummaryrefslogtreecommitdiff
path: root/index.org
diff options
context:
space:
mode:
Diffstat (limited to 'index.org')
-rw-r--r--index.org142
1 files changed, 142 insertions, 0 deletions
diff --git a/index.org b/index.org
new file mode 100644
index 0000000..9c35b07
--- /dev/null
+++ b/index.org
@@ -0,0 +1,142 @@
+* Overview
+
+*Xenv* is a text preprocessor that expands references to environment
+variables in the input text to their actual values. Environment
+variables are referenced using POSIX-compatible shell syntax.
+Text is read from the standard input and expanded text goes to the
+standard output.
+
+* Rationale
+
+It became a de-facto practice to configure docker containers using
+environment variables. The method is obvious when configuration
+is consumed by some programming language (*php*, *python* or the
+like). However, sometimes the need arises to expand environment
+variables in configuration files of the utilities that provide no
+mechanism for this (such as *mysqld* or *ldap*, for instance).
+
+I often use [[http://puszcza.gnu.org.ua/software/pies/][GNU pies]] as entrypoint for images I produce. It uses
+[[https://www.gnu.org/software/m4][m4]] for preprocessing its configuration. Several mechanisms have
+been proposed for expanding environment variables in it: implementing
+special
+[[http://puszcza.gnu.org.ua/software/pies/manual/Docker-Entrypoint.html][macros]] or a [[http://git.gnu.org.ua/cgit/gsc/m4env.git/][wrapper program]]. However, the shortcomings of both
+became apparent and the need of something more convenient motivated
+the inception of this utility.
+
+* Variable references
+
+The input text can reference the environment variables using the
+following constructs:
+
+- $ _variable_
+
+ The value of _variable_ is substituted.
+
+- ${ _variable_ }
+
+ The value of _variable_ is substituted.
+
+- ${ _variable_ :- _word_ }
+
+ If _variable_ is unset or null, the expansion of _word_ is substituted.
+ Otherwise, the value of _variable_ is substituted.
+
+- ${ _variable_ := _word_ }
+
+ If _variable_ is unset or null, the expansion of _word_ is
+ assigned to _variable_. The value of _variable_ is then substituted.
+
+- ${ _variable_ :? _word_ }
+
+ If _variable_ is null or unset, the expansion of _word_ (or a
+ message to that effect if word is not present) is output to standard error.
+ Otherwise, the value of _variable_ is substituted.
+
+- ${ _variable_ :+ _word_ }
+
+ If _variable_ is null or unset, nothing is substituted, otherwise the
+ expansion of _word_ is substituted.
+
+- ${ _variable_ :| _word1_ | _word2_ }
+
+ Unless _variable_ is null or unset, substitues the expansion of
+ _word1_, otherwise the expansion of _word2_.
+
+In the constructs above the colon can be omitted, resulting in a test
+only for a variable that is unset.
+
+The _indirection operator_ *$* can be changed to another symbol using
+the command line option *-S*.
+
+* Documentation
+
+The documentaion for *xenv* is [[http://man.gnu.org.ua/manpage/?1+xenv][available online]].
+
+* Downloads
+
+Download the [[https://download.gnu.org.ua/release/xenv/xenv-1.1.tar.gz][latest version]] of *xenv*.
+
+The tarball is signed using the author's GPG key. To verify it,
+import the author's key using the following command:
+
+#+BEGIN_SRC shell-script
+gpg --keyserver keys.gnupg.net --recv-keys 3602B07F55D0C732
+#+END_SRC
+
+Then, download the [[https://download.gnu.org.ua/release/xenv/xenv-1.1.tar.gz.sig][signature]] file and run
+
+#+BEGIN_SRC shell-script
+gpg --verify xenv-1.1.tar.gz
+#+END_SRC
+
+Checksums for this tarball are [[https://puszcza.gnu.org.ua/forum/forum.php?forum_id=1270][listed here]].
+
+This and other versions of the utility can be downloaded from
+https://download.gnu.org.ua/release/xenv (the *ftp* protocol
+is also supported).
+
+** Other references:
+
+- [[https://puszcza.gnu.org.ua/projects/xenv][Project development page]]
+
+- [[http://git.gnu.org.ua/cgit/xenv.git][Git repository]]
+
+* Bug reports
+
+If you think you found a bug in *xenv* or in its documentation, please
+send a mail to [[mailto:gray@gnu.org][Sergey Poznyakoff]] or use the web [[https://puszcza.gnu.org.ua/bugs/?group=xenv][bug tracker]].
+
+* Copyright
+
+Copyright (C) 2021 Sergey Poznyakoff
+
+Permission is granted to anyone to make or distribute verbatim copies
+of this document as received, in any medium, provided that the
+copyright notice and this permission notice are preserved,
+thus giving the recipient permission to redistribute in turn.
+
+Permission is granted to distribute modified versions
+of this document, or of portions of it,
+under the above conditions, provided also that they
+carry prominent notices stating who last changed them.
+
+* Document settings :noexport:
+
+Please ignore this section. It supplies the variables necessary for
+proper rendering of this document.
+
+:PROPERTIES:
+:VISIBILITY: folded
+:END:
+
+#+TITLE: xenv
+#+STARTUP: showall
+#+EXCLUDE_TAGS: noexport
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css" />
+#+OPTIONS: ^:nil
+
+# Local Variables:
+# mode: org
+# paragraph-separate: "[ ^L]*$"
+# version-control: never
+# End:

Return to:

Send suggestions and report system problems to the System administrator.