Conventions Used in this Book

#### Beyond Linux® From Scratch - Version 2019-02-27

### Chapter 1. Welcome to BLFS

- Prev

  Which Sections of the Book Do I Want?

- Next

  Book Version

- Up
- Home

# Conventions Used in this Book

## Typographical Conventions

To make things easy to follow, there are a number of conventions used throughout the book. Following are some examples:

    ./configure --prefix=/usr

> This form of text is designed to be typed exactly as seen unless otherwise noted in the surrounding text. It is also used to identify references to specific commands.

    install-info: unknown option
    `--dir-file=/mnt/lfs/usr/info/dir'

> This form of text (fixed width text) is showing screen output, probably a result from issuing a command. It is also used to show filenames such as `/boot/grub/grub.conf`

Emphasis

> This form of text is used for several purposes in the book but mainly to emphasize important points or to give examples as to what to type.

http://www.linuxfromscratch.org/

> This form of text is used for hypertext links external to the book such as HowTos, download locations, websites, etc.

SeaMonkey-2.49.4

> This form of text is used for links internal to the book such as another section describing a different package.

    cat > $LFS/etc/group << "EOF"
    root:x:0:
    bin:x:1:
    ......
    EOF

> This type of section is used mainly when creating configuration files. The first command (in bold) tells the system to create the file `$LFS/etc/group` from whatever is typed on the following lines until the sequence EOF is encountered. Therefore, this whole section is generally typed as seen.

`<REPLACED TEXT>`

> This form of text is used to encapsulate text that should be modified and is not to be typed as seen, or copy and pasted. Note that the square brackets are not part of the text, but should be substituted for as well.

`root`

> This form of text is used to show a specific system user or group reference in the instructions.

## Conventions Used for Package Dependencies

When packages are created, the authors depend on prior work. In order to build a package in BLFS, these dependencies must be built prior to the desired package. For each package, any prerequisite packages are listed in one or more separate sections: Required, Recommended, and Optional.

### Required Dependencies

These dependencies are the minimum prerequisite packages required to build the package. Omitted from the list are packages in LFS and required dependencies of other required packages.

### Recommended Dependencies

These dependencies are those that the BLFS editors have determined are important to give the package reasonable capabilities. Package installation instructions assume they are installed. If a recommended package is not desired, the instructions may need to be modified to accommodate the missing package.

### Optional Dependencies

These dependencies are those that the package may use. Integration of optional dependencies may be automatic by the package or may need additional instructions not presented by BLFS. Optional packages may be listed without corresponding BLFS instructions. In this case it is up to the user to determine appropriate installation instructions.

## Conventions Used for Kernel Configuration Options

Some packages have specific needs regarding the kernel configuration. The general layout is the following:

    Master section --->
      Subsection --->
        [*]     Required parameter                     [CONFIG_REQU_PAR]
        <*>     Required parameter (not as module)     [CONFIG_REQU_PAR_NMOD]
        <*/M>   Required parameter (could be a module) [CONFIG_REQU_PAR_MOD]
        <*/M/ > Optional parameter                     [CONFIG_OPT_PAR]
        [ ] Incompatible parameter                     [CONFIG_INCOMP_PAR]
        < > Incompatible parameter (even as module)    [CONFIG_INCOMP_PAR_MOD]

[CONFIG_...] on the right gives the name of the option, so you can easily check whether it is set in your `config` file. The meaning of the various entries is:

> Master section | top level menu item
> Subsection | submenu item
> Required parameter | the option could be either built-in or not selected: it must be selected
> Required parameter (not as module) | the option could be either built-in, module, or not selected: it must be selected as built-in
> Required parameter (could be a module) | the option could be either built-in, module, or not selected: it must be selected, either as built-in or module
> Optional parameter | rarely used: the option could be either built-in, module, or not selected: it may be selected at will
> Incompatible parameter | the option could be either built-in or not selected: it must not be selected
> Incompatible parameter (even as module) | the option could be either built-in, module, or not selected: it must not be selected

Note that, depending on other selections, the angle brackets (<>) may appear as braces ({}), if the option cannot be unselected, or even dashes (-*- or -M-), when the choice is imposed. The help text about the option specifies the other selections on which this option relies, and how those other selections are set.

## SBU values in BLFS

As in LFS, each package in BLFS has a build time listed in Standard Build Units (SBUs). These times are relative to the time it took to build binutils in LFS and are intended to provide some insight into how long it will take to build a package. Most times listed are for a single processor or core to build the package. In some cases, large, long running builds tested on multi-core systems have SBU times listed with comments such as '(parallelism=4)'. These values indicate testing was done using multiple cores. Note that while this speeds up the build on systems with the appropriate hardware, the speedup is not linear and to some extent depends on the individual package and specific hardware used.

For packages which use ninja (e.g. anything using meson) or rust, by default all cores are used so similar comments will be seen on such packages even when the build time is minimal.

Where even a parallel build takes more than 15 SBU, on certain machines the time may be considerably greater even when the build does not use swap. In particular, different micro-architectures will build some files at different relative speeds and this can introduce delays when certain make targets wait for another file to be created. Where a large build uses a lot of C++ files, processors with Simultaneous Multi Threading will share the Floating Point Unit and can take 45% longer than when using four 'prime' cores (measured on an intel i7 using taskset and keeping the other cores idle).

Some packages do not support parallel builds and using -j1 for the make command is required. Packages that are known to have such limits are marked as such in the text.

Last updated on 2018-09-23 12:06:59 -0500

- Prev

  Which Sections of the Book Do I Want?

- Next

  Book Version

- Up
- Home