diff --git a/appendices/dependencies.xml b/appendices/dependencies.xml index 99b84c385..1fbab8e10 100644 --- a/appendices/dependencies.xml +++ b/appendices/dependencies.xml @@ -2998,14 +2998,14 @@ &dependencies; Bash, Binutils, Coreutils, Diffutils, Eudev, Findutils, Gawk, - GCC, Gettext, Glibc, Grep, Libcap, Make, Ncurses, Sed, and Zlib + GCC, Gettext, Glibc, Grep, Make, Ncurses, Sed, and Zlib &runtime; - Glibc, Libcap, Ncurses, Readline, and Zlib + Glibc, Ncurses, Readline, and Zlib @@ -3027,6 +3027,8 @@ &external; + Libcap-NG, Linux-PAM and The package or section the problem was encountered in - The exact error message, or a clear decription of the problem + The exact error message, or a clear description of the problem Note whether you have deviated from the book at all diff --git a/chapter04/addinguser.xml b/chapter04/addinguser.xml index a7f12a1ea..999d50ba5 100644 --- a/chapter04/addinguser.xml +++ b/chapter04/addinguser.xml @@ -62,7 +62,7 @@ useradd -s /bin/bash -g lfs -m -k /dev/null lfs lfs - This is the actual name for the created user. + This is the name of the new user. @@ -71,7 +71,7 @@ useradd -s /bin/bash -g lfs -m -k /dev/null lfs If you want to log in as &lfs-user; or switch to &lfs-user; from a non-&root; user (as opposed to switching to user &lfs-user; when logged in as &root;, which does not require the &lfs-user; user to - have a password), you need to set a password of &lfs-user;. Issue the + have a password), you need to set a password for &lfs-user;. Issue the following command as the &root; user to set the password: passwd lfs diff --git a/chapter04/settingenviron.xml b/chapter04/settingenviron.xml index a57246217..d801aa9ab 100644 --- a/chapter04/settingenviron.xml +++ b/chapter04/settingenviron.xml @@ -19,9 +19,9 @@ exec env -i HOME=$HOME TERM=$TERM PS1='\u:\w\$ ' /bin/bash EOF - When logged on as user lfs - or switched to the &lfs-user; user using a su command - with - option, + When logged on as user lfs, + or when switched to the &lfs-user; user using an su command + with the - option, the initial shell is a login shell which reads the /etc/profile of the host (probably containing some settings and environment variables) and then .bash_profile. @@ -30,8 +30,7 @@ EOF one with a completely empty environment, except for the HOME, TERM, and PS1 variables. This ensures that no unwanted and potentially hazardous environment variables from the host system - leak into the build environment. The technique used here achieves the goal of - ensuring a clean environment. + leak into the build environment. The new instance of the shell is a non-login shell, which does not read, and execute, the contents of the /etc/profile or @@ -100,7 +99,7 @@ EOF programs, making their messages follow the conventions of a specified country. Setting LC_ALL to POSIX or C (the two are equivalent) ensures that everything will work as expected in - the chroot environment. + the cross-compilation environment. @@ -108,8 +107,8 @@ EOF LFS_TGT=(uname -m)-lfs-linux-gnu The LFS_TGT variable sets a non-default, but compatible machine - description for use when building our cross compiler and linker and when cross - compiling our temporary toolchain. More information is contained in + description for use when building our cross-compiler and linker and when + cross-compiling our temporary toolchain. More information is provided by . @@ -132,7 +131,7 @@ EOF if [ ! -L /bin ]; then PATH=/bin:$PATH; fi If /bin is not a symbolic - link, then it has to be added to the PATH variable. + link, it must be added to the PATH variable. @@ -163,7 +162,7 @@ EOF export ... - While the above commands have set some variables, in order + While the preceding commands have set some variables, in order to make them visible within any sub-shells, we export them. @@ -172,7 +171,7 @@ EOF - Several commercial distributions add a non-documented instantiation + Several commercial distributions add an undocumented instantiation of /etc/bash.bashrc to the initialization of bash. This file has the potential to modify the lfs @@ -185,9 +184,9 @@ EOF [ ! -e /etc/bash.bashrc ] || mv -v /etc/bash.bashrc /etc/bash.bashrc.NOUSE - After use of the lfs - user is finished at the beginning of , you can restore + When the lfs + user is no longer needed (at the beginning of ), you may safely restore /etc/bash.bashrc (if desired). Note that the LFS Bash package we will build in @@ -196,7 +195,7 @@ EOF completed LFS system. - Finally, to have the environment fully prepared for building the + Finally, to ensure the environment is fully prepared for building the temporary tools, force the bash shell to read the new user profile: diff --git a/chapter05/binutils-pass1.xml b/chapter05/binutils-pass1.xml index 4dab2b1a5..65e8dd2ae 100644 --- a/chapter05/binutils-pass1.xml +++ b/chapter05/binutils-pass1.xml @@ -84,7 +84,7 @@ cd build --prefix=$LFS/tools This tells the configure script to prepare to install the - binutils programs in the $LFS/tools directory. diff --git a/chapter05/gcc-pass1.xml b/chapter05/gcc-pass1.xml index bc875215b..2096acbe7 100644 --- a/chapter05/gcc-pass1.xml +++ b/chapter05/gcc-pass1.xml @@ -50,9 +50,9 @@ use them: There are frequent misunderstandings about this chapter. The - procedures are the same as every other chapter as explained earlier (). First extract the gcc tarball from the sources - directory and then change to the directory created. Only then should you + procedures are the same as every other chapter, as explained earlier (). First, extract the gcc-&gcc-version; tarball from the sources + directory, and then change to the directory created. Only then should you proceed with the instructions below. tar -xf ../mpfr-&mpfr-version;.tar.xz @@ -103,9 +103,9 @@ cd build --with-glibc-version=&glibc-version; - This option specifies the version of glibc which will be + This option specifies the version of Glibc which will be used on the target. It is not relevant to the libc of the host - distro because everything compiled by pass1 gcc will run in the + distro because everything compiled by pass1 GCC will run in the chroot environment, which is isolated from libc of the host distro. @@ -148,7 +148,7 @@ cd build --disable-shared This switch forces GCC to link its internal libraries - statically. We need this because the shared libraries require glibc, + statically. We need this because the shared libraries require Glibc, which is not yet installed on the target system. @@ -199,7 +199,7 @@ cd build time of this build of GCC $LFS/usr/include/limits.h does not exist, so the internal header that has just been installed is a partial, self-contained file and does not include the extended features of - the system header. This is adequate for building glibc, but the full + the system header. This is adequate for building Glibc, but the full internal header will be needed later. Create a full version of the internal header using a command that is identical to what the GCC build system does in normal circumstances: diff --git a/chapter05/glibc.xml b/chapter05/glibc.xml index f9d2ff2dc..d3e5600e8 100644 --- a/chapter05/glibc.xml +++ b/chapter05/glibc.xml @@ -43,7 +43,7 @@ Installation of Glibc - Some of the Glibc programs use the non-FHS compliant + Some of the Glibc programs use the non-FHS-compliant /var/db directory to store their runtime data. Apply the following patch to make such programs store their runtime data in the FHS-compliant locations: @@ -107,7 +107,7 @@ cd build libc_cv_slibdir=/usr/lib This ensures that the library is installed in /usr/lib instead - of the default /lib64 on 64 bit machines. + of the default /lib64 on 64-bit machines. @@ -125,11 +125,11 @@ cd build The missing or incompatible msgfmt program is generally harmless. This msgfmt program is part of the - Gettext package which the host distribution should provide. + Gettext package, which the host distribution should provide. There have been reports that this package may fail when - building as a "parallel make". If this occurs, rerun the make command - with a "-j1" option. + building as a "parallel make". If that occurs, rerun the make command + with the "-j1" option. Compile the package: @@ -140,9 +140,9 @@ cd build If LFS is not properly set, and despite the recommendations, you are building as root, the next command will - install the newly built glibc to your host system, which most likely - will render it unusable. So double check that the environment is - correctly set, before running the following command. + install the newly built Glibc to your host system, which will almost + certainly render it unusable. So double-check that the environment is + correctly set, and that you are not &root;, before running the following command. make DESTDIR=$LFS install @@ -156,15 +156,15 @@ cd build packages to define the location where the package should be installed. If it is not set, it defaults to the root (/) directory. Here we specify that - the package be installed in $LFS - , which will become the root after $LFS + , which will become the root directory in . - Fix hardcoded path to the executable loader in + Fix a hard coded path to the executable loader in the ldd script: sed '/RTLDLIST=/s@/usr@@g' -i $LFS/usr/bin/ldd @@ -185,10 +185,10 @@ readelf -l a.out | grep ld-linux Note that for big-endian machines, the interpreter name will be /lib/ld-linux-aarch64_be.so.1. - If the output is not shown as above or there was no output at all, + If the output is not as shown above, or there is no output at all, then something is wrong. Investigate and retrace the steps to find out where the problem is and correct it. This issue must be resolved before - continuing on. + continuing. Once all is well, clean up the test file: @@ -196,14 +196,14 @@ readelf -l a.out | grep ld-linux - Building packages in the next chapter will serve as an + Building the packages in the next chapter will serve as an additional check that the toolchain has been built properly. If some - package, especially binutils-pass2 or gcc-pass2, fails to build, it is + package, especially Binutils-pass2 or GCC-pass2, fails to build, it is an indication that something has gone wrong with the - previous Binutils, GCC, or Glibc installations. + preceding Binutils, GCC, or Glibc installations. Now that our cross-toolchain is complete, finalize the installation - of the limits.h header. For doing so, run a utility provided by the GCC + of the limits.h header. To do this, run a utility provided by the GCC developers: $LFS/tools/libexec/gcc/$LFS_TGT/&gcc-version;/install-tools/mkheaders diff --git a/chapter05/libstdc++.xml b/chapter05/libstdc++.xml index c02c9aff8..e0ea2e790 100644 --- a/chapter05/libstdc++.xml +++ b/chapter05/libstdc++.xml @@ -28,7 +28,7 @@ to compile C++ code (part of GCC is written in C++), but we had to defer its installation when we built - because it depends on glibc, which was not yet available in the target + because Libstdc++ depends on Glibc, which was not yet available in the target directory. @@ -53,12 +53,12 @@ gcc-&gcc-version; directory. - Create a separate build directory for libstdc++ and enter it: + Create a separate build directory for Libstdc++ and enter it: mkdir -v build cd build - Prepare libstdc++ for compilation: + Prepare Libstdc++ for compilation: ../libstdc++-v3/configure \ --host=$LFS_TGT \ @@ -75,7 +75,7 @@ cd build --host=... - Specifies that the cross compiler we have just built + Specifies that the cross-compiler we have just built should be used instead of the one in /usr/bin. @@ -93,27 +93,27 @@ cd build --with-gxx-include-dir=/tools/$LFS_TGT/include/c++/&gcc-version; This specifies the installation directory for include files. - Because libstdc++ is the standard C++ library for LFS, this + Because Libstdc++ is the standard C++ library for LFS, this directory should match the location where the C++ compiler ($LFS_TGT-g++) would search for the standard C++ include files. In a normal build, this information - is automatically passed to the libstdc++ configure + is automatically passed to the Libstdc++ configure options from the top level directory. In our case, this information must be explicitly given. The C++ compiler will prepend the sysroot path - $LFS (specified building - GCC pass 1) to the include file search path, so it will actually + $LFS (specified when building + GCC-pass1) to the include file search path, so it will actually search in $LFS/tools/$LFS_TGT/include/c++/&gcc-version;. The combination of the DESTDIR variable (in the make install command below) - and this switch ensures to install the headers there. + and this switch causes the headers to be installed there. - Compile libstdc++ by running: + Compile Libstdc++ by running: make @@ -122,7 +122,7 @@ cd build make DESTDIR=$LFS install Remove the libtool archive files because they are harmful for - cross compilation: + cross-compilation: rm -v $LFS/usr/lib/lib{stdc++,stdc++fs,supc++}.la diff --git a/part3intro/toolchaintechnotes.xml b/part3intro/toolchaintechnotes.xml index 53c1f4a23..7401350d8 100644 --- a/part3intro/toolchaintechnotes.xml +++ b/part3intro/toolchaintechnotes.xml @@ -40,8 +40,8 @@ The LFS book is not (and does not contain) a general tutorial to - build a cross (or native) toolchain. Don't use the commands in the - book for a cross toolchain for some purpose other + build a cross- (or native) toolchain. Don't use the commands in the + book for a cross-toolchain for some purpose other than building LFS, unless you really understand what you are doing. @@ -74,7 +74,7 @@ As an example, let us imagine the following scenario (sometimes - referred to as Canadian Cross): we have a + referred to as Canadian Cross). We have a compiler on a slow machine only, let's call it machine A, and the compiler ccA. We also have a fast machine (B), but no compiler for (B), and we want to produce code for a third, slow machine (C). We will build a @@ -145,32 +145,36 @@ Implementation of Cross-Compilation for LFS - All packages involved with cross compilation in the book use an + All the cross-compiled packages in this book use an autoconf-based building system. The autoconf-based building system accepts system types in the form cpu-vendor-kernel-os, - referred to as the system triplet. Since the vendor field is mostly - irrelevant, autoconf allows to omit it. An astute reader may wonder + referred to as the system triplet. Since the vendor field is often + irrelevant, autoconf lets you omit it. + + An astute reader may wonder why a triplet refers to a four component name. The - reason is the kernel field and the os field originated from one + kernel field and the os field began as a single system field. Such a three-field form is still valid - today for some systems, for example - x86_64-unknown-freebsd. But for other systems, - two systems can share the same kernel but still be too different to - use a same triplet for them. For example, an Android running on a + today for some systems, for example, + x86_64-unknown-freebsd. But + two systems can share the same kernel and still be too different to + use the same triplet to describe them. For example, Android running on a mobile phone is completely different from Ubuntu running on an ARM64 - server, despite they are running on the same type of CPU (ARM64) and - using the same kernel (Linux). - Without an emulation layer, you cannot run an - executable for the server on the mobile phone or vice versa. So the - system field is separated into kernel and os fields to - designate these systems unambiguously. For our example, the Android + server, even though they are both running on the same type of CPU (ARM64) and + using the same kernel (Linux). + + Without an emulation layer, you cannot run an + executable for a server on a mobile phone or vice versa. So the + system field has been divided into kernel and os fields, to + designate these systems unambiguously. In our example, the Android system is designated aarch64-unknown-linux-android, and the Ubuntu system is designated - aarch64-unknown-linux-gnu. The word - triplet remained. A simple way to determine your + aarch64-unknown-linux-gnu. + + The word triplet remains embedded in the lexicon. A simple way to determine your system triplet is to run the config.guess script that comes with the source for many packages. Unpack the binutils - sources and run the script: ./config.guess and note + sources, run the script ./config.guess, and note the output. For example, for a 32-bit Intel processor the output will be i686-pc-linux-gnu. On a 64-bit system it will be x86_64-pc-linux-gnu. On most @@ -193,11 +197,11 @@ tree. - In order to fake a cross compilation in LFS, the name of the host triplet + In order to fake a cross-compilation in LFS, the name of the host triplet is slightly adjusted by changing the "vendor" field in the LFS_TGT variable so it says "lfs". We also use the - --with-sysroot option when building the cross linker and - cross compiler to tell them where to find the needed host files. This + --with-sysroot option when building the cross-linker and + cross-compiler to tell them where to find the needed host files. This ensures that none of the other programs built in can link to libraries on the build machine. Only two stages are mandatory, plus one more for tests. @@ -237,11 +241,11 @@ Now, there is more about cross-compiling: the C language is not just a compiler, but also defines a standard library. In this book, the GNU C library, named glibc, is used (there is an alternative, "musl"). This library must - be compiled for the LFS machine; that is, using the cross compiler cc1. - But the compiler itself uses an internal library implementing complex + be compiled for the LFS machine; that is, using the cross-compiler cc1. + But the compiler itself uses an internal library providing complex subroutines for functions not available in the assembler instruction set. This internal library is named libgcc, and it must be linked to the glibc - library to be fully functional! Furthermore, the standard library for + library to be fully functional. Furthermore, the standard library for C++ (libstdc++) must also be linked with glibc. The solution to this chicken and egg problem is first to build a degraded cc1-based libgcc, lacking some functionalities such as threads and exception handling, and then @@ -249,36 +253,55 @@ degraded), and also to build libstdc++. This last library will lack some of the functionality of libgcc. - This is not the end of the story: the upshot of the preceding - paragraph is that cc1 is unable to build a fully functional libstdc++, but - this is the only compiler available for building the C/C++ libraries - during stage 2! Of course, the compiler built during stage 2, cc-lfs, - would be able to build those libraries, but (1) the build system of - gcc does not know that it is usable on pc, and (2) using it on pc - would create a risk of linking to the pc libraries, since cc-lfs is a native - compiler. So we have to re-build libstdc++ later as a part of - gcc stage 2. + The upshot of the preceding paragraph is that cc1 is unable to + build a fully functional libstdc++ with the degraded libgcc, but cc1 + is the only compiler available for building the C/C++ libraries + during stage 2. Of course, the compiler built by stage 2, cc-lfs, + would be able to build those libraries, but: - In &ch-final; (or stage 3), all packages needed for - the LFS system are built. Even if a package is already installed into - the LFS system in a previous chapter, we still rebuild the package - unless we are completely sure it's unnecessary. The main reason for - rebuilding these packages is to settle them down: if we reinstall a LFS + + + + Generally cc-lfs cannot run on pc (the host distro). Despite the + triplets of pc and lfs are compatible to each other, an executable + for lfs will depend on glibc-&glibc-version; while the host distro + may utilize a different libc implementation (for example, musl) or + a previous release of glibc (for example, glibc-2.13). + + + + + Even if cc-lfs happens to run on pc, using it on pc would create + a risk of linking to the pc libraries, since cc-lfs is a native + compiler. + + + + + So when we build gcc stage 2, we instruct the building system to + rebuild libgcc and libstdc++ with cc1, but link libstdc++ to the newly + rebuilt libgcc instead of the degraded build. Then the rebuilt + libstdc++ will be fully functional. + + In &ch-final; (or stage 3), all the packages needed for + the LFS system are built. Even if a package has already been installed into + the LFS system in a previous chapter, we still rebuild the package. The main reason for + rebuilding these packages is to make them stable: if we reinstall a LFS package on a complete LFS system, the installed content of the package - should be same as the content of the same package installed in + should be the same as the content of the same package when installed in &ch-final;. The temporary packages installed in &ch-tmp-cross; or - &ch-tmp-chroot; cannot satisfy this expectation because some of them - are built without optional dependencies installed, and autoconf cannot - perform some feature checks in &ch-tmp-cross; because of cross - compilation, causing the temporary packages to lack optional features + &ch-tmp-chroot; cannot satisfy this requirement, because some of them + are built without optional dependencies, and autoconf cannot + perform some feature checks in &ch-tmp-cross; because of cross-compilation, + causing the temporary packages to lack optional features, or use suboptimal code routines. Additionally, a minor reason for - rebuilding the packages is allowing to run the testsuite. + rebuilding the packages is to run the test suites. - Other procedural details + Other Procedural Details The cross-compiler will be installed in a separate $LFS/tools directory, since it will not @@ -300,11 +323,11 @@ its library search order. Detailed information can be obtained from ld by passing it the --verbose flag. For example, $LFS_TGT-ld --verbose | grep SEARCH - will illustrate the current search paths and their order. Note that this - example can be run as shown only while being user + will illustrate the current search paths and their order. (Note that this + example can be run as shown only while logged in as user lfs. If you come back to this - page later, replace $LFS_TGT-ld with just - ld. + page later, replace $LFS_TGT-ld with + ld). The next package installed is gcc. An example of what can be seen during its run of configure is: @@ -317,28 +340,28 @@ checking what linker to use... /mnt/lfs/tools/i686-lfs-linux-gnu/bin/ldgcc itself, the same search paths are not necessarily used. To find out which standard linker gcc - will use, run: $LFS_TGT-gcc -print-prog-name=ld. Again, - remove the $LFS_TGT- part if coming back to this - later. + will use, run: $LFS_TGT-gcc -print-prog-name=ld. (Again, + remove the $LFS_TGT- prefix if coming back to this + later.) Detailed information can be obtained from gcc by passing it the -v command line option while compiling a program. For example, $LFS_TGT-gcc -v example.c (or without - $LFS_TGT- if coming back later to this) will show + $LFS_TGT- if coming back later) will show detailed information about the preprocessor, compilation, and assembly stages, including gcc's search paths for included headers and their order. - Next installed are sanitized Linux API headers. These allow the + Next up: sanitized Linux API headers. These allow the standard C library (glibc) to interface with features that the Linux kernel will provide. - The next package installed is glibc. The most important + Next comes glibc. The most important considerations for building glibc are the compiler, binary tools, and kernel headers. The compiler is generally not an issue since glibc will always use the compiler relating to the --host - parameter passed to its configure script; e.g. in our case, the compiler + parameter passed to its configure script; e.g., in our case, the compiler will be $LFS_TGT-gcc. The binary tools and kernel headers can be a bit more complicated. Therefore, we take no risks and use the available configure switches to enforce the correct selections. After @@ -350,12 +373,12 @@ checking what linker to use... /mnt/lfs/tools/i686-lfs-linux-gnu/bin/ld-nostdinc and -isystem flags to control the compiler's include search path. These items highlight an important aspect of the glibc - package—it is very self-sufficient in terms of its build machinery + package—it is very self-sufficient in terms of its build machinery, and generally does not rely on toolchain defaults. As mentioned above, the standard C++ library is compiled next, followed in - by other programs that need - to be cross compiled for breaking circular dependencies at build time. + by other programs that must + be cross-compiled to break circular dependencies at build time. The install step of all those packages uses the DESTDIR variable to force installation in the LFS filesystem. @@ -377,7 +400,7 @@ checking what linker to use... /mnt/lfs/tools/i686-lfs-linux-gnu/bin/ld, final versions of all the - packages needed for a fully functional system are built, tested and + packages needed for a fully functional system are built, tested, and installed. diff --git a/prologue/errata.xml b/prologue/errata.xml index 275eac7da..bfb6bc01b 100644 --- a/prologue/errata.xml +++ b/prologue/errata.xml @@ -21,10 +21,12 @@ build the LFS system. In addition, the Linux From Scratch editors maintain a list of security - vulnerabilities discovered after a book has been released. To see - whether there are any known security vulnerabilities, please visit - before proceeding with your build. You should also continue - to consult the advisories, and fix any security vulnerabilities, even - when the LFS system has been completely constructed. + vulnerabilities discovered after a book has been released. To read the list, please visit + before proceeding with your build. You should apply + the changes suggested by the advisories to the relevant sections of the + book as you build the LFS system. And, if you will use the LFS system as + a real desktop or server system, you should continue to consult the + advisories and fix any security vulnerabilities, even when the LFS system + has been completely constructed.