$Id$
1. INTRODUCTION::
To automatize packages build from the BLFS book instructions is a huge
task. The BLFS book isn't linear, some package pages need to use a non
default layout, there are circular dependencies, several packages can be
installed on a non default prefix, build commands can change based on what
dependencies will be used, etc.
Said that, the goal of blfs-tool is try to help you solving packages
dependencies and creating your own build scripts and Makefile. Few of the
auto-generated build scripts and Makefile could work "as is", thus as a
general rule you will need to review and edit the scripts while reading
the book.
2. PREREQUISITES::
To use this tool you MUST to:
- have experience building BLFS packages
- know how to edit and write shell scripts
- know how a Makefile works
- be able to trace build failures and to find what is causing it
(user error, package bug, BLFS command bug, or jhalfs code bug)
If you do not have the above skills, please don't use this tool.
3. USAGE::
Due the complexity of the BLFS book, the scripts and Makefile generation is
done in several steps:
3.1 INSTALLED PACKAGES TRACKING SYSTEM
This tool includes a very simple tracking system to know what packages
has been installed using the tool. It is used to skip installed packages
from target selection menu and to know if an installed package has been updated
on the BLFS book. Don't rely on this feature as a packages management tool.
The directory where tracking files will be stored need be created
before installing blfs-tool. You can place that directory anywhere, taking
care that the builder user must have read and write privileges on that
directory and on all files it contains.
To use the default path set in the installation menu, run as root:
install -d -m1777 /var/lib/jhalfs/BLFS
3.2 BLFS_TOOL INSTALLATION::
Run "make" to launch the jhalfs menuconfig interface. Select the BLFS
book and it version. Then set the installation directory (default
$HOME/blfs_root), the BLFS sources directory (default blfs-xml), and
the installed packages tracking directory (default /var/lib/jhalfs/BLFS).
All required files will be placed in the installation directory and
BLFS XML sources will be checkout to the named sub-directory.
Installed files:
blfs-xml/* SVN tree of the selected BLFS book version
lib/* functions libraries, xsl stylesheets, and auto-generated
meta-packages dependencies tree files
menu/* lxdialog and menuconfig source code
README.BLFS this file
TODO developers notes
update_book.sh update the XML book sources and regenerates packages
database and meta-packages dependencies tree
gen_config.sh regenerates Config.in
gen_pkg_book.sh solve dependencies and generates linear BLFS books
and build scripts
gen-makefile.sh generates target Makefile
progress_bar.sh the target Makefile progress bar
Makefile run gen_config.sh to update Config.in,
then launch the menuconfig interface, and lastly run
gen_pkg_book.sh based on configuration settings
Config.in menuconfig interface input file
packages auto-generated packages database
envars.conf envars needed when running the target build scripts
From now on, all the work must be done from inside the installation
root directory.
When finished the installation, the configuration and target selection
menu is launch.
3.3 UPDATING BOOK SOURCES::
If using the development book version, and if you want to update already
installed packages to the new version found in that book, you need to update
the XML sources and packages database.
To do that run "./update_book.sh"
On the next configuration run, packages already installed but listed
with a new version in the book will be available for target selection and
used to solve dependencies.
3.4 CONFIGURING AND PARSING THE BOOK::
Next step is to create a book and build scripts in dependencies build order
for a target package. A target can be a package or a meta-package.
WARNING:
Only one target (meta-package or individual package) must be
selected on each configuration run.
That is due that there is no way to solve dependencies properly
when more than one target are selected at the same time.
Run <make> to launch the configuration interface. The main menu contains
three block: meta-package selection, individual package selection, and
build options.
When a meta-package is selected is possible to unselect unwanted components.
That unselected components will be skipped if no other components depends
on them.
In the build options section the dependencies level and default packages
used to solve alternatives are set. Can be set also if the build will be
made as a normal user or as root. That settings are saved to be reused on
future configuration runs.
If, for example, your target selection is Xsoft-->Graphweb-->galeon a
directory named "galeon" will be created. Inside that directory you will
find a directory named "HTML" that contains a galeon-based HTML book with
its dependencies in build order, and a "scripts" directory with build
scripts for that packages.
There is also two other directories, "dependencies" and "xincludes", that
contains files generated while resolving dependencies trees.
3.5 EDITING BUILD SCRIPTS
Now is time to review the generated book and scripts, making in the
scripts any changes required to fix generation bugs or to fit your needs.
Scripts for additional packages (i.e., for non-BLFS packages) can be
inserted in an easy way due how the scripts are named. For example, if you
want to install the external dependency "bar" before "foo" package and the
"foo" script is named "064-z-foo", you need to create a "064-y-bar" build
script.
Remember that the packages tracking system isn't a packages management tool
and know nothing about packages not in the BLFS book.
Also, review and edit envars.conf. That file is used to set global envars
needed by the build scripts.
3.6 CREATING THE MAKEFILE
When the build scripts are ready to be run, the Makefile can be
created. Be sure that you cd into the "package" directory and run
../gen_makefile.sh
Review the Makefile and if all looks sane, start the build.
4. GENERATED BUILD SCRIPTS ISSUES::
In this section known issues with the generated build scripts are
discussed. They are due build procedures and/or BLFS layout particularities
than we can't handle. In several cases editing the build scripts is mandatory.
You may need also to insert some build script created by you to resolve
unhandled dependencies and/or to remove some script installing the affected
package by hand.
4.1 BLFS BOOTSCRIPTS
For now, bootscripts installation will fail. You will need to edit the
scripts for packages that install bootscripts and fix their installation
command. That could be fixed in the future, but not sure.
4.2 PACKAGES CONFIGURATION
For that packages that have a "Configuration" section, you should to
edit it build script to fit the configuration to your needs.
4.4 PDL and Perl modules.
The generated scripts for that packages are plainly broken and can't
be fixed. You must to replace it by your own ones or install that
packages by hand.
4.4 GCC, JDK, Sane, and KDE-multimedia
On the pages for that packages, the BLFS book actually have instructions
to install two packages. You must to edit the scripts to fix it. We will
try to fix some of them, but may not be possible.
4.5 XORG7
The generated scripts for Xorg7 pseudo-packages don't have support for
$SRC_ARCHIVE nor MD5 checking.
If you has downloaded previously the packages, you must to edit the scripts
to make it to use your local packages.
Also, you will need to edit the scripts to fix the commands that must
be applied only to a concrete individual sub-package. For example the "for"
loop to install xorg7-util packages may read like:
for package in $(cat $WGET_LST) ; do
packagedir=$(echo $package | sed 's/.tar.bz2//')
tar -xf $package
cd $packagedir
sed -i "s@/usr/X11R6@$XORG_PREFIX@" X11.tmpl &&
./configure $XORG_CONFIG --with-config-dir=$XORG_PREFIX/lib/X11/config
sudo sh -c "make install"
./configure $XORG_CONFIG --with-config-dir=$XORG_PREFIX/lib/X11/config &&
make
sudo sh -c "make install"
./configure $XORG_CONFIG &&
make
sudo sh -c "make install"
cd ..
rm -rf $packagedir
done
After reading the HTML page to know what commands is for what package,
the loop can be changed to read something like:
for package in $(cat $WGET_LST) ; do
packagedir=$(echo $package | sed 's/.tar.bz2//')
tar -xf $package
cd $packagedir
if [ ${packagedir} = "xorg-cf-files" ] ; then
sed -i "s@/usr/X11R6@$XORG_PREFIX@" X11.tmpl &&
./configure $XORG_CONFIG --with-config-dir=$XORG_PREFIX/lib/X11/config
sudo sh -c "make install"
elif [ ${packagedir} = "Imake" ] ; then
./configure $XORG_CONFIG --with-config-dir=$XORG_PREFIX/lib/X11/config &&
make
sudo sh -c "make install"
else
./configure $XORG_CONFIG &&
make
sudo sh -c "make install"
fi
cd ..
rm -rf $packagedir
done
4.6 PATCHES
By default all required patches will be downloaded from the NET.
If you has downloaded previously the patches, you must to edit the scripts
to make it to use your local patches.
Also, be sure that all scripts have the commands to download/apply the
required patches. Due book layout issues some patches may be missing.
4.7 ROOT COMMANDS
If building as a normal user (the default setting) be sure that all
commands that need root privileges are run using sudo.
Due book layout issues some sudo command may be missing.
4.8 OTHERS
May have other issues that we are not aware on them yet. If you find
someone, please report it to <alfs-discuss@linuxfromscratch.org>.