INSTALL

   1 Plymouth isn't really designed to be built from source and get installed by end users.  For it to work correctly, it needs integration with the distribution.  Because it starts so early, it needs to be packed into the distribution's initial ram disk, and the distribution needs to poke plymouth to tell it how boot is progressing.
   2
   3 Unfortunately, there isn't great documentation for distributors.  In the mean time, this email exchange might be useful:
   4
   5 Hi,
   6
   7 > I recently found a video showing Fedora booting with plymouth and I
   8 > liked it. So I wanted to use plymouth with my favorite distri (gentoo).
   9 > I know I'm enduser and the info text on freedesktop.org says plymouth
  10 > is not meant to be installed by end users but I want to give it a try.
  11 > I have KMS running and am using my own initramfs anyway (encrypted root
  12 > disk) so how hard can it be? Can anybody please give me some straight
  13 > forward hints on how to use plymouth? (The INSTALL file is empty and
  14 > the README file is boring)
  15
  16 So the basic idea is you need to:
  17
  18 1) build plymouth into the system.  On fedora we use these conffigure flags:
  19
  20 .%configure  --enable-tracing --disable-tests --without-boot-entry \
  21          --without-default-plugin                              \
  22          --with-logo=%{_datadir}/pixmaps/system-logo-white.png \
  23          --with-background-start-color-stop=0x0073B3           \
  24          --with-background-end-color-stop=0x00457E             \
  25          --with-background-color=0x3391cd                      \
  26          --with-system-root-install                            \
  27          --with-rhgb-compat-link
  28
  29 %configure is a macro that expands to:
  30
  31 ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
  32
  33 (and some other stuff)
  34
  35 %{_datadir} is just /usr/share
  36
  37 You probably won't need --with-rhgb-compat-link since that's only
  38 there for compatibility with Fedora's old infrastructure.
  39
  40 --with-system-root-install makes plymouthd and plymouth install
  41 themselves into / instead of /usr.  This is important so that the
  42 plymouth client can work in cases where the root fs is mounted, but
  43 /usr isn't yet.
  44
  45 Somehow you need to hook into your distros mkinitrd mechanism.   I
  46 mean you need to copy the plymouth binaries, plugins, and data files
  47 into the initrd everytime you rebuild your initrd. See
  48 plymouth-populate-initrd for how we do it on fedora (mkinitrd calls
  49 plymouth-populate-initrd).  I would like to upstream hooks for other
  50 distros mkinitrd systems, so the out of the box experience is easier.
  51
  52 Inside the initrd, you need to start plymouthd early.  The earlier the
  53 better, but not before /sys, /proc/,  and /dev/pts are mounted, and
  54 not before /dev/tty[01] and /dev/fb0 are created.
  55
  56 At some point during the initrd you need to load the kms driver.
  57 After it's loaded the graphics mode should get set up and /dev/fb0
  58 will be functional.  That's when you call plymouth --show-splash to
  59 show the splash screen.
  60
  61 To decrypt your root, run
  62
  63 plymouth ask-for-password --command="/sbin/cryptsetup luksOpen -T ..."
  64
  65 where the --command is whatever makes sense for you.
  66
  67 Right after you mount the root file system (but before you switch to it), run
  68
  69 plymouth --newroot=/wherevertherootismounted
  70
  71 This tells plymouth it can load some files off the real filesystem
  72 (like fonts, and stuff we don't want to stick in the initrd).
  73
  74 while boot you need to run plymouth --update=some-milestone-id
  75
  76 periodically to update the progress bar.
  77
  78 When / is mounted read-write you need to run
  79
  80 plymouth --sysinit
  81
  82 Finally, when plymouth is done, you need to run plymouth --quit
  83
  84 I have to run to catch a bus but i think that's the basics.
  85
  86 > I'm even willing to give something back and convert your hints
  87 > into an easy step by step howto.
  88 That'd be great!
  89
  90 --Ray