jhalfs git · trunk
jhalfs LFS build automation (mirror)
Python 78.4% Shell 19.8% Makefile 1.8%git clone https://git.christianimmanuel.de/mirrors-forks/jhalfs.gitwget https://git.christianimmanuel.de/mirrors-forks/jhalfs/archive/jhalfs.tar.gzMajor refactoring of README
Describe each item in the menu, fix layout, and try to follow the order of tasks to do to run jhalfs.
README | 393 +++++++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 248 insertions(+), 145 deletions(-) diff --git a/README b/README index 13d6f61..038c6f3 100644 --- a/README +++ b/README @@ -1,150 +1,268 @@ 1. INTRODUCTION:: - The scripts in this directory implement an automation of the building - of a GNU/LInux system, as described in the Linux From Scratch book series. - The name of the project is jhalfs: in that name, "alfs" stands for - "automated linux from scratch", and the initials "jh" have been kept since - the original "jhalfs-0.2" code developed by Jeremy Huntwork. - - The list of supported books can be found at - http://wiki.linuxfromscratch.org/alfs/wiki/SupportedBooks. - - The documentation is split among various README.* files. Here is a list - of what is in which: - - README (this file): instructions to use the LFS book. This should be - enough if you just want to build a base system as per the LFS book. It is - also a required reading for all the other projects. - - README.BLFS: instructions to install an automated build infrastructure - for the BLFS book. There are two ways to do so: (i) install the - tools at the end of an LFS build, or - (ii) install the tools on an already running system. Both methods are - described in that file. - - README.CUSTOM: instructions to run custom commands either during the xLFS - build, at the end of a xLFS build. Note that you will not find - instructions on how to write those commands, but some examples are - available. - - README.PACKAGE_MANAGEMENT: instructions to use package management during - the build - - Other sources of information are the context help in the menu interface, - and the xLFS books themselves. + The scripts in this directory implement an automation of the building + of a GNU/LInux system, as described in the Linux From Scratch book series. + The name of the project is jhalfs: in that name, "alfs" stands for + "automated linux from scratch", and the initials "jh" have been kept since + the original "jhalfs-0.2" code developed by Jeremy Huntwork. + + The list of supported books can be found at + http://wiki.linuxfromscratch.org/alfs/wiki/SupportedBooks (maybe outdated, + current develoment books and latest version are always supported). + + The documentation is split among various README.* files. Here is a list + of what is in which: + - README (this file): instructions to use the LFS book. This should be + enough if you just want to build a base system as per the LFS book. It + is also a required reading for all the other projects. + - README.BLFS: instructions to install an automated build infrastructure + for the BLFS book. There are two ways to do so: (i) install the + tools at the end of an LFS build, or + (ii) install the tools on an already running system. Both methods are + described in that file. + - README.CUSTOM: instructions to run custom commands either during the LFS + build, or at the end of a LFS build. Note that you will not find + instructions on how to write those commands, but some examples are + available. + - README.PACKAGE_MANAGEMENT: instructions to use package management during + the build (Note: the only package manager that is regularly tested is + porg) + + Other sources of information are the context help in the menu interface, + and the LFS books themselves (both required readings of course!). 2. PREREQUISITES:: - As said elsewhere, it is strongly advised that you first build manually - a complete system before attempting to automate the build. + It is strongly advised that you first build manually a complete system + before attempting to automate the build. - Of course the "Host System Requirements" should be fulfilled. The needed - supplementary packages are detailed at the bottom of the page: - https://www.linuxfromscratch.org/alfs/download.html. In short, you need - wget, sudo, libxml2, libxslt, docbook-4.5-xml, and docbook-xsl-nons. + Of course the "Host System Requirements" should be fulfilled. Some + supplementary packages are needed for using jhalfs. They are detailed + at the bottom of the page: + https://www.linuxfromscratch.org/alfs/download.html. In short, you need + wget, sudo, libxml2, libxslt, docbook-4.5-xml, and docbook-xsl-nons. 3. INSTALLATION:: - No installation is required. You may want to move the files in this - directory to a convenient location, and then follow the instructions below. + No installation is required. You may want to move the files in this + directory to a convenient location, and then follow the instructions below. 4. CONFIGURATION:: - 4.1. CONFIGURATION OF THE TOOLS: - There is no configuration of the tools themselves. The various - parameters for the build are set through a menu driven interface. See - the section RUNNING below for details. - - 4.2. PRELIMINARY TASKS: - This tool has no support at all for creating a partition and a mount - point for the built system. You should follow the book up to the section - "Mounting the new partition". Note that the default name for the - partition mount point is "/mnt/build_dir", instead of /mnt/{c,}lfs. - You can change that default to anything you'd like in the menu, so you - may name it /mnt/lfs, or whatever you like. We'll use the name - /mnt/build_dir in the sequel. - - The tool can download the needed packages for you, or you may download - them yourself. The tool may optionally use a package archive directory - where the downloaded packages are stored. That directory name may be made - available to the tool in two ways: (i) export the SRC_ARCHIVE variable, - for example SRC_ARCHIVE=/usr/src, (ii) enter the name at the "Package - Archive Directory" menu prompt. Note that the user should have write - permission to that directory. If a needed package is found in that - directory, it is copied to /mnt/build_dir/sources, if not, it is - downloaded to that directory and copied to /mnt/build_dir/sources, - except if found in /mnt/build_dir/sources, in which case, it is just - copied to $SRC_ARCHIVE. If you want the tool to download packages and you - do not want to archive them, just unset SRC_ARCHIVE, and keep the - default entry for "Package Archive Directory". If you choose to download - the packages by yourself, you should download (or copy) them to - /mnt/build_dir/sources directly. - - If you want to build the kernel as part of the automated build, select - "Build the kernel" in the menu. Then, a configuration file must be - provided. In order to do so, it is recommended to download the kernel - tarball, unpack it, run <make menuconfig> (or any other *config), - configure the kernel as per - the book, and save the resulting .config file to a location where it can - be retrieved later on (a convenient location and name is - $SRC_ARCHIVE/config-<arch>-<kernel version>-<config details>). - - Another file you may provide is the fstab file. To use it, select - "Use a custom fstab file" in the menu interface, and enter the name of - the file where asked. As for the kernel configuration, this file has to - be prepared before running the menu. A convenient location and name is - $SRC_ARCHIVE/fstablfs. - - At a more advanced level, you may want to supply custom commands - to be run at the end of (C)LFS build. Scripts containing those commands - are located in the ./custom/config directory. Examples are given in - ./custom/examples. A template is provided as ./custom/template. See - README.CUSTOM for more details. + 4.1. CONFIGURATION OF THE TOOLS: + There is no configuration of the tools themselves. The various + parameters for the build are set through a menu driven interface. See + the section RUNNING below for details. + + 4.2. PRELIMINARY TASKS: + This tool has no support at all for creating a partition and a mount + point for the built system. You should follow the book up to the section + "Mounting the new partition". Note that the default name for the + partition mount point is "/mnt/build_dir", instead of /mnt/lfs. + You can change that default to anything you'd like in the menu, so you + may name it /mnt/lfs if you prefer . We'll use the name /mnt/build_dir + in the sequel. + + For downloading packages, you can use the tool or download them + yourself. Even if using the tool, it is recommended to set up a source + repository where you store already downloaded packages. The tool will + automatically search a package in this repository before downloading it + if it is not found there. This repository cannot be the same as + /mnt/build_dir/sources. As an example, we'll use /usr/src. You should + arrange for the user running the tool to have write access to this + directory. + + If you want to build the kernel as part of the automated build, + a configuration file must be provided. In order to do so, it is + recommended to download the kernel tarball, unpack it, run + <make menuconfig> (or any other *config), configure the kernel as per + the book, and save the resulting .config file to a location where it can + be retrieved later on. It is suggested to put it into the source + repository, with a versioned name, e.g. + /usr/src/config-<arch>-<kernel version>-<config details>. + + Another file you may provide is the fstab file. As for the kernel + configuration, this file has to be prepared before running the menu. + You can copy-paste the file from the "Creating the /etc/fstab File" + page, then edit to suit the future lfs system layout, then save the + file. A convenient location and name is /usr/src/fstablfs. + + At a more advanced level, you may want to supply custom commands + to be run at the end of LFS build. Scripts containing those commands + are located in the ./custom/config directory. Examples are given in + ./custom/examples. A template is provided as ./custom/template. See + README.CUSTOM for more details. 5. RUNNING:: - IMPORTANT:: - You must be logged as a normal user with sudo privileges to run + IMPORTANT:: + You must be logged as a normal user with sudo privileges to run the Makefile. Furthermore, you are supposed to have enough privilege to become any user. If you are not bothered about security issues, - the entry for the user "jhalfs_user" in /etc/sudoers could be - jhalfs_user ALL=(ALL) NOPASSWD:ALL - - The command <make> will launch a menu based configuration program. The - underlying menu code was borrowed from BusyBox and slightly modified for - our use. - - Help on parameter function is available from the on-line help. Please - make use of that feature: it may contain additional information not - duplicated in this file. - - You should first choose which book and flavour you want to build. Note - that when you choose the BLFS book, the tool will just install the BLFS - tool to your system. You'll have to run that installed tool to build - packages in BLFS. See README.BLFS to know how. If you choose any other - book, you'll have to configure the settings and the build parameters - from the menu. Note that you may choose to install the blfs tools onto - the newly built system. It is not the same thing as choosing - the BLFS book in the menu, which will install the blfs tools on the - currently running system. - - The "General Settings" menu is where the "Build Directory" name is to be - entered. Other entries in that menu select what the tool should do. The - "Run the Makefile" entry selects whether the tool will start the build - automatically after generating the needed files. The "Rebuild files" selects - whether to clean the build directory before doing anything else. To protect - against removing important files, this can only be done in an empty directory, - or a directory previously populated by the tool. - - The "Build Settings" menu is where various options for the build can be - selected. Two options, "Use a custom fstab file" and "Build the kernel", - have been described above. "Do not use/display progress_bar", if set, will - prevent a progress bar to be displayed during the build. That may be useful - on slow machine. The other options should be self explanatory, using either - the online help or book reading. - - The "Advanced Features" menu is for various maintenance tasks, like - testing the build instructions or reporting build statistics. One useful - option is "Optimization and parallelisation". It is not recommended to use - it for setting compiler optimization flags, although it is possible, but - if you select it, you'll be able to select the number of parallel `make' - jobs, which allows much faster builds on modern multicore CPUs. + the entry for the user running the tool in /etc/sudoers could be + <user> ALL=(ALL) NOPASSWD:ALL + + The command <make> will launch a menu based configuration program, + similar to the kernel "menuconfig" configuration tool. + + Help on parameter function is available from the on-line help (type the + character `?' after highlighting the parameter). Please do use the help: + it may contain additional information not duplicated in this file. + + MENU "BOOK Settings" + + Use BOOK: You have three choices: LFS System V, LFS systemd, BLFS. + The BLFS part is described in README.BLFS + + Book version: You have two choices: "Branch" or "Working Copy" + Branch will have the tool clone the book's git repository. The + choice of the branch (actually any git commit) or of the file + location for the working copy is done in the next menu entry. + + Multilib: Four choices: Normal LFS, Multilib with i686 libraries, + multilib with x32 libraries, multilib with all libraries. + It is recommended to use "Normal LFS" unless you know what you + are doing + + Build method: two choices: chroot (as in book), boot + Presently, the "boot" method is not implemented, so keep the default. + + Add blfs-tools support (see README.BLFS) + This will install the blfs tools onto the newly built system. It + is not the same thing as choosing the BLFS book in the menu, which + will install the blfs tools on the currently running system. + + Add custom tools support (see README.CUSTOM) + + MENU "General Settings" + + Build Directory: the name of the root of the LFS system + This is the equivalent of the LFS variable in the book. Set it + to "/mnt/lfs" if you have followed the book for creating the LFS + partition and mount point. + + Retrieve source files: Say y to have jhalfs download the packages + If you say no, you must download the packages yourself and put + them into the /mnt/build_dir/sources directory. Follow book's + chapter 3 instructions. + If you say yes, you'll be asked several other questions: + - Package Archive Directory: Repository of downloaded packages + This directory, which is on the host and should be writable + by the user running the tool, is for storing downloaded packages. + If you keep the default "$SRC_ARCHIVE", you can set this variable + to the absolute path of the repository and export it. Or if the + variable is not set, jhalfs downloads the sources directly to + /mnt/build_dir/sources. + Instead of using the SRC_ARCHIVE envar, you can also enter the + path of the repository directory into this field. + - Retry on 'connection refused' failure: self explanatory + - Number of retry attempts on download failures: self explanatory + - Download timeout (in seconds): self explanatory + + Run the makefile: start the build immediately after running the tool + This is not the preferred method: it is recommended to rather + run "make -C /mnt/build_dir/jhalfs" after the tool has finished + setting up the build. But this may be handy if you are sure everything + is well, and want to leave the tool and the build run without + supervision. + + Rebuild files: clean up the /mnt/build_dir directory + Say n if you want to rerun the tool (to update generated scripts + for example) without removing what has already been done. Otherwise, + say y. Note that there are some guards against removing a directory + containing useful things, but double check that the /mnt/build_dir + directory is really what you want to erase. + + MENU "Build Settings" + + MENU Parallelism settings + - Use all cores: + If you say y, MAKEFLAGS will be set to "-j$(nproc)" at the + beginning of each script. Other envars are supposed to be passed + from the environment, as done in new books. Note that for old books, + this means the scripts using make or ninja will be run with all + cores, but not when this needs to set special envars like + TESTSUITEFLAGS. You can still define the number of cores used + in next field. + If you say n, you'll be asked for a static number of threads + to use. + - set of cpus to use, or 'all' for all cpus (only if using all cores): + You can define here the cores you want to use. See help for + details. This is the preferred way of reducing the number of cores + rather than using a static thread number. + - Number of parallel `make' jobs (only if not using all cores): + Every occurrence of $(nproc) in new books will be replaced with + the number entered here. Also MAKEFLAGS will be set to "-jN" (where + N is the number entered) at the beginning of each scripts. Furthermore + NINJAJOBS will be set to N in the environment. This allows to run all + books with N threads, except for paarts that need other envars to be + set + - Build Binutils pass1 without parallelism (Real SBU) + The standard SBU is defined as the time to run the binutils-pass1 + build with only one thread. Saying y here allows to get a value for + it. If you say n, the value is not meaningful for SBU measurements. + + Run testsuites: say y to run the test suites + You'll have the choice between running all the test suites, or only + those deemed critical (binutils, gmp, mpfr, mpc, and gcc). + + Package management: see README.PACKAGE_MANAGEMENT + + Create a log of installed files for each package: self explanatory + + Strip Installed Binaries/Libraries: use the book instructions for + stripping + + DO NOT use/display progress_bar (self explanatory) + + MENU System configuration + + Use a custom fstab file: + If you say y, you'll have to provide a file containing the fstab + for the LFS system. See above "preliminary tasks". + + Build the kernel: + If you say y, you'll be asked for a file containing the kernel + configuration. See above "preliminary tasks". + + Install non-wide-character ncurses (rarely used nowadays): + If you say y, the system will use instructions in the note on the + ncurses page to install those libraries. + + TimeZone: set to the result of "tzselect" + + Language: set to the result of the instructions on "The Bash Shell + Startup Files" page. + + Install the full set of locales: installs all the locales known to + glibc. + + Groff page size: choice between "A4" and "Letter". + + Hostname: self explanatory + + Network configuration: various fields for setting network. Look at + chapter 9 for background. + + Console configuration: various fields for setting console, as described + in chapter 9. + + MENU Advanced features: + + Optimization: Optimization settings are done by editing files in the + "optimize" directory. The menu just allows you to choose between applying + optimizations only to the final chapter or to all the book. Say n for + a normal build + + Create SBU and disk usage report: self explanatory + + Save temporary system work: self explanatory (see help) + + Run comparison analysis on final stage: build the system several times + using the preceding one, to test whether it is able to rebuild itself + identically. Don't use normally... + + Internal Settings (WARNING: for jhalfs developers only): says it all Once you have set the parameters and saved the configuration, the script is launched. Its aim is to extract instructions from the selected book @@ -275,21 +393,6 @@ boot build method where the final build may be done on a separate machine. - Q. "What is the function of "User account" and "Group account" menu - settings?" - A. If you are running jhalfs from a low or non-privileged account you may - not have the priv to create/delete the user needed to build temporary - tools. - These settings allow you to use your own user and group name to do those - build steps. - - These variables are adjustable also when invoking make: - - cd $BUILDDIR; make LUSER=myaccount LGROUP=mygroup - - The only changes to your account will be the creation of a NEW .bashrc - after saving your original to .bashrc.XXX - Q. "How could I stop the build at a predefined chosen point?" A. Launch the Makefile manually passing the last numbered target to be build as the break point. For example: