- Timestamp:
- 11/23/2023 09:07:45 AM (5 months ago)
- Branches:
- ablfs-more, trunk
- Children:
- 41a4032, ca368ad
- Parents:
- cd87e52
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
README
rcd87e52 r35094ed 1 1 1. INTRODUCTION:: 2 2 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 19 tools at the end of an LFS build, or 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 27 the build 28 29 Other sources of information are the context help in the menu interface, 30 and the xLFS books themselves. 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 (maybe outdated, 11 current develoment books and latest version are always supported). 12 13 The documentation is split among various README.* files. Here is a list 14 of what is in which: 15 - README (this file): instructions to use the LFS book. This should be 16 enough if you just want to build a base system as per the LFS book. It 17 is also a required reading for all the other projects. 18 - README.BLFS: instructions to install an automated build infrastructure 19 for the BLFS book. There are two ways to do so: (i) install the 20 tools at the end of an LFS build, or 21 (ii) install the tools on an already running system. Both methods are 22 described in that file. 23 - README.CUSTOM: instructions to run custom commands either during the LFS 24 build, or at the end of a LFS build. Note that you will not find 25 instructions on how to write those commands, but some examples are 26 available. 27 - README.PACKAGE_MANAGEMENT: instructions to use package management during 28 the build (Note: the only package manager that is regularly tested is 29 porg) 30 31 Other sources of information are the context help in the menu interface, 32 and the LFS books themselves (both required readings of course!). 31 33 32 34 2. PREREQUISITES:: 33 35 34 As said elsewhere, it is strongly advised that you first build manually 35 a complete system before attempting to automate the build. 36 37 Of course the "Host System Requirements" should be fulfilled. The needed 38 supplementary packages are detailed at the bottom of the page: 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. 36 It is strongly advised that you first build manually a complete system 37 before attempting to automate the build. 38 39 Of course the "Host System Requirements" should be fulfilled. Some 40 supplementary packages are needed for using jhalfs. They are detailed 41 at the bottom of the page: 42 https://www.linuxfromscratch.org/alfs/download.html. In short, you need 43 wget, sudo, libxml2, libxslt, docbook-4.5-xml, and docbook-xsl-nons. 41 44 42 45 3. INSTALLATION:: 43 46 44 No installation is required. You may want to move the files in this45 directory to a convenient location, and then follow the instructions below.47 No installation is required. You may want to move the files in this 48 directory to a convenient location, and then follow the instructions below. 46 49 47 50 4. CONFIGURATION:: 48 51 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 60 may name it /mnt/lfs, or whatever you like. We'll use the name 61 /mnt/build_dir in the sequel. 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. 78 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 82 tarball, unpack it, run <make menuconfig> (or any other *config), 83 configure the kernel as per 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. 52 4.1. CONFIGURATION OF THE TOOLS: 53 There is no configuration of the tools themselves. The various 54 parameters for the build are set through a menu driven interface. See 55 the section RUNNING below for details. 56 57 4.2. PRELIMINARY TASKS: 58 This tool has no support at all for creating a partition and a mount 59 point for the built system. You should follow the book up to the section 60 "Mounting the new partition". Note that the default name for the 61 partition mount point is "/mnt/build_dir", instead of /mnt/lfs. 62 You can change that default to anything you'd like in the menu, so you 63 may name it /mnt/lfs if you prefer . We'll use the name /mnt/build_dir 64 in the sequel. 65 66 For downloading packages, you can use the tool or download them 67 yourself. Even if using the tool, it is recommended to set up a source 68 repository where you store already downloaded packages. The tool will 69 automatically search a package in this repository before downloading it 70 if it is not found there. This repository cannot be the same as 71 /mnt/build_dir/sources. As an example, we'll use /usr/src. You should 72 arrange for the user running the tool to have write access to this 73 directory. 74 75 If you want to build the kernel as part of the automated build, 76 a configuration file must be provided. In order to do so, it is 77 recommended to download the kernel tarball, unpack it, run 78 <make menuconfig> (or any other *config), configure the kernel as per 79 the book, and save the resulting .config file to a location where it can 80 be retrieved later on. It is suggested to put it into the source 81 repository, with a versioned name, e.g. 82 /usr/src/config-<arch>-<kernel version>-<config details>. 83 84 Another file you may provide is the fstab file. As for the kernel 85 configuration, this file has to be prepared before running the menu. 86 You can copy-paste the file from the "Creating the /etc/fstab File" 87 page, then edit to suit the future lfs system layout, then save the 88 file. A convenient location and name is /usr/src/fstablfs. 89 90 At a more advanced level, you may want to supply custom commands 91 to be run at the end of LFS build. Scripts containing those commands 92 are located in the ./custom/config directory. Examples are given in 93 ./custom/examples. A template is provided as ./custom/template. See 94 README.CUSTOM for more details. 99 95 100 96 5. RUNNING:: 101 97 102 IMPORTANT::103 You must be logged as a normal user with sudo privileges to run98 IMPORTANT:: 99 You must be logged as a normal user with sudo privileges to run 104 100 the Makefile. Furthermore, you are supposed to have enough privilege 105 101 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 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. 112 113 Help on parameter function is available from the on-line help. Please 114 make use of that feature: it may contain additional information not 115 duplicated in this file. 116 117 You should first choose which book and flavour you want to build. Note 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. 102 the entry for the user running the tool in /etc/sudoers could be 103 <user> ALL=(ALL) NOPASSWD:ALL 104 105 The command <make> will launch a menu based configuration program, 106 similar to the kernel "menuconfig" configuration tool. 107 108 Help on parameter function is available from the on-line help (type the 109 character `?' after highlighting the parameter). Please do use the help: 110 it may contain additional information not duplicated in this file. 111 112 MENU "BOOK Settings" 113 114 Use BOOK: You have three choices: LFS System V, LFS systemd, BLFS. 115 The BLFS part is described in README.BLFS 116 117 Book version: You have two choices: "Branch" or "Working Copy" 118 Branch will have the tool clone the book's git repository. The 119 choice of the branch (actually any git commit) or of the file 120 location for the working copy is done in the next menu entry. 121 122 Multilib: Four choices: Normal LFS, Multilib with i686 libraries, 123 multilib with x32 libraries, multilib with all libraries. 124 It is recommended to use "Normal LFS" unless you know what you 125 are doing 126 127 Build method: two choices: chroot (as in book), boot 128 Presently, the "boot" method is not implemented, so keep the default. 129 130 Add blfs-tools support (see README.BLFS) 131 This will install the blfs tools onto the newly built system. It 132 is not the same thing as choosing the BLFS book in the menu, which 133 will install the blfs tools on the currently running system. 134 135 Add custom tools support (see README.CUSTOM) 136 137 MENU "General Settings" 138 139 Build Directory: the name of the root of the LFS system 140 This is the equivalent of the LFS variable in the book. Set it 141 to "/mnt/lfs" if you have followed the book for creating the LFS 142 partition and mount point. 143 144 Retrieve source files: Say y to have jhalfs download the packages 145 If you say no, you must download the packages yourself and put 146 them into the /mnt/build_dir/sources directory. Follow book's 147 chapter 3 instructions. 148 If you say yes, you'll be asked several other questions: 149 - Package Archive Directory: Repository of downloaded packages 150 This directory, which is on the host and should be writable 151 by the user running the tool, is for storing downloaded packages. 152 If you keep the default "$SRC_ARCHIVE", you can set this variable 153 to the absolute path of the repository and export it. Or if the 154 variable is not set, jhalfs downloads the sources directly to 155 /mnt/build_dir/sources. 156 Instead of using the SRC_ARCHIVE envar, you can also enter the 157 path of the repository directory into this field. 158 - Retry on 'connection refused' failure: self explanatory 159 - Number of retry attempts on download failures: self explanatory 160 - Download timeout (in seconds): self explanatory 161 162 Run the makefile: start the build immediately after running the tool 163 This is not the preferred method: it is recommended to rather 164 run "make -C /mnt/build_dir/jhalfs" after the tool has finished 165 setting up the build. But this may be handy if you are sure everything 166 is well, and want to leave the tool and the build run without 167 supervision. 168 169 Rebuild files: clean up the /mnt/build_dir directory 170 Say n if you want to rerun the tool (to update generated scripts 171 for example) without removing what has already been done. Otherwise, 172 say y. Note that there are some guards against removing a directory 173 containing useful things, but double check that the /mnt/build_dir 174 directory is really what you want to erase. 175 176 MENU "Build Settings" 177 178 MENU Parallelism settings 179 - Use all cores: 180 If you say y, MAKEFLAGS will be set to "-j$(nproc)" at the 181 beginning of each script. Other envars are supposed to be passed 182 from the environment, as done in new books. Note that for old books, 183 this means the scripts using make or ninja will be run with all 184 cores, but not when this needs to set special envars like 185 TESTSUITEFLAGS. You can still define the number of cores used 186 in next field. 187 If you say n, you'll be asked for a static number of threads 188 to use. 189 - set of cpus to use, or 'all' for all cpus (only if using all cores): 190 You can define here the cores you want to use. See help for 191 details. This is the preferred way of reducing the number of cores 192 rather than using a static thread number. 193 - Number of parallel `make' jobs (only if not using all cores): 194 Every occurrence of $(nproc) in new books will be replaced with 195 the number entered here. Also MAKEFLAGS will be set to "-jN" (where 196 N is the number entered) at the beginning of each scripts. Furthermore 197 NINJAJOBS will be set to N in the environment. This allows to run all 198 books with N threads, except for paarts that need other envars to be 199 set 200 - Build Binutils pass1 without parallelism (Real SBU) 201 The standard SBU is defined as the time to run the binutils-pass1 202 build with only one thread. Saying y here allows to get a value for 203 it. If you say n, the value is not meaningful for SBU measurements. 204 205 Run testsuites: say y to run the test suites 206 You'll have the choice between running all the test suites, or only 207 those deemed critical (binutils, gmp, mpfr, mpc, and gcc). 208 209 Package management: see README.PACKAGE_MANAGEMENT 210 211 Create a log of installed files for each package: self explanatory 212 213 Strip Installed Binaries/Libraries: use the book instructions for 214 stripping 215 216 DO NOT use/display progress_bar (self explanatory) 217 218 MENU System configuration 219 220 Use a custom fstab file: 221 If you say y, you'll have to provide a file containing the fstab 222 for the LFS system. See above "preliminary tasks". 223 224 Build the kernel: 225 If you say y, you'll be asked for a file containing the kernel 226 configuration. See above "preliminary tasks". 227 228 Install non-wide-character ncurses (rarely used nowadays): 229 If you say y, the system will use instructions in the note on the 230 ncurses page to install those libraries. 231 232 TimeZone: set to the result of "tzselect" 233 234 Language: set to the result of the instructions on "The Bash Shell 235 Startup Files" page. 236 237 Install the full set of locales: installs all the locales known to 238 glibc. 239 240 Groff page size: choice between "A4" and "Letter". 241 242 Hostname: self explanatory 243 244 Network configuration: various fields for setting network. Look at 245 chapter 9 for background. 246 247 Console configuration: various fields for setting console, as described 248 in chapter 9. 249 250 MENU Advanced features: 251 252 Optimization: Optimization settings are done by editing files in the 253 "optimize" directory. The menu just allows you to choose between applying 254 optimizations only to the final chapter or to all the book. Say n for 255 a normal build 256 257 Create SBU and disk usage report: self explanatory 258 259 Save temporary system work: self explanatory (see help) 260 261 Run comparison analysis on final stage: build the system several times 262 using the preceding one, to test whether it is able to rebuild itself 263 identically. Don't use normally... 264 265 Internal Settings (WARNING: for jhalfs developers only): says it all 148 266 149 267 Once you have set the parameters and saved the configuration, the script … … 276 394 machine. 277 395 278 Q. "What is the function of "User account" and "Group account" menu279 settings?"280 A. If you are running jhalfs from a low or non-privileged account you may281 not have the priv to create/delete the user needed to build temporary282 tools.283 These settings allow you to use your own user and group name to do those284 build steps.285 286 These variables are adjustable also when invoking make:287 288 cd $BUILDDIR; make LUSER=myaccount LGROUP=mygroup289 290 The only changes to your account will be the creation of a NEW .bashrc291 after saving your original to .bashrc.XXX292 293 396 Q. "How could I stop the build at a predefined chosen point?" 294 397 A. Launch the Makefile manually passing the last numbered target to be build
Note:
See TracChangeset
for help on using the changeset viewer.
