[877cc6a] | 1 | 1. INTRODUCTION::
|
---|
[4457252] | 2 |
|
---|
[cc8dba9] | 3 | The scripts in this directory implement an automation of the building
|
---|
| 4 | of a GNU/LInux system, as described in the Linux From Scratch book series.
|
---|
| 5 | The name of the project is jhalfs: in that name, "alfs" stands for
|
---|
| 6 | "automated linux from scratch", and the initials "jh" have been kept since
|
---|
| 7 | the original "jhalfs-0.2" code developed by Jeremy Huntwork.
|
---|
| 8 |
|
---|
| 9 | The list of supported books can be found at
|
---|
| 10 | http://wiki.linuxfromscratch.org/alfs/wiki/SupportedBooks.
|
---|
| 11 |
|
---|
| 12 | The documentation is split among various README.* files. Here is a list
|
---|
| 13 | of what is in which:
|
---|
| 14 | - README (this file): instructions to use the LFS book. This should be
|
---|
| 15 | enough if you just want to build a base system as per the LFS book. It is
|
---|
| 16 | also a required reading for all the other projects.
|
---|
| 17 | - README.BLFS: instructions to install an automated build infrastructure
|
---|
| 18 | for the BLFS book. There are two ways to do so: (i) install the
|
---|
[0fa52f2] | 19 | tools at the end of an LFS build, or
|
---|
[cc8dba9] | 20 | (ii) install the tools on an already running system. Both methods are
|
---|
| 21 | described in that file.
|
---|
| 22 | - README.CUSTOM: instructions to run custom commands either during the xLFS
|
---|
| 23 | build, at the end of a xLFS build. Note that you will not find
|
---|
| 24 | instructions on how to write those commands, but some examples are
|
---|
| 25 | available.
|
---|
| 26 | - README.PACKAGE_MANAGEMENT: instructions to use package management during
|
---|
[0fa52f2] | 27 | the build
|
---|
[cc8dba9] | 28 |
|
---|
| 29 | Other sources of information are the context help in the menu interface,
|
---|
| 30 | and the xLFS books themselves.
|
---|
[3e7ceed] | 31 |
|
---|
[f4ed135] | 32 | 2. PREREQUISITES::
|
---|
| 33 |
|
---|
[cc8dba9] | 34 | As said elsewhere, it is strongly advised that you first build manually
|
---|
| 35 | a complete system before attempting to automate the build.
|
---|
[f4ed135] | 36 |
|
---|
[cc8dba9] | 37 | Of course the "Host System Requirements" should be fulfilled. The needed
|
---|
| 38 | supplementary packages are detailed at the bottom of the page:
|
---|
[f9a7f8e] | 39 | https://www.linuxfromscratch.org/alfs/download.html. In short, you need
|
---|
| 40 | wget, sudo, libxml2, libxslt, docbook-4.5-xml, and docbook-xsl-nons.
|
---|
[f4ed135] | 41 |
|
---|
| 42 | 3. INSTALLATION::
|
---|
[597d802] | 43 |
|
---|
[cc8dba9] | 44 | No installation is required. You may want to move the files in this
|
---|
| 45 | directory to a convenient location, and then follow the instructions below.
|
---|
[877cc6a] | 46 |
|
---|
[50b1fb7] | 47 | 4. CONFIGURATION::
|
---|
[877cc6a] | 48 |
|
---|
[cc8dba9] | 49 | 4.1. CONFIGURATION OF THE TOOLS:
|
---|
| 50 | There is no configuration of the tools themselves. The various
|
---|
| 51 | parameters for the build are set through a menu driven interface. See
|
---|
| 52 | the section RUNNING below for details.
|
---|
| 53 |
|
---|
| 54 | 4.2. PRELIMINARY TASKS:
|
---|
| 55 | This tool has no support at all for creating a partition and a mount
|
---|
| 56 | point for the built system. You should follow the book up to the section
|
---|
| 57 | "Mounting the new partition". Note that the default name for the
|
---|
| 58 | partition mount point is "/mnt/build_dir", instead of /mnt/{c,}lfs.
|
---|
| 59 | You can change that default to anything you'd like in the menu, so you
|
---|
[b7583ec] | 60 | may name it /mnt/lfs, or whatever you like. We'll use the name
|
---|
| 61 | /mnt/build_dir in the sequel.
|
---|
[cc8dba9] | 62 |
|
---|
| 63 | The tool can download the needed packages for you, or you may download
|
---|
| 64 | them yourself. The tool may optionally use a package archive directory
|
---|
| 65 | where the downloaded packages are stored. That directory name may be made
|
---|
| 66 | available to the tool in two ways: (i) export the SRC_ARCHIVE variable,
|
---|
| 67 | for example SRC_ARCHIVE=/usr/src, (ii) enter the name at the "Package
|
---|
| 68 | Archive Directory" menu prompt. Note that the user should have write
|
---|
| 69 | permission to that directory. If a needed package is found in that
|
---|
| 70 | directory, it is copied to /mnt/build_dir/sources, if not, it is
|
---|
| 71 | downloaded to that directory and copied to /mnt/build_dir/sources,
|
---|
| 72 | except if found in /mnt/build_dir/sources, in which case, it is just
|
---|
| 73 | copied to $SRC_ARCHIVE. If you want the tool to download packages and you
|
---|
| 74 | do not want to archive them, just unset SRC_ARCHIVE, and keep the
|
---|
| 75 | default entry for "Package Archive Directory". If you choose to download
|
---|
| 76 | the packages by yourself, you should download (or copy) them to
|
---|
| 77 | /mnt/build_dir/sources directly.
|
---|
[2e1c1c3] | 78 |
|
---|
[cc8dba9] | 79 | If you want to build the kernel as part of the automated build, select
|
---|
| 80 | "Build the kernel" in the menu. Then, a configuration file must be
|
---|
| 81 | provided. In order to do so, it is recommended to download the kernel
|
---|
[f9a7f8e] | 82 | tarball, unpack it, run <make menuconfig> (or any other *config),
|
---|
| 83 | configure the kernel as per
|
---|
[cc8dba9] | 84 | the book, and save the resulting .config file to a location where it can
|
---|
| 85 | be retrieved later on (a convenient location and name is
|
---|
| 86 | $SRC_ARCHIVE/config-<arch>-<kernel version>-<config details>).
|
---|
| 87 |
|
---|
| 88 | Another file you may provide is the fstab file. To use it, select
|
---|
| 89 | "Use a custom fstab file" in the menu interface, and enter the name of
|
---|
| 90 | the file where asked. As for the kernel configuration, this file has to
|
---|
| 91 | be prepared before running the menu. A convenient location and name is
|
---|
| 92 | $SRC_ARCHIVE/fstablfs.
|
---|
| 93 |
|
---|
| 94 | At a more advanced level, you may want to supply custom commands
|
---|
| 95 | to be run at the end of (C)LFS build. Scripts containing those commands
|
---|
| 96 | are located in the ./custom/config directory. Examples are given in
|
---|
| 97 | ./custom/examples. A template is provided as ./custom/template. See
|
---|
| 98 | README.CUSTOM for more details.
|
---|
[a705708] | 99 |
|
---|
[f4ed135] | 100 | 5. RUNNING::
|
---|
[7785f91] | 101 |
|
---|
[b7583ec] | 102 | IMPORTANT::
|
---|
| 103 | You must be logged as a normal user with sudo privileges to run
|
---|
| 104 | the Makefile. Furthermore, you are supposed to have enough privilege
|
---|
| 105 | to become any user. If you are not bothered about security issues,
|
---|
| 106 | the entry for the user "jhalfs_user" in /etc/sudoers could be
|
---|
| 107 | jhalfs_user ALL=(ALL) NOPASSWD:ALL
|
---|
| 108 |
|
---|
[cc8dba9] | 109 | The command <make> will launch a menu based configuration program. The
|
---|
| 110 | underlying menu code was borrowed from BusyBox and slightly modified for
|
---|
| 111 | our use.
|
---|
[7785f91] | 112 |
|
---|
[6acdc9c] | 113 | Help on parameter function is available from the on-line help. Please
|
---|
[cc8dba9] | 114 | make use of that feature: it may contain additional information not
|
---|
| 115 | duplicated in this file.
|
---|
[c7c32a3] | 116 |
|
---|
| 117 | You should first choose which book and flavour you want to build. Note
|
---|
[cc8dba9] | 118 | that when you choose the BLFS book, the tool will just install the BLFS
|
---|
| 119 | tool to your system. You'll have to run that installed tool to build
|
---|
| 120 | packages in BLFS. See README.BLFS to know how. If you choose any other
|
---|
| 121 | book, you'll have to configure the settings and the build parameters
|
---|
| 122 | from the menu. Note that you may choose to install the blfs tools onto
|
---|
| 123 | the newly built system. It is not the same thing as choosing
|
---|
| 124 | the BLFS book in the menu, which will install the blfs tools on the
|
---|
| 125 | currently running system.
|
---|
| 126 |
|
---|
| 127 | The "General Settings" menu is where the "Build Directory" name is to be
|
---|
| 128 | entered. Other entries in that menu select what the tool should do. The
|
---|
| 129 | "Run the Makefile" entry selects whether the tool will start the build
|
---|
| 130 | automatically after generating the needed files. The "Rebuild files" selects
|
---|
| 131 | whether to clean the build directory before doing anything else. To protect
|
---|
| 132 | against removing important files, this can only be done in an empty directory,
|
---|
| 133 | or a directory previously populated by the tool.
|
---|
| 134 |
|
---|
| 135 | The "Build Settings" menu is where various options for the build can be
|
---|
| 136 | selected. Two options, "Use a custom fstab file" and "Build the kernel",
|
---|
| 137 | have been described above. "Do not use/display progress_bar", if set, will
|
---|
| 138 | prevent a progress bar to be displayed during the build. That may be useful
|
---|
| 139 | on slow machine. The other options should be self explanatory, using either
|
---|
| 140 | the online help or book reading.
|
---|
| 141 |
|
---|
| 142 | The "Advanced Features" menu is for various maintenance tasks, like
|
---|
| 143 | testing the build instructions or reporting build statistics. One useful
|
---|
| 144 | option is "Optimization and parallelisation". It is not recommended to use
|
---|
| 145 | it for setting compiler optimization flags, although it is possible, but
|
---|
| 146 | if you select it, you'll be able to select the number of parallel `make'
|
---|
| 147 | jobs, which allows much faster builds on modern multicore CPUs.
|
---|
[c7c32a3] | 148 |
|
---|
| 149 | Once you have set the parameters and saved the configuration, the script
|
---|
[cc8dba9] | 150 | is launched. Its aim is to extract instructions from the selected book
|
---|
| 151 | to generate scripts, and to generate a Makefile, which allows running
|
---|
| 152 | the scripts in the right order. The script verifies first that the host
|
---|
| 153 | can run itself and build the xLFS system, then validates the configuration
|
---|
| 154 | and lists the parameters. At this point, you may choose to quit or to
|
---|
| 155 | continue with the listed parameters. The script will then proceed to
|
---|
| 156 | generate the Makefile and the build scripts, optionally download
|
---|
| 157 | packages, and eventually verify the host prerequisite. If you have
|
---|
| 158 | selected "Run the makefile", the command <make> is launched in the
|
---|
| 159 | adequate directory, and the build begins. If not, you'll have to run
|
---|
| 160 | "make" manually, for example: "make -C /mnt/build_dir/jhalfs", if you
|
---|
| 161 | have used the default parameters (see the layout under $BUILDDIR in the
|
---|
| 162 | Q&A below).
|
---|
| 163 |
|
---|
| 164 | NOTE::
|
---|
| 165 | If you run the jhalfs script directly the only function you can select
|
---|
| 166 | is to display the version number by running <./jhalfs -v>
|
---|
| 167 |
|
---|
| 168 | 6. LAYOUT::
|
---|
[877cc6a] | 169 |
|
---|
[0fa52f2] | 170 | /BLFS/* (see README.BLFS)
|
---|
[d517356] | 171 |
|
---|
[50b1fb7] | 172 | /LFS/master.sh
|
---|
| 173 | /lfs.xsl
|
---|
[b240ee6] | 174 |
|
---|
[0fa52f2] | 175 | /common/chroot.xsl
|
---|
| 176 | /common_functions
|
---|
| 177 | /create-sbu_du-report.sh
|
---|
| 178 | /hostreqs.xsl
|
---|
| 179 | /kernfs.xsl
|
---|
[b240ee6] | 180 | /makefile_functions
|
---|
[50b1fb7] | 181 | /packages.xsl
|
---|
| 182 | /progress_bar.sh
|
---|
[0fa52f2] | 183 | /urls.xsl
|
---|
[fe30c61] | 184 | /libs/func_*
|
---|
[b240ee6] | 185 |
|
---|
[0fa52f2] | 186 | /custom/examples/*
|
---|
| 187 | /config/* (needs to be created after cloning since it is an
|
---|
| 188 | empty directory initially)
|
---|
| 189 | /template
|
---|
[b240ee6] | 190 |
|
---|
[50b1fb7] | 191 | /extras/do_copy_files
|
---|
[b240ee6] | 192 | /do_ica_prep
|
---|
| 193 | /do_ica_work
|
---|
| 194 |
|
---|
[0fa52f2] | 195 | /menu/*
|
---|
| 196 |
|
---|
[50b1fb7] | 197 | /optimize/opt_config
|
---|
| 198 | /opt_override
|
---|
| 199 | /optimize_functions
|
---|
| 200 | /opt_config.d/noOpt
|
---|
| 201 | /noSymbols
|
---|
[0fa52f2] | 202 | /O2pipe
|
---|
[50b1fb7] | 203 | /O3pipe
|
---|
| 204 | /O3pipe_march
|
---|
| 205 | /defOpt_fPIC
|
---|
| 206 |
|
---|
[0fa52f2] | 207 | /pkgmngt/packageManager.xml.dpkg
|
---|
| 208 | /packageManager.xml.pacman
|
---|
| 209 | /packageManager.xml.porg
|
---|
| 210 | /packageManager.xml.template
|
---|
| 211 | /packInstall.sh.dpkg
|
---|
| 212 | /packInstall.sh.pacman
|
---|
| 213 | /packInstall.sh.porg
|
---|
| 214 | /packInstall.sh.template
|
---|
| 215 |
|
---|
| 216 | CHEATSHEET
|
---|
| 217 | FUNCTION_LIST
|
---|
| 218 | LICENSE
|
---|
[597d802] | 219 | README
|
---|
[50b1fb7] | 220 | README.BLFS
|
---|
[daa489d] | 221 | README.CUSTOM
|
---|
[0fa52f2] | 222 | README.PACKAGE_MANAGEMENT
|
---|
[50b1fb7] | 223 | TODO
|
---|
[d3b8635] | 224 |
|
---|
[50b1fb7] | 225 | Config.in
|
---|
| 226 | jhalfs
|
---|
[0fa52f2] | 227 | Makefile
|
---|
[d3b8635] | 228 |
|
---|
[cc8dba9] | 229 | 7. FAQ::
|
---|
| 230 | Q. "It doesn't work"
|
---|
| 231 | A. There are several reasons why it may be so. One possibility is the
|
---|
[b15261a] | 232 | following: jhalfs was designed to work against the development versions
|
---|
| 233 | of the LFS series of books. Consequently changes in a book sometimes
|
---|
| 234 | break older versions of jhalfs. Before you start pulling out your hair,
|
---|
[cc8dba9] | 235 | download the latest version of jhalfs to see if that solves your
|
---|
| 236 | problem. Note that it may be the other way around. If you want to build
|
---|
[b15261a] | 237 | an old version of the book, you may have to downgrade your jhalfs
|
---|
[cc8dba9] | 238 | version.
|
---|
[d3b8635] | 239 |
|
---|
[e51d4db] | 240 | Q. "How do I specify the build location?"
|
---|
[fbdd1a8] | 241 | A. The original LFS document worked against the well known location
|
---|
| 242 | /mnt/lfs. This script automates the build of all of the LFS series of
|
---|
| 243 | books and uses a generic location $BUILDDIR with a default value of
|
---|
| 244 | /mnt/build_dir. You may change this value to suit your needs.
|
---|
[d3b8635] | 245 |
|
---|
[511923a] | 246 | The layout below $BUILDDIR is as follows.
|
---|
| 247 | $BUILDDIR/
|
---|
[50b1fb7] | 248 | jhalfs (Makefile, cmd scripts, logs, etc..)
|
---|
| 249 | sources (where packages reside)
|
---|
[0fa52f2] | 250 | tools (temporary cross compiler)
|
---|
[50b1fb7] | 251 | ...
|
---|
| 252 | FHS dir structure
|
---|
| 253 | ...
|
---|
| 254 | blfs_root (files to use blfs-tool if selected to install it)
|
---|
[d3b8635] | 255 |
|
---|
[e51d4db] | 256 | Q. "What is the function of the SRC_ARCHIVE variable?"
|
---|
[50b1fb7] | 257 | A. When jhalfs runs and packages download was selected, it creates a local
|
---|
[b15261a] | 258 | copy of the necessary packages in $BUILDDIR/sources by downloading the
|
---|
[50b1fb7] | 259 | files. If the variable SRC_ARCHIVE is defined the software will first
|
---|
| 260 | look in this location for the file and, if found, will copy it to
|
---|
[b15261a] | 261 | $BUILDDIR/sources.
|
---|
[73e5448] | 262 | If the files are not found in SRC_ARCHIVE _and_ you have write priv to
|
---|
[f4b3d20] | 263 | the directory any downloaded files will be mirrored there.
|
---|
[d3b8635] | 264 |
|
---|
[e51d4db] | 265 | Q. "How do I set the SRC_ARCHIVE location?"
|
---|
[511923a] | 266 | A. The best way to set the value of SRC_ARCHIVE is
|
---|
[50b1fb7] | 267 |
|
---|
[511923a] | 268 | export SRC_ARCHIVE=/wherever/you/store/downloaded/packages
|
---|
[50b1fb7] | 269 |
|
---|
| 270 | or you can set the full path in the proper menu entry.
|
---|
[d3b8635] | 271 |
|
---|
[e51d4db] | 272 | Q. "Why have 2 copies of the files?"
|
---|
[73e5448] | 273 | A. The package files must be visible during the chroot phase and this is a
|
---|
[fbdd1a8] | 274 | simple and reliable method of doing so. This method also handles the
|
---|
[0fa52f2] | 275 | boot build method where the final build may be done on a separate
|
---|
[fbdd1a8] | 276 | machine.
|
---|
| 277 |
|
---|
| 278 | Q. "What is the function of "User account" and "Group account" menu
|
---|
| 279 | settings?"
|
---|
| 280 | A. If you are running jhalfs from a low or non-privileged account you may
|
---|
| 281 | not have the priv to create/delete the user needed to build temporary
|
---|
| 282 | tools.
|
---|
| 283 | These settings allow you to use your own user and group name to do those
|
---|
[50b1fb7] | 284 | build steps.
|
---|
| 285 |
|
---|
| 286 | These variables are adjustable also when invoking make:
|
---|
[877cc6a] | 287 |
|
---|
[b15261a] | 288 | cd $BUILDDIR; make LUSER=myaccount LGROUP=mygroup
|
---|
[6ad5a2f] | 289 |
|
---|
[50b1fb7] | 290 | The only changes to your account will be the creation of a NEW .bashrc
|
---|
| 291 | after saving your original to .bashrc.XXX
|
---|
| 292 |
|
---|
[dbcdfd7] | 293 | Q. "How could I stop the build at a predefined chosen point?"
|
---|
| 294 | A. Launch the Makefile manually passing the last numbered target to be build
|
---|
| 295 | as the break point. For example:
|
---|
| 296 |
|
---|
| 297 | make BREAKPOINT=84-bash
|
---|
| 298 |
|
---|
| 299 | The build can be stopped also at the end of a top-level build phase by
|
---|
| 300 | calling directly the appropriate mk_* target. For example:
|
---|
| 301 |
|
---|
| 302 | make mk_LUSER
|
---|
| 303 |
|
---|
| 304 | See the Makefile to know the proper target names for that book build.
|
---|
| 305 |
|
---|
[877cc6a] | 306 | Authors:
|
---|
| 307 | George Boudreau
|
---|
| 308 | Manuel Canales Esparcia
|
---|
[fbdd1a8] | 309 | Pierre Labastie
|
---|