gentoo/docs/initscripts_analysis-and-guide

   1
   2            Splashutils & Initscripts: An Analysis and a Guide
   3            --------------------------------------------------
   4
   5 Last update: 2006-02-02
   6
   7
   8 1. Introduction
   9 ---------------
  10
  11 This document is an extended version of the 'splashutils_initscripts' file,
  12 updated with info about the latest (1.1.9.3) version of splashutils and with
  13 a more detailed analysis of the functions found in splashutils-gentoo.
  14
  15 The intended audience of this text is people working on splash initscript
  16 integration for distros other than Gentoo and people interested in how the
  17 Gentoo splash initscript system works.
  18
  19
  20 2. Things to consider when implementing a splashutils initscript solution
  21 -------------------------------------------------------------------------
  22
  23 It is highly recommended that you reuse as much code as possible from
  24 'splash-functions.sh' and 'splash' from the splashutils-gentoo tarball.
  25 Keeping the code similar to the upstream version will make it possible to
  26 quickly follow any changes in splashutils.
  27
  28 With the recent versions of splashutils, some interfaces found in these
  29 two files are exported for use in the scripts bundled with splash themes.
  30 Code reuse is this no longer just a matter of convenience, it's now also
  31 a matter of interoperability between distros. In order to make it possible
  32 to use themes on any distro, please keep the following things in mind
  33 when designing your initscripts:
  34
  35  - there should exist a splash() function accepting the same arguments as
  36    in the splash() function found in splash-functions.sh
  37  - the variables $spl_cachedir and $spl_tempdir should be defined;
  38    $spl_cachedir should point to a writable directory, usually mounted
  39    as a tmpfs filesystem
  40  - the splash_setup() function should be defined and should work exactly
  41    as the one found in splash-functions.sh
  42  - `splash_svclist_get start` should return a list of boot-up services
  43    in the order in which they will be started
  44  - splash_get_mode() should be defined and should work just like the version
  45    found in splash-functions.sh
  46  - splash_comm_send() should be defined and it should make safe
  47    communication with the splash daemon possible
  48
  49 The recommended way of using splashutils is the splash daemon mode.
  50 The old way of simply calling splash_util is discouraged due to its
  51 slowness. The splash daemon mode is described in docs/daemon (from
  52 the splashutils tarball).
  53
  54 Please also note, that it should be possible to use the 'splash' wrapper
  55 script with little or no changes. There's no need to rewrite it from scratch.
  56
  57
  58 3. An analysis of the Gentoo initscripts
  59 ----------------------------------------
  60
  61 All splash-related functions in Gentoo systems are contained within a
  62 single file called 'splash-functions.sh' and located in /sbin. This file
  63 is sourced from the rc scripts. It interfaces with the rc scripts with
  64 a single function called splash(). The function is defined as a null function
  65 that does nothing by default. When 'splash-functions.sh' is sourced, the
  66 null function gets overridden.
  67
  68 * splash()
  69   The splash() function is responsible for handling events coming from rc
  70   scripts and preparing the splash cache space when it's first called. It
  71   should also allow for event hooks. A list of recognized events can be
  72   found in the comments in splash-functions.sh. The names of the events
  73   should be kept unchanged to ensure theme inter-distro compatibility.
  74
  75 * splash_setup()
  76   The splash_setup() function is responsible for reading splash
  77   configuration from a file and parsing kernel command line parameters.
  78   The global variable names it sets should be kept unchanged.
  79
  80 * splash_init()
  81   This function is called at the 'rc_init' event. It should start the
  82   splash daemon when first called, and do other preparatory tasks.
  83
  84 * splash_cache_prep()
  85   This function is reponsible for preparing the splash cache -- usually a
  86   small tmpfs filesystem. The splash cache should be writable at all times.
  87
  88 * splash_cache_cleanup()
  89   Cleans the splash cache.
  90
  91 * splash_svclist_get()
  92   This function returns an ordered list of initscripts that will be executed.
  93
  94 * splash_svclist_update()
  95   This function updates a cached ordered list of initscripts executed during
  96   boot. This is Gentoo specific code and will have to be rewritten for every
  97   distro.
  98
  99 * splash_exit()
 100   Called when the 'rc_exit' event is received. Should make sure that the
 101   splash daemon is stopped, killing it if necessary.
 102
 103 * splash_comm_send()
 104   Sends messages to the splash daemon via the splash FIFO. Note that in
 105   order to make things safe, we have to check whether the splash daemon
 106   is still alive before sending anything through the FIFO.
 107
 108 * splash_get_mode()
 109   Returns 'silent', 'verbose' or 'off', depending on the current splash state.
 110
 111 * splash_verbose()
 112   Switches the splash to verbose mode.
 113
 114 * splash_{load,save}_vars()
 115   Loads/saves some common variables to a file in the splash cache.
 116
 117 The functions defined in splash-functions.sh and not described here are either
 118 not very important or easy to understand.
 119
 120 Should you have any questions about the initscript system, or some suggestions
 121 to make, feel free to mail me.
 122
 123 --
 124  Michal Januszewski <spock@gentoo.org>