325 lines
15 KiB
Plaintext
325 lines
15 KiB
Plaintext
1. INTRODUCTION::
|
|
|
|
The scripts in this directory implement an automation of the building
|
|
of a GNU/LInux system, as described in the Linux From Scratch book series.
|
|
The name of the project is jhalfs: in that name, "alfs" stands for
|
|
"automated linux from scratch", and the initials "jh" have been kept since
|
|
the original "jhalfs-0.2" code developed by Jeremy Huntwork.
|
|
|
|
The list of supported books can be found at
|
|
http://wiki.linuxfromscratch.org/alfs/wiki/SupportedBooks.
|
|
|
|
The documentation is split among various README.* files. Here is a list
|
|
of what is in which:
|
|
- README (this file): instructions to use the LFS book. This should be
|
|
enough if you just want to build a base system as per the LFS book. It is
|
|
also a required reading for all the other projects.
|
|
- README.CLFS: supplementary instructions to use the CLFS book series.
|
|
- README.BLFS: instructions to install an automated build infrastructure
|
|
for the BLFS book. There are two ways to do so: (i) install the
|
|
tools at the end of an LFS build (CLFS is not supported in that case), or
|
|
(ii) install the tools on an already running system. Both methods are
|
|
described in that file.
|
|
- README.CUSTOM: instructions to run custom commands either during the xLFS
|
|
build, at the end of a xLFS build. Note that you will not find
|
|
instructions on how to write those commands, but some examples are
|
|
available.
|
|
- README.PACKAGE_MANAGEMENT: instructions to use package management during
|
|
the build (only for LFS, patches welcome for CLFS...)
|
|
|
|
Other sources of information are the context help in the menu interface,
|
|
and the xLFS books themselves.
|
|
|
|
2. PREREQUISITES::
|
|
|
|
As said elsewhere, it is strongly advised that you first build manually
|
|
a complete system before attempting to automate the build.
|
|
|
|
Of course the "Host System Requirements" should be fulfilled. The needed
|
|
supplementary packages are detailed at the bottom of the page:
|
|
https://www.linuxfromscratch.org/alfs/download.html. In short, you need
|
|
wget, sudo, libxml2, libxslt, docbook-4.5-xml, and docbook-xsl-nons.
|
|
|
|
3. INSTALLATION::
|
|
|
|
No installation is required. You may want to move the files in this
|
|
directory to a convenient location, and then follow the instructions below.
|
|
|
|
4. CONFIGURATION::
|
|
|
|
4.1. CONFIGURATION OF THE TOOLS:
|
|
There is no configuration of the tools themselves. The various
|
|
parameters for the build are set through a menu driven interface. See
|
|
the section RUNNING below for details.
|
|
|
|
4.2. PRELIMINARY TASKS:
|
|
This tool has no support at all for creating a partition and a mount
|
|
point for the built system. You should follow the book up to the section
|
|
"Mounting the new partition". Note that the default name for the
|
|
partition mount point is "/mnt/build_dir", instead of /mnt/{c,}lfs.
|
|
You can change that default to anything you'd like in the menu, so you
|
|
may name it /mnt/lfs, or whatever you like. We'll use the name
|
|
/mnt/build_dir in the sequel.
|
|
|
|
The tool can download the needed packages for you, or you may download
|
|
them yourself. The tool may optionally use a package archive directory
|
|
where the downloaded packages are stored. That directory name may be made
|
|
available to the tool in two ways: (i) export the SRC_ARCHIVE variable,
|
|
for example SRC_ARCHIVE=/usr/src, (ii) enter the name at the "Package
|
|
Archive Directory" menu prompt. Note that the user should have write
|
|
permission to that directory. If a needed package is found in that
|
|
directory, it is copied to /mnt/build_dir/sources, if not, it is
|
|
downloaded to that directory and copied to /mnt/build_dir/sources,
|
|
except if found in /mnt/build_dir/sources, in which case, it is just
|
|
copied to $SRC_ARCHIVE. If you want the tool to download packages and you
|
|
do not want to archive them, just unset SRC_ARCHIVE, and keep the
|
|
default entry for "Package Archive Directory". If you choose to download
|
|
the packages by yourself, you should download (or copy) them to
|
|
/mnt/build_dir/sources directly.
|
|
|
|
If you want to build the kernel as part of the automated build, select
|
|
"Build the kernel" in the menu. Then, a configuration file must be
|
|
provided. In order to do so, it is recommended to download the kernel
|
|
tarball, unpack it, run <make menuconfig> (or any other *config),
|
|
configure the kernel as per
|
|
the book, and save the resulting .config file to a location where it can
|
|
be retrieved later on (a convenient location and name is
|
|
$SRC_ARCHIVE/config-<arch>-<kernel version>-<config details>).
|
|
|
|
Another file you may provide is the fstab file. To use it, select
|
|
"Use a custom fstab file" in the menu interface, and enter the name of
|
|
the file where asked. As for the kernel configuration, this file has to
|
|
be prepared before running the menu. A convenient location and name is
|
|
$SRC_ARCHIVE/fstablfs.
|
|
|
|
At a more advanced level, you may want to supply custom commands
|
|
to be run at the end of (C)LFS build. Scripts containing those commands
|
|
are located in the ./custom/config directory. Examples are given in
|
|
./custom/examples. A template is provided as ./custom/template. See
|
|
README.CUSTOM for more details.
|
|
|
|
5. RUNNING::
|
|
|
|
IMPORTANT::
|
|
You must be logged as a normal user with sudo privileges to run
|
|
the Makefile. Furthermore, you are supposed to have enough privilege
|
|
to become any user. If you are not bothered about security issues,
|
|
the entry for the user "jhalfs_user" in /etc/sudoers could be
|
|
jhalfs_user ALL=(ALL) NOPASSWD:ALL
|
|
|
|
The command <make> will launch a menu based configuration program. The
|
|
underlying menu code was borrowed from BusyBox and slightly modified for
|
|
our use.
|
|
|
|
Help on parameter function is available from the on-line help. Please
|
|
make use of that feature: it may contain additional information not
|
|
duplicated in this file.
|
|
|
|
You should first choose which book and flavour you want to build. Note
|
|
that when you choose the BLFS book, the tool will just install the BLFS
|
|
tool to your system. You'll have to run that installed tool to build
|
|
packages in BLFS. See README.BLFS to know how. If you choose any other
|
|
book, you'll have to configure the settings and the build parameters
|
|
from the menu. Note that you may choose to install the blfs tools onto
|
|
the newly built system. It is not the same thing as choosing
|
|
the BLFS book in the menu, which will install the blfs tools on the
|
|
currently running system.
|
|
|
|
The "General Settings" menu is where the "Build Directory" name is to be
|
|
entered. Other entries in that menu select what the tool should do. The
|
|
"Run the Makefile" entry selects whether the tool will start the build
|
|
automatically after generating the needed files. The "Rebuild files" selects
|
|
whether to clean the build directory before doing anything else. To protect
|
|
against removing important files, this can only be done in an empty directory,
|
|
or a directory previously populated by the tool.
|
|
|
|
The "Build Settings" menu is where various options for the build can be
|
|
selected. Two options, "Use a custom fstab file" and "Build the kernel",
|
|
have been described above. "Do not use/display progress_bar", if set, will
|
|
prevent a progress bar to be displayed during the build. That may be useful
|
|
on slow machine. The other options should be self explanatory, using either
|
|
the online help or book reading.
|
|
|
|
The "Advanced Features" menu is for various maintenance tasks, like
|
|
testing the build instructions or reporting build statistics. One useful
|
|
option is "Optimization and parallelisation". It is not recommended to use
|
|
it for setting compiler optimization flags, although it is possible, but
|
|
if you select it, you'll be able to select the number of parallel `make'
|
|
jobs, which allows much faster builds on modern multicore CPUs.
|
|
|
|
Once you have set the parameters and saved the configuration, the script
|
|
is launched. Its aim is to extract instructions from the selected book
|
|
to generate scripts, and to generate a Makefile, which allows running
|
|
the scripts in the right order. The script verifies first that the host
|
|
can run itself and build the xLFS system, then validates the configuration
|
|
and lists the parameters. At this point, you may choose to quit or to
|
|
continue with the listed parameters. The script will then proceed to
|
|
generate the Makefile and the build scripts, optionally download
|
|
packages, and eventually verify the host prerequisite. If you have
|
|
selected "Run the makefile", the command <make> is launched in the
|
|
adequate directory, and the build begins. If not, you'll have to run
|
|
"make" manually, for example: "make -C /mnt/build_dir/jhalfs", if you
|
|
have used the default parameters (see the layout under $BUILDDIR in the
|
|
Q&A below).
|
|
|
|
NOTE::
|
|
If you run the jhalfs script directly the only function you can select
|
|
is to display the version number by running <./jhalfs -v>
|
|
|
|
6. LAYOUT::
|
|
|
|
/BLFS (see README.BLFS)
|
|
|
|
/CLFS/master.sh
|
|
/clfs.xsl
|
|
|
|
/CLFS2/master.sh
|
|
/clfs2.xsl
|
|
|
|
/CLFS3/master.sh
|
|
/clfs3.xsl
|
|
|
|
/LFS/master.sh
|
|
/lfs.xsl
|
|
|
|
/common/common_functions
|
|
/makefile_functions
|
|
/packages.xsl
|
|
/urls.xsl
|
|
/create-sbu_du-report.sh
|
|
/progress_bar.sh
|
|
/blfs-tool-deps/9xx-*
|
|
/libs/func_*
|
|
|
|
/custom/template
|
|
/config/
|
|
/examples/*
|
|
/examples_CLFS-E/*
|
|
|
|
/extras/do_copy_files
|
|
/do_ica_prep
|
|
/do_ica_work
|
|
|
|
/optimize/opt_config
|
|
/opt_override
|
|
/optimize_functions
|
|
/opt_config.d/noOpt
|
|
/noSymbols
|
|
/O3pipe
|
|
/O3pipe_march
|
|
/defOpt_fPIC
|
|
|
|
/menu/*
|
|
|
|
README
|
|
README.BLFS
|
|
README.CLFS
|
|
README.CUSTOM
|
|
TODO
|
|
LICENSE
|
|
|
|
Config.in
|
|
Makefile
|
|
jhalfs
|
|
blfs-tool
|
|
|
|
7. FAQ::
|
|
Q. "It doesn't work"
|
|
A. There are several reasons why it may be so. One possibility is the
|
|
following: jhalfs was designed to work against the development versions
|
|
of the LFS series of books. Consequently changes in a book sometimes
|
|
break older versions of jhalfs. Before you start pulling out your hair,
|
|
download the latest version of jhalfs to see if that solves your
|
|
problem. Note that it may be the other way around. If you want to build
|
|
an old version of the book, you may have to downgrade your jhalfs
|
|
version.
|
|
|
|
Q. "How do I specify the build location?"
|
|
A. The original LFS document worked against the well known location
|
|
/mnt/lfs. This script automates the build of all of the LFS series of
|
|
books and uses a generic location $BUILDDIR with a default value of
|
|
/mnt/build_dir. You may change this value to suit your needs.
|
|
|
|
The layout below $BUILDDIR is as follows.
|
|
$BUILDDIR/
|
|
jhalfs (Makefile, cmd scripts, logs, etc..)
|
|
sources (where packages reside)
|
|
tools (temporary bootstrap system)
|
|
cross-tools (temporary CLFS only)
|
|
...
|
|
FHS dir structure
|
|
...
|
|
blfs_root (files to use blfs-tool if selected to install it)
|
|
|
|
Q. "What is the function of the SRC_ARCHIVE variable?"
|
|
A. When jhalfs runs and packages download was selected, it creates a local
|
|
copy of the necessary packages in $BUILDDIR/sources by downloading the
|
|
files. If the variable SRC_ARCHIVE is defined the software will first
|
|
look in this location for the file and, if found, will copy it to
|
|
$BUILDDIR/sources.
|
|
If the files are not found in SRC_ARCHIVE _and_ you have write priv to
|
|
the directory any downloaded files will be mirrored there.
|
|
|
|
Q. "How do I set the SRC_ARCHIVE location?"
|
|
A. The best way to set the value of SRC_ARCHIVE is
|
|
|
|
export SRC_ARCHIVE=/wherever/you/store/downloaded/packages
|
|
|
|
or you can set the full path in the proper menu entry.
|
|
|
|
Q. "Why have 2 copies of the files?"
|
|
A. The package files must be visible during the chroot phase and this is a
|
|
simple and reliable method of doing so. This method also handles the
|
|
CLFS boot build method where the final build may be done on a separate
|
|
machine.
|
|
|
|
Q. "What is the function of "User account" and "Group account" menu
|
|
settings?"
|
|
A. If you are running jhalfs from a low or non-privileged account you may
|
|
not have the priv to create/delete the user needed to build temporary
|
|
tools.
|
|
These settings allow you to use your own user and group name to do those
|
|
build steps.
|
|
|
|
These variables are adjustable also when invoking make:
|
|
|
|
cd $BUILDDIR; make LUSER=myaccount LGROUP=mygroup
|
|
|
|
The only changes to your account will be the creation of a NEW .bashrc
|
|
after saving your original to .bashrc.XXX
|
|
|
|
Q. "When I try to build CLFS the Makefile fails at mid-point"
|
|
A. There could be numerous reasons for the failure but the most likely
|
|
reason is you are doing a cross-build using the 'chroot' method and the
|
|
target is not compatible with the host. If you choose to build using
|
|
the chroot method a test is performed at the end of the temptools
|
|
phase. If the test succeeds the build continues inside a chroot jail.
|
|
However if the test fails, it means the host and target are not
|
|
compatible an you should use the 'boot' method to create your target
|
|
code.
|
|
As an extreme example: You can build a sparc target on a x86 platform but
|
|
only the temptools phase. You must select the 'boot' method and not the
|
|
'chroot.' You must transfer the toolchain to a sparc platform, reboot the
|
|
sparc box and continue the build.
|
|
Of all the LFS series of books Cross-LFS requires the greatest
|
|
understanding of host/target hardware combination. Please read the book
|
|
carefully and don't skip the easy parts (there are none...)
|
|
|
|
Q. "How could I stop the build at a predefined chosen point?"
|
|
A. Launch the Makefile manually passing the last numbered target to be build
|
|
as the break point. For example:
|
|
|
|
make BREAKPOINT=84-bash
|
|
|
|
The build can be stopped also at the end of a top-level build phase by
|
|
calling directly the appropriate mk_* target. For example:
|
|
|
|
make mk_LUSER
|
|
|
|
See the Makefile to know the proper target names for that book build.
|
|
|
|
Authors:
|
|
George Boudreau
|
|
Manuel Canales Esparcia
|
|
Pierre Labastie
|