Readme.eng
This document briefly describes what Sovereign is and how to use it.

0. Introducing Sovereign
    Greetings, fellow software engineer!
    Welcome to the world of independence from the army of Linux distributions,
    both the "bleeding edge" liberal flavors and "yet to be deprecated"
    conservative ones.

    Sovereign Development Framework is meant to provide you with a consistent
    set of tools and libraries for your everyday software development.
    With Sovereign, you can work on your projects peacefully, deferring
    distribution-specific tasks closer to the stages of testing and packaging
    the releases.

    Technically, a deployed Sovereign framework is a set of tools and libraries
    installed with a specific prefix ("/opt/sgn"). All you have to do to start
    working with the new tools is to add "/opt/sgn" to the beginning of your
    PATH. As the result, all the programs you compile will be linked with
    libraries from /opt/sgn/lib, and you'll never have to worry about what is
    there in distribution-specific /lib and /usr/lib.

    If you construct your Sovereign system so that it includes all the
    dependencies of your project, then no single library from /lib and /usr/lib
    will be used at all, and Sovereign will be able to serve as a binary
    portability layer for your programs, leaving Linux kernel ABI compatibility
    as the only portability issue (and the kernel's ABI is known to be carefully
    maintained).

    Here's a list of possible problems that Sovereign is meant to solve for you:
    * The tools and libraries in the distribution you currently use are becoming
      old (lack features, provide deprecated APIs, have known bugs), and you
      want to get newer versions without breaking the distribution.
    * The distribution you have chosen has incorporated a buggy new version of
      a tool/library that you need, and you want to "hold the horses" and keep
      working with one of the previous versions without breaking you current
      GNU/Linux installation.
    * You need a tool/library which is not included in your current
      distribution, and the needed software conflicts with installed versions of
      some packages.
    * You use quite a few computers for your everyday development (a couple
      notebooks and desktops, your office workstation, a dozen nodes in
      a testing cluster, etc.), and you don't bother maintaining coherent
      GNU/Linux distros on all of the boxes.
    * The type of Linux distribution you use is dictated by a corporate policy,
      and you don't want to waste your time tuning it for your needs and
      ensuring that everything works as expected.
    * You've got a server system without much -devel packet installed (and
      probably without gcc), and want to compile and run some programs without
      installing any additional packets.

    Got interested? Welcome onboard!

1. Conventions used throughout this document
    1.1. All sample commands are tabulated and prepended with a '$' character
    to indicated that commands are to be executed manually from the console.
    For example:
	$ cd ~/'sovereign'
    1.2. Sample commands are assumed to be executed from the directory where
    Sovereign is unpacked on your system.
    1.3. Most of the commands should be executed as root.
    1.4. All sample commands are assumed to be executed in the GNU Bourne Again
    SHell ("bash").

2. Preparing the Sovereign build environment
    1.1. Before executing any Sovereign scripts, you must set the 'SGN_HOME'
    environment variable to the path where Sovereign is unpacked on your system:
	$ cd ~/'sovereign'
	$ export SGN_HOME=`pwd`

    1.2. Before you start, prepare virtual ext2 images by executing
    the following command:
	$ ./sgn_init_images.sh
    This will create two images: sgn_install.img (512 Mb), and sgn_system.img
    (1024 Mb). Alternatively, you can create these images manually.

    sgn_install.img is used during compilation of Sovereign binary packages (SGN
    packages, or SGNs).

    sgn_system.img is the target filesystem for your new Sovereign installation.
    After the Sovereign system is ready, you'll be able to obtain your personal
    development framework by mounting sgn_system.img at /opt/sgn like this:
	$ mount -o loop,ro sgn_system.img /opt/sgn

3. Building new Sovereign binary packages.
    To build a new SGN package, you'll need:
	1. A shell script for building the package.
           Such scripts are located in the "depot" subdirectory,
           like "depot/gcc/gcc-4.2.2.sh".
	2. Source tarballs for the package in question and relevant patches.
	   For example, to build gcc-4.2.2, you'll need two files:
	   "src/gcc/gcc-4.2.2.tar.bz2" and
	   "src/gcc/gcc-4.2.2_patches/gcc-4.2.2_dwarf2out_c_patch".
        3. The tools required to build the package (like gettext, flex, make)
	   should be installed on your host system. Sovereign maintains
	   runtime independence from the host system, but currently provides
	   only partial compile-time independence.
    Once you have all the required items in place, building a new SGN is
    as simple as executing the following command (building gcc-4.2.2
    as an example):
	$ ./sgn_make.sh depot/gcc/gcc-4.2.2.sh
    After the script finishes, the new package will be put at
    ./sgn/gcc-4.2.2.sgn.

    Currently, SGN packages are just .tar.gz archives with a different
    filename extension. To install such a package, go to the root of your
    rw-mounted sgn_system.img and do "tar xzf gcc-4.2.2.sgn".
    You can use a helper script to do just the same:
	$ ./sgn_install.sh src/gcc-4.2.2.sgn
    It is planned that later SGN packages will include more information about
    the installation process like post-install scripts, so the "tar xzf" way
    will stop working some day.

