Copyright (C) 2008-2009 Douglas Jerome <>
Some sections of this document are derived from ttylinux-src-7.0/REAME written by Pascal Schmidt; some text copyright (C) Pascal Schmidt.
$RCSfile: How_To_Build_ttylinux.txt,v $
$Revision: 1.9 $
$Date: 2009/09/07 21:34:14 $
07sep09 drj Final fixups for 9.0 release.
22aug09 drj Fixups for clarity (I hope) and x86_64.
22dec08 drj RCS timestamp check.
09dec08 drj Small fixups.
28nov08 drj Corrected some of the Bug Reports and Help text.
25nov08 drj Added license, requirements and help information.
23nov08 drj Finished and baselined first version for ttylinux.
------------------------------------------------
How to Build ttylinux
-- Document Outline --
1. Introduction
2. Licenses
3. Building Requirements
4. Build cross-tools
5. Build ttylinux
6. Build Individual Package
7. User Application
8. Build Results
9. Bug Reports and Help
===============
1. Introduction
===============
In the following descriptions there are example commands; they are prefixed by a shell prompt of "% ", and comments to shell commands begin with the shell comment character '#".
===========
2. Licenses
===========
The ttylinux cross-tools:
- guide document is licensed under the FSF FDL1
- make system is licensed under the FSF GPL2
- components are GNU and Linux kernel projects licensed under FSF GPL
versions 2 or 3.
The ttylinux make system, documents, and the base file system package are all
licensed under the GNU General Public License (GPL), a copy of which you can
find in the file doc/COPYING.
The component source packages, in the pkg-src/ directory, are licensed under a
number of different licenses. The License section of the User Guide,
doc/User_Guide.html, has an overview of the packages' licenses. For more
details, refer to the source packages.
========================
3. Building Requirements
========================
To build ttylinux you need the build system, which contains this file so you
must already have it, and the individual source packages that need to be stored
in the pkg-src/ directory. The source packages each must have a corresponding
build script in the pkg-bld/ directory and a configuration package in the
pkg-cfg/ directory.
A combined tarball of the build system and all the source packages can be
downloaded from the ttylinux homepage, which currently is located at both of
the following URLs.
The build process creates device nodes, sets ownership and privileges for
root-owned files and mounts loopback file system images; therefore, you need to
be root, uid 0 and guid 0, to run the build process.
You will need at least 500 MB of free disk space to complete the build; the
first build process includes building a cross-compiler tool chain with a full
cross-building Binutils, GCC and GLIBC. Subsequent ttylinux builds use the
cross-tool chain and require about 350 MB.
On a 2.1 Ghz dual Athlon MP 2800 with 1.5 GB of RAM, the build takes 33:40.80
elapsed time with 108% CPU utilization.
On ThinkPad W500 with Core(tm)2 Duo P8600 at 2.4 Ghz with 2.0 GB of RAM, the
build takes 18:44.37 elapsed time with 107%CPU CPU utilization.
Software Requirements
---------------------
ttylinux is actively developed on a custom Linux distribution; there is not an
officially supported Linux distribution used for ttylinux development.
cross-tools digression:
cross-tools is a ttylinux project; it is used to build ttylinux. A cross-
compiling tool chain (a set of tools consisting of Binutils, GCC and GLIBC)
is built first, then the cross-tool chain is used to build ttylinux. The
goal is that a cross-tool chain can be built on almost any recent version
of Linux, and that enables the building of a single configuration of
ttylinux from almost any Linux host. For example, the i486 target tool
chain can be built on almost any recent Linux system, and each one of those
i486 target tool chains, running on various different Linux systems, is the
same version of Binutls, GCC and GLIBC and they all build the same i486
ttylinux.
The cross-tool i486 cross-tool chain is the primary tool chain used to develop
ttylinux.
The following are the software development tools and their versions that are
used to develop and maintain the ttylinux cross-tool chains and ttylinux.
Roughly the same versions installed on a typical Linux distribution ought to
work.
Tool Notes
---------------- -------
autoconf-2.61
automake-1.10
bash-3.2
binutils-2.17
bison-2.3
bzip2-1.0.4
coreutils-6.9
diffutils-2.8.4
dev86-0.16.17 ........ for lilo
findutils-4.2.30
flex-2.5.33
gawk-3.1.5
gcc-4.1.2
gettext-0.16.1
glibc-2.5 ............ version probably doesn't much matter
grep-2.5.1a
gzip-1.3.9
libtool-1.5.22
m4-1.4.9
make-3.81
ncurses-5.6
patch-2.5.4
perl-5.8.8 ........... maybe not used
sed-4.1.5
tar-1.16.1
texinfo-4.8a
====================
4. Build cross-tools
====================
Note you do NOT need to be root to build a cross-tool chain.
ttylinux uses a cross-compiler tool set that needs to be setup. The setup
downloads the source packages for Binutils, GCC and GLIBC and then compiles
them with your system's compiler to create the cross-building tool chain.
The cross-tool i486 cross-tool chain is primary tool chain used to develop
ttylinux.
These are the steps for setting up and building an i486 cross-tool chain,
starting from the ttylinux directory:
% cd cross-tools-X.X # where X.X completes the actual directory name
% make setup
% make dload
% make i486 # use "TIMECMD=time make i486" for timing statistics
% cd ..
The "make setup" command prepares cross-tools for building tool chains. The
"make dload" command will download the needed source code packages; over 100 MB
will be downloaded, be patient. These two commands do not need to be repeated
for building more cross tool chains.
The "make i486" command will build an i486 cross-compiler tool chain. This
process takes at least 40 minutes on a dual 2.1 GH Athlon system. You can
"make x86_64" for about another 40 minutes of fun.
After making the i486 tool chain, change directory to _scripts and run the test
script as root. The test script creates small C and C++ programs, cross-builds
them with the i486 tool chain, executes them in the proper environment and
checks to see they generate correct output:
% cd cross-tools-X.X # where X.X completes the actual directory name
% cd _scripts
% su root
% ./test-i486.sh
% exit # leave root su
% cd ../..
There is a user guide for cross-tools, you should read it if you want to
understand more about cross-tool building.
Try "make help" in the cross-tools directory.
cross-tools is known to build i486 tool chains on these systems:
=> Linux 2.6.21.5 SMP PREEMPT i686 athlon-4 i386 GNU/Linux (primary dev system)
=> CentOS release 5.3 i686 i686 i386 GNU/Linux, Dual 333 Mhz Pentium II
=> Fedora release 10 x86_64 x86_64 x86_64 GNU/Linux, ThinkPad W500 intel P8600
cross-tools is known to build these cross-compiling tool chains for successfully
building ttylinux on both i386 Linux (IA32 32-bit Linux systems) and x86_64
Linux (x86_64 64-bit Linux systems):
=> i486
=> i686
=> x86_64
If you have trouble building one of these cross tool chains, use the
MinimaLinux forum, , and we'll try to help.
=================
5. Build ttylinux
=================
You need to be root, uid and gid both need to be 0.
In the ttylinux directory, try "make help".
There are two shell script files in the ttylinux directory, neither one needs
to be changed.
ttylinux.dist-config.sh
ttylinux.site-config.sh
The "ttylinux.site-config.sh" needs no changes.
Now give these make commands:
% make clean
% make init
% make pkgs
% make loader
% make fsys
% make kernel
% make bootcd
or just try:
% make dist
NOTE About True Cross-building With cross-tools
GLIBC is built with, and is a part of, cross-tools; it is configure with
"--enable-kernel=2.6.0" and built against the Linux kernel headers files
used by the cross-tool chain. All other ttylinux packages are cross-built
against this GLIBC and its Linux kernel header files. Please, don't use a
Linux kernel with ttylinux that is older than the cross-tool Linux kernel
headers, or your nose will fall off and you'll get a bunch of pimples.
General packages are built by the "make pkgs" command. The list of ttylinux
packages is in the file "config/packages.txt"; this file also has the URL for
each package from which the package comes.
===========================
6. Build Individual Package
===========================
An individual package, whether it is in the package list or not, can be built;
the following example builds the bash package.
% make PACKAGE="bash-3.2" bash-3.2
This command can be performed anytime after "make init"; any previous build of
the package is overwritten. This is handy when developing and modifying
individual packages, particularly those that are not in the package list.
===================
7. User Application
===================
There is an example User App that can be built anytime after "make init"; if it
is built before "make fsys" it will be in the bootable image. This User App is
an example package, currently incomplete, for using ttylinux in an embedded
system or any system that has a main directed purpose. The User App is built
by the following command.
% make PACKAGE="userapp-1.0" userapp-1.0
================
8. Build Results
================
Packages
--------
Package build results are in the pkg-bin/ directory. All packages in this
directory are put into the ttylinux file system and bootable image.
Images
------
The build results are in the img directory; there are a file system image and
a boot CD-ROM ISO image.
build-root
----------
There is a build-root directory containing the entire build; the packages are
constructed by taking some of the files from the build-root. Usually most
files are used, but in the case of GLIBC there are many files not used in the
package, the internationalization, i18n, and localization, l10n, files.
The build can be interactively evaluated by executing the following command if
the ttylinux build is of the same architecture as the build host e.g., you are
building ttylinux on a typical 32-bit or multilib x86 Linux system and build
the i486 ttylinux:
% . ttylinux-chroot.sh
The above command sets your top-level root directory to be the ttylinunx
build-root, so you are still running your build system's kernel but using the
ttylinux build as the root directory.
Bootable CD-ROM
----------------
You can burn the boot CD-ROM ISO image to a CD-ROM and boot it.
Bootable USB Disk
-----------------
The config/isolinux directory contains the CD-ROM mastering image source files,
include Linux kernel and file system image. There is a shell script that can
be used to make USB disk bootable with ttylinux. The shell script is in the
build-root/sbin/ directory; it is "ttylinux-flash". This shell script is in
the ttylinux file system, so ttylinux itself is capable of making a USB disk
bootable with ttylinux. Either lilo or syslinux can be used as the boot loader
on the USB disk; the script options used to indicate lilo and syslinux are "-l",
"--lilo", "-s" and "--syslinux".
Example:
On your host system, if you have a USB disk mounted at /mnt/flash on device
/dev/sda1, then try one of the following command.
% build-root/sbin/ttylinux-flash --lilo config/cdrom /mnt/flash /dev/sda
% build-root/sbin/ttylinux-flash -s config/cdrom /mnt/flash /dev/sda
Example:
From a CD-ROM-booted ttylinux system, if you have a USB disk mounted at
/mnt/flash on device /dev/sda1 and the CD-ROM mounted on /mnt/cdrom, then
try one of the following command.
% ttylinux-flash -l /mnt/cdrom /mnt/flash /dev/sda
% ttylinux-flash --syslinux /mnt/cdrom /mnt/flash /dev/sda
=======================
9. Bug Reports and Help
=======================
It is a goal to support building ttylinux on any normal Linux x86 distribution.Reporting bugs in cross-tools, ttylinux and their documents is appreciated.
Douglas Jerome <>
There is a web-based forum that is active from time to time; it is active on date this was written, 2008-11-28, and is intended to be active as long as minimalinux is supporting ttylinux, barring spammer abuse.
Help may be available on irc, which is very low bandwith and seemingly more appropriate for inane banter that sometimes is fun.
irc.freenode.net #ttylinux
[eof]
