[PATCH 50/50] Some documentation updates

1 files changed, 19 insertions, 0 deletions

diff --git a/README b/README
index 7749fdb..abc282a 100644
--- a/README
+++ b/README
@@ -19,6 +19,25 @@ we'll grow some hooks for running arbitrary commands in the flow of
 the script, but it's worth trying to resist the urge as much as we can
 as hooks are guaranteed to be the path to slow-down.
 
+Most of the initrd generation functionality in dracut is provided by a bunch
+of generator modules that are sourced by the main dracut script to install
+specific functionality into the initrd.  They live in the modules subdirectory,
+and use functionality provided by dracut-functions to do their work.
+Some general rules for writing modules:
+ * Use one of the inst family of functions to actually install files
+   on to the initrd.  They handle mangling the pathnames and (for binaries,
+   scripts, and kernel modules) installing dependencies as appropriate so
+   you do not have to.
+ * Scripts that end up on the initrd should be POSIX compliant. dracut
+   will try to use /bin/dash as /bin/sh for the initrd if it is available,
+   so you should install it on your system -- dash aims for strict POSIX
+   compliance to the extent possible.
+ * Hooks MUST be POSIX compliant -- they are sourced by the init script,
+   and having a bashism break your user's ability to boot really sucks.
+ * Generator modules should have a two digit numeric prefix -- they run in
+   ascending sort order. Anything in the 90-99 range is stuff that dracut
+   relies on, so try not to break those hooks.
+
 Also, there is an attempt to keep things as distribution-agnostic as
 possible.  Every distribution has their own tool here and it's not
 something which is really interesting to have separate across them.