Updates to README and README.BLFS. First "alpha release"

README

@@ -77,23 +77,28 @@ $Id$
 
 6. BLFS_TOOL SUPPORT::
 
-     For books that support it, there is an option to install blfs-tool and its
+     For books that support it (TODO: which ones?), there is an option
-     dependencies on the final system. The pre-made build dependencies
+     to install an automated framework for building BLFS packages. Let
+     us call it blfs-tool for now. When you tick `BOOK Settings/Add
+     blfs-tool support' in jhalfs configuration menu, the tools are
+     installed in $BLFS_ROOT (default /blfs_root) on the xLFS system,
+     and a few dependencies (which you may select) are built at the
+     end of the jhalfs run. The pre-made build dependencies
      scripts has been written based on a LFS build. For CLFS and HLFS
-     builds you may need to adjust that scripts, that are found into the
+     builds you may need to adjust those scripts, that are found into the
      common/blfs-tool-deps directory in the jhalfs sources tree.
 
+     (TODO: is this relevant to present CLFS?)
      WARNING:: If you add blfs-tool support on a CLFS Sysroot build
-               you MUST to edit the dependencies scripts to fix the
+               you MUST edit the scripts to fix the installation paths.
-               installation paths.
-               Be careful when you modify the scripts as you can
-               easily disable the host system.
 
      After booting the new xLFS system some steps are needed to finish
-     blfs-tool installation:
+     the installation of the automated tools:
 
        - A user account must be created. You must be logged on that user
-         account to use blfs-tool.
+         account to use blfs-tool. This is not strictly necessary,
+         since the packages can be built as root, too, but it is
+         never a good idea to build packages as root.
 
        - Move /blfs-root to that user's home and change ownership of the
          directory and files to the user.
@@ -104,13 +109,21 @@ $Id$
        - If you think that you may need the libxml2/libxslt Python modules,
          remove the libxml2 and libxslt trackin files found in $TRACKING_DIR.
 
-       - Configure sudo, adding the needed privileges for the user.
+       - Configure sudo, adding the needed privileges for the user. For
+         newer sudo version, do not forget to add a line Defaults secure_path=
+         containing /sbin and /usr/sbin (in /etc/sudoers), otherwise some
+         executables are not found.
+
+       - Although it is not strictly necessary, it is recommended to install
+         the bash shell startup files (as per `3.After LFS Configuration
+         Issues' of the BLFS book), as some instructions in BLFS rely on
+         their being present.
 
      We assume that blfs-tool will be used on a running fresh xLFS system.
      To use it to build BLFS packages from the chroot jail is also possible,
-     but is for you to figure out how to do that.
+     but not supported.
 
-     To know how to blfs-tool works, see README.BLFS.
+     To know how to use blfs-tool, see README.BLFS.
 
 7. LAYOUT::
 

README.BLFS

@@ -45,13 +45,16 @@ $Id$
     management tool.
 
        The tracking system itself is an XML file: instpkg.xml. It is
-    initialized when make is first run in blfs_root. It resides in a directory
+    initialized when <make> is first run in blfs_root. It resides in a
-    which is created when needed during the process of building custom tools
+    directory, which is created when needed during the process of building
-    or blfs tools, after xLFS. You can specify that directory location in
+    custom tools or blfs dependencies, right after xLFS. You can specify
-    the blfs tools submenu of jhalfs. You may need to update permissions
+    that directory location in the blfs-tools submenu of jhalfs. You may
-    and/or ownership of this directory before using the blfs tool.
+    need to update permissions and/or ownership of this directory before
+    using the blfs tool (see README in jhalfs).
 
-       The default location of the tracking directory is /var/lib/jhalfs/BLFS
+       The default location of the tracking directory is /var/lib/jhalfs/BLFS.
+    NB : after the initial build, that directory is only used to contain
+    instpkg.xml
 
   3.2  BLFS_TOOL INSTALLATION::
 
