1 files changed, 48 insertions, 0 deletions
diff --git a/docs/README.cross b/docs/README.cross
new file mode 100644
index 0000000..91aa5d0
--- /dev/null
+++ b/docs/README.cross
@@ -0,0 +1,48 @@
+Dracut supports running against a sysroot directory that is different
+from the actual root (/) directory of the running system. It is most
+useful for creating/bootstrapping a new system that may or may not be
+using the same CPU architecture as the host system, i.e. building a
+whole Linux system with a cross-compiler framework like Yocto.
+
+The user-visible frontend change is the introduction of a new option
+called "-r" or "--sysroot". It expects a directory that contains the
+complete Linux system that has all the files (kernel drivers, firmware,
+executables, libraries and others) necessary to construct the initramfs.
+
+E.g: dracut --sysroot /path/to/sysroot initramfs.img kernelversion
+
+To support this, a new global variable was introduced inside dracut.
+This variable is called "dracutsysrootdir" and all the files installed
+into the initramfs image is searched relative to the sysroot directory.
+This variable can also be set externally to dracut without using option
+-r/--sysroot.
+
+There are other details that are necessary to tweak to be able to
+run on cross-compiled (a.k.a. foreign) binaries.
+
+dracut uses these crucial utilities during its operation:
+
+ldd
+===
+It lists dynamic library dependencies for executables or libraries
+
+ldconfig
+========
+It creates /etc/ld.so.cache, i.e. the cached information about libraries
+known to the system.
+
+These utilities the way they exist on the host system only work on
+the host system.
+
+To support cross-compiled binaries, a different ldd variant is needed that
+works on those binaries. One such ldd script is found at
+https://gist.github.com/jerome-pouiller/c403786c1394f53f44a3b61214489e6f
+
+ldconfig in GLIBC as is does support a sysroot with its -r option.
+
+Extra environment variables needed to run dracut on the sysroot are
+documented in the dracut(8) man page.
+
+For the Plymouth boot splash to be added to the initramfs image,
+this gitlab PR is needed for Plymouth:
+https://gitlab.freedesktop.org/plymouth/plymouth/merge_requests/72