This section discusses the T2 build system as it has been implemented since version 2.0 and we assume that you want to build an end-users boot-able and install-able target like the generic, minimal, desktop or server target.
T2 requires just a few prerequisites for building:
a Bash shell: as the T2 scripts take advantage of some convenient Bash specific features and shortcuts
ncurses: for the scripts/Config tool
cat, cut, sed & co: for the usual shell scripting
The build scripts will check for the most important tools and print a diagnostic if a tool or feature is found missing.
More information can be found in the trouble-shooting section (see the section called “Troubleshooting”) and kernel configuration (see the section called “Linux Kernel”).
T2 comes with a menu driven configuration utility even for the build configuration:
scripts/Config
which compiles the configuration program (you need gcc installed for this).
The most important option (ok - well maybe the most important after the architecture for the build ...) is to choose a so-called 'target'.
Relevant targets are:
Generic System
Generic Embedded
Exact Desktop System
Archivista (Scan-)Box
Sega Dreamcast Console
Psion Windermere PDA
Reference-Build for creating *.cache files
Wireless Router (experimental!)
Most of the targets have a customization option. The "Generic System" customization looks like this:
No package preselection template
Minimalistic package selection
Minimalistic package selection and X.org
Minimalistic package selection, X.org and basic desktop
A base selection for benchmarking purpose
Also depending on the target type the distribution media can be selected. For the "Generic System":
Install CD / disk
Live CD
Just package and create isofs.txt
Distribute package only
If you want to alter the package selection (performed by the target) this is finally possibly at this stage, under the expert menu. The deselected packages are also not downloaded from the Internet.
So now we start configuring the target that will build the packages for the system:
scripts/Config
The most useful options in scripts/Config are:
Always abort if package-build fails: Deselect normally, so your build continues (there are always failing packages.
Retry building broken packages: When starting a rebuild (after fixing a package) the build retries the packages it could not build before.
Disable packages which are marked as broken: When checked T2 will not try to build the packages that have errors (as noted in the cache file see the section called “Cache File (.cache)”)
Always clean up src dirs (even on pkg fail): Select when you need the disk space - though it can be useful to have the src dir when you need to troubleshoot.
Print Build-Output to terminal when building: Select for exiting output.
Make rebuild stage (stage 9): Select only if you have too much CPU power or are paranoid to solve rare dependency problems between packages. The downside is a doubled total build time - and should normally not be necessary.
Now the auto-build-system has a config to use and can so determine which packages are requested to be downloaded and build. The scripts/Download contains the functionality to perform the downloads - and when started with the -required option it only fetches the sources needed by the given config.
scripts/Download -required
Downloads the selected packages with which you can build a running system. See the section called “Download Tips” for some tips.
Downloading the full sources for the various packages used may takes a while - depending on how fast you can move up to 2Gb through your Internet connection. While waiting you may want to go out, sleep, work and go through that routine again.
The Download script may complain you have the wrong version of bash and you need curl.
The full options of scripts/Download are [2]:
Usage:
scripts/Download [options] [ Package(s) ]
scripts/Download [options] [ Desc file(s) ]
scripts/Download [options] -repository Repositories
scripts/Download [options] { -all | -required }
Where [options] is an alias for:
[ -cfg <config> ] [ -nock ] [ -alt-dir <AlternativeDirectory> ]
[ -mirror <URL> | -check ] [ -try-questionable ] [ -notimeout ]
[ -longtimeout ] [ -curl-opt <curl-option>[:<curl-option>[:..]] ]
[ -proxy <server>[:<port>] ] [ -proxy-auth <username>[:<password>] ]
[ -copy ] [ -move ]
On default, this script auto-detects the best T2 SDE mirror.
Mirrors can also be a local directories in the form of 'file:///<dir>'.
scripts/Download -mk-cksum Filename(s)
scripts/Download [ -list | -list-unknown | -list-missing | -list-cksums ]
Quite a few contributors and sponsors of T2 Linux have created mirrors for source tar balls - scripts/Download tries to select the fastest mirror.
Sometimes a mirror is incomplete or out-of-date. The Download scripts will try to fetch the file from the original upstream location in that case. If too many files are missing on the mirror that was selected, you might however like to choose another one.
To select a specific mirror:
scripts/Download -mirror http://www.ibiblio.org/pub/linux/t2/7.0
Running scripts/Download with the argument '-mirror none' will instruct the scripts to always fetch the sources from the original site, first.
All packages get downloaded from the original locations. For each package the T2 distribution maintains a package file which points to the ftp, http or cvs location and filename. Sometimes the download site changes, more often the version numbering of a file changes. At that point the package file needs to be edited. After a successful download you may send the patch to the T2 Linux maintainers - so others get an automatic update.
Missing packages are not necessarily a problem. If you are aware what a package does and you know you don't actually need it you can pretty much ignore the error. For base packages it is usually a good idea to fetch them all.
It may be useful to download the most recent version of T2 (stable or development) since it will reflect the most recent state of the original packages.
To actually find which files are missing run:
scripts/Download -list-missing
If a package fails to download because it is not on a mirror and the original has moved away you may want to fix the URL in the package directly.
Find the package in the package directory and modify the package.desc directly. Update the URL in the [D] field and set the checksum to 0. Also update the [V] version field if it has changed.
With the fixed URL re-run:
scripts/Download -required
or if there are some more files in the queue, downloading explicitly a single package can be forced with:
scripts/Download packagename
If it worked and the package builds fine (see Chapter 4, Building T2) it is recommended you send in the change to the T2 maintainers - to prevent other people from going through the same work (see the section called “Getting New Packages Into T2” for more information). The one thing you'll have to do is to fix the checksum in the [D] field (see the section called “Checksum”).
The Download script has a facility for checking the integrity of the downloaded packages. It does so during each download - but you can also run a check manually:
scripts/Download -check -all
iterates over all the packages and checks for matching checksums. If a package got corrupted, in one way or the other, it returns an error.
To get the checksum of a single tarball:
scripts/Download -mk-cksum path
Or use the even easier script which creates a checksum patch automatically:
scripts/Create-CkSumPatch package > cksum.patch patch -p1 < cksum.patch
in short just:
scripts/Create-CkSumPatch package | patch -p1
Before starting a new download it is an idea to create the 'download' directory and mount it from elsewhere (a symbolic link will not work with the build phase later, though in this stage it will do) this way you can use the same repository when moving to a new version of the T2 Linux scripts (check the section called “Unknown Files”).
When going through several cycles of upgrading and downloading packages (see also the section called “Download Tips”) you'll find the same packages with different versions of tarballs in your download tree (e.g. apache-1.25 and apache-1.26). The older files (apache-1.25) are considered obsolete and are named 'unknown files' in T2 jargon.
scripts/Download -list-unknown
To remove unknown files (treating it as white-space separated list and only pass thru column 2):
scripts/Download -list-unknown | cut -d ' ' -f 3 | xargs rm -vf
or since recently just:
scripts/Cleanup -download
To build the target you must be root. There are two main reasons why this is currently the case:
For normal builds with a native compilation phase chroot is used. However, the chroot system-call commonly is only allowed for the root user.
Various files require special permissions as well as probably specific owner and group settings for the resulting system work properly. However, those ownership and permission settings are only allowed to set for the root user.
To compensate for this, pre-load libraries, such as implemented with fakeroot, could be used to intercept and fake this meta-data while building, and this also is on the future T2 roadmap to integrate.
To build the target, execute as root:
scripts/Build-Target
which starts building all the stages (see the section called “Build Stages”). The output of the build can be found in build/$SDECFG_ID/TOOLCHAIN/logs/.
In the stable series this happens only rarely - but it might happen sometimes in the development series. Packages can break because they go out-of-date (dependencies do not match) or because the downloaded package mismatches the build scripts, or maybe, because there is something wrong with your build environment.
The output of the build process of the individual packages is captured in the directory build/$SDECFG_ID/var/adm/logs/. All the packages with errors show the .err extension.
A tabular overview is provided by scripts/Create-ErrList, like for example:
Error logs from live-7.0-trunk-desktop-x86-pentiumpro: [5] network/pilot-link [5] emulators/qemu 876 builds total, 874 completed fine, 2 with errors.
Check the content of the error files to see if you can fix the problem (see also the section called “Fixing Broken Packages”).
Before starting a rebuild select 'Retry Broken Packages' in scripts/Config.
Every package gets built in a directory named src.$pkg.$config.$id To remove these packages (if there is an error it can be useful to check the content of the partial build!) usescripts/Cleanup.
Warning
Simply type 'scripts/Cleanup' to remove the src.* directories. DO NOT REMOVE THEM BY HAND! This directories may contain bind mounts to the rest of the source tree and it is possible that you are going to remove everything T2 SDE base directory if you make a simple 'rm -rf' to remove them!
By passing --build the script will also remove existing builds from inside the build/ directory, --cache will ccache related cache directories from inside build/ and last but not least --full remove the entire generated content in the build/ directory.
Now you should have a ready system build. If you selected "Install CD / disks" or "Live CD" in the configuration phase then you have the Installer also. Since many different targets exist, those targets should share a common installer application. A typical installer needs different things like a embedded C library, many small size binaries and the installer binaries and scripts.
To summarize, a typical cycle to build a T2 target looks like:
scripts/Config scripts/Download scripts/Build-Target