| 1 | $Id$
|
|---|
| 2 |
|
|---|
| 3 | 1. INTRODUCTION::
|
|---|
| 4 |
|
|---|
| 5 | If you want to add blfs-tool support into an 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 tracking system itself is an XML file: instpkg.xml. It is
|
|---|
| 48 | initialized when make is first run in blfs_root. It resides in a directory
|
|---|
| 49 | which is created when needed during the process of building custom tools
|
|---|
| 50 | or blfs tools, after xLFS. You can specify that directory location in
|
|---|
| 51 | the blfs tools submenu of jhalfs. You may need to update permissions
|
|---|
| 52 | and/or ownership of this directory before using the blfs tool.
|
|---|
| 53 |
|
|---|
| 54 | The default location of the tracking directory is /var/lib/jhalfs/BLFS
|
|---|
| 55 |
|
|---|
| 56 | 3.2 BLFS_TOOL INSTALLATION::
|
|---|
| 57 |
|
|---|
| 58 | The tools are installed just after the building of xLFS, if the
|
|---|
| 59 | appropriate options have been selected in the building menu, as per
|
|---|
| 60 | jhalfs README. If you forgot to select the options and xLFS has been
|
|---|
| 61 | built, it is possible to go back to selecting the appropriate
|
|---|
| 62 | BLFS tools options in the jhalfs menu, then tick `Run makefile'
|
|---|
| 63 | and not `Rebuild files'. You obtain a /blfs_root directory in the
|
|---|
| 64 | root directory of the new xLFS system, which contains the followings:
|
|---|
| 65 |
|
|---|
| 66 | blfs-xml/* SVN tree of the selected BLFS book version
|
|---|
| 67 | lib/* functions libraries
|
|---|
| 68 | menu/* lxdialog and menuconfig source code
|
|---|
| 69 | xsl/* XSL stylesheets used at several stages of the process
|
|---|
| 70 | README.BLFS this file
|
|---|
| 71 | TODO developers notes (well, not often updated)
|
|---|
| 72 | gen_pkg_book.sh resolves dependencies and generates linear BLFS books
|
|---|
| 73 | and build scripts
|
|---|
| 74 | gen-makefile.sh generates the target Makefile
|
|---|
| 75 | progress_bar.sh the target Makefile progress bar
|
|---|
| 76 | gen-special.sh Helper script for generating the package database
|
|---|
| 77 | Makefile Used by make to update the package database from the SVN
|
|---|
| 78 | tree, then launch the menuconfig interface, and run
|
|---|
| 79 | gen_pkg_book.sh based on configuration settings
|
|---|
| 80 | packages.xml auto-generated packages database
|
|---|
| 81 | packdesc.dtd a simple DTD describing the format of the package
|
|---|
| 82 | database
|
|---|
| 83 | envars.conf envars needed when running the target build scripts
|
|---|
| 84 |
|
|---|
| 85 | From now on, all the work must be done from inside the installation
|
|---|
| 86 | root directory.
|
|---|
| 87 |
|
|---|
| 88 | You may move that directory to the $HOME of a non root user, or build
|
|---|
| 89 | as root from that directory.
|
|---|
| 90 |
|
|---|
| 91 | 3.3 UPDATING BOOK SOURCES::
|
|---|
| 92 |
|
|---|
| 93 | If you are using the development book version and you want to update
|
|---|
| 94 | installed packages to the latest version found in that book, you need to
|
|---|
| 95 | update the XML sources and packages database.
|
|---|
| 96 |
|
|---|
| 97 | To do that run "make update". It may happen that the subversion
|
|---|
| 98 | version of your building host is older than the version you just
|
|---|
| 99 | built. This may generate weird errors like "'.' omitted". The easiest
|
|---|
| 100 | thing to do in that case, is to completely remove the blfs-xml directory
|
|---|
| 101 | and run "make update".
|
|---|
| 102 |
|
|---|
| 103 | On the next configuration run, packages already installed but listed
|
|---|
| 104 | with a new version in the book will be available for target selection
|
|---|
| 105 | and used to solve dependencies.
|
|---|
| 106 |
|
|---|
| 107 | 3.4 CONFIGURING AND PARSING THE BOOK::
|
|---|
| 108 |
|
|---|
| 109 | The next step is to create a book and build scripts in dependency
|
|---|
| 110 | build order for one or several packages.
|
|---|
| 111 |
|
|---|
| 112 | Run <make> to launch the configuration interface. The main menu contains
|
|---|
| 113 | two blocks: individual package selection, and build options.
|
|---|
| 114 |
|
|---|
| 115 | In the build options section, the dependencies level and default packages
|
|---|
| 116 | used to solve alternatives are set (currently, only for the mTA). You can
|
|---|
| 117 | also select whether the build will be made as a normal user or as root.
|
|---|
| 118 | Those settings are saved to be reused in future configuration runs.
|
|---|
| 119 |
|
|---|
| 120 | When you are done with the menu, a few checks occur, and the book is
|
|---|
| 121 | generated. When circular dependencies are found, a 3 line message is
|
|---|
| 122 | printed:
|
|---|
| 123 | A is a dependency of B
|
|---|
| 124 | C is a dependency of A
|
|---|
| 125 | A is a dependency of C
|
|---|
| 126 | and a question:
|
|---|
| 127 | Do you want to build A first?
|
|---|
| 128 | This means that the system has found the dependency chain: B->A->C->A.
|
|---|
| 129 | You have therefore to choose whether A is built before C, or
|
|---|
| 130 | C before A: the system cannot make that choice (well, maybe in a few
|
|---|
| 131 | year, with an AI system able to understand the book). if you answer no,
|
|---|
| 132 | C is built first. If you answer yes, C is put in place of A as a dependency
|
|---|
| 133 | of B, then the tree dependency restarts from there, that is with the
|
|---|
| 134 | layout B->C->... You may then hit the case B->C->A->C, for which you
|
|---|
| 135 | should answer no, unless you want to enter an infinite (human driven) loop.
|
|---|
| 136 |
|
|---|
| 137 | You end up with a book.xml file which contains the linearized book,
|
|---|
| 138 | and a rendered HTML, in the directory book-html, which you can browse with
|
|---|
| 139 | "lynx book-html/index.html" (or with any other browser).
|
|---|
| 140 |
|
|---|
| 141 | Furthermore, there is a directory "scripts", which contains the generated
|
|---|
| 142 | scriptlets.
|
|---|
| 143 |
|
|---|
| 144 | There is also another directory, "dependencies" that contains files
|
|---|
| 145 | generated while resolving dependencies.
|
|---|
| 146 |
|
|---|
| 147 | 3.5 EDITING BUILD SCRIPTS
|
|---|
| 148 |
|
|---|
| 149 | Now it is time to review the generated book and scripts, making any
|
|---|
| 150 | changes to the scripts necessary to fix generation bugs or to suit your
|
|---|
| 151 | needs.
|
|---|
| 152 |
|
|---|
| 153 | Scripts for additional packages (i.e., for non-BLFS packages) can be
|
|---|
| 154 | easily inserted. For example, if you want to install the external dependency
|
|---|
| 155 | "bar" before "foo" package and the "foo" script is named "064-z-foo", you
|
|---|
| 156 | just need to create a "064-y-bar" build script.
|
|---|
| 157 |
|
|---|
| 158 | Remember, the package tracking system isn't a package management tool
|
|---|
| 159 | and knows nothing about packages not in the BLFS book.
|
|---|
| 160 |
|
|---|
| 161 | Also, review and edit envars.conf. This file is used to set global envars
|
|---|
| 162 | needed by the build scripts.
|
|---|
| 163 |
|
|---|
| 164 | 3.6 CREATING THE MAKEFILE
|
|---|
| 165 |
|
|---|
| 166 | When the build scripts are ready to be run, the Makefile can be
|
|---|
| 167 | created. Create an empty directory (for example "mkdir work") and cd
|
|---|
| 168 | to that directory. Then run ../gen-makefile.sh
|
|---|
| 169 |
|
|---|
| 170 | Review the Makefile, and, if all looks sane, start the build by running
|
|---|
| 171 | "make".
|
|---|
| 172 |
|
|---|
| 173 | 4. GENERATED BUILD SCRIPTS ISSUES::
|
|---|
| 174 |
|
|---|
| 175 | In this section, known issues with the generated build scripts are
|
|---|
| 176 | discussed. They are due to build procedures and/or BLFS layout
|
|---|
| 177 | particularities that we can't handle. In several cases, editing the
|
|---|
| 178 | build scripts is mandatory.
|
|---|
| 179 | You may also need to insert some build scripts created by you to resolve
|
|---|
| 180 | unhandled dependencies and/or to remove some script installing the affected
|
|---|
| 181 | package by hand.
|
|---|
| 182 |
|
|---|
| 183 | 4.1 BLFS BOOTSCRIPTS
|
|---|
| 184 |
|
|---|
| 185 | Normally, bootscript installation should work. On the other hand, the
|
|---|
| 186 | book does not give instruction for running them, so you might have to
|
|---|
| 187 | manually insert /etc/init.d/<initscript> at some place during the build.
|
|---|
| 188 |
|
|---|
| 189 | 4.2 PACKAGE CONFIGURATION
|
|---|
| 190 |
|
|---|
| 191 | For those packages that have a "Configuration" section, you should
|
|---|
| 192 | edit the build script to fit the needs of your system. Sometimes, the
|
|---|
| 193 | bash startup files are modified (see for example the instructions for
|
|---|
| 194 | llvm). You might have to insert something like "source /etc/bash_profile"
|
|---|
| 195 | at some point during the build.
|
|---|
| 196 |
|
|---|
| 197 | 4.4 GCC, JDK, Sane, and KDE-multimedia, freetype2, MesaLib and others
|
|---|
| 198 |
|
|---|
| 199 | On the pages for those packages, the BLFS book actually has instructions
|
|---|
| 200 | to download and install two or more packages. You must edit the scripts to
|
|---|
| 201 | fix this.
|
|---|
| 202 |
|
|---|
| 203 | We will try to fix some of them, but this may not be possible.
|
|---|
| 204 |
|
|---|
| 205 | 4.5 XORG7
|
|---|
| 206 |
|
|---|
| 207 | The generated scripts for Xorg7 packages have $SRC_ARCHIVE
|
|---|
| 208 | support for individual packages, but not for patches nor *.wget and *.md5
|
|---|
| 209 | files.
|
|---|
| 210 |
|
|---|
| 211 | If you have previously downloaded the patches, you must edit
|
|---|
| 212 | the scripts to use your local packages.
|
|---|
| 213 |
|
|---|
| 214 | The *.wget and *.md5 files should be downladed always from inside
|
|---|
| 215 | the scripts to be sure that the most current individual packages are
|
|---|
| 216 | used. Thus don't reuse previously existing ones.
|
|---|
| 217 |
|
|---|
| 218 | In the script for xorg7-font, be sure to move the fonts directories
|
|---|
| 219 | symlinks creation to after the "for ... done" loop.
|
|---|
| 220 |
|
|---|
| 221 | 4.6 PATCHES
|
|---|
| 222 |
|
|---|
| 223 | By default, all required patches will be downloaded from the NET.
|
|---|
| 224 |
|
|---|
| 225 | If you have previously downloaded the patches, you must edit the
|
|---|
| 226 | scripts to use your local patches.
|
|---|
| 227 |
|
|---|
| 228 | Also, be sure that all scripts have the commands to download/apply the
|
|---|
| 229 | required patches. Due to book layout issues, some patches may be missing.
|
|---|
| 230 |
|
|---|
| 231 | 4.7 ROOT COMMANDS
|
|---|
| 232 |
|
|---|
| 233 | If building as a normal user (the default setting), be sure that all
|
|---|
| 234 | commands that require root privileges are run using sudo. Also make sure
|
|---|
| 235 | necessary root privilege commands are visible in your PATH.
|
|---|
| 236 |
|
|---|
| 237 | Due to book layout issues, some sudo commands may be missing.
|
|---|
| 238 |
|
|---|
| 239 | 4.8 OTHERS
|
|---|
| 240 |
|
|---|
| 241 | There may be other issues that we are not aware of. If you find
|
|---|
| 242 | any, please report it to <alfs-discuss@linuxfromscratch.org>.
|
|---|
| 243 |
|
|---|
| 244 |
|
|---|
