The CLFS team would like to acknowledge people who have assisted in making the book what it is today.

Our Leaders:

Our CLFS Team:

Outside the Development Team

The CLFS team would also like to acknowledge contributions of people from clfs-dev@lists.cross-lfs.org and associated mailing lists who have provided valuable technical and editorial corrections while testing the Cross-LFS book.

The Linux From Scratch Project

Thank you all for your support.

The CLFS system will be built by using a previously installed Unix system or Linux distribution (such as Debian, Fedora, Mandriva, SUSE, or Ubuntu). This existing system (the host) will be used as a starting point to provide necessary programs, including a compiler, linker, and shell, to build the new system. Select the “development” option during the distribution installation to be able to access these tools.

As an alternative to installing an entire separate distribution onto your machine, you may wish to use a livecd. Most distributions provide a livecd, which provides an environment to which you can add the required tools onto, allowing you to successfully follow the instructions in this book. Remember that if you reboot the livecd you will need to reconfigure the host environment before continuing with your build.

Preparing a New Partition of this book describes how to create a new Linux native partition and file system, the place where the new CLFS system will be compiled and installed. Packages and Patches explains which packages and patches need to be downloaded to build a CLFS system and how to store them on the new file system. Final Preparations discusses the setup for an appropriate working environment. Please read Final Preparations carefully as it explains several important issues the developer should be aware of before beginning to work through Constructing Cross-Compile Tools and beyond.

Constructing Cross-Compile Tools explains the installation of cross-compile tools which will be built on the host but be able to compile programs that run on the target machine. These cross-compile tools will be used to create a temporary, minimal system that will be the basis for building the final CLFS system. Some of these packages are needed to resolve circular dependencies—for example, to compile a compiler, you need a compiler.

The process of building cross-compile tools first involves building and installing all the necessary tools to create a build system for the target machine. With these cross-compiled tools, we eliminate any dependencies on the toolchain from our host distro.

After we build our “Cross-Tools”, we start building a very minimal working system in /tools. This minimal system will be built using the cross-toolchain in /cross-tools.

In Installing Basic System Software, the full CLFS system is built. Depending on the system you are cross-compiling for, you will either boot the minimal temp-system on the target machine, or chroot into it.

The chroot (change root) program is used to enter a virtual environment and start a new shell whose root directory will be set to the CLFS partition. This is very similar to rebooting and instructing the kernel to mount the CLFS partition as the root partition. The major advantage is that “chrooting” allows the builder to continue using the host while CLFS is being built. While waiting for package compilation to complete, a user can switch to a different virtual console (VC) or X desktop and continue using the computer as normal.

Some systems cannot be built by chrooting so they must be booted instead. Generally, if you building for a different arch than the host system, you must reboot because the kernel will likely not support the target machine. Booting involves installing a few additional packages that are needed for bootup, installing bootscripts, and building a miminal kernel. We also describe some alternative booting methods in Section 7.18, “What to do next”

To finish the installation, the CLFS-Bootscripts are set up in Setting Up System Bootscripts, and the kernel and boot loader are set up in Making the CLFS System Bootable. The End contains information on furthering the CLFS experience beyond this book. After the steps in this book have been implemented, the computer will be ready to reboot into the new CLFS system.

This is the process in a nutshell. Detailed information on each step is discussed in the following chapters and package descriptions. Items that may seem complicated will be clarified, and everything will fall into place as the reader embarks on the CLFS adventure.

This is version 2.1.0 of the Cross-Compiled Linux From Scratch book, dated October 06, 2013. If this book is more than six months old, a newer and better version is probably already available. To find out, please check one of the mirrors via http://trac.cross-lfs.org/.

Below is a list of detailed changes made since the previous release of the book.

Below is a list of changes specifics for this architecture made since the previous release of the book. For general changes see Master Changelog,

If an issue or a question is encountered while working through this book, check the FAQ page at http://trac.cross-lfs.org/wiki/faq#generalfaq. Questions are often already answered there. If your question is not answered on this page, try to find the source of the problem. The following hint will give you some guidance for troubleshooting: http://hints.cross-lfs.org/index.php/Errors.

We also have a wonderful CLFS community that is willing to offer assistance through the mailing lists and IRC (see the Section 1.5, “Resources” section of this book). However, we get several support questions everyday and many of them can be easily answered by going to the FAQ and by searching the mailing lists first. So for us to offer the best assistance possible, you need to do some research on your own first. This allows us to focus on the more unusual support needs. If your searches do not produce a solution, please include all relevant information (mentioned below) in your request for help.

gcc -DALIASPATH=\"/mnt/clfs/usr/share/locale:.\"
-DLOCALEDIR=\"/mnt/clfs/usr/share/locale\"
-DLIBDIR=\"/mnt/clfs/usr/lib\"
-DINCLUDEDIR=\"/mnt/clfs/usr/include\" -DHAVE_CONFIG_H -I. -I.
-g -O2 -c getopt1.c
gcc -g -O2 -static -o make ar.o arscan.o commands.o dir.o
expand.o file.o function.o getopt.o implicit.o job.o main.o
misc.o read.o remake.o rule.o signame.o variable.o vpath.o
default.o remote-stub.o version.o opt1.o
-lutil job.o: In function `load_too_high':
/clfs/tmp/make-3.79.1/job.c:1565: undefined reference
to `getloadavg'
collect2: ld returned 1 exit status
make[2]: *** [make] Error 1
make[2]: Leaving directory `/clfs/tmp/make-3.79.1'
make[1]: *** [all-recursive] Error 1
make[1]: Leaving directory `/clfs/tmp/make-3.79.1'
make: *** [all-recursive-am] Error 2