4. Scripting the builds ("targets")
    To free you from manually building the packages one by one, there's a helper
    mechanism which allows you to prepare a list of the packages you want and
    let Sovereign build it all automatically.

    These package lists are plain text files located in the "targets"
    subdirectory. Their format is really simple. Here's an example:
	# NAME		VERSION			FLAGS
	binutils	binutils-2.18
	gcc		gcc-4.2.2
	linux-headers	linux-headers-2.6.23.8
	glibc		glibc-2.7
	lfs-adjust	lfs-adjust-0.1-direct	script
    It's a table, one row per package, three columns:
	NAME    - Name of the package, the one without the version string.
		  Build scripts for the package are located at "depot/${NAME}",
		  and the sources are at "src/${NAME}".
	VERSION - Versioned name of the package. The exact build script for
		  the package is "depot/${NAME}/${VERSION}.sh".
	FLAGS   - There's one possible flag currently: "script".
		  If the "script" flag is specified, then the package's build
		  shell script is considered an installation script, i.e. it
		  is not used to build the package (the package does not require
		  building at all), but to install the package.

    To build a target ("targets/sovereign_0.0" as an example), execute
    the following command:
	$ ./sgn_target.sh targets/sovereign_0.0 make_install
    This will cause every listed package to be compiled (as by running
    ./sgn_make.sh) and then unpacked to sgn_system.img (as by running
    ./sgn_install.sh).

    If you already have all the necessary SGN packages in place and only want
    to install them without recompiling, execute the following:
	$ ./sgn_target.sh targets/sovereign_0.0 install

    At last, if you want to rebuild the packages without installing them, run:
	$ ./sgn_target.sh targets/sovereign_0.0 make
    Note that the most fundamental packages (like binutils, gcc, glibc,
    linux-headers) are very sensitive to the set of packages already installed
    in sgn_system.img, and you may not be able to recompile them for
    an already-deployed Sovereign system. In this case, you can create a clean
    sgn_system.img, then create a target to rebuild the base SGN system, and
    then install the rest of the packages (which are presumably already
    compiled) with another target, using "./sgn_target.sh ... install".

5. Using your new Sovereign system.
    To start working with the Sovereign framework, mount sgn_system.img
    to /opt/sgn:
	$ mount -o loop,ro sgn_system.img /opt/sgn
    Mounting the image is read-only prevents it from being accidentally
    corrupted. If you're sure about your actions, your're free to mount it as
    read-write.

    The simplest way of substituting your host's tools with the tools from
    /opt/sgn is to add "/opt/sgn" to the beginning of the PATH environment
    variable:
	$ export PATH="/opt/sgn:$PATH"

    It is recommended to go a bit further though, and create a clean shell
    environment to guarantee that your host system's environment doesn't sneak
    in with its environment variables. To do this, create two files,
    "sgn_shell.sh", and "sgn_bashrc". The proposed content of these files
    is provided below.
	** sgn_shell.sh **
	    #!/bin/sh
	    exec env -i SGN_PREFIX='/opt/sgn' HOME="$HOME" TERM=$TERM" \
			DISPLAY="$DISPLAY" /bin/bash --rcfile sgn_bashrc

	** sgn_bashrc **
	    export LANG=en_US.UTF-8
	    set +h
	    export PS1='\[\033[1;32m\]\u \w$\[\033[0m\] '
	    export PATH="/opt/sgn/bin:/bin:/usr/bin:/usr/local/bin"
	    alias ls='ls --color=tty'

    Make sgn_shell.sh executable:
	$ chmod a+x ./sgn_shell.sh
    To jump to the new Sovereign environment, execute:
	$ ./sgn_shell.sh
    We'll call the resulting environment the "sgn shell".

    Switching to root from your sgn shell using 'su' will again clutter the
    environment with host system's settings, so it is a good idea to write
    a wrapper for 'su' to avoid that. Create a file /usr/local/bin/sgnsu
    with the following contents:
	** sgnsu **
	    #!/bin/sh
	    su -m -c "PS1=\"\[\033[1;31m\]\u \w$\[\033[0m\] \"   \
		     HOME=\"/root\" PATH=\"$PATH:/opt/sgn/sbin\" \
		     /bin/bash --norc"
    Make sgnsu executable:
	$ chmod a+x /usr/local/bin/sgnsu
    Now you're able to safely switch to root by running 'sgnsu' instead of 'su'.

6. Help enhance Sovereign
    If you have compiled some custom Sovereign packages, like a major version of
    Qt, or GNOME libraries, or maybe something relatively small yet relevant,
    consider submitting your build scripts and target files to the main
    Sovereign tree. This is a good way of collaborating by getting some free
    testing of each other's build scripts and targets.

    To submit a package or provide feedback on the existing ones,
    send a mail to <sgn-packages at sourceforge dot net>.
SourceForge.net Logo