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>. | ||||