make [2]: *** [make] Error 1

In this chapter, the partition which will host the CLFS system is prepared. We will create the partition itself, create a file system on it, and mount it.

Like most other operating systems, CLFS is usually installed on a dedicated partition. The recommended approach to building a CLFS system is to use an available empty partition or, if you have enough unpartitioned space, to create one. However, if you're building for a different architecture you can simply build everything in “/mnt/clfs” and transfer it to your target machine.

A minimal system requires around 6 gigabytes (GB). This is enough to store all the source tarballs and compile the packages. The CLFS system itself will not take up this much room. A large portion of this requirement is to provide sufficient free temporary storage. Compiling packages can require a lot of disk space which will be reclaimed after the package is installed. If the CLFS system is intended to be the primary Linux system, additional software will probably be installed which will require additional space (2-10 GB).

Because there is not always enough Random Access Memory (RAM) available for compilation processes, it is a good idea to use a small disk partition as swap space. This is used by the kernel to store seldom-used data and leave more memory available for active processes. The swap partition for an CLFS system can be the same as the one used by the host system, in which case it is not necessary to create another one.

Start a disk partitioning program such as cfdisk or fdisk with a command line option naming the hard disk on which the new partition will be created—for example /dev/hda for the primary Integrated Drive Electronics (IDE) disk. Create a Linux native partition and a swap partition, if needed. Please refer to cfdisk(8) or fdisk(8) if you do not yet know how to use the programs.

Remember the designation of the new partition (e.g., hda5). This book will refer to this as the CLFS partition. Also remember the designation of the swap partition. These names will be needed later for the /etc/fstab file.

Now that a blank partition has been set up, the file system can be created. The most widely-used system in the Linux world is the second extended file system (ext2), but with newer high-capacity hard disks, journaling file systems are becoming increasingly popular. We will create an ext2 file system. Instructions for other file systems can be found at http://cblfs.cross-lfs.org/index.php?section=6#File_System.

To create an ext2 file system on the CLFS partition, run the following:

mke2fs /dev/[xxx]

Replace [xxx] with the name of the CLFS partition (hda5 in our previous example).

debugfs -R feature /dev/[xxx]

cd /tmp
tar xjf /path/to/sources/e2fsprogs-1.42.8.tar.bz2
cd e2fsprogs-1.42.8
mkdir build
cd build
../configure
make #note that we intentionally don't 'make install' here!
./misc/mke2fs /dev/[xxx]
cd /tmp
rm -rf e2fsprogs-1.42.8

If a swap partition was created, it will need to be initialized for use by issuing the command below. If you are using an existing swap partition, there is no need to format it.

mkswap /dev/[yyy]

Replace [yyy] with the name of the swap partition.

Now that a file system has been created, the partition needs to be made accessible. In order to do this, the partition needs to be mounted at a chosen mount point. For the purposes of this book, it is assumed that the file system is mounted under /mnt/clfs, but the directory choice is up to you.

Choose a mount point and assign it to the CLFS environment variable by running:

export CLFS=/mnt/clfs

Next, create the mount point and mount the CLFS file system by running:

mkdir -pv ${CLFS}
mount -v /dev/[xxx] ${CLFS}

Replace [xxx] with the designation of the CLFS partition.

If using multiple partitions for CLFS (e.g., one for / and another for /usr), mount them using:

mkdir -pv ${CLFS}
mount -v /dev/[xxx] ${CLFS}
mkdir -v ${CLFS}/usr
mount -v /dev/[yyy] ${CLFS}/usr

Replace [xxx] and [yyy] with the appropriate partition names.

Ensure that this new partition is not mounted with permissions that are too restrictive (such as the nosuid, nodev, or noatime options). Run the mount command without any parameters to see what options are set for the mounted CLFS partition. If nosuid, nodev, and/or noatime are set, the partition will need to be remounted.

Now that there is an established place to work, it is time to download the packages.

This chapter includes a list of packages that need to be downloaded for building a basic Linux system. The listed version numbers correspond to versions of the software that are known to work, and this book is based on their use. We highly recommend not using newer versions because the build commands for one version may not work with a newer version. The newest package versions may also have problems that require work-arounds. These work-arounds will be developed and stabilized in the development version of the book.

