source: README.BLFS@ e557f50

$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 jhalfs is try to help you solving packages
  dependencies and creating your own build scripts/Makefile. Some of the
  auto-generated build scripts and Makefile could work "as is", but as a
  general rule you will need to review and edit the scripts while reading
  the book.

  NOTE:: The code is still under development and may contains several bugs


2. USAGE::

     Due the complexity of the BLFS book, the scripts/Makefile generation is
  done in several steps:

  2.1  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) and the BLFS sources directory (default blfs-xml).

       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
    blfs-parser.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           (not created yet) run gen_config.sh to update Config.in,
                       then launch the menuconfig interface, and lastly run
                       blfs-parser.sh based on configuration settings
    Config.in          menuconfig interface imput file
    packages           auto-generated packages database
    alternatives.conf  (to be removed) configuration file for alternative packages
    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.

  2.2  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"

  2.3  CONFIGURING AND PARSING THE BOOK:: (to be rewritten when ready menuconfig)

       Next step is to create a book and build scripts in dependencies build order
    for a target package. A target package can be any of the ones listed in the
    packages file. That is done using the blfs-parser.sh script, but we are trying
    to make a menuconfig based system.

       The script need three arguments:

    package name         as listed in packages file
    dependencies level   1 for required,
                         2 for required an recommended
                         3 for required, recommended, and optional
    sudo usage           y if sudo will be used (you want build as a normal user)
                         n if sudo isn't needed (you want build as root)

       For example:

       ./blfs-parser galeon 3 y

    will create a directory named "galeon". Inside that directory you find a
    directory named "HTML" that contains a galeon-based HTML book with all
    dependencies in build order and a "scripts" directory with build scripts
    that uses sudo for commands that need root privileges.

       There is also two other directories, dependencies and xincludes, that
    contains files generated while resolving dependencies trees.

  2.4  EDITING BUILD SCRIPTS

       Now is the 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.

      Note that the packages tracking system isn't a packages manegament tool
    and know nothing about packages not in the BLFS book.

  2.5  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 look sane, start the build.


(Text is needed about meta-packages, the installed packages tracking system
and like)

3. 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.

   3.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.

   3.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.

   3.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.

   3.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.

   3.5  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>.