Changeset 392bd25 for README.BLFS


Ignore:
Timestamp:
07/05/2007 06:37:13 PM (17 years ago)
Author:
George Boudreau <georgeb@…>
Branches:
2.3, 2.3.x, 2.4, ablfs, ablfs-more, legacy, new_features, trunk
Children:
615ba88
Parents:
f600e66
Message:

1st pass at documentation housekeeping

File:
1 edited

Legend:

Unmodified
Added
Removed

  • README.BLFS

    rf600e66 r392bd25  
    331. INTRODUCTION::
    44
    5      To automatize packages build from the BLFS book instructions is a huge
    6   task. The BLFS book isn't linear, some package pages need to use a non
    7   default layout, there are circular dependencies, several packages can be
    8   installed on a non default prefix, build commands can change based on what
    9   dependencies will be used, etc.
    10 
    11      Said that, the goal of blfs-tool is try to help you solving packages
    12   dependencies and creating your own build scripts and Makefile. Few of the
    13   auto-generated build scripts and Makefile could work "as is", thus as a
    14   general rule you will need to review and edit the scripts while reading
    15   the book.
     5     To automate package builds from the BLFS book instructions is a huge
     6  task. Some of the issues are: the BLFS book isn't linear; some package
     7  pages use a custom layout; there are circular dependencies; several
     8  packages can be installed on a non-default prefix; build commands can
     9  change based on what dependencies will be used, etc.
     10
     11     That being said, the goal of the blfs-tool is to help you solve package
     12  dependencies, create build scripts and a Makefile. Few of the auto-generated
     13  build scripts and Makefile will work "as is", thus, as a general rule,
     14  you will need to review and edit the scripts while reading the book.
    1615
    1716
    18172. PREREQUISITES::
    1918
    20      To use this tool you MUST to:
     19     To use this tool you MUST:
    2120
    2221     - have experience building BLFS packages
    … …  
    31303. USAGE::
    3231
    33      Due the complexity of the BLFS book, the scripts and Makefile generation is
    34   done in several steps:
     32     Due the complexity of the BLFS book, the scripts and Makefile generation
     33  is done in several steps:
    3534
    3635  3.1  INSTALLED PACKAGES TRACKING SYSTEM
    3736
    38        This tool includes a very simple tracking system to know what packages
    39     has been installed using the tool. It is used to skip installed packages
    40     from target selection menu and to know if an installed package has been updated
    41     on the BLFS book. Don't rely on this feature as a packages management tool.
    42 
    43        The directory where tracking files will be stored need be created
    44     before installing blfs-tool. You can place that directory anywhere, taking
    45     care that the builder user must have read and write privileges on that
    46     directory and on all files it contains.
     37       This tool includes a very simple tracking system to log which packages
     38    have been installed using the tool. It is used to skip installed packages
     39    from target selection menu and to test if an installed package has been
     40    updated in the BLFS book. Do not rely on this feature as a package
     41    management tool.
     42
     43       The directory where tracking files will be stored needs to be created
     44    before installing blfs-tool. You can place this directory anywhere, taking
     45    care that the user must have read and write privileges on that directory
     46    and on all files it contains.
    4747
    4848       To use the default path set in the installation menu, run as root:
    … …  
    5353
    5454       Run "make" to launch the jhalfs menuconfig interface. Select the BLFS
    55     book and it version. Then set the installation directory (default
     55    book and version. Then set the installation directory (default
    5656    $HOME/blfs_root), the BLFS sources directory (default blfs-xml), and
    5757    the installed packages tracking directory (default /var/lib/jhalfs/BLFS).
    5858
    5959       All required files will be placed in the installation directory and
    60     BLFS XML sources will be checkout to the named sub-directory.
     60    BLFS XML sources will be installed in the named sub-directory.
    6161
    6262       Installed files:
    … …  
    7171                       database and meta-packages dependencies tree
    7272    gen_config.sh      regenerates Config.in
    73     gen_pkg_book.sh    solve dependencies and generates linear BLFS books
     73    gen_pkg_book.sh    resolves dependencies and generates linear BLFS books
    7474                       and build scripts
    75     gen-makefile.sh    generates target Makefile
     75    gen-makefile.sh    generates the target Makefile
    7676    progress_bar.sh    the target Makefile progress bar
    7777    Makefile           run gen_config.sh to update Config.in,
    … …  
    9090  3.3  UPDATING BOOK SOURCES::
    9191
    92        If using the development book version, and if you want to update already
    93     installed packages to the new version found in that book, you need to update
    94     the XML sources and packages database.
     92       If you are using the development book version and you want to update
     93    installed packages to the latest version found in that book, you need to
     94    update the XML sources and packages database.
    9595
    9696       To do that run "./update_book.sh"
    9797
    9898       On the next configuration run, packages already installed but listed
    99     with a new version in the book will be available for target selection and
    100     used to solve dependencies.
     99    with a new version in the book will be available for target selection
     100    and used to solve dependencies.
    101101
    102102  3.4  CONFIGURING AND PARSING THE BOOK::
    103103
    104        Next step is to create a book and build scripts in dependencies build order
    105     for a target package. A target can be a package or a meta-package.
     104       The next step is to create a book and build scripts in dependency
     105    build order for a target package. A target can be a package or a
     106    meta-package.
    106107
    107108    WARNING:
    108109           Only one target (meta-package or individual package) must be
    109110           selected on each configuration run.
    110            That is due that there is no way to solve dependencies properly
    111            when more than one target are selected at the same time.
     111           There is no way to solve dependencies properly when more
     112           than one target are selected.
    112113
    113114       Run <make> to launch the configuration interface. The main menu contains
    114     three block: meta-package selection, individual package selection, and
     115    three blocks: meta-package selection, individual package selection, and
    115116    build options.
    116117
    117        When a meta-package is selected is possible to unselect unwanted components.
    118     That unselected components will be skipped if no other components depends
    119     on them.
    120 
    121        In the build options section the dependencies level and default packages
    122     used to solve alternatives are set. Can be set also if the build will be
    123     made as a normal user or as root. That settings are saved to be reused on
     118       When a meta-package is selected, it is possible to unselect unwanted
     119    components. The unselected components will be skipped if no other components
     120    depends on them.
     121
     122       In the build options section, the dependencies level and default packages
     123    used to solve alternatives are set. You can also select whether the build will
     124    be made as a normal user or as root. That settings are saved to be reused in
    124125    future configuration runs.
    125126
    126        If, for example, your target selection is Xsoft-->Graphweb-->galeon a
     127       If, for example, your target selection is Xsoft-->Graphweb-->galeon, a
    127128    directory named "galeon" will be created. Inside that directory you will
    128129    find a directory named "HTML" that contains a galeon-based HTML book with
    … …  
    130131    scripts for that packages.
    131132
    132        There is also two other directories, "dependencies" and "xincludes", that
    133     contains files generated while resolving dependencies trees.
     133       There are also two other directories ("dependencies" and "xincludes")
     134    that contain files generated while resolving dependencies trees.
    134135
    135136  3.5  EDITING BUILD SCRIPTS
    136137
    137        Now is time to review the generated book and scripts, making in the
    138     scripts any changes required to fix generation bugs or to fit your needs.
     138       Now it is time to review the generated book and scripts, making any changes
     139    to the scripts necessary to fix generation bugs or to suit your needs.
    139140
    140141       Scripts for additional packages (i.e., for non-BLFS packages) can be
    141     inserted in an easy way due how the scripts are named. For example, if you
    142     want to install the external dependency "bar" before "foo" package and the
    143     "foo" script is named "064-z-foo", you need to create a "064-y-bar" build
    144     script.
    145 
    146       Remember that the packages tracking system isn't a packages management tool
    147     and know nothing about packages not in the BLFS book.
    148 
    149       Also, review and edit envars.conf. That file is used to set global envars
     142    easily inserted. For example, if you want to install the external dependency
     143    "bar" before "foo" package and the "foo" script is named "064-z-foo", you
     144    need to create a "064-y-bar" build script.
     145
     146      Remember, the package tracking system isn't a package management tool
     147    and knows nothing about packages not in the BLFS book.
     148
     149      Also, review and edit envars.conf. This file is used to set global envars
    150150    needed by the build scripts.
    151151
    … …  
    154154       When the build scripts are ready to be run, the Makefile can be
    155155    created. Be sure that you cd into the "package" directory and run
    156 
    157        ../gen_makefile.sh
    158 
    159     Review the Makefile and if all looks sane, start the build.
     156    ../gen-makefile.sh
     157
     158    Review the Makefile, and, if all looks sane, start the build.
    160159
    1611604. GENERATED BUILD SCRIPTS ISSUES::
    162161
    163       In this section known issues with the generated build scripts are
    164    discussed. They are due build procedures and/or BLFS layout particularities
    165    than we can't handle. In several cases editing the build scripts is mandatory.
    166    You may need also to insert some build script created by you to resolve
    167    unhanded dependencies and/or to remove some script installing the affected
     162      In this section, known issues with the generated build scripts are
     163   discussed. They are due to build procedures and/or BLFS layout particularities
     164   that we can't handle. In several cases, editing the build scripts is mandatory.
     165   You may also need to insert some build scripts created by you to resolve
     166   unhandled dependencies and/or to remove some script installing the affected
    168167   package by hand.
    169168
    170169   4.1  BLFS BOOTSCRIPTS
    171170
    172         For now, bootscripts installation will fail. You will need to edit the
    173      scripts for packages that install bootscripts and fix their installation
    174      command. That could be fixed in the future, but not sure.
    175 
    176    4.2  PACKAGES CONFIGURATION
    177 
    178         For that packages that have a "Configuration" section, you should to
    179      edit it build script to fit the configuration to your needs.
     171        For now, bootscripts installation will fail. You will need to edit
     172     the scripts for packages that install bootscripts and fix their
     173     installation command. That could be fixed in the future.
     174
     175   4.2  PACKAGE CONFIGURATION
     176
     177        For those packages that have a "Configuration" section, you should
     178     edit the build script to fit the needs of your system.
    180179
    181180   4.4  PDL and Perl modules.
    182181
    183         The generated scripts for that packages are plainly broken and can't
    184      be fixed. You must to replace it by your own ones or install that
     182        The generated scripts for these packages are broken and can not
     183     be fixed. You must replace them with your own scripts or install the
    185184     packages by hand.
    186185
    187186   4.4  GCC, JDK, Sane, and KDE-multimedia
    188187
    189         On the pages for that packages, the BLFS book actually have instructions
    190      to install two packages. You must to edit the scripts to fix it. We will
    191      try to fix some of them, but may not be possible.
     188        On the pages for these packages, the BLFS book actually has instructions
     189     to install two packages. You must edit the scripts to fix this.
     190
     191        We will try to fix some of them, but this may not be possible.
    192192
    193193   4.5  XORG7
    … …  
    196196     $SRC_ARCHIVE nor MD5 checking.
    197197
    198         If you has downloaded previously the packages, you must to edit the scripts
    199      to make it to use your local packages.
     198        If you have previously downloaded the packages, you must edit the
     199     scripts to use your local packages.
    200200
    201201        Also, you will need to edit the scripts to fix the commands that must
    202      be applied only to a concrete individual sub-package. For example the "for"
    203      loop to install xorg7-util packages may read like:
     202     be applied only to a concrete individual sub-package. For example, the
     203     "for" loop to install xorg7-util packages may read like:
    204204
    205205for package in $(cat $WGET_LST) ; do
    … …  
    220220done
    221221
    222         After reading the HTML page to know what commands is for what package,
     222        After reading the HTML page to find what command is for what package,
    223223     the loop can be changed to read something like:
    224224
    … …  
    246246   4.6  PATCHES
    247247
    248         By default all required patches will be downloaded from the NET.
    249 
    250         If you has downloaded previously the patches, you must to edit the scripts
    251      to make it to use your local patches.
     248        By default, all required patches will be downloaded from the NET.
     249
     250        If you have previously downloaded the patches, you must edit the
     251     scripts to use your local patches.
    252252
    253253        Also, be sure that all scripts have the commands to download/apply the
    254      required patches. Due book layout issues some patches may be missing.
     254     required patches. Due to book layout issues, some patches may be missing.
    255255
    256256   4.7  ROOT COMMANDS
    257257
    258         If building as a normal user (the default setting) be sure that all
    259      commands that need root privileges are run using sudo.
    260 
    261         Due book layout issues some sudo command may be missing.
     258        If building as a normal user (the default setting), be sure that all
     259     commands that require root privileges are run using sudo.
     260
     261        Due to book layout issues, some sudo commands may be missing.
    262262
    263263   4.8  OTHERS
    264264
    265         May have other issues that we are not aware on them yet. If you find
    266      someone, please report it to <alfs-discuss@linuxfromscratch.org>.
    267 
    268 
     265        There may be other issues that we are not aware of. If you find
     266     any, please report it to <alfs-discuss@linuxfromscratch.org>.
     267
     268
Note: See TracChangeset for help on using the changeset viewer.