summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorLucía Andrea Illanes Albornoz <lucia@luciaillanes.de>2023-03-20 19:45:45 +0100
committerLucía Andrea Illanes Albornoz <lucia@luciaillanes.de>2023-03-20 19:45:45 +0100
commit131fe2372940b4ef107454e0f1454be7aa08e901 (patch)
tree4a15bee12c7c6e7608cdc3ddbabd161ebca4fdd3
parent550c1831733f61c4af8e32179dc7df39bcd7a1de (diff)
downloadmidipix_build-131fe2372940b4ef107454e0f1454be7aa08e901.tar.bz2
midipix_build-131fe2372940b4ef107454e0f1454be7aa08e901.tar.xz
Document subr.rtl/*.subr functions, pt. II.
-rw-r--r--subr.rtl/rtl_fileop.subr2
-rw-r--r--subr.rtl/rtl_install.subr8
-rw-r--r--subr.rtl/rtl_install_v2.subr128
3 files changed, 137 insertions, 1 deletions
diff --git a/subr.rtl/rtl_fileop.subr b/subr.rtl/rtl_fileop.subr
index b628ac05..10d741c5 100644
--- a/subr.rtl/rtl_fileop.subr
+++ b/subr.rtl/rtl_fileop.subr
@@ -22,7 +22,7 @@ rtlp_fileop_log() {
#
# rtl_fileop() - clean download cache for single package
-# @_op: file operation
+# @_op: file operation (one of: cd, chmod, chgrp, chown, cp_follow, cp, install, ln_symbolic, mv, touch, mkdir, mkfifo, rm, source, source_opt, test)
# @...: file operation arguments
#
# Returns: zero (0) on success, non-zero (>0) on failure
diff --git a/subr.rtl/rtl_install.subr b/subr.rtl/rtl_install.subr
index 5273a5ca..a0a9b8d0 100644
--- a/subr.rtl/rtl_install.subr
+++ b/subr.rtl/rtl_install.subr
@@ -3,6 +3,14 @@
# set +o errexit -o noglob -o nounset is assumed.
#
+#
+# rtl_install() - install files
+# @[-v]: increase verbosity
+# @_prefix: installation prefix pathname
+# @...: install operation (one of: -* (remove,) !*=* (move/rename,) /=* (create directory/ies,) @*=* (create/update symbolic link,) m[0-7][0-7][0-7][0-7]=* (set mode bits,) o*=* (set user/group owner,) *=* (copy))
+#
+# Returns: zero (0) on success, non-zero (>0) on failure
+#
rtl_install() {
local _ri_verbose="" _ri_prefix="" \
_ri_chmod_mode="" _ri_dname="" _ri_file_fname_dst="" _ri_file_fname_src="" \
diff --git a/subr.rtl/rtl_install_v2.subr b/subr.rtl/rtl_install_v2.subr
index 572af6e5..480121f8 100644
--- a/subr.rtl/rtl_install_v2.subr
+++ b/subr.rtl/rtl_install_v2.subr
@@ -474,6 +474,134 @@ rtlp_install_v2_splitl_subexpr() {
};
# }}}
+#
+# rtl_install_v2() - install files
+# @_rstatus: reference to out variable of status string on failure
+# @[-i]: continue on soft errors
+# @[-I ifs]: process spec_list with ifs instead of NL
+# @[-n]: perform dry run
+# @[-p name=val]: set named parameter
+# @[-v]: increase verbosity
+# @_prefix: pathname prefix
+# @_spec_list: ifs-separated list of specs
+#
+# {{{ File installation DSL
+#
+# ```
+# (*
+# SH_GLOB_PATTERN = any valid portable shell pattern (see sh(1)); superset of PATHNAME
+# SH_SUBSTRING_PATTERN = any valid portable substring processing shell pattern (see sh(1));
+# superset of PATHNAME
+# PARAMETER = any valid portable shell variable name except that [0-9] may occur
+# the beginning
+# PATHNAME = any valid filename, directory name, relative or absolute pathname
+# excluding the characters NUL and NL
+# *)
+#
+# spec = { op_flag, } op_unary, "=", op_spec, "\n", { spec } ;
+# | { op_flag, } op_binary, op_spec, "=" op_spec, "\n", { spec } ;
+# | "#" COMMENT ;
+# op_unary = "-" | "/" | "t" ;
+# op_binary = ":" | "!" | "@" | "+" | "g" | "m" | "o" | "T" ;
+# op_flag = "?" ;
+# op_spec = pattern_spec | PATHNAME | expr_spec | op_spec ;
+#
+# pattern_spec = "%<", SH_GLOB_PATTERN, ">" ;
+#
+# expr_spec = "%[", expr, { sexpr_spec }, "%]" ;
+# expr = [ "@" ], "0" .. "9" | "DNAME" | "FNAME" | "ITEM" | PARAMETER ;
+#
+# sexpr_spec = sexpr_op_unary, SH_SUBSTRING_PATTERN, { sexpr } ;
+# sexpr_op_unary = "##" | "#" | "%%" | "%" ;
+# ```
+#
+# Single ``"="`` characters in ``spec``, the ``"%<"`` and ``"%["`` character
+# sequences in ``pattern_spec`` and ``expr_spec``, resp., and the ``sexpr_op_unary``
+# as well as ``sexpr_op_binary`` characters or character sequences may be
+# escaped with a single backslash (``"\"``.) ``SH_SUBSTRING_PATTERN`` differs
+# from ``SH_GLOB_PATTERN`` solely in that any of ``sexpr_op_unary`` and
+# ``sexpr_op_binary`` occuring at the beginning of or in the former must
+# be escaped with a single backslash (``"\"``,) e.g. ``"#\#pattern"`` and
+# ``"%\%pattern"``, etc. and ``"#pat\%ern"`` and ``%patt\#ern", etc., resp.
+#
+# Named parameters (``PARAMETER``) are supplied via the ``-p name=value``
+# argument to ``rtl_install()``, whereas numbered parameters are for
+# internal usage only; the ``"DNAME"``, ``"FNAME"``, and ``"ITEM"`` parameters
+# lazily evaluate to the directory name, file (aka base) name, and full
+# pathname of the current item being processed relative to a specification
+# with a pattern in it.
+#
+# The following operation flags are defined:
+#
+# | Flag | Description |
+# | --------- | ------------------------ |
+# | ``?`` | Continue on soft failure |
+#
+# The following operations are defined:
+#
+# | Operation | Arity | Description |
+# | -------------- | ------ | ---------------------------------------------------------------- |
+# | ``-`` | Unary | Remove directories and/or files |
+# | ``/`` | Unary | Create directories or trees thereof |
+# | ``t`` | Unary | touch(1) files and/or directories |
+# | ``:`` | Binary | Copy directories and/or files |
+# | ``!`` | Binary | Move/rename directories and/or files |
+# | ``@`` | Binary | Create/update symbolic links |
+# | ``+`` | Binary | Copy directories and/or files if newer and follow symbolic links |
+# | ``g`` | Binary | Set group owner of files and/or directories |
+# | ``m`` | Binary | Set mode bits of files and/or directories |
+# | ``o`` | Binary | Set user and/or group owner of files and/or directories |
+# | ``T`` | Binary | touch(1) files and/or directories with timestamp |
+#
+# The following expression modifiers are defined:
+#
+# | Modifier | Description |
+# | -------------- | ----------------------------------------- |
+# | ``@`` | Recursively reevaluate after substituting |
+#
+# The following subexpression operators are defined:
+#
+# | Operation | Arity | Description |
+# | -------------- | ------ | ---------------------------------------------------------------- |
+# | ``##`` | Unary | Remove largest prefix from left-hand side |
+# | ``#`` | Unary | Remove prefix from left-hand side |
+# | ``%%`` | Unary | Remove largest postfix from right-hand side |
+# | ``%`` | Unary | Remove postfix from right-hand side |
+#
+# ```shell
+# #
+# # Examples:
+# #
+#
+# #
+# # Create directory %[_minipix]/bin and copy all files
+# # in %[_minipix_dist]/bin/ to %[_minipix]/bin/ with
+# # identical file names.
+# /=%[_minipix]/bin
+# ?%[_minipix_dist]/bin/%<*>=%[_minipix]/bin/%[FNAME]
+#
+# #
+# # Rename all files in share/info/ matching *.info to
+# # their filenames with the `.info' postfix removed and
+# # `-2.64.info' appended and all files in share/man/man1/
+# # matching *.1 with the `.1' postfix removed and -2.64.1
+# # appended.
+# !share/info/%<*.info>=share/info/%[FNAME%.info]-2.64.info
+# !share/man/man1/%<*.1>=share/man/man1/%[FNAME%.1]-2.64.1
+#
+# #
+# # Create/update symbolic links named include/ffi.h and
+# # include/ffitarget.h with ../lib/libffi-3.2.1/include/ffi.h
+# # and ../lib/libffi-3.2.1/include/ffitarget.h as targets, resp.
+# @../lib/libffi-3.2.1/include/ffi.h=include/ffi.h
+# @../lib/libffi-3.2.1/include/ffitarget.h=include/ffitarget.h
+#
+# ```
+#
+# }}}
+#
+# Returns: zero (0) on success, non-zero (>0) on failure
+#
rtl_install_v2() {
local _ri2_rstatus="${1#\$}" \
_ri2_prefix="" _ri2_spec_flag="" _ri2_spec_list="" _ri2_iflag=0 _ri2_IFS="${IFS:- }" \