Download locations may not always be accessible. If a download location has changed since this book was published, Google (http://www.google.com/) provides a useful search engine for most packages. If this search is unsuccessful, try one of the alternative means of downloading discussed at http://cross-lfs.org/files/packages/git/.

Create a directory called ${CLFS}/sources and use it to store your sources and patches. All packages should be compiled there as well. Using any other location for compiling may have unexpected results.

To create this directory, execute, as user root, the following command before starting the download session:

mkdir -v ${CLFS}/sources

Make this directory writable and sticky. When a directory is marked “sticky”, that means that even if multiple users have write permission on that directory, any file within that directory can only be deleted or modified by its owner. The following command will enable the write and sticky modes:

chmod -v a+wt ${CLFS}/sources

You can download all needed packages and patches into this directory either by using the links on the following pages in this section, or by passing the download list to wget:

wget -i dl.list -P ${CLFS}/sources

Verification of downloaded packages can be done by downloading the following MD5 or SHA1 checksum lists:

MD5SUMS:

pushd ${CLFS}/sources
md5sum -c MD5SUMS
popd

SHA1SUMS:

pushd ${CLFS}/sources
md5sum -c SHA1SUMS 
popd

Download or otherwise obtain the following packages:

Total size of these packages: about 312 MB

Total size of these packages: about 5 MB

In addition to the packages, several patches are also required. These patches correct any mistakes in the packages that should be fixed by the maintainer. The patches also make small modifications to make the packages easier to work with. The following patches will be needed to build a CLFS system:

Total size of these patches: about 23 MB

In addition to the above required patches, there exist a number of optional patches created by the CLFS community. These optional patches solve minor problems or enable functionality that is not enabled by default. Feel free to peruse the patches database located at http://patches.cross-lfs.org/2.1.0/ and acquire any additional patches to suit the system needs.

Total size of these patches: about 20 KB

Throughout this book, the environment variable CLFS will be used several times. It is paramount that this variable is always defined. It should be set to the mount point chosen for the CLFS partition. Check that the CLFS variable is set up properly with:

echo ${CLFS}

Make sure the output shows the path to the CLFS partition's mount point, which is /mnt/clfs if the provided example was followed. If the output is incorrect, the variable can be set with:

export CLFS=/mnt/clfs

Having this variable set is beneficial in that commands such as install -dv ${CLFS}/tools can be typed literally. The shell will automatically replace “${CLFS}” with “/mnt/clfs” (or whatever the variable was set to) when it processes the command line.

If you haven't created the ${CLFS} directory, do so at this time by issuing the following commands:

install -dv ${CLFS}

Do not forget to check that ${CLFS} is set whenever you leave and reenter the current working environment (as when doing a “su” to root or another user).

All programs compiled in Constructing a Temporary System will be installed under ${CLFS}/tools to keep them separate from the programs compiled in Installing Basic System Software. The programs compiled here are temporary tools and will not be a part of the final CLFS system. By keeping these programs in a separate directory, they can easily be discarded later after their use. This also prevents these programs from ending up in the host production directories (easy to do by accident in Constructing a Temporary System).

Create the required directory by running the following as root:

install -dv ${CLFS}/tools

The next step is to create a /tools symlink on the host system. This will point to the newly-created directory on the CLFS partition. Run this command as root as well:

ln -sv ${CLFS}/tools /

The created symlink enables the toolchain to be compiled so that it always refers to /tools, meaning that the compiler, assembler, and linker will work. This will provide a common place for our temporary tools system.

The cross-binutils and cross-compiler built in Constructing Cross-Compile Tools will be installed under ${CLFS}/cross-tools to keep them separate from the host programs. The programs compiled here are cross-tools and will not be a part of the final CLFS system or the temp-system. By keeping these programs in a separate directory, they can easily be discarded later after their use.

Create the required directory by running the following as root:

install -dv ${CLFS}/cross-tools

The next step is to create a /cross-tools symlink on the host system. This will point to the newly-created directory on the CLFS partition. Run this command as root as well:

ln -sv ${CLFS}/cross-tools /

The symlink isn't technically necessary (though the book's instructions do assume its existence), but is there mainly for consistency (because /tools is also symlinked to ${CLFS}/tools) and to simplify the installation of the cross-compile tools.

When logged in as user root, making a single mistake can damage or destroy a system. Therefore, we recommend building the packages as an unprivileged user. You could use your own user name, but to make it easier to set up a clean work environment, create a new user called clfs as a member of a new group (also named clfs) and use this user during the installation process. As root, issue the following commands to add the new user:

groupadd clfs
useradd -s /bin/bash -g clfs -d /home/clfs clfs
mkdir -pv /home/clfs
chown -v clfs:clfs /home/clfs

To log in as clfs (as opposed to switching to user clfs when logged in as root, which does not require the clfs user to have a password), give clfs a password:

passwd clfs

Grant clfs full access to ${CLFS}/cross-tools and ${CLFS}/tools by making clfs the directorys' owner:

chown -v clfs ${CLFS}/tools
chown -v clfs ${CLFS}/cross-tools

If a separate working directory was created as suggested, give user clfs ownership of this directory:

chown -v clfs ${CLFS}/sources

Next, login as user clfs. This can be done via a virtual console, through a display manager, or with the following substitute user command:

su - clfs

The “-” instructs su to start a login shell as opposed to a non-login shell. The difference between these two types of shells can be found in detail in bash(1) and info bash.

Set up a good working environment by creating two new startup files for the bash shell. While logged in as user clfs, issue the following command to create a new .bash_profile:

cat > ~/.bash_profile << "EOF"
exec env -i HOME=${HOME} TERM=${TERM} PS1='\u:\w\$ ' /bin/bash
EOF

When logged on as user clfs, the initial shell is usually a login shell which reads the /etc/profile of the host (probably containing some settings and environment variables) and then .bash_profile. The exec env -i.../bin/bash command in the .bash_profile file replaces the running shell with a new one with a completely empty environment, except for the HOME, TERM, and PS1 variables. This ensures that no unwanted and potentially hazardous environment variables from the host system leak into the build environment. The technique used here achieves the goal of ensuring a clean environment.

The new instance of the shell is a non-login shell, which does not read the /etc/profile or .bash_profile files, but rather reads the .bashrc file instead. Create the .bashrc file now:

