manpage: expand doc on build and runtime hooks

Fully document the recommended API for install hooks, and the various
hook points available for early userspace hooks.

Signed-off-by: Dave Reisner <dreisner@archlinux.org>

1 files changed, 98 insertions, 10 deletions

diff --git a/mkinitcpio.8.txt b/mkinitcpio.8.txt
index 070cfeb..9b95f5a 100644
--- a/mkinitcpio.8.txt
+++ b/mkinitcpio.8.txt
@@ -83,13 +83,6 @@ Options
 *-z, \--compress* 'compress'::
 	Override the compression method with the 'compress' program.
 
-About Hooks
------------
-A hook is a script that executes in the initial ramdisk. Scripts are listed in
-order of execution as a space separated string in the *HOOKS* variable in the
-mkinitcpio configuration file. Hooks can, for example, set up the udev device
-filesystem, load IDE modules, etc.
-
 About Presets
 -------------
 A preset is a pre-defined definition on how to create an initial ramdisk.
@@ -98,6 +91,97 @@ you generate a new initial ramdisk, you define a preset and use the -p switch
 to generate an initial ramdisk according to your preset. Presets are located in
 /etc/mkinitcpio.d
 
+About Install Hooks
+-------------------
+Install hooks are bash scripts which are sourced during mkinitcpio runtime in
+order to add modules, binaries, and other files to the image. A variety of
+functions exist to facilitate this.
+
+*add_module* 'modname'::
+
+	Adds the module specified by 'modname' to the image. Dependencies are derived
+	and added automatically.
+
+*add_binary* 'binary' [ 'destination' ] [ 'mode' ]::
+
+	Adds a binary to the image. The argument 'binary' need not be an absolute
+	path and, if needed, a lookup will be performed. If the binary is a dynamically
+	linked ELF binary, dependencies will be automatically added. Optionally, a
+	destination within the initramfs image as well as a file mode can be specified.
+	By default, the desintation and mode be taken from the source derived from
+	'binary'.
+
+*add_file* 'path' [ 'destination' ] [ 'mode' ]::
+
+	Adds a file and any needed parent directories to the image. Optionally, a
+	destination within the initramfs image as well as a file mode can be specified.
+	By default, the destination and mode will be taken from the source and mode of
+	the file specified by the 'path'.
+
+*add_dir* 'path'::
+
+	Adds a directory and its parents to the image.
+
+*add_full_path* 'path'::
+
+	Recursively adds a path to the image. This will inherently call *add_file*
+	and *add_dir* accordingly.
+
+*add_all_modules* [ '-f filter' ] *pattern*::
+
+	add modules to the image, without regard for the autodetect whitelist. *pattern*
+	should be a subdirectory within the kernel tree describing a subset of modules to
+	be included. Further refinement can be provided via the -f flag with an extended
+	regular expression.
+
+*add_checked_modules* [ '-f filter' ] *pattern*::
+
+	Similar to *add_all_modules* with the constraint that only modules matching the
+	whitelist generated by the autodetect hook will be added to the image. If the
+	autodetect hook is not present in the image, this function is identical to
+	*add_all_modules*.
+
+*add_runscript* [ 'scriptname' ]::
+
+	Adds a runtime hook to the image, which is a busybox ash compatible shell
+	script. The name of the script is guarenteed to match the name of the hook the
+	script is called. It *can* be overriden, but this is not recommended, as this
+	only exists for legacy compatability.
+
+About Runtime Hooks
+-------------------
+Runtime hooks added to the image via the *add_runscript* function from an
+install hook are able to provide extra functionality during early userspace.
+Specific functions in these files will run at different times. A hook can
+define one or more of these. At each hook point, hooks are run in the order
+that they are defined in the HOOKS variable, except for cleanup hooks which are
+run in reverse.
+
+*run_earlyhook*::
+
+	Functions of this name will be run once the API mounts have been setup the
+	kernel command line has been parsed. Daemons needed for early userspace should
+	be started from this hook point.
+
+*run_hook*::
+
+	Functions of this name will be run after any early hooks, and after user
+	defined modules have been installed. This is the most common hook point, and
+	functionality such as scanning for LVM volumes and mapping encrypted volumes
+	should be performed here.
+
+*run_latehook*::
+
+	Functions of this name will be run after root has been mounted. This is generally
+	used for further necessary setup in the real root, such as mounting other system
+	partitions.
+
+*run_cleanuphook*::
+
+	Functions of this name are run as late as possible. Any daemons started
+	from a run_earlyhook function should be shut down here in preparation for
+	switching to the real root.
+
 Early Init Environment
 ----------------------
 mkinitcpio gives special treatment to certain environment variables passed on
@@ -157,9 +241,13 @@ Files
 '/etc/mkinitcpio.d'::
 	Folder containing mkinitcpio presets.
 
-'/usr/lib/initcpio'::
-'/lib/initcpio'::
-	Files related to creating an initial ramdisk.
+'/usr/lib/initcpio/install'::
+'/lib/initcpio/install'::
+	Search path for build time hooks.
+
+'/usr/lib/initcpio/hooks'::
+'/lib/initcpio/hooks'::
+	Search path for early userspace runtime hooks.
 
 Examples
 --------