Improve documentation of the project

Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com>

diff --git a/README b/README
index 58eab6473adf9143bd7a10fe46d9f85aa3e51859..10058a6858301d72b828ead25845230501a7126e 100644 (file)
--- a/README
+++ b/README
@@ -8,3 +8,79 @@ for you.
 
 Raisin is meant to be easy to read so that it can be used as a guideline
 on how to build and configure the system.
+
+
+
+= Usage =
+
+Set your configuration parameters in the "config" file, then run
+
+./raise.sh
+
+Go and grab a coffee. When the script completes, you'll have a full
+Xen system installation under DESTDIR.
+
+raise.sh takes care of:
+
+- git cloning all the components enabled in the config
+- installing all the dependencies needed to build each components (requires sudo)
+- building them
+- installing them under DESTDIR (the "dist" sub-directory by default)
+
+raise.sh can optionally perform the installation under / and fully
+configure the system for you. If you want this behaviour run
+
+./raise.sh -i
+
+
+
+= Adding new components =
+
+Adding new components is easy!
+
+Just introduce a new component script file under "components", following
+the example of the already existing ones. Remember to add the component
+name in the series file in the right order (for example anything that
+depends on Xen, should be built after Xen).
+
+
+You need to implement a few bash functions in the component script file:
+
+* component_build
+git clones, builds and installs the new component under DESTDIR
+
+* component_clean
+cleans the build
+
+* component_configure
+The component has already been installed under /, now configure the
+system for it
+
+* component_unconfigure
+The component has already been uninstalled from /, now remove the
+configuration
+
+These functions are called by raise.sh automatically if the component is
+enabled in the config.
+
+
+You can/should rely on the following global variables in your component
+script file:
+
+GIT: git command to run, but prefer the git-checkout.sh script
+MAKE: make command to run
+SUDO: sudo command to run
+DISTRO: which Linux distribution we are running on, Debian, Fedora, etc
+ARCH: which architecture we are running on, x86_64, arm32, etc.
+BASEDIR: absolute path of the raisin directory
+PREFIX: installation PREFIX
+INST_DIR: absolute path of the installation directory
+COMPONENT_UPSTREAM_URL: git url to clone, set by config
+COMPONENT_UPSTREAM_REVISION: branch or tag to checkout, set by config
+
+You can also rely on any utility functions in common-functions.sh, in
+particular:
+
+install_dependencies
+start_initscripts
+stop_initscripts

diff --git a/common-functions.sh b/common-functions.sh
index 706d332b3be8404c05bf577c789715e049a2e623..f6c0de35f0a5f030aaa740fc3580ae40ee33cc60 100644 (file)
--- a/common-functions.sh
+++ b/common-functions.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 
+# Executed once at the beginning of the script
 function common_init() {
     export BASEDIR=`pwd`
     export GIT=${GIT-git}

diff --git a/config b/config
index 5b474c7d11e83492d040d5a46e76ee67908ce1f3..2b37acc320331e93f55ab3ff9cc729fb72045857 100644 (file)
--- a/config
+++ b/config
@@ -1,11 +1,15 @@
 # Config variables for raisin
 
 # Build config
+## Make command to run
 MAKE="make -j2"
+## Installation prefix (configure --prefix)
 PREFIX="/usr"
+## Install everything under DESTDIR
+## If you want to install under / run raise.sh -i
 DESTDIR=dist
 
-# Git urls
+# Git urls. Use the http urls if you are behind a firewall.
 #XEN_UPSTREAM_URL="http://xenbits.xen.org/git-http/xen.git"
 #GRUB_UPSTREAM_URL="http://git.savannah.gnu.org/r/grub.git"
 #LIBVIRT_UPSTREAM_URL="https://gitorious.org/libvirt/libvirt.git"
@@ -16,6 +20,6 @@ LIBVIRT_UPSTREAM_URL="git://libvirt.org/libvirt.git"
 # Software versions. Leave blank if you want to avoid the build, like
 # this: GRUB_UPSTREAM_REVISION=
 # Grub and Libvirt needs Xen to build and run.
-XEN_UPSTREAM_REVISION="RELEASE-4.5.0"
+XEN_UPSTREAM_REVISION="master"
 GRUB_UPSTREAM_REVISION="master"
 LIBVIRT_UPSTREAM_REVISION="master"

diff --git a/raise.sh b/raise.sh
index 887779ba4ef9ae3fe49c681d6301d5817c77befd..64530355e6d86c7659d775441402735f89fd9a99 100755 (executable)
--- a/raise.sh
+++ b/raise.sh
@@ -13,6 +13,8 @@ help() {
     echo "    -i | --install       Install under / and configure the system"
 }
 
+
+# start execution
 common_init
 
 # parameters check
@@ -42,7 +44,7 @@ done
 mkdir -p "$INST_DIR" &>/dev/null
 install_dependencies git
 
-# build and install under $DESTDIR ($BASEDIR/dist by default)
+# build and install under $DESTDIR
 for_each_component clean
 for_each_component build
 

diff --git a/unraise.sh b/unraise.sh
index 6c7b8dec3df17ff9132e226f332d14547adc339c..88d49cc656081b4abe45bf50579bb17c91ecbff9 100755 (executable)
--- a/unraise.sh
+++ b/unraise.sh
@@ -5,6 +5,8 @@ set -e
 source config
 source common-functions.sh
 
+
+# start execution
 common_init
 
 for_each_component clean