From 091d624df5c599faef288f4d2c447f167003392a Mon Sep 17 00:00:00 2001 From: David Bryant Date: Thu, 17 Nov 2022 12:08:13 -0600 Subject: [PATCH 01/10] Correct capitalization, spelling, grammar, and idiom. Tighten the prose by removing some circumlocutions. --- chapter08/glibc.xml | 20 ++++++++++---------- chapter08/introduction.xml | 24 ++++++++++++------------ chapter08/pkgmgt.xml | 15 ++++++++------- 3 files changed, 30 insertions(+), 29 deletions(-) diff --git a/chapter08/glibc.xml b/chapter08/glibc.xml index 0bc9a5dcf..a85559d24 100644 --- a/chapter08/glibc.xml +++ b/chapter08/glibc.xml @@ -43,7 +43,7 @@ Installation of Glibc - First, fix an issue building Glibc with parallel jobs and make-4.4 + First, fix an issue building Glibc with parallel jobs and Make-4.4 or later: sed '/MAKEFLAGS :=/s/)r/) -r/' -i Makerules @@ -82,7 +82,7 @@ cd build --disable-werror - This option disables the -Werror option passed to + This option disables the -werror option passed to GCC. This is necessary for running the test suite. @@ -90,7 +90,7 @@ cd build --enable-kernel=&min-kernel; - This option tells the build system that this glibc may + This option tells the build system that this Glibc may be used with kernels as old as &min-kernel;. This means generating workarounds in case a system call introduced in a later version cannot be used. @@ -217,7 +217,7 @@ esac make install - Fix hardcoded path to the executable loader in + Fix a hardcoded path to the executable loader in the ldd script: sed '/RTLDLIST=/s@/usr@@g' -i /usr/bin/ldd @@ -235,9 +235,9 @@ mkdir -pv /var/cache/nscd install -v -Dm644 ../nscd/nscd.service /usr/lib/systemd/system/nscd.service Next, install the locales that can make the system respond in a - different language. None of the locales are required, but if some of them - are missing, the test suites of future packages would skip important - testcases. + different language. None of these locales are required, but if some of them + are missing, the test suites of some packages will skip important + test cases. Individual locales can be installed using the localedef program. E.g., the second @@ -290,7 +290,7 @@ localedef -i zh_TW -f UTF-8 zh_TW.UTF-8 In addition, install the locale for your own country, language and character set. - Alternatively, install all locales listed in the + Alternatively, install all the locales listed in the glibc-&glibc-version;/localedata/SUPPORTED file (it includes every locale listed above and many more) at once with the following time-consuming command: @@ -326,7 +326,7 @@ localedef -i ja_JP -f SHIFT_JIS ja_JP.SJIS 2> /dev/null || true - Adding nsswitch.conf + Adding Nsswitch.conf The /etc/nsswitch.conf file needs to be created because the Glibc defaults do not work well in a networked environment. @@ -356,7 +356,7 @@ EOF - Adding time zone data + Adding Time Zone Data Install and set up the time zone data with the following: tar -xf ../../tzdata&tzdata-version;.tar.gz diff --git a/chapter08/introduction.xml b/chapter08/introduction.xml index b23175b3f..b05a9761a 100644 --- a/chapter08/introduction.xml +++ b/chapter08/introduction.xml @@ -22,17 +22,17 @@ We do not recommend using optimizations. They can make a program run slightly faster, but they may also cause compilation - difficulties and problems when running the program. If a package refuses to + difficulties, and problems when running the program. If a package refuses to compile when using optimization, try to compile it without optimization and see if that fixes the problem. Even if the package does compile when using optimization, there is the risk it may have been compiled incorrectly because - of the complex interactions between the code and build tools. Also note that + of the complex interactions between the code and the build tools. Also note that the and options using values not specified in the book have not been tested. This may cause problems with the toolchain packages (Binutils, GCC and Glibc). The small potential gains - achieved in using compiler optimizations are often outweighed by the risks. + achieved by using compiler optimizations are often outweighed by the risks. First-time builders of LFS are encouraged to build without custom - optimizations. The subsequent system will still run very fast and be stable + optimizations. The resulting system will still run very fast, and be stable at the same time. Before the installation instructions, each installation page provides @@ -42,31 +42,31 @@ instructions, there is a list of programs and libraries (along with brief descriptions) that the package installs. - The SBU values and required disk space includes test suite data + The SBU values and required disk space include test suite data for all applicable packages in . SBU values have been calculated using a single CPU core (-j1) for all operations. - About libraries + About Libraries In general, the LFS editors discourage building and installing static - libraries. The original purpose for most static libraries has been made + libraries. Most static libraries have been made obsolete in a modern Linux system. In addition, linking a static library into a program can be detrimental. If an update to the library is needed - to remove a security problem, all programs that use the static library will - need to be relinked to the new library. Since the use of static libraries + to remove a security problem, every program that uses the static library will + need to be relinked with the new library. Since the use of static libraries is not always obvious, the relevant programs (and the procedures needed to do the linking) may not even be known. - In the procedures in this chapter, we remove or disable installation of + The procedures in this chapter remove or disable installation of most static libraries. Usually this is done by passing a option to configure. In other cases, alternate means are needed. In a few cases, especially - glibc and gcc, the use of static libraries remains essential to the general + Glibc and GCC, the use of static libraries remains an essential feature of the package building process. - For a more complete discussion of libraries, see the discussion + For a more complete discussion of libraries, see Libraries: Static or shared? in the BLFS book. diff --git a/chapter08/pkgmgt.xml b/chapter08/pkgmgt.xml index 60c472ad4..7496f09a4 100644 --- a/chapter08/pkgmgt.xml +++ b/chapter08/pkgmgt.xml @@ -12,10 +12,10 @@ Package Management is an often requested addition to the LFS Book. A Package Manager tracks the installation of files, making it easier to - remove and upgrade packages. As well as the binary and library files, a - package manager will handle the installation of configuration files. Before + remove and upgrade packages. A good package manager will handle the + installation of configuration files, and also install the executable files. Before you begin to wonder, NO—this section will not talk about nor recommend - any particular package manager. What it provides is a roundup of the more + any particular package manager. What it does provide is a roundup of the more popular techniques and how they work. The perfect package manager for you may be among these techniques, or it may be a combination of two or more of these techniques. This section briefly mentions issues that may arise when upgrading @@ -61,8 +61,8 @@ - If Linux API headers or glibc need to be upgraded to a newer - version, (e.g., from glibc-2.31 to glibc-2.32), it is safer to + If the Linux API headers or Glibc need to be upgraded to a newer + version, (e.g., from Glibc-2.31 to Glibc-2.32), it is safer to rebuild LFS. Though you may be able to rebuild all the packages in their dependency order, we do not recommend it. @@ -202,7 +202,7 @@ it is installed in /usr though in reality it is installed in the /usr/pkg hierarchy. Installing in - this manner is not usually a trivial task. For example, consider that you + this manner is not usually a trivial task. For example, suppose you are installing a package libfoo-1.1. The following instructions may not install the package properly: @@ -321,7 +321,8 @@ make DESTDIR=/usr/pkg/libfoo/1.1 install depend on the position of files on a disk system. Cloning an LFS build to another computer with the same architecture as the base system is as simple as using tar on the LFS partition that contains - the root directory (about 250MB uncompressed for a base LFS build), copying + the root directory (about 900MB uncompressed for a basic LFS build), copying + that file via network transfer or CD-ROM / USB stick to the new system, and expanding it. After that, a few configuration files will have to be changed. Configuration files that may need to be updated include: From 27601131e4ee4d960546e966e7f4326102b23d47 Mon Sep 17 00:00:00 2001 From: David Bryant Date: Thu, 17 Nov 2022 16:14:42 -0600 Subject: [PATCH 02/10] Correctd the spelling of "Werror" -- it's "-Werror" in GCC, but it's "--disable-error" in Glibc. Thanks to Thomas Trepl for spotting my mistake. --- chapter08/glibc.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chapter08/glibc.xml b/chapter08/glibc.xml index a85559d24..d121084df 100644 --- a/chapter08/glibc.xml +++ b/chapter08/glibc.xml @@ -70,7 +70,7 @@ cd build Prepare Glibc for compilation: ../configure --prefix=/usr \ - --disable-werror \ + --disable-Werror \ --enable-kernel=&min-kernel; \ --enable-stack-protector=strong \ --with-headers=/usr/include \ @@ -82,7 +82,7 @@ cd build --disable-werror - This option disables the -werror option passed to + This option disables the -Werror option passed to GCC. This is necessary for running the test suite. From 7054cc64eaf9737732a1d63eb5edc9a04af94459 Mon Sep 17 00:00:00 2001 From: Xi Ruoyao Date: Fri, 18 Nov 2022 12:07:51 +0800 Subject: [PATCH 03/10] glibc: it should be --disable-werror, not --disable-Werror Please try not to use the "replace" feature of the text editor blindly. Appendix C of the GNU C Library Reference Manual clearly says: '--disable-werror' By default, the GNU C Library is built with '-Werror'. If you wish to build without this option (for example, if building with a newer version of GCC than this version of the GNU C Library was tested with, so new warnings cause the build with '-Werror' to fail), you can configure with '--disable-werror'. --- chapter08/glibc.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapter08/glibc.xml b/chapter08/glibc.xml index d121084df..7cf111ef8 100644 --- a/chapter08/glibc.xml +++ b/chapter08/glibc.xml @@ -70,7 +70,7 @@ cd build Prepare Glibc for compilation: ../configure --prefix=/usr \ - --disable-Werror \ + --disable-werror \ --enable-kernel=&min-kernel; \ --enable-stack-protector=strong \ --with-headers=/usr/include \ From f714a8fa3bdd85d28bd9eb49ab0f1f59e39a5054 Mon Sep 17 00:00:00 2001 From: Xi Ruoyao Date: Fri, 18 Nov 2022 12:35:53 +0800 Subject: [PATCH 04/10] chroot: reword how chroot works Technically chroot command "tells" bash nothing. It basically calls chroot("$LFS"), then chdir("/"), then execve(["/usr/bin/env", "-i", ...]). The kernel also does not tell bash something like "hey, the root is now $LFS" but just executes (almost) all system calls from bash as-if $LFS is /. The man page of chroot says: DESCRIPTION Run COMMAND with root directory set to NEWROOT. Just use the same grammar construction here. --- chapter07/chroot.xml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/chapter07/chroot.xml b/chapter07/chroot.xml index 69bc6ce69..b8de03dc2 100644 --- a/chapter07/chroot.xml +++ b/chapter07/chroot.xml @@ -38,9 +38,10 @@ From this point on, there is no need to use the LFS variable any more because all work will be restricted - to the LFS file system; the chroot command tells the Bash shell that - $LFS is now the root - (/) directory. + to the LFS file system; the chroot command runs the + Bash shell with the root + (/) directory set to + $LFS. Notice that /tools/bin is not in the PATH. This means that the cross toolchain will no longer be From 2f9498afa401af249bb5c2090b3cc393e659ceb0 Mon Sep 17 00:00:00 2001 From: Xi Ruoyao Date: Fri, 18 Nov 2022 12:52:09 +0800 Subject: [PATCH 05/10] kernfs: remove a false note Things are a little tricky: 1. If the host is "modern" (any desktop distro after 2013), the kernel supports devtmpfs and the host udev will do adjustments to the devtmpfs. All instances of devtmpfs shares the same content so we'll see the work of both the kernel and the host udev in chroot. 2. If the host is old but the kernel supports devtmpfs (i. e. the host is not using devtmpfs for its /dev), when we mount devtmpfs on $LFS/dev we'll see the work of the kernel in chroot, but not the work of udev. **Building LFS does not need any work of udev.** 3. If the host is very old and the kernel does not support devtmpfs at all, we can't mount devtmpfs. Mounting a devtmpfs will work for 1 and 2, while bind mounting will work for 1, 2, and 3. So we use bind mounting here. I don't want to squash all these details into the book, so just remove the false statement here. --- chapter07/kernfs.xml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/chapter07/kernfs.xml b/chapter07/kernfs.xml index 48826d06c..4ec299708 100644 --- a/chapter07/kernfs.xml +++ b/chapter07/kernfs.xml @@ -41,8 +41,7 @@ for details.) If the host kernel supports &devtmpfs;, we can simply mount a &devtmpfs; at $LFS/dev and rely - on the kernel to populate it (i.e., the udev daemon will do the - necessary work automatically). + on the kernel to populate it. But some host kernels lack &devtmpfs; support; these host distros use different methods to create the content of From 940769457b0ae75a6a07db10534eafa3175b9018 Mon Sep 17 00:00:00 2001 From: Xi Ruoyao Date: Fri, 18 Nov 2022 13:13:37 +0800 Subject: [PATCH 06/10] kernfs: reword the description of bind mount "Duplicated copy" is wrong IMO. If you copy A to B, B won't be changed when you modify A. But if you bind mount A to B, B will reflect any change made to A. Again copy something from mount(2): A bind mount makes a file or a directory subtree visible at another point within the single directory hierarchy. --- chapter07/kernfs.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chapter07/kernfs.xml b/chapter07/kernfs.xml index 4ec299708..1f72fecf2 100644 --- a/chapter07/kernfs.xml +++ b/chapter07/kernfs.xml @@ -50,8 +50,8 @@ $LFS/dev directory is by bind mounting the host system's /dev directory. A bind mount is - a special type of mount that generates a duplicate copy of a - directory or mount point at some other location. Use the following + a special type of mount that makes a directory subtree or a file + visible at some other location. Use the following command to do this. mount -v --bind /dev $LFS/dev From 1cc301fbb3db368fe1bad436a1a662c303fcc29b Mon Sep 17 00:00:00 2001 From: Xi Ruoyao Date: Fri, 18 Nov 2022 13:25:38 +0800 Subject: [PATCH 07/10] glibc: Decapitalize nsswitch.conf In UNIX file names are case-sensitive. You cannot capitialize it even if it appears in a title. --- chapter08/glibc.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapter08/glibc.xml b/chapter08/glibc.xml index 7cf111ef8..0295e0aab 100644 --- a/chapter08/glibc.xml +++ b/chapter08/glibc.xml @@ -326,7 +326,7 @@ localedef -i ja_JP -f SHIFT_JIS ja_JP.SJIS 2> /dev/null || true - Adding Nsswitch.conf + Adding nsswitch.conf The /etc/nsswitch.conf file needs to be created because the Glibc defaults do not work well in a networked environment. From b1c8283fe71b3fe2d4419c3e74012e4b23052700 Mon Sep 17 00:00:00 2001 From: Xi Ruoyao Date: Fri, 18 Nov 2022 13:57:47 +0800 Subject: [PATCH 08/10] chapter08: reword description of compiler optimizations We don't recommend customizing optimizations, but we use optimizations provided by package default or release build mode. Reword the paragraph so the people won't be puzzled once they see "--enable-optimizations" in Python, or "--buildtype=release" (to prevent unoptimized build) in BLFS meson commands. --- chapter08/introduction.xml | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/chapter08/introduction.xml b/chapter08/introduction.xml index b05a9761a..2be7fe053 100644 --- a/chapter08/introduction.xml +++ b/chapter08/introduction.xml @@ -20,20 +20,28 @@ work is to know what each package is used for and why you (or the system) may need it. - We do not recommend using optimizations. They can make + We do not recommend using customized optimizations. They can make a program run slightly faster, but they may also cause compilation difficulties, and problems when running the program. If a package refuses to - compile when using optimization, try to compile it without optimization and - see if that fixes the problem. Even if the package does compile when using + compile with a customized optimization, try to compile it without + optimization and see if that fixes the problem. Even if the package does compile when using a customized optimization, there is the risk it may have been compiled incorrectly because of the complex interactions between the code and the build tools. Also note that the and options using values not specified in the book have not been tested. This may cause problems with the toolchain packages (Binutils, GCC and Glibc). The small potential gains - achieved by using compiler optimizations are often outweighed by the risks. + achieved by customizing compiler optimizations are often outweighed by the risks. First-time builders of LFS are encouraged to build without custom - optimizations. The resulting system will still run very fast, and be stable - at the same time. + optimizations. + + On the other hand, we keeps the optimizations enabled by the default + configuration of packages. In addition, we sometimes explicitly enable an + optimized configuration provided by the package but not enabled by + default. The package maintainers have already tested these configurations + and consider them safe, so it's not likely they would break the build. + Generally the default configuration already enables + or , so the resulting system will still run very fast + without any customized optimization, and be stable at the same time. Before the installation instructions, each installation page provides information about the package, including a concise description of what it From f8b186063150f471f9e72f2e317fe21d2d0f1e81 Mon Sep 17 00:00:00 2001 From: Xi Ruoyao Date: Fri, 18 Nov 2022 14:13:12 +0800 Subject: [PATCH 09/10] pkgmgt: reword the description of cfg files handling Let's not miss the point... --- chapter08/pkgmgt.xml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/chapter08/pkgmgt.xml b/chapter08/pkgmgt.xml index 7496f09a4..d4b616bc7 100644 --- a/chapter08/pkgmgt.xml +++ b/chapter08/pkgmgt.xml @@ -12,8 +12,9 @@ Package Management is an often requested addition to the LFS Book. A Package Manager tracks the installation of files, making it easier to - remove and upgrade packages. A good package manager will handle the - installation of configuration files, and also install the executable files. Before + remove and upgrade packages. A good package manager will also handle the + configuration files specially to keep the user configuration when the + package is reinstalled or upgraded. Before you begin to wonder, NO—this section will not talk about nor recommend any particular package manager. What it does provide is a roundup of the more popular techniques and how they work. The perfect package manager for you may From 7115c88406ec78ea55d5dd576b4c2b4c31556641 Mon Sep 17 00:00:00 2001 From: Xi Ruoyao Date: Fri, 18 Nov 2022 14:28:29 +0800 Subject: [PATCH 10/10] chapter08: fix minor grammar issues --- chapter08/introduction.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/chapter08/introduction.xml b/chapter08/introduction.xml index 2be7fe053..f80ccc0c1 100644 --- a/chapter08/introduction.xml +++ b/chapter08/introduction.xml @@ -34,9 +34,9 @@ First-time builders of LFS are encouraged to build without custom optimizations. - On the other hand, we keeps the optimizations enabled by the default - configuration of packages. In addition, we sometimes explicitly enable an - optimized configuration provided by the package but not enabled by + On the other hand, we keep the optimizations enabled by the default + configuration of the packages. In addition, we sometimes explicitly enable an + optimized configuration provided by a package but not enabled by default. The package maintainers have already tested these configurations and consider them safe, so it's not likely they would break the build. Generally the default configuration already enables