Hacking
*******

INTRODUCTION
------------

This file is intended to help you get off-the-ground with incorportating
Splashy into your own distribution or adding new features to Splashy.

A few things to keep in mind while reading Splashy sources:
  * We follow the GNU Coding Standard. Please become familiar with these
    standards especially before submitting patches (Google is your friend).
  * All Splashy sources are inside the "src" directory and they are prefixed
    according to what they do (library-like,namespace-like). Thus,
    "splashy_functions.c" holds functions that apply only to splashy itself,
    not splashy_config or splashy_update or splashy_* anything. 
  * When in doubt, ask in splashy-devel@lists.alioth.debian.org or in #splashy
    at irc.freenode.net

FIFO COMMANDS
-------------

When talking to the Splashy server you can use the following commands:

  progress <number>  Updates the progress bar to <number>%, where N is a number
                     between 0 and 100
  PROGRESS <number>  Same as "progress". For compatibility with usplash
  print <string>     Print <string> in the text box
  TEXT <string>      Same as "print". For compatibility with usplash
  clrprint           Clears the text box area
  CLEAR              Same as "clrprint". For compatibility with usplash
  repaint            Redraw the background image
  chvt <number>      Switch to vt <number>. See "allowchvt"
  allowchvt          Splashy ignores all "chvt" commands until this command is
                     sent
  timeout            Sets the amount of seconds splashy waits for new commands
                     in the fifo file. If that time is exceeded, it exits
  exit               Exits Splashy server
  QUIT               Same as "exit". For compatibility with usplash

Sending commands to the Splashy server is then as simple as:

echo "exit" > /etc/splashy/splashy.fifo

This will cause the "echo" command to hold the process until Splashy reads the
FIFO (man fifo). If you don't like this behaviour, the splashy_update command is
provided: splashy_update does not block the process trying to write to the fifo
file.


IINITRAMFS
----------

Splashy should be copied to the initramfs by using the provided hooks and
scripts. These files go into:

  /usr/share/initramfs/hooks/splashy
  /usr/share/initramfs/scripts/init-top/splashy

The command to create a new initramfs on Debian image is: 

  update-initramfs -u

To see the content of the initramfs run:

  mkdir /tmp/initrd
  cd /tmp/initrd
  cat /boot/initrd.img-`uname -r` | gzip -d | cpio -i

After this you will see everything that the initramfs image has.

A few things to note: 
  * Be sure that the init-top script (splashy) runs "/sbin/splashy boot"
  * ldd sbin/splashy should show a static binary and only libc6 as output:
      $> ldd sbin/splashy
        linux-gate.so.1 =>  (0xffffe000)
        libpthread.so.0 => /lib/tls/i686/cmov/libpthread.so.0 (0xb7f0b000)
        libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7ee9000)
        libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb7dba000)
        /lib/ld-linux.so.2 (0xb7f3a000)
  * Running "/sbin/splashy boot" or "/sbin/splashy test" should ensure that
    splashy from initramfs is good. Remember that Splashy is just a user-space
    application

THEMES
------

To validate all themes against our themes.xsd schema, do:

./scripts/xml-validator -S schemas/theme.xsd themes/*/theme.xml

TROUBLESHOOTING
---------------

  * libgcc_s.so.1 must be installed for pthread_cancel to work 
    - Error is fixed by adding /lib to /etc/ld.so.conf and running ldconfig. Which is done by
      default in current distros. Splashy needs to be linked against this file with: -lgcc_s.
      which is already in src/Makefile.am: splashy_LDFLAGS = -lgcc_s ...

APPENDIX A - Debian Packaging

  * package version:
    - edit the debian-related/trunk/debian/changelog. for SVN releases we use the convention:
        SPLASHY_VERSION-PACKAGED_NUMBER_OF_TIMESsvnYYYYMMDDHHMM
      which roughly looks like:
        0.1.8-2svn200607170938
      
      Assume time to be UTC
      For all regular releases, the standard debian package version applies:
        SPLASHY_VERSION-PACKAGED_NUMBER_OF_TIMES
      which roughly looks like:
        0.1.8-2

  * go into the "trunk" folder and type: ./scripts/make-debian
    if in doubt, read that script to learn what it takes to package Splashy for debian
 
 APPENDIX B - Fedora Core Packaging
   (work in progress)

   * use the package spec supplied in trunk/splashy.spec to create an RPM:
     - cp -r trunk /tmp/splashy
     - cd /tmp/splashy
     - ./autogen.sh
     - make dist-bzip2
     - copy splashy-VERSION.tar.bz2 to /usr/src/{rpm,redhat,others}/SOURCES
     - rpmbuild -ba splashy.spec