cat > ~/.bashrc << "EOF"
set +h
umask 022
CLFS=/mnt/clfs
LC_ALL=POSIX
PATH=/cross-tools/bin:/bin:/usr/bin
export CLFS LC_ALL PATH
EOF

The set +h command turns off bash's hash function. Hashing is ordinarily a useful feature—bash uses a hash table to remember the full path of executable files to avoid searching the PATH time and again to find the same executable. However, the new tools should be used as soon as they are installed. By switching off the hash function, the shell will always search the PATH when a program is to be run. As such, the shell will find the newly compiled tools in /cross-tools as soon as they are available without remembering a previous version of the same program in a different location.

Setting the user file-creation mask (umask) to 022 ensures that newly created files and directories are only writable by their owner, but are readable and executable by anyone (assuming default modes are used by the open(2) system call, new files will end up with permission mode 644 and directories with mode 755).

The CLFS variable should be set to the chosen mount point.

The LC_ALL variable controls the localization of certain programs, making their messages follow the conventions of a specified country. If the host system uses a version of Glibc older than 2.2.4, having LC_ALL set to something other than “POSIX” or “C” (during this chapter) may cause issues if you exit the chroot environment and wish to return later. Setting LC_ALL to “POSIX” or “C” (the two are equivalent) ensures that everything will work as expected in the chroot environment.

By putting /cross-tools/bin at the beginning of the PATH, the cross-compiler built in Constructing Cross-Compile Tools will be picked up by the build process for the temp-system packages before anything that may be installed on the host. This, combined with turning off hashing, helps to ensure that you will be using the cross-compile tools to build the temp-system in /tools.

Finally, to have the environment fully prepared for building the temporary tools, source the just-created user profile:

source ~/.bash_profile

Most packages provide a test suite. Running the test suite for a newly built package is a good idea because it can provide a “sanity check” indicating that everything compiled correctly. A test suite that passes its set of checks usually proves that the package is functioning as the developer intended. It does not, however, guarantee that the package is totally bug free.

It is not possible to run testsuites when cross-compiling, so package installation instructions do not explain how to run testsuites until Installing Basic System Software.

This chapter shows you how to create cross platform tools.

If for some reason you have to stop and come back later, remember to use the su - clfs command, and it will setup the build environment that you left.

CFLAGS and CXXFLAGS must not be set during the building of cross-tools.

To disable CFLAGS and CXXFLAGS use the following commands:

unset CFLAGS
unset CXXFLAGS

Now add these to ~/.bashrc, just in case you have to exit and restart building later:

echo unset CFLAGS >> ~/.bashrc
echo unset CXXFLAGS >> ~/.bashrc

Setting Host and Target

During the building of the cross-compile tools you will need to set a few variables that will be dependent on your particular needs. The first variable will be the triplet of the host machine, which will be put into the CLFS_HOST variable. To account for the possibility that the host and target are the same arch, as cross-compiling won't work when host and target are the same, part of the triplet needs to be changed slightly to add "cross". Set CLFS_HOST using the following command:

export CLFS_HOST=$(echo ${MACHTYPE} | sed -e 's/-[^-]*/-cross/')

Now you will need to set the triplet for the target architecture. Set the target variable using the following command:

export CLFS_TARGET="[target triplet]"

Replace [target triplet] with the appropriate machine triplet using the table at the bottom of the page.

Copy settings to the Environment

Now add these to ~/.bashrc, just in case you have to exit and restart building later:

cat >> ~/.bashrc << EOF
export CLFS_HOST="${CLFS_HOST}"
export CLFS_TARGET="${CLFS_TARGET}"
EOF

This chapter shows how to compile and install a minimal Linux system. This system will contain just enough tools to start constructing the final CLFS system in Installing Basic System Software and allow a working environment with more user convenience than a minimum environment would.

The tools in this chapter are cross-compiled using the toolchain in /cross-tools and will be installed under the ${CLFS}/tools directory to keep them separate from the files installed in Installing Basic System Software and the host production directories. Since the packages compiled here are temporary, we do not want them to pollute the soon-to-be CLFS system.

Check one last time that the CLFS environment variable is set up properly:

echo ${CLFS}

Make sure the output shows the path to the CLFS partition's mount point, which is /mnt/clfs, using our example.

During this section of the build you will see several WARNING messages like the one below. It is safe to ignore these messages.

configure: WARNING: If you wanted to set the --build type, don't use --host.
    If a cross compiler is detected then cross compile mode will be used.

Setup target-specific variables for the compiler and linkers:

export CC="${CLFS_TARGET}-gcc"
export CXX="${CLFS_TARGET}-g++"
export AR="${CLFS_TARGET}-ar"
export AS="${CLFS_TARGET}-as"
export RANLIB="${CLFS_TARGET}-ranlib"
export LD="${CLFS_TARGET}-ld"
export STRIP="${CLFS_TARGET}-strip"

Then add the build variables to ~/.bashrc to prevent issues if you stop and come back later:

echo export CC=\""${CC}\"" >> ~/.bashrc
echo export CXX=\""${CXX}\"" >> ~/.bashrc
echo export AR=\""${AR}\"" >> ~/.bashrc
echo export AS=\""${AS}\"" >> ~/.bashrc
echo export RANLIB=\""${RANLIB}\"" >> ~/.bashrc
echo export LD=\""${LD}\"" >> ~/.bashrc
echo export STRIP=\""${STRIP}\"" >> ~/.bashrc

There are two different ways you can proceed from this point to build the final system. You can build a kernel, a bootloader, and a few other utilities, boot into the temporary system, and build the rest there. Alternatively, you can chroot into the temporary system.

The boot method is needed when you are building on a different architecture. For example, if you are building a PowerPC system from an x86, you can't chroot. The chroot method is for when you are building on the same architecture. If you are building on, and for, an x86 system, you can simply chroot. The rule of thumb here is if the architectures match and you are running the same series kernel you can just chroot. If you aren't running the same series kernel, or are wanting to run a different ABI, you will need to use the boot option.

If you are in any doubt about this, you can try the following commands to see if you can chroot:

/tools/lib/libc.so.6
/tools/bin/gcc -v

If either of these commands fail, you will have to follow the boot method.

To chroot, you will also need a Linux Kernel-2.6.32 or greater (having been compiled with GCC-4.1.2 or greater). The reason for the kernel version requirement is that eglibc is built to generate the library for the smallest version of the Linux kernel expected to be supported.

To check your kernel version, run cat /proc/version - if it does not say that you are running a 2.6.32 or later Linux kernel, compiled with GCC 4.1.2 or later, you cannot chroot.

For the boot method, follow If You Are Going to Boot.

For the chroot method, follow If You Are Going to Chroot.

This chapter shows how to complete the build of temporary tools to create a minimal system that will be used to boot the target machine and to build the final system packages.

There are a few additional packages that will need to be installed to allow you to boot the minimal system. Some of these packages will be installed onto root or in /usr on the CLFS partition (${CLFS}/bin, ${CLFS}/usr/bin, etc...), rather than /tools, using the "DESTDIR" option with make. This will require the clfs user to have write access to the rest of the CLFS partition, so you will need to temporarily change the ownership of ${CLFS} to the clfs user. Run the following command as root:

chown -v clfs ${CLFS}

It is time to create some structure in the CLFS file system. Create a standard directory tree by issuing the following commands:

mkdir -pv ${CLFS}/{bin,boot,dev,{etc/,}opt,home,lib,mnt}
mkdir -pv ${CLFS}/{proc,media/{floppy,cdrom},run/{,shm},sbin,srv,sys}
mkdir -pv ${CLFS}/var/{lock,log,mail,spool}
mkdir -pv ${CLFS}/var/{opt,cache,lib/{misc,locate},local}
install -dv -m 0750 ${CLFS}/root
install -dv -m 1777 ${CLFS}{/var,}/tmp
mkdir -pv ${CLFS}/usr/{,local/}{bin,include,lib,sbin,src}
mkdir -pv ${CLFS}/usr/{,local/}share/{doc,info,locale,man}
mkdir -pv ${CLFS}/usr/{,local/}share/{misc,terminfo,zoneinfo}
mkdir -pv ${CLFS}/usr/{,local/}share/man/man{1,2,3,4,5,6,7,8}
for dir in ${CLFS}/usr{,/local}; do
  ln -sv share/{man,doc,info} $dir
done

Directories are, by default, created with permission mode 755, but this is not desirable for all directories. In the commands above, two changes are made—one to the home directory of user root, and another to the directories for temporary files.

The first mode change ensures that not just anybody can enter the /root directory—the same as a normal user would do with his or her home directory. The second mode change makes sure that any user can write to the /tmp and /var/tmp directories, but cannot remove another user's files from them. The latter is prohibited by the so-called “sticky bit,” the highest bit (1) in the 1777 bit mask.

Some programs use hard-wired paths to programs which do not exist yet. In order to satisfy these programs, create a number of symbolic links which will be replaced by real files throughout the course of the next chapter after the software has been installed.

ln -sv /tools/bin/{bash,cat,echo,grep,login,passwd,pwd,sleep,stty} ${CLFS}/bin
ln -sv /tools/sbin/{agetty,blkid} ${CLFS}/sbin
ln -sv /tools/bin/file ${CLFS}/usr/bin
ln -sv /tools/lib/libgcc_s.so{,.1} ${CLFS}/usr/lib
ln -sv /tools/lib/libstd*so* ${CLFS}/usr/lib
ln -sv bash ${CLFS}/bin/sh
ln -sv /run ${CLFS}/var/run

In order for user root to be able to login and for the name “root” to be recognized, there must be relevant entries in the /etc/passwd and /etc/group files.

Create the ${CLFS}/etc/passwd file by running the following command:

cat > ${CLFS}/etc/passwd << "EOF"
root::0:0:root:/root:/bin/bash
EOF

The actual password for root (the “::” used here is just a placeholder and allows you to login with no password) will be set later.

Create the ${CLFS}/etc/group file by running the following command:

cat > ${CLFS}/etc/group << "EOF"
root:x:0:
bin:x:1:
sys:x:2:
kmem:x:3:
tty:x:5:
tape:x:4:
daemon:x:6:
floppy:x:7:
disk:x:8:
lp:x:9:
dialout:x:10:
audio:x:11:
video:x:12:
utmp:x:13:
usb:x:14:
cdrom:x:15:
EOF