@@ -64,24 +67,44 @@ $Id$
     root directory of the new xLFS system, which contains the followings:
 
     blfs-xml/*              SVN tree of the selected BLFS book version
-    lib/*              functions libraries 
+    lib/constants.inc       functions libraries 
+       /func_dependencies     for building the dependency tree
     menu/*                  lxdialog and menuconfig source code
-    xsl/*              XSL stylesheets used at several stages of the process
+    xsl/gen_pkg_list.xsl    XSL stylesheet to generate the package database
+       /gen_config.xsl      XSL stylesheet to generate the Config.in file
+                            for use in the menuconfig system
+       /dependencies.xsl    XSL stylesheet to generate the dependency list
+                            of a package
+       /make_book.xsl       XSL stylesheet to generate the linear book.xml
+       /scripts.xsl         XSL stylesheet to generate the scriptlets from
+                            book.xml
+       /bump.xsl            XSL stylesheet to generate to update the tracking
+                            file
     README.BLFS             this file
-    TODO               developers notes (well, not often updated)
+    TODO                    developers notes (well, not updated often)
-    gen_pkg_book.sh    resolves dependencies and generates linear BLFS books
+    gen_pkg_book.sh         resolves dependencies and generates linear BLFS
-                       and build scripts
+                            books and build scripts
     gen-makefile.sh         generates the target Makefile
     progress_bar.sh         the target Makefile progress bar
     gen-special.sh          Helper script for generating the package database
-    Makefile           Used by make to update the package database from the SVN
+    Makefile                Used by make to update the package database from
-                       tree, then launch the menuconfig interface, and run
+                            the SVN tree, then launch the menuconfig interface,
-                       gen_pkg_book.sh based on configuration settings
+                            and run gen_pkg_book.sh based on configuration
-    packages.xml       auto-generated packages database
+                            settings
     packdesc.dtd            a simple DTD describing the format of the package
-                       database
+                            database and the tracking file.
     envars.conf             envars needed when running the target build scripts
 
+  Several files are generated during the process:
+
+    packages.xml            auto-generated packages database
+    Config.in               input file for the menu driven choices
+    configuration           file generated by the menuconfig process
+    dependencies/*          files recording the dependency tree
+    book.xml                the linearized book
+    book-html/*             the linearized book rendered in html
+    scripts/*               the scriptlets
+
        From now on, all the work must be done from inside the installation
     root directory.
 
@@ -92,7 +115,8 @@ $Id$
 
        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.
+    update the XML sources and packages database. This is not necessary if
+    you just built xLFS, and you can skip to step 3.4.
 
        To do that run "make update". It may happen that the subversion
     version of your building host is older than the version you just
@@ -113,10 +137,14 @@ $Id$
     two blocks: individual package selection, and build options.
 
        In the build options section, the dependencies level and default packages
-    used to solve alternatives are set (currently, only for the mTA). You can
+    used to solve alternatives are set (currently, only for the MTA). You can
     also select whether the build will be made as a normal user or as root.
     Those settings are saved to be reused in future configuration runs.
 
+       Note that you may select as many targets as you want, not just one
+    as in the previous version of this tool. But we suggest to not select
+    too many at a time to be able to sort issues!
+
        When you are done with the menu, a few checks occur, and the book is
     generated. When circular dependencies are found, a 3 line message is
     printed:
@@ -128,7 +156,7 @@ $Id$
     This means that the system has found the dependency chain: B->A->C->A.
     You have therefore to choose whether A is built before C, or
     C before A: the system cannot make that choice (well, maybe in a few
-    year, with an AI system able to understand the book). if you answer no,
+    year, with an AI system able to understand the book). If you answer no,
     C is built first. If you answer yes, C is put in place of A as a dependency
     of B, then the tree dependency restarts from there, that is with the
     layout B->C->... You may then hit the case B->C->A->C, for which you
@@ -144,7 +172,7 @@ $Id$
        There is also another directory, "dependencies" that contains files
     generated while resolving dependencies.
 
-  3.5  EDITING BUILD SCRIPTS
+  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
@@ -161,7 +189,7 @@ $Id$
       Also, review and edit envars.conf. This file is used to set global envars
     needed by the build scripts.
 
-  3.6  CREATING THE MAKEFILE
+  3.6  CREATING THE MAKEFILE::
 
        When the build scripts are ready to be run, the Makefile can be
     created. Create an empty directory (for example "mkdir work") and cd
@@ -180,13 +208,13 @@ $Id$
    unhandled dependencies and/or to remove some script installing the affected
    package by hand.
 
-   4.1  BLFS BOOTSCRIPTS
+   4.1  BLFS BOOTSCRIPTS::
 
       Normally, bootscript installation should work. On the other hand, the
    book does not give instruction for running them, so you might have to
-   manually insert /etc/init.d/<initscript> at some place during the build.
+   manually insert /etc/init.d/rd.d/<initscript> at some place during the build.
 
-   4.2  PACKAGE CONFIGURATION
+   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. Sometimes, the
@@ -194,7 +222,7 @@ $Id$
    llvm). You might have to insert something like "source /etc/bash_profile"
    at some point during the build.
 
-   4.4  GCC, JDK, Sane, and KDE-multimedia, freetype2, MesaLib and others
+   4.3  GCC, JDK, Sane, and KDE-multimedia, freetype2, MesaLib and others
 
         On the pages for those packages, the BLFS book actually has instructions
      to download and install two or more packages. You must edit the scripts to
@@ -202,7 +230,7 @@ $Id$
 
         We will try to fix some of them, but this may not be possible.
 
-   4.5  XORG7
+   4.4  XORG7
 
         The generated scripts for Xorg7 packages have $SRC_ARCHIVE
      support for individual packages, but not for patches nor *.wget and *.md5
@@ -215,10 +243,7 @@ $Id$
      the scripts to be sure that the most current individual packages are
      used. Thus don't reuse previously existing ones.
 
-       In the script for xorg7-font, be sure to move the fonts directories
+   4.5  PATCHES
-     symlinks creation to after the "for ... done" loop.
-
-   4.6  PATCHES
 
         By default, all required patches will be downloaded from the NET.
 
@@ -228,17 +253,25 @@ $Id$
         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
+   4.6  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.
+     necessary root privilege commands are visible in your PATH. Or use
+     the `Defaults secure_path=' in /etc/sudoers. Also, the scripts use a
+     fragile construct:
+       sudo bash -c '<commands to be executed as root>'
+     which fail if the commands to be executed contain themselves a ' or access
+     a bash variable $XXX. So carefully review them.
 
         Due to book layout issues, some sudo commands may be missing.
 
-   4.8  OTHERS
+   4.7  OTHERS
 
         There may be other issues that we are not aware of. If you find
      any, please report it to <alfs-discuss@linuxfromscratch.org>.
 
-
+        Presently, there is an error in the book in file
+     x/installing/x7proto.xml. You should change the role='required' to
+     role='optional' in the optional dependencies, if you plan to build
+     X.