tags/2.3.2/README.BLFS

   1 $Id$
   2
   3 1. INTRODUCTION::
   4
   5      If you want to add blfs-tool support into a xLFS base system build,
   6   read the "BLFS_TOOL SUPPORT" section found in the README and be sure
   7   to follow the after-booting installation intructions.
   8
   9      To automate package builds from the BLFS book instructions is a huge
  10   task. Some of the issues are: the BLFS book isn't linear; some package
  11   pages use a custom layout; there are circular dependencies; several
  12   packages can be installed on a non-default prefix; build commands can
  13   change based on what dependencies will be used, etc.
  14
  15      That being said, the goal of the blfs-tool is to help you solve package
  16   dependencies, create build scripts and a Makefile. Few of the auto-generated
  17   build scripts and Makefile will work "as is", thus, as a general rule,
  18   you will need to review and edit the scripts while reading the book.
  19
  20
  21 2. PREREQUISITES::
  22
  23      To use this tool you MUST:
  24
  25      - have experience building BLFS packages
  26      - know how to edit and write shell scripts
  27      - know how a Makefile works
  28      - be able to trace build failures and to find what is causing it
  29        (user error, package bug, BLFS command bug, or jhalfs code bug)
  30
  31      If you do not have the above skills, please don't use this tool.
  32
  33
  34 3. USAGE::
  35
  36      Due the complexity of the BLFS book, the scripts and Makefile generation
  37   is done in several steps:
  38
  39   3.1  INSTALLED PACKAGES TRACKING SYSTEM
  40
  41        This tool includes a very simple tracking system to log which packages
  42     have been installed using the tool. It is used to skip installed packages
  43     from target selection menu and to test if an installed package has been
  44     updated in the BLFS book. Do not rely on this feature as a package
  45     management tool.
  46
  47        The directory where tracking files will be stored needs to be created
  48     before installing blfs-tool. You can place this directory anywhere, taking
  49     care that the user must have read and write privileges on that directory
  50     and on all files it contains.
  51
  52        To use the default path set in the installation menu, run as root:
  53
  54     install -d -m1777 /var/lib/jhalfs/BLFS
  55
  56   3.2  BLFS_TOOL INSTALLATION::
  57
  58        Run "make" to launch the jhalfs menuconfig interface. Select the BLFS
  59     book and version. Then set the installation directory (default
  60     $HOME/blfs_root), the BLFS sources directory (default blfs-xml), and
  61     the installed packages tracking directory (default /var/lib/jhalfs/BLFS).
  62
  63        All required files will be placed in the installation directory and
  64     BLFS XML sources will be installed in the named sub-directory.
  65
  66        Installed files:
  67
  68     blfs-xml/*         SVN tree of the selected BLFS book version
  69     lib/*              functions libraries, xsl stylesheets, and auto-generated
  70                        meta-packages dependencies tree files
  71     menu/*             lxdialog and menuconfig source code
  72     README.BLFS        this file
  73     TODO               developers notes
  74     update_book.sh     update the XML book sources and regenerates packages
  75                        database and meta-packages dependencies tree
  76     gen_config.sh      regenerates Config.in
  77     gen_pkg_book.sh    resolves dependencies and generates linear BLFS books
  78                        and build scripts
  79     gen-makefile.sh    generates the target Makefile
  80     progress_bar.sh    the target Makefile progress bar
  81     Makefile           run gen_config.sh to update Config.in,
  82                        then launch the menuconfig interface, and lastly run
  83                        gen_pkg_book.sh based on configuration settings
  84     Config.in          menuconfig interface input file
  85     packages           auto-generated packages database
  86     envars.conf        envars needed when running the target build scripts
  87
  88        From now on, all the work must be done from inside the installation
  89     root directory.
  90
  91        When finished the installation, the configuration and target selection
  92     menu is launch.
  93
  94   3.3  UPDATING BOOK SOURCES::
  95
  96        If you are using the development book version and you want to update
  97     installed packages to the latest version found in that book, you need to
  98     update the XML sources and packages database.
  99
 100        To do that run "./update_book.sh"
 101
 102        On the next configuration run, packages already installed but listed
 103     with a new version in the book will be available for target selection
 104     and used to solve dependencies.
 105
 106   3.4  CONFIGURING AND PARSING THE BOOK::
 107
 108        The next step is to create a book and build scripts in dependency
 109     build order for a target package. A target can be a package or a
 110     meta-package.
 111
 112     WARNING:
 113            Only one target (meta-package or individual package) must be
 114            selected on each configuration run.
 115            There is no way to solve dependencies properly when more
 116            than one target are selected.
 117
 118        Run <make> to launch the configuration interface. The main menu contains
 119     three blocks: meta-package selection, individual package selection, and
 120     build options.
 121
 122        When a meta-package is selected, it is possible to unselect unwanted
 123     components. The unselected components will be skipped if no other components
 124     depends on them.
 125
 126        In the build options section, the dependencies level and default packages
 127     used to solve alternatives are set. You can also select whether the build will
 128     be made as a normal user or as root. That settings are saved to be reused in
 129     future configuration runs.
 130
 131        If, for example, your target selection is Xsoft-->Graphweb-->galeon, a
 132     directory named "galeon" will be created. Inside that directory you will
 133     find a directory named "HTML" that contains a galeon-based HTML book with
 134     its dependencies in build order, and a "scripts" directory with build
 135     scripts for that packages.
 136
 137        There are also two other directories ("dependencies" and "xincludes")
 138     that contain files generated while resolving dependencies trees.
 139
 140   3.5  EDITING BUILD SCRIPTS
 141
 142        Now it is time to review the generated book and scripts, making any changes
 143     to the scripts necessary to fix generation bugs or to suit your needs.
 144
 145        Scripts for additional packages (i.e., for non-BLFS packages) can be
 146     easily inserted. For example, if you want to install the external dependency
 147     "bar" before "foo" package and the "foo" script is named "064-z-foo", you
 148     need to create a "064-y-bar" build script.
 149
 150       Remember, the package tracking system isn't a package management tool
 151     and knows nothing about packages not in the BLFS book.
 152
 153       Also, review and edit envars.conf. This file is used to set global envars
 154     needed by the build scripts.
 155
 156   3.6  CREATING THE MAKEFILE
 157
 158        When the build scripts are ready to be run, the Makefile can be
 159     created. Be sure that you cd into the "package" directory and run
 160     ../gen-makefile.sh
 161
 162     Review the Makefile, and, if all looks sane, start the build.
 163
 164 4. GENERATED BUILD SCRIPTS ISSUES::
 165
 166       In this section, known issues with the generated build scripts are
 167    discussed. They are due to build procedures and/or BLFS layout particularities
 168    that we can't handle. In several cases, editing the build scripts is mandatory.
 169    You may also need to insert some build scripts created by you to resolve
 170    unhandled dependencies and/or to remove some script installing the affected
 171    package by hand.
 172
 173    4.1  BLFS BOOTSCRIPTS
 174
 175         For now, bootscripts installation will fail. You will need to edit
 176      the scripts for packages that install bootscripts and fix their
 177      installation command. That could be fixed in the future.
 178
 179    4.2  PACKAGE CONFIGURATION
 180
 181         For those packages that have a "Configuration" section, you should
 182      edit the build script to fit the needs of your system.
 183
 184    4.4  PDL, Perl modules, and Glib-Bindings.
 185
 186         The generated scripts for these packages are broken and can not
 187      be fixed. You must rename it as the sub-package to be installed and
 188      edit it to use the proper commads for that sub-package.
 189
 190         You may need to create additional scripts for these sub-package
 191      dependencies, if any.
 192
 193    4.4  GCC, JDK, Sane, and KDE-multimedia, freetype2, MesaLib and others
 194
 195         On the pages for these packages, the BLFS book actually has instructions
 196      to download and install two or more packages. You must edit the scripts to
 197      fix this.
 198
 199         We will try to fix some of them, but this may not be possible.
 200
 201    4.5  XORG7
 202
 203         The generated scripts for Xorg7 pseudo-packages have $SRC_ARCHIVE
 204      support for individual packages, but not for patches nor *.wget and *.md5
 205      files.
 206
 207         If you have previously downloaded the patches, you must edit
 208      the scripts to use your local packages.
 209
 210        The *.wget and *.md5 files should be downladed always from inside
 211      the scripts to be sure that the most current individual packages are
 212      used. Thus don't reuse previouly existing ones.
 213
 214        In the script for xorg7-font, be sure to move the fonts directories
 215      symlinks creation to after the "for ... done" loop.
 216
 217    4.6  PATCHES
 218
 219         By default, all required patches will be downloaded from the NET.
 220
 221         If you have previously downloaded the patches, you must edit the
 222      scripts to use your local patches.
 223
 224         Also, be sure that all scripts have the commands to download/apply the
 225      required patches. Due to book layout issues, some patches may be missing.
 226
 227    4.7  ROOT COMMANDS
 228
 229         If building as a normal user (the default setting), be sure that all
 230      commands that require root privileges are run using sudo. Also make sure
 231      necessary root privilege commands are visible in your PATH.
 232
 233         Due to book layout issues, some sudo commands may be missing.
 234
 235    4.8  OTHERS
 236
 237         There may be other issues that we are not aware of. If you find
 238      any, please report it to <alfs-discuss@linuxfromscratch.org>.
 239
 240