mirror of
https://github.com/Zeckmathederg/glfs.git
synced 2025-01-24 23:32:12 +08:00
298 lines
11 KiB
XML
298 lines
11 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
|
<!ENTITY % general-entities SYSTEM "../../general.ent">
|
|
%general-entities;
|
|
]>
|
|
|
|
<sect1 id="conventions">
|
|
<?dbhtml filename="conventions.html"?>
|
|
|
|
|
|
<title>Conventions Used in this Book</title>
|
|
|
|
<sect2>
|
|
<title>Typographical Conventions</title>
|
|
<para>To make things easy to follow, a number of conventions are used
|
|
throughout the book. Here are some examples:</para>
|
|
|
|
<screen><userinput>./configure --prefix=/usr</userinput></screen>
|
|
|
|
<blockquote>
|
|
<para>This form of text should be typed exactly as shown unless
|
|
otherwise noted in the surrounding text. It is also used to identify
|
|
references to specific commands.</para>
|
|
</blockquote>
|
|
|
|
<screen><computeroutput>install-info: unknown option
|
|
`--dir-file=/mnt/lfs/usr/info/dir'</computeroutput></screen>
|
|
|
|
<blockquote>
|
|
<para>This form of text (fixed width font) shows screen
|
|
output, probably the result of issuing a command. It is also used to
|
|
show filenames such as <filename>/boot/grub/grub.conf</filename></para>
|
|
</blockquote>
|
|
|
|
<note>
|
|
<para>Please configure your browser to display fixed-width text with
|
|
a good monospaced font, with which you can distinguish the glyphs of
|
|
<literal>Il1</literal> or <literal>O0</literal> clearly.</para>
|
|
</note>
|
|
|
|
<para><emphasis>Emphasis</emphasis></para>
|
|
|
|
<blockquote>
|
|
<para>This form of text is used for several purposes,
|
|
but mainly to emphasize important points, or to give examples of
|
|
what to type.</para>
|
|
</blockquote>
|
|
|
|
<para><ulink url="https://www.&lfs-domainname;/"/></para>
|
|
|
|
<blockquote>
|
|
<para>This form of text is used for hypertext links external to
|
|
the book, such as HowTos, download locations, websites, etc.</para>
|
|
</blockquote>
|
|
|
|
<para><xref linkend="seamonkey"/></para>
|
|
|
|
<blockquote>
|
|
<para>This form of text is used for links internal to
|
|
the book, such as another section describing a different package.</para>
|
|
</blockquote>
|
|
|
|
<screen><userinput>cat > $LFS/etc/group << "EOF"
|
|
<literal>root:x:0:
|
|
bin:x:1:
|
|
......</literal>
|
|
EOF</userinput></screen>
|
|
|
|
<blockquote>
|
|
<para>This style is mainly used when creating configuration
|
|
files. The first command (in bold) tells the system to create
|
|
the file <filename>$LFS/etc/group</filename> from whatever is typed on the
|
|
following lines, until the sequence EOF is encountered.
|
|
Therefore, this whole section is usually typed exactly as shown.
|
|
Remember, copy and paste is your friend!</para>
|
|
</blockquote>
|
|
|
|
<para><replaceable><REPLACED TEXT></replaceable></para>
|
|
|
|
<blockquote>
|
|
<para>This form of text is used to encapsulate text that should be
|
|
modified, and is not to be typed as shown, or copied and pasted.
|
|
The angle brackets are not part of the literal text; they are part of the
|
|
substitution.</para>
|
|
</blockquote>
|
|
|
|
<para><systemitem class='username'>root</systemitem></para>
|
|
|
|
<blockquote>
|
|
<para>This form of text is used to show a specific system user or group
|
|
reference in the instructions.</para>
|
|
</blockquote>
|
|
|
|
<para> </para> <!-- add extra white space to improve readability -->
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Conventions Used for Package Dependencies</title>
|
|
|
|
<para>When new packages are created, the software's authors depend on prior work. In
|
|
order to build a package in BLFS, these dependencies must be built before
|
|
the desired package can be compiled. For each package, prerequisites are listed
|
|
in one or more separate sections: Required, Recommended, and Optional.</para>
|
|
|
|
<bridgehead renderas="sect3">Required Dependencies</bridgehead>
|
|
|
|
<para>These dependencies are the bare minimum needed to
|
|
build the package. Packages in LFS, and the required
|
|
dependencies of these required packages, are omitted from this list.
|
|
Always remember to check for nested dependencies. If a dependency is
|
|
said to be <quote>runtime</quote>, then it is not needed for building
|
|
the package, but only to use it after installation.</para>
|
|
|
|
<bridgehead renderas="sect3">Recommended Dependencies</bridgehead>
|
|
|
|
<para>These are dependencies the BLFS editors have determined
|
|
are important to give the package reasonable capabilities. If a
|
|
recommended dependency is not said to be <quote>runtime</quote>, package
|
|
installation instructions assume it is installed. If it
|
|
is not installed, the instructions may require modification, to
|
|
accommodate the missing package. A recommended <quote>runtime</quote>
|
|
dependency does not need to be installed before building the package, but
|
|
must be built afterwards for running the package with reasonable
|
|
capabilities.</para>
|
|
|
|
<bridgehead renderas="sect3">Optional Dependencies</bridgehead>
|
|
|
|
<para>These are dependencies the package <emphasis>may</emphasis> use. Integration
|
|
of optional dependencies may be automatic by the package, or
|
|
additional steps not presented by BLFS may be necessary. Optional dependencies are
|
|
sometimes listed without explicit BLFS instructions. In this case you must
|
|
determine how to perform the installation yourself.</para>
|
|
|
|
<para> </para> <!-- add extra white space to improve readability -->
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Conventions Used for Kernel Configuration Options</title>
|
|
|
|
<para>Some packages require specific kernel configuration options.
|
|
The general layout for these looks like this:</para>
|
|
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
href="conventions-kernel.xml"/>
|
|
|
|
<para>[...] on the right gives the symbolic name of the option, so you
|
|
can easily check whether it is set in your <filename>.config</filename>
|
|
file. Note that the <filename>.config</filename> file contains a
|
|
<literal>CONFIG_</literal> prefix before all symbolic names. The
|
|
meaning of the various entries is:
|
|
|
|
<blockquote>
|
|
<informaltable frame='none'><tgroup cols="2">
|
|
<colspec align="left"/><colspec align="left"/><tbody>
|
|
<row>
|
|
<entry><emphasis role="bold">Master section</emphasis></entry>
|
|
<entry>top level menu item</entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="bold">Subsection</emphasis></entry>
|
|
<entry>submenu item</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<emphasis role="bold">Required parameter</emphasis></entry>
|
|
<entry>
|
|
the option can either be built-in, or not selected: it must be
|
|
selected
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<emphasis role="bold">Required parameter (not as
|
|
module)</emphasis>
|
|
</entry>
|
|
<entry>
|
|
the option can be built-in, a module, or not selected (tri-state):
|
|
it must be selected as built-in
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<emphasis role="bold">Required parameter (could be
|
|
a module)</emphasis>
|
|
</entry>
|
|
<entry>
|
|
the option can be built-in, a module, or not selected:
|
|
it must be selected, either as built-in or as a module
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<emphasis role="bold">Required parameter (as
|
|
a module)</emphasis>
|
|
</entry>
|
|
<entry>
|
|
the option can be built-in, a module, or not selected:
|
|
it must be selected as a module; selecting it as built-in
|
|
may cause unwanted effects
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<emphasis role="bold">Optional parameter</emphasis>
|
|
</entry>
|
|
<entry>
|
|
the option can be built-in, a module, or not
|
|
selected: it may be selected as a module or built-in if you
|
|
need it for driving the hardware or optional kernel features
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<emphasis role="bold">Optional parameter (as a module
|
|
if enabled)</emphasis>
|
|
</entry>
|
|
<entry>
|
|
the option can be built-in, a module, or not
|
|
selected: it may be selected as a module if you need it
|
|
for driving the hardware or optional kernel features, but
|
|
selecting it as built-in may cause unwanted effects
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<emphasis role="bold">Incompatible parameter</emphasis>
|
|
</entry>
|
|
<entry>
|
|
the option can either be built-in or not selected: it must
|
|
<emphasis>not</emphasis> be selected
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<emphasis role="bold">Incompatible parameter (even as module)</emphasis>
|
|
</entry>
|
|
<entry>
|
|
the option can be built-in, a module, or not selected:
|
|
it must <emphasis>not</emphasis> be selected
|
|
</entry>
|
|
</row>
|
|
</tbody></tgroup></informaltable>
|
|
</blockquote>
|
|
</para>
|
|
|
|
<para>Note that, depending on other selections, the angle brackets
|
|
(<>) in the configuration menu may appear as braces ({}) if the option cannot be unselected,
|
|
or even as dashes (-*- or -M-), when the choice is imposed.
|
|
The help text describing the option specifies the other selections on which this
|
|
option relies, and how those other selections are set.</para>
|
|
|
|
<para>
|
|
The letter in <emphasis role='blue'>blue</emphasis> is the hotkey
|
|
for this option. If you are running
|
|
<command>make menuconfig</command>, you can press a key to quickly
|
|
traverse all the options with this key as the hotkey on the screen.
|
|
</para>
|
|
|
|
<para> </para> <!-- add extra white space to improve readability -->
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>SBU values in BLFS</title>
|
|
|
|
<para>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 the specific hardware used. </para>
|
|
|
|
<para>For packages which use ninja (i.e., anything using meson) or rust, by
|
|
default all cores are used; similar comments will be seen on such packages
|
|
even when the build time is minimal.</para>
|
|
|
|
<para>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).</para>
|
|
|
|
<para>Some packages do not support parallel builds; for these, the
|
|
make command must specify -j1. Packages that are known to impose such limits are
|
|
so marked in the text.</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|