chore: set expectation for function compatibility

Set clear boundaries for which functions are maintained for
compatibility with existing dracut modules.

Document the compatibility differences between dracut.sh and
dracut-functions.sh, and move any functions from dracut.sh to
dracut-functions.sh that are clearly required for dracut
module compatibility.

This commit moves all functions from dracut.sh to dracut-functions.sh
that are already documented in man/dracut.modules.7.adoc.

diff --git a/dracut-functions.sh b/dracut-functions.sh
index 617ccf91c4380e292333eee788f5446148449635..e2f62b9c82f0cf13ccbb65afa8972b590c5a9a98 100755 (executable)
--- a/dracut-functions.sh
+++ b/dracut-functions.sh
@@ -1,6 +1,13 @@
 #!/bin/bash
 #
-# functions used by dracut and other tools.
+# functions used by dracut modules (including out-of-tree modules)
+#
+# There is an expectation to preserv compatibility between dracut
+# releases for out-of-tree dracut modules for functions listed
+# in this file.
+#
+# All functions in this file are meant to be public and documented in
+# dracut.modules man page.
 #
 # Copyright 2005-2009 Red Hat, Inc.  All rights reserved.
 #
@@ -1077,3 +1084,122 @@ pe_get_image_base() {
     [[ $? -eq 1 ]] && return 1
     echo "$((16#$base_image))"
 }
+
+inst_dir() {
+    local _ret
+    [[ -e ${initdir}/"$1" ]] && return 0 # already there
+    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} -d "$@"; then
+        return 0
+    else
+        _ret=$?
+        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} -d "$@"
+        return "$_ret"
+    fi
+}
+
+inst() {
+    local dstdir="${dstdir:-"$initdir"}"
+    local _ret _hostonly_install
+    if [[ $1 == "-H" ]] && [[ $hostonly ]]; then
+        _hostonly_install="-H"
+        shift
+    fi
+    [[ -e ${dstdir}/"${2:-$1}" ]] && return 0 # already there
+    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} ${_hostonly_install:+-H} "$@"; then
+        return 0
+    else
+        _ret=$?
+        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} ${_hostonly_install:+-H} "$@"
+        return $_ret
+    fi
+}
+
+inst_simple() {
+    local dstdir="${dstdir:-"$initdir"}"
+    local _ret _hostonly_install
+    if [[ $1 == "-H" ]] && [[ $hostonly ]]; then
+        _hostonly_install="-H"
+        shift
+    fi
+    [[ -e ${dstdir}/"${2:-$1}" ]] && return 0 # already there
+    if [[ $1 == /* ]]; then
+        [[ -e ${dracutsysrootdir-}/${1#"${dracutsysrootdir-}"} ]] || return 1 # no source
+    else
+        [[ -e $1 ]] || return 1 # no source
+    fi
+    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} ${loginstall:+-L "$loginstall"} ${_hostonly_install:+-H} "$@"; then
+        return 0
+    else
+        _ret=$?
+        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} ${loginstall:+-L "$loginstall"} ${_hostonly_install:+-H} "$@"
+        return $_ret
+    fi
+}
+
+inst_multiple() {
+    local dstdir="${dstdir:-"$initdir"}"
+    local _ret _hostonly_install
+    if [[ $1 == "-H" ]] && [[ $hostonly ]]; then
+        _hostonly_install="-H"
+        shift
+    fi
+    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} -a ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} ${_hostonly_install:+-H} "$@"; then
+        return 0
+    else
+        _ret=$?
+        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} -a ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} ${_hostonly_install:+-H} "$@"
+        return $_ret
+    fi
+}
+
+inst_binary() {
+    local _ret
+    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} "$@"; then
+        return 0
+    else
+        _ret=$?
+        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} "$@"
+        return "$_ret"
+    fi
+}
+
+inst_script() {
+    local _ret
+    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} "$@"; then
+        return 0
+    else
+        _ret=$?
+        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} "$@"
+        return "$_ret"
+    fi
+}
+
+# Use with form hostonly="$(optional_hostonly)" inst_xxxx <args>
+# If hostonly mode is set to "strict", hostonly restrictions will still
+# be applied, else will ignore hostonly mode and try to install all
+# given modules.
+optional_hostonly() {
+    if [[ $hostonly_mode == "strict" ]]; then
+        printf -- "%s" "${hostonly-}"
+    else
+        printf ""
+    fi
+}
+
+# install function specialized for hooks
+# $1 = type of hook, $2 = hook priority (lower runs first), $3 = hook
+# All hooks should be POSIX/SuS compliant, they will be sourced by init.
+inst_hook() {
+    local hook
+    if ! [[ -f $3 ]]; then
+        dfatal "Cannot install a hook ($3) that does not exist."
+        dfatal "Aborting initrd creation."
+        exit 1
+    elif ! [[ $hookdirs == *$1* ]]; then
+        dfatal "No such hook type $1. Aborting initrd creation."
+        exit 1
+    fi
+    hook="/var/lib/dracut/hooks/${1}/${2}-${3##*/}"
+    inst_simple "$3" "$hook"
+    chmod u+x "$initdir/$hook"
+}

diff --git a/dracut.sh b/dracut.sh
index 80dc2884d30b6ce6c5e3e08ad3aecbae97104f5e..ce66f30a7e4376ca6116d233932c569c3a00f653 100755 (executable)
--- a/dracut.sh
+++ b/dracut.sh
@@ -21,6 +21,11 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
+# functions in this file are meant to be internal to dracut and
+# not meant to be exposed to dracut modules.
+# Please do not use functions from this file in your dracut module
+# Only use functions from dracut-functions.sh
+
 # store for logging
 
 unset BASH_ENV
@@ -1656,56 +1661,6 @@ if [[ ${hostonly-} == "-h" ]] && [[ $no_kernel != yes ]]; then
 fi
 
 [[ ${DRACUT_RESOLVE_LAZY-} ]] || export DRACUT_RESOLVE_DEPS=1
-inst_dir() {
-    local _ret
-    [[ -e ${initdir}/"$1" ]] && return 0 # already there
-    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} -d "$@"; then
-        return 0
-    else
-        _ret=$?
-        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} -d "$@"
-        return "$_ret"
-    fi
-}
-
-inst() {
-    local dstdir="${dstdir:-"$initdir"}"
-    local _ret _hostonly_install
-    if [[ $1 == "-H" ]] && [[ $hostonly ]]; then
-        _hostonly_install="-H"
-        shift
-    fi
-    [[ -e ${dstdir}/"${2:-$1}" ]] && return 0 # already there
-    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} ${_hostonly_install:+-H} "$@"; then
-        return 0
-    else
-        _ret=$?
-        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} ${_hostonly_install:+-H} "$@"
-        return $_ret
-    fi
-}
-
-inst_simple() {
-    local dstdir="${dstdir:-"$initdir"}"
-    local _ret _hostonly_install
-    if [[ $1 == "-H" ]] && [[ $hostonly ]]; then
-        _hostonly_install="-H"
-        shift
-    fi
-    [[ -e ${dstdir}/"${2:-$1}" ]] && return 0 # already there
-    if [[ $1 == /* ]]; then
-        [[ -e ${dracutsysrootdir-}/${1#"${dracutsysrootdir-}"} ]] || return 1 # no source
-    else
-        [[ -e $1 ]] || return 1 # no source
-    fi
-    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} ${loginstall:+-L "$loginstall"} ${_hostonly_install:+-H} "$@"; then
-        return 0
-    else
-        _ret=$?
-        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} ${loginstall:+-L "$loginstall"} ${_hostonly_install:+-H} "$@"
-        return $_ret
-    fi
-}
 
 inst_symlink() {
     local _ret _hostonly_install
@@ -1724,22 +1679,6 @@ inst_symlink() {
     fi
 }
 
-inst_multiple() {
-    local dstdir="${dstdir:-"$initdir"}"
-    local _ret _hostonly_install
-    if [[ $1 == "-H" ]] && [[ $hostonly ]]; then
-        _hostonly_install="-H"
-        shift
-    fi
-    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} -a ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} ${_hostonly_install:+-H} "$@"; then
-        return 0
-    else
-        _ret=$?
-        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${dstdir:+-D "$dstdir"} -a ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} ${_hostonly_install:+-H} "$@"
-        return $_ret
-    fi
-}
-
 dracut_install() {
     inst_multiple "$@"
 }
@@ -1774,45 +1713,11 @@ inst_library() {
     inst "$@"
 }
 
-inst_binary() {
-    local _ret
-    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} "$@"; then
-        return 0
-    else
-        _ret=$?
-        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} "$@"
-        return "$_ret"
-    fi
-}
-
-inst_script() {
-    local _ret
-    if $DRACUT_INSTALL ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} "$@"; then
-        return 0
-    else
-        _ret=$?
-        derror FAILED: "$DRACUT_INSTALL" ${dracutsysrootdir:+-r "$dracutsysrootdir"} ${initdir:+-D "$initdir"} ${loginstall:+-L "$loginstall"} ${DRACUT_RESOLVE_DEPS:+-l} ${DRACUT_FIPS_MODE:+-f} "$@"
-        return "$_ret"
-    fi
-}
-
 # empty function for compatibility
 inst_fsck_help() {
     :
 }
 
-# Use with form hostonly="$(optional_hostonly)" inst_xxxx <args>
-# If hostonly mode is set to "strict", hostonly restrictions will still
-# be applied, else will ignore hostonly mode and try to install all
-# given modules.
-optional_hostonly() {
-    if [[ $hostonly_mode == "strict" ]]; then
-        printf -- "%s" "${hostonly-}"
-    else
-        printf ""
-    fi
-}
-
 mark_hostonly() {
     for i in "$@"; do
         echo "$i" >> "$initdir/lib/dracut/hostonly-files"
@@ -1973,24 +1878,6 @@ build_ld_cache() {
     fi
 }
 
-# install function specialized for hooks
-# $1 = type of hook, $2 = hook priority (lower runs first), $3 = hook
-# All hooks should be POSIX/SuS compliant, they will be sourced by init.
-inst_hook() {
-    local hook
-    if ! [[ -f $3 ]]; then
-        dfatal "Cannot install a hook ($3) that does not exist."
-        dfatal "Aborting initrd creation."
-        exit 1
-    elif ! [[ $hookdirs == *$1* ]]; then
-        dfatal "No such hook type $1. Aborting initrd creation."
-        exit 1
-    fi
-    hook="/var/lib/dracut/hooks/${1}/${2}-${3##*/}"
-    inst_simple "$3" "$hook"
-    chmod u+x "$initdir/$hook"
-}
-
 # install any of listed files
 #
 # If first argument is '-d' and second some destination path, first accessible