source: README.BLFS@ 4a33ef0

$Id$

1. INTRODUCTION::

     To automate package builds from the BLFS book instructions is a huge
  task. Some of the issues are: the BLFS book isn't linear; some package
  pages use a custom 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.

     That being said, the goal of the blfs-tool is to help you solve package
  dependencies, create build scripts and a Makefile. Few of the auto-generated
  build scripts and Makefile will 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:

     - 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 log which packages
    have been installed using the tool. It is used to skip installed packages
    from target selection menu and to test if an installed package has been
    updated in the BLFS book. Do not rely on this feature as a package
    management tool.

       The directory where tracking files will be stored needs to be created
    before installing blfs-tool. You can place this directory anywhere, taking
    care that the 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 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 installed in 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    resolves dependencies and generates linear BLFS books
                       and build scripts
    gen-makefile.sh    generates the 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 you are using the development book version and you want to update
    installed packages to the latest 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::

       The next step is to create a book and build scripts in dependency
    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.
           There is no way to solve dependencies properly when more
           than one target are selected.

       Run <make> to launch the configuration interface. The main menu contains
    three blocks: meta-package selection, individual package selection, and
    build options.

       When a meta-package is selected, it is possible to unselect unwanted
    components. The 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. You can also select whether the build will
    be made as a normal user or as root. That settings are saved to be reused in
    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 are also two other directories ("dependencies" and "xincludes")
    that contain files generated while resolving dependencies trees.

  3.5  EDITING BUILD SCRIPTS

       Now it is time to review the generated book and scripts, making any changes
    to the scripts necessary to fix generation bugs or to suit your needs.

       Scripts for additional packages (i.e., for non-BLFS packages) can be
    easily inserted. 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, the package tracking system isn't a package management tool
    and knows nothing about packages not in the BLFS book.

      Also, review and edit envars.conf. This 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 to build procedures and/or BLFS layout particularities
   that we can't handle. In several cases, editing the build scripts is mandatory.
   You may also need to insert some build scripts 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.

   4.2  PACKAGE CONFIGURATION

        For those packages that have a "Configuration" section, you should
     edit the build script to fit the needs of your system.

   4.4  PDL, Perl modules, and Glib-Bindings.

        The generated scripts for these packages are broken and can not
     be fixed. You must replace them with your own scripts or install the
     packages by hand.

   4.4  GCC, JDK, Sane, and KDE-multimedia

        On the pages for these packages, the BLFS book actually has instructions
     to install two packages. You must edit the scripts to fix this.

        We will try to fix some of them, but this may not be possible.

   4.5  XORG7

        The generated scripts for Xorg7 pseudo-packages don't have support for
     $SRC_ARCHIVE. If you have previously downloaded the packages, you must edit
     the scripts to use your local packages.

   4.6  PATCHES

        By default, all required patches will be downloaded from the NET.

        If you have previously downloaded the patches, you must edit the
     scripts to use your local patches.

        Also, be sure that all scripts have the commands to download/apply the
     required patches. Due to 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 require root privileges are run using sudo. Also make sure
     necessary root privilege commands are visible in your PATH.

        Due to book layout issues, some sudo commands may be missing.

   4.8  OTHERS

        There may be other issues that we are not aware of. If you find
     any, please report it to <alfs-discuss@linuxfromscratch.org>.