The created groups are not part of any standard—they are groups decided on in part by the requirements of the Eudev configuration in the final system, and in part by common convention employed by a number of existing Linux distributions. The Linux Standard Base (LSB, available at http://www.linuxbase.org) recommends only that, besides the group “root” with a Group ID (GID) of 0, a group “bin” with a GID of 1 be present. All other group names and GIDs can be chosen freely by the system administrator since well-written programs do not depend on GID numbers, but rather use the group's name.

The login, agetty, and init programs (and others) use a number of log files to record information such as who was logged into the system and when. However, these programs will not write to the log files if they do not already exist. Initialize the log files and give them proper permissions:

touch ${CLFS}/var/run/utmp ${CLFS}/var/log/{btmp,lastlog,wtmp}
chmod -v 664 ${CLFS}/var/run/utmp ${CLFS}/var/log/lastlog
chmod -v 600 ${CLFS}/var/log/btmp

The /var/run/utmp file records the users that are currently logged in. The /var/log/wtmp file records all logins and logouts. The /var/log/lastlog file records when each user last logged in. The /var/log/btmp file records the bad login attempts.

The new instance of the shell that will start when the system is booted is a login shell, which will read .bash_profile file. Create the .bash_profile file now:

cat > ${CLFS}/root/.bash_profile << "EOF"
set +h
PS1='\u:\w\$ '
LC_ALL=POSIX
PATH=/bin:/usr/bin:/sbin:/usr/sbin:/tools/bin:/tools/sbin
export LC_ALL PATH PS1
EOF

The LC_ALL variable controls the localization of certain programs, making their messages follow the conventions of a specified country. Setting LC_ALL to “POSIX” or “C” (the two are equivalent) ensures that everything will work as expected on your temporary system.

By putting /tools/bin and /tools/sbin at the end of the standard PATH, all the programs installed in Constructing a Temporary System are only picked up by the shell if they have not yet been built on the target system. This configuration forces use of the final system binaries as they are built over the temp-system, minimising the chance of final system programs being built against the temp-system.

The /etc/fstab file is used by some programs to determine where file systems are to be mounted by default, which must be checked, and in which order. Create a new file systems table like this:

cat > ${CLFS}/etc/fstab << "EOF"
# Begin /etc/fstab

# file system  mount-point  type   options          dump  fsck
#                                                         order

/dev/[xxx]     /            [fff]  defaults         1     1
/dev/[yyy]     swap         swap   pri=1            0     0
proc           /proc        proc   defaults         0     0
sysfs          /sys         sysfs  defaults         0     0
devpts         /dev/pts     devpts gid=5,mode=620   0     0
shm            /dev/shm     tmpfs  defaults         0     0
tmpfs          /run         tmpfs  defaults         0     0
devtmpfs       /dev         devtmpfs mode=0755,nosuid 0     0

# End /etc/fstab
EOF

Replace [xxx], [yyy], and [fff] with the values appropriate for the system, for example, hda2, hda5, and ext2. For details on the six fields in this file, see man 5 fstab.

The /dev/shm mount point for tmpfs is included to allow enabling POSIX-shared memory. The kernel must have the required support built into it for this to work (more about this is in the next section). Please note that very little software currently uses POSIX-shared memory. Therefore, consider the /dev/shm mount point optional. For more information, see Documentation/filesystems/tmpfs.txt in the kernel source tree.

Currently, the ${CLFS} directory and all of its subdirectories are owned by the user clfs, a user that exists only on the host system. For security reasons, the ${CLFS} root directory and all of its subdirectories should be owned by root. Change the ownership for ${CLFS} and its subdirectories by running this command:

chown -Rv 0:0 ${CLFS}

The following files are to be owned by the group utmp not by root.

chgrp -v 13 ${CLFS}/var/run/utmp ${CLFS}/var/log/lastlog

Now you're at the point to get your ${CLFS} directory copied over to your target machine. The easiest method would be to tar it up and copy the file.

tar -jcvf ${CLFS}.tar.bz2 ${CLFS}

This chapter shows how to prepare a chroot jail to build the final system packages into.

Various file systems exported by the kernel are used to communicate to and from the kernel itself. These file systems are virtual in that no disk space is used for them. The content of the file systems resides in memory.

Begin by creating directories onto which the file systems will be mounted:

mkdir -pv ${CLFS}/{dev,proc,sys}

Now mount the file systems:

mount -vt proc proc ${CLFS}/proc
mount -vt sysfs sysfs ${CLFS}/sys

Remember that if for any reason you stop working on the CLFS system and start again later, it is important to check that these file systems are mounted again before entering the chroot environment.

Two device nodes, /dev/console and /dev/null, are required to be present on the filesystem. These are needed by the kernel even before starting Eudev early in the boot process, so we create them here:

mknod -m 600 ${CLFS}/dev/console c 5 1
mknod -m 666 ${CLFS}/dev/null c 1 3

Once the system is complete and booting, the rest of our device nodes are created by the Eudev package. Since this package is not available to us right now, we must take other steps to provide device nodes under on the CLFS filesystem. We will use the “bind” option in the mount command to make our host system's /dev structure appear in the new CLFS filesystem:

mount -v -o bind /dev ${CLFS}/dev

Additional file systems will soon be mounted from within the chroot environment. To keep the host up to date, perform a “fake mount” for each of these now:

if [ -h ${CLFS}/dev/shm ]; then
  link=$(readlink ${CLFS}/dev/shm)
  mkdir -p ${CLFS}/$link
  mount -f -vt tmpfs shm ${CLFS}/$link
  unset link
else
  mount -f -vt tmpfs shm ${CLFS}/dev/shm
fi
mount -f -vt devpts -o gid=5,mode=620 devpts ${CLFS}/dev/pts

It is time to enter the chroot environment to begin building and installing the final CLFS system. As user root, run the following command to enter the realm that is, at the moment, populated with only the temporary tools:

chroot "${CLFS}" /tools/bin/env -i \
    HOME=/root TERM="${TERM}" PS1='\u:\w\$ ' \
    PATH=/bin:/usr/bin:/sbin:/usr/sbin:/tools/bin \
    /tools/bin/bash --login +h

The -i option given to the env command will clear all variables of the chroot environment. After that, only the HOME, TERM, PS1, and PATH variables are set again. The TERM=${TERM} construct will set the TERM variable inside chroot to the same value as outside chroot. This variable is needed for programs like vim and less to operate properly. If other variables are needed, such as CFLAGS or CXXFLAGS, this is a good place to set them again.

From this point on, there is no need to use the CLFS variable anymore, because all work will be restricted to the CLFS file system. This is because the Bash shell is told that ${CLFS} is now the root (/) directory.

Notice that /tools/bin comes last in the PATH. This means that a temporary tool will no longer be used once its final version is installed. This occurs when the shell does not “remember” the locations of executed binaries—for this reason, hashing is switched off by passing the +h option to bash.

It is important that all the commands throughout the remainder of this chapter and the following chapters are run from within the chroot environment. If you leave this environment for any reason (rebooting for example), remember to first mount the proc and devpts file systems (discussed in the previous section) and enter chroot again before continuing with the installations.

Note that the bash prompt will say I have no name! This is normal because the /etc/passwd file has not been created yet.

Currently, the /tools and /cross-tools directories are owned by the user clfs, a user that exists only on the host system. Although the /tools and /cross-tools directories can be deleted once the CLFS system has been finished, they can be retained to build additional CLFS systems. If the /tools and /cross-tools directories are kept as is, the files are owned by a user ID without a corresponding account. This is dangerous because a user account created later could get this same user ID and would own the /tools directory and all the files therein, thus exposing these files to possible malicious manipulation.

To avoid this issue, add the clfs user to the new CLFS system later when creating the /etc/passwd file, taking care to assign it the same user and group IDs as on the host system. Alternatively, assign the contents of the /tools and /cross-tools directories to user root by running the following commands:

chown -Rv 0:0 /tools
chown -Rv 0:0 /cross-tools

The commands use 0:0 instead of root:root, because chown is unable to resolve the name “root” until the passwd file has been created.

It is time to create some structure in the CLFS file system. Create a standard directory tree by issuing the following commands:

mkdir -pv /{bin,boot,dev,{etc/,}opt,home,lib,mnt}
mkdir -pv /{proc,media/{floppy,cdrom},run/shm,sbin,srv,sys}
mkdir -pv /var/{lock,log,mail,spool}
mkdir -pv /var/{opt,cache,lib/{misc,locate},local}
install -dv -m 0750 /root
install -dv -m 1777 {/var,}/tmp
mkdir -pv /usr/{,local/}{bin,include,lib,sbin,src}
mkdir -pv /usr/{,local/}share/{doc,info,locale,man}
mkdir -pv /usr/{,local/}share/{misc,terminfo,zoneinfo}
mkdir -pv /usr/{,local/}share/man/man{1..8}
for dir in /usr{,/local}; do
  ln -sv share/{man,doc,info} $dir
done

Directories are, by default, created with permission mode 755, but this is not desirable for all directories. In the commands above, two changes are made—one to the home directory of user root, and another to the directories for temporary files.

The first mode change ensures that not just anybody can enter the /root directory—the same as a normal user would do with his or her home directory. The second mode change makes sure that any user can write to the /tmp and /var/tmp directories, but cannot remove another user's files from them. The latter is prohibited by the so-called “sticky bit,” the highest bit (1) in the 1777 bit mask.

Some programs use hard-wired paths to programs which do not exist yet. In order to satisfy these programs, create a number of symbolic links which will be replaced by real files throughout the course of the next chapter after the software has been installed.

ln -sv /tools/bin/{bash,cat,echo,grep,pwd,stty} /bin
ln -sv /tools/bin/file /usr/bin
ln -sv /tools/lib/libgcc_s.so{,.1} /usr/lib
ln -sv /tools/lib/libstd* /usr/lib
ln -sv bash /bin/sh
ln -sv /run /var/run

In order for user root to be able to login and for the name “root” to be recognized, there must be relevant entries in the /etc/passwd and /etc/group files.

Create the /etc/passwd file by running the following command:

cat > /etc/passwd << "EOF"
root:x:0:0:root:/root:/bin/bash
EOF

The actual password for root (the “x” used here is just a placeholder) will be set later.

Create the /etc/group file by running the following command:

cat > /etc/group << "EOF"
root:x:0:
bin:x:1:
sys:x:2:
kmem:x:3:
tty:x:5:
tape:x:4:
daemon:x:6:
floppy:x:7:
disk:x:8:
lp:x:9:
dialout:x:10:
audio:x:11:
video:x:12:
utmp:x:13:
usb:x:14:
cdrom:x:15:
EOF

The created groups are not part of any standard—they are groups decided on in part by the requirements of the Eudev configuration in the final system, and in part by common convention employed by a number of existing Linux distributions. The Linux Standard Base (LSB, available at http://www.linuxbase.org) recommends only that, besides the group “root” with a Group ID (GID) of 0, a group “bin” with a GID of 1 be present. All other group names and GIDs can be chosen freely by the system administrator since well-written programs do not depend on GID numbers, but rather use the group's name.

To remove the “I have no name!” prompt, start a new shell. Since a full Glibc was installed in Constructing Cross-Compile Tools and the /etc/passwd and /etc/group files have been created, user name and group name resolution will now work.

exec /tools/bin/bash --login +h

Note the use of the +h directive. This tells bash not to use its internal path hashing. Without this directive, bash would remember the paths to binaries it has executed. To ensure the use of the newly compiled binaries as soon as they are installed, the +h directive will be used for the duration of the next chapters.

The login, agetty, and init programs (and others) use a number of log files to record information such as who was logged into the system and when. However, these programs will not write to the log files if they do not already exist. Initialize the log files and give them proper permissions:

touch /var/run/utmp /var/log/{btmp,lastlog,wtmp}
chgrp -v utmp /var/run/utmp /var/log/lastlog
chmod -v 664 /var/run/utmp /var/log/lastlog
chmod -v 600 /var/log/btmp

The /var/run/utmp file records the users that are currently logged in. The /var/log/wtmp file records all logins and logouts. The /var/log/lastlog file records when each user last logged in. The /var/log/btmp file records the bad login attempts.

This chapter builds the tools needed by some packages to run the tests that they have. I.e., make check. Tcl, Expect, and DejaGNU are needed for the GCC and Binutils testsuites. Check is needed for KBD tests. Installing four packages for testing purposes may seem excessive, but it is very reassuring, if not essential, to know that the most important tools are working properly.

In this chapter, we enter the building site and start constructing the CLFS system in earnest. The installation of this software is straightforward. Although in many cases the installation instructions could be made shorter and more generic, we have opted to provide the full instructions for every package to minimize the possibilities for mistakes. The key to learning what makes a Linux system work is to know what each package is used for and why the user (or the system) needs it. For every installed package, a summary of its contents is given, followed by concise descriptions of each program and library the package installed.

If using compiler optimizations, please review the optimization hint at http://hints.cross-lfs.org/index.php/Optimization. Compiler optimizations can make a program run slightly faster, but they may also cause compilation difficulties and problems when running the program. If a package refuses to compile when using optimization, try to compile it without optimization and see if that fixes the problem. Even if the package does compile when using optimization, there is the risk it may have been compiled incorrectly because of the complex interactions between the code and build tools. Also note that the -march and -mtune options may cause problems with the toolchain packages (Binutils, GCC and Glibc). The small potential gains achieved in using compiler optimizations are often outweighed by the risks. First-time builders of CLFS are encouraged to build without custom optimizations. The subsequent system will still run very fast and be stable at the same time.

The order that packages are installed in this chapter needs to be strictly followed to ensure that no program accidentally acquires a path referring to /tools hard-wired into it. For the same reason, do not compile packages in parallel. Compiling in parallel may save time (especially on dual-CPU machines), but it could result in a program containing a hard-wired path to /tools, which will cause the program to stop working when that directory is removed.

To keep track of which package installs particular files, a package manager can be used. For a general overview of different styles of package managers, please take a look at the next page.

Package Management is an often-requested addition to the CLFS Book. A Package Manager allows tracking the installation of files making it easy to remove and upgrade packages. Before you begin to wonder, NO—this section will not talk about nor recommend any particular package manager. What it provides is a roundup of the more popular techniques and how they work. The perfect package manager for you may be among these techniques or may be a combination of two or more of these techniques. This section briefly mentions issues that may arise when upgrading packages.

Some reasons why no specific package manager is recommended in CLFS or CBLFS include:

There are some hints written on the topic of package management. Visit the Hints subproject and see if one of them fits your need.

./configure --prefix=/usr/pkg/libfoo/1.1
make
make install

./configure --prefix=/usr
make
make DESTDIR=/usr/pkg/libfoo/1.1 install

In the final-system build, you are no longer cross-compiling so it is possible to run package testsuites. Some test suites are more important than others. For example, the test suites for the core toolchain packages—GCC, Binutils, and Glibc—are of the utmost importance due to their central role in a properly functioning system. The test suites for GCC and Glibc can take a very long time to complete, especially on slower hardware, but are strongly recommended.

A common issue with running the test suites for Binutils and GCC is running out of pseudo terminals (PTYs). This can result in a high number of failing tests. This may happen for several reasons, but the most likely cause (if you chrooted) is that the host system does not have the devpts file system set up correctly. This issue is discussed in greater detail at http://trac.cross-lfs.org/wiki/faq#no-ptys.

Sometimes package test suites will fail, but for reasons which the developers are aware of and have deemed non-critical. Consult the logs located at http://cross-lfs.org/testsuite-logs/git/ to verify whether or not these failures are expected. This site is valid for all tests throughout this book.

Now we amend the GCC specs file so that it points to the new dynamic linker. A perl command accomplishes this:

gcc -dumpspecs | \
perl -p -e 's@/tools/lib/ld@/lib/ld@g;' \
     -e 's@\*startfile_prefix_spec:\n@$_/usr/lib/ @g;' > \
     $(dirname $(gcc --print-libgcc-file-name))/specs

It is a good idea to visually inspect the specs file to verify the intended change was actually made.

Note that /lib is now the prefix of our dynamic linker.

echo 'main(){}' > dummy.c
gcc dummy.c
readelf -l a.out | grep ': /lib'

[Requesting program interpreter: /lib/ld-linux.so.2]

rm -v dummy.c a.out