initramfs-tools-0.92j from mirrrors.kernel.orgdebian/0.92j

3 files changed, 288 insertions, 0 deletions

diff --git a/docs/example_hook b/docs/example_hook
new file mode 100644
index 0000000..a0d015a
--- /dev/null
+++ b/docs/example_hook
@@ -0,0 +1,114 @@
+#!/bin/sh
+
+#
+# This is an example hook script.  It will be run by 'mkinitramfs'
+# when it creates the image.  It's job is to decide which files to
+# install, then install them into the staging area, where the
+# initramfs is being created.  This happens when a new 'linux-image'
+# package is installed, or when the administrator runs 'mkinitramfs'
+# by hand to update an initramfs image.
+#
+# TODO: What about the case where you install something that should be
+#	added to the initramfs, but the linux-image it relates to has
+#	already been installed previously?  Does this happen often
+#	enough that it needs to be handled?  How can it be handled?
+#
+#	* Think about the 'usplash'.  The initramfs will need to be
+#	 updated if a theme change or update is desired.  Maybe it
+#	 should not be totally automatic, but offered on upgrade
+#	 predicated on a user response to a debconf question?  That
+#	 issue needs to be explored and a solution specified.
+#
+#  * Do not assume that any needed subdirectories have been created
+#	yet, but don't bail out if they are already there.
+#
+#  * All of the standard system tools are available, of course, since
+#	this hook is running in the real system, not the initramfs.
+#
+#  * TODO: ... ?  Anything else to tell them in this bullet-list?
+#
+
+#
+# The environment contains at least:
+#
+#  CONFDIR -- usually /etc/mkinitramfs, can be set on mkinitramfs
+#		 command line.
+#
+#  DESTDIR -- The staging directory where we are building the image.
+#
+# TODO: Decide what environment variables are meaningful and defined
+#	in this context, then document them as part of the interface.
+#
+# TODO: May need a version_compare function for comparison of VERSION?
+
+
+#
+# List the soft prerequisites here.  This is a space separated list of
+# names, of scripts that are in the same directory as this one, that
+# must be run before this one can be.
+#
+PREREQ=""
+
+prereqs()
+{
+	echo "$PREREQ"
+}
+
+case $1 in
+# get pre-requisites
+prereqs)
+	prereqs
+	exit 0
+	;;
+esac
+
+
+# You can do anything you need to from here on.
+#
+
+# Source the optional 'hook-functions' scriptlet, if you need the
+# functions defined within it.  Read it to see what is available to
+# you.  It contains functions for copying dynamically linked program
+# binaries, and kernel modules into the DESTDIR.
+#
+. /usr/share/initramfs-tools/hook-functions
+
+
+# If this hook script is a conffile (and thus stored in
+# /etc/mkinitramfs/hooks), it must take care to do the right thing
+# when the package containing it is removed but not purged.  There of
+# course may be other reasons to have custom logic deciding what to
+# install.  The version variable may be useful for this.
+#
+if [ -x /usr/bin/myprog ]; then
+	copy_exec /usr/bin/myprog usr/bin
+fi
+
+# To accompany this, there should usually be a script for inside the
+# initramfs named something like:
+#
+#   "/etc/mkinitramfs/local-premount/myprog"
+#
+# ... and it should do what is necessary to have 'myprog' get run
+# inside the early runtime environment.
+
+# Handle an error:
+#
+if [ -n "$an_error_occured" ];
+then
+	#
+	# TODO: Do we need 'warn()', 'error()', and/or 'fatal()' for this?
+	#
+	echo "An error occured in $0: $an_error_occured" >&2
+	exit 1
+	#
+	# TODO: Decide if different error codes are meaningful, what they
+	#	mean, and what the semantics of them are wrt 'mkinitramfs'
+	#	pass or fail.  Consider naming the error values with
+	#	mnemonic symbols rather than magic numbers.  They may or
+	#	may not be the same set of errors as the set for
+	#	in-initramfs scripts.
+	#
+fi
+
+exit 0
diff --git a/docs/example_hook_cpiogz b/docs/example_hook_cpiogz
new file mode 100644
index 0000000..f3e44d9
--- /dev/null
+++ b/docs/example_hook_cpiogz
@@ -0,0 +1,84 @@
+#!/bin/sh
+
+#
+# The environment contains at least:
+#
+#  CONFDIR -- usually /etc/mkinitramfs, can be set on mkinitramfs
+#		 command line.
+#
+#  DESTDIR -- The staging directory where we are building the image.
+#
+# TODO: Decide what environment variables are meaningful and defined
+#	in this context, then document them as part of the interface.
+#
+# TODO: Write a common header for these examples or move this
+#	documentation to a man page and reference it here. :-)
+#
+
+#
+# List the soft prerequisites here.  This is a space separated list of
+# names, of scripts that are in the same directory as this one, that
+# must be run before this one can be.
+#
+PREREQ=""
+
+prereqs()
+{
+	echo "$PREREQ"
+}
+
+case $1 in
+# get pre-requisites
+prereqs)
+	prereqs
+	exit 0
+	;;
+esac
+
+#
+# Source the 'hook-functions' scriptlet (for 'catenate_cpiogz'):
+#
+. /usr/share/initramfs-tools/hook-functions
+
+#
+# Lets pretend it has a conffile (think debconf), and we source it
+# here.  Don't make debconf lookup calls here.  The postinst for the
+# package owning this hook script should have done that and configured
+# the "/etc/default/conffile" already.
+#
+# TODO: How does the package ensure that it's installed BEFORE the
+#	corresponding 'linux-image' package?  Can it declare that, in
+#	the case where it's an add-on that the 'linux-image' is not
+#	aware of?  This might be an apt and dpkg issue.
+#
+#	* Eg. an optional usplash or suspend2ui_fbsplash package.
+#
+. /etc/default/mypackage-initramfs
+
+#
+# Also pretend that we only include our initramfs overlay if an opion
+# is not "no", and the 'linux-image' package we are generating this
+# initramfs for matches the version this script's package is designed
+# for.  Just for example; pretend this example mkinitramfs hook script
+# is part of a 'linux-image' or 'xxx-modules' package.
+#
+if [ "$MYOPTION" != "no" -a "$version" = "2.6.12+ss2.1.9.1" ]; then
+	catenate_cpiogz /usr/lib/mypackage/initramfs.cpio.gz
+fi
+
+#
+# In this case, there does not have to be an (eg.):
+#
+#   "/etc/mkinitramfs/init-top/mypackage"
+#
+# ... since that script is probably inside of the initramfs overlay
+# already.  If it's a conffile though, it does not belong in there,
+# and should be placed in the appropriate location inside of
+# "/etc/mkinitramfs".  Remember that if it needs access to the
+# settings in our "/etc/default/mypackage-initramfs", then that file
+# must also get copied into a location inside of ${DESTDIR} by this
+# hook script in order to make it available inside of the initramfs
+# environment.
+#
+
+exit 0
diff --git a/docs/example_script b/docs/example_script
new file mode 100644
index 0000000..d7f407f
--- /dev/null
+++ b/docs/example_script
@@ -0,0 +1,90 @@
+#!/bin/sh
+
+#
+# This script is run inside of the initramfs environment during the
+# system boot process.  It is installed there by 'mkinitramfs'.  The
+# package that owns it may opt to install it in either an appropriate
+# location under "/usr/share/initramfs-tools/scripts/", or a similar
+# location under "/etc/mkinitramfs/scripts/", depending upon whether
+# it should be considered to be a user modifiable conffile or not.
+#
+# TODO: How do we deal with the case where the package that installed
+#	this has been removed but not purged, if we always arbitrarily
+#	copy all of these scripts into the initramfs?
+#
+#  * The available toolset is limited inside this environment...
+#
+#	TODO: document that toolset in the man page.
+#
+#  * /dev, /proc, and /sys are already mounted.  / is a ?? ro/rw
+#	filesystem... etc. more documentation.
+#
+#  * It is expected that /proc and /sys will be umounted before
+#	changing over to the real root file system, so you must not keep
+#	any files open on them beyond these scripts.
+#
+#  * You may like to strip these documentation comments from this
+#	example if you take it for a template, to save a little space in
+#	the initramfs, since nobody will ever read it from inside of
+#	there anyhow.
+#
+
+#
+# The environment contains at least the following variables:
+#
+# TODO: Decide what environment variables are meaningful and defined
+#	in this context, then document them as part of the interface.
+#
+# Because this script will be run as a full separate process, rather
+# than sourced inside the context of the driver script, if it needs to
+# pass information to another script that may run after it, it must do
+# so by writing data to a file location known to both scripts.  Simply
+# setting an environment variable will not work.
+#
+
+#
+# List the soft prerequisites here.  This is a space separated list of
+# names, of scripts that are in the same directory as this one, that
+# must be run before this one can be.
+#
+PREREQ=""
+
+prereqs()
+{
+	echo "$PREREQ"
+}
+
+case $1 in
+# get pre-requisites
+prereqs)
+	prereqs
+	exit 0
+	;;
+esac
+
+# Do the work here.
+
+echo "Got here!"
+
+# Handle an error:
+
+if [ -n "$an_error_occured" ];
+then
+	#
+	# TODO: Do we need 'warn()', 'error()', and/or 'fatal()' for this?
+	# I think we ultimately do, and that they need to be in their own
+	# well-documented location so that an overlay can override them.
+	# Think 'usplash' progress updates.
+	#
+	echo "An error occured in $0: $an_error_occured" >&2
+	exit 1
+	#
+	# TODO: Decide if different error codes are meaningful, what they
+	#	mean, and what the semantics of them are wrt 'init' pass
+	#	or panic.  Consider naming the error values with mnemonic
+	#	symbols rather than magic numbers.
+	#
+fi
+
+exit 0
+