From 883eba538be9086ec18f52f97e60cf4d9076af78 Mon Sep 17 00:00:00 2001 From: Jo Zzsi Date: Sat, 22 Nov 2025 17:38:48 -0500 Subject: [PATCH] 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. --- dracut-functions.sh | 128 +++++++++++++++++++++++++++++++++++++++++++- dracut.sh | 123 ++---------------------------------------- 2 files changed, 132 insertions(+), 119 deletions(-) diff --git a/dracut-functions.sh b/dracut-functions.sh index 617ccf91c..e2f62b9c8 100755 --- 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 +# 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 80dc2884d..ce66f30a7 100755 --- a/dracut.sh +++ b/dracut.sh @@ -21,6 +21,11 @@ # along with this program. If not, see . # +# 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 -# 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 -- 2.47.3