source: introduction/welcome/conventions.xml@ 4de7ca7

Last change on this file since 4de7ca7 was 4de7ca7, checked in by Bruce Dubbs <bdubbs@…>, 4 years ago

Numerous typos and text corrections

git-svn-id: svn:// af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 9.8 KB
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
8<sect1 id="conventions">
9 <?dbhtml filename="conventions.html"?>
11 <sect1info>
12 <othername>$LastChangedBy$</othername>
13 <date>$Date$</date>
14 </sect1info>
16 <title>Conventions Used in this Book</title>
18 <sect2>
19 <title>Typographical Conventions</title>
20 <para>To make things easy to follow, there are a number of conventions used
21 throughout the book. Following are some examples:</para>
23<screen><userinput>./configure --prefix=/usr</userinput></screen>
25 <blockquote>
26 <para>This form of text is designed to be typed exactly as seen unless
27 otherwise noted in the surrounding text. It is also used to identify
28 references to specific commands.</para>
29 </blockquote>
31<screen><computeroutput>install-info: unknown option
34 <blockquote>
35 <para>This form of text (fixed width text) is showing screen
36 output, probably a result from issuing a command. It is also used to
37 show filenames such as <filename>/boot/grub/grub.conf</filename></para>
38 </blockquote>
40 <para><emphasis>Emphasis</emphasis></para>
42 <blockquote>
43 <para>This form of text is used for several purposes in the
44 book but mainly to emphasize important points or to give examples as to
45 what to type.</para>
46 </blockquote>
48 <para><ulink url="http://www.&lfs-domainname;/"/></para>
50 <blockquote>
51 <para>This form of text is used for hypertext links external to
52 the book such as HowTos, download locations, websites, etc.</para>
53 </blockquote>
55 <!--<para><xref linkend="seamonkey"/></para>-->
57 <blockquote>
58 <para>This form of text is used for links internal to
59 the book such as another section describing a different package.</para>
60 </blockquote>
62<screen><userinput>cat &gt; $LFS/etc/group &lt;&lt; "EOF"
68 <blockquote>
69 <para>This type of section is used mainly when creating configuration
70 files. The first command (in bold) tells the system to create
71 the file <filename>$LFS/etc/group</filename> from whatever is typed on the
72 following lines until the sequence EOF is encountered.
73 Therefore, this whole section is generally typed as seen.</para>
74 </blockquote>
76 <para><replaceable>&lt;REPLACED TEXT&gt;</replaceable></para>
78 <blockquote>
79 <para>This form of text is used to encapsulate text that should be
80 modified and is not to be typed as seen, or copy and pasted. Note that
81 the square brackets are not part of the text, but should be substituted
82 for as well.</para>
83 </blockquote>
85 <para><systemitem class='username'>root</systemitem></para>
87 <blockquote>
88 <para>This form of text is used to show a specific system user or group
89 reference in the instructions.</para>
90 </blockquote>
92 </sect2>
94 <sect2 id="dependencies">
95 <title>Conventions Used for Package Dependencies</title>
97 <para>When packages are created, the authors depend on prior work. In
98 order to build a package in BLFS, these dependencies must be built prior to
99 the desired package. For each package, any prerequisite packages are listed
100 in one or more separate sections: Required, Recommended, and Optional.</para>
102 <bridgehead renderas="sect3">Required Dependencies</bridgehead>
104 <para>These dependencies are the minimum prerequisite packages required to
105 build the package. Omitted from the list are packages in LFS and required
106 dependencies of other required packages.</para>
108 <bridgehead renderas="sect3">Recommended Dependencies</bridgehead>
110 <para>These dependencies are those that the BLFS editors have determined
111 are important to give the package reasonable capabilities. Package
112 installation instructions assume they are installed. If a recommended
113 package is not desired, the instructions may need to be modified to
114 accommodate the missing package.</para>
116 <bridgehead renderas="sect3">Optional Dependencies</bridgehead>
118 <para>These dependencies are those that the package may use. Integration
119 of optional dependencies may be automatic by the package or may need
120 additional instructions not presented by BLFS. Optional packages may be
121 listed without corresponding BLFS instructions. In this case it is up to
122 the user to determine appropriate installation instructions. </para>
124 </sect2>
126 <sect2>
127 <title>Conventions Used for Kernel Configuration Options</title>
129 <para>Some packages have specific needs regarding the kernel configuration.
130 The general layout is the following:</para>
132<screen><literal>Master section ---&gt;
133 Subsection ---&gt;
134 [*] Required parameter [CONFIG_REQU_PAR]
135 &lt;*&gt; Required parameter (not as module) [CONFIG_REQU_PAR_NMOD]
136 &lt;*/M&gt; Required parameter (could be a module) [CONFIG_REQU_PAR_MOD]
137 &lt;*/M/ &gt; Optional parameter [CONFIG_OPT_PAR]
138 [ ] Incompatible parameter [CONFIG_INCOMP_PAR]
139 &lt; &gt; Incompatible parameter (even as module) [CONFIG_INCOMP_PAR_MOD]</literal></screen>
141 <para>[CONFIG_...] on the right gives the name of the option, so you can
142 easily check whether it is set in your <filename>config</filename> file.
143 The meaning of the various entries is:
145 <blockquote>
146 <informaltable frame='none'><tgroup cols="2">
147 <colspec align="left"/><colspec align="left"/><tbody>
148 <row>
149 <entry><emphasis role="bold">Master section</emphasis></entry>
150 <entry>top level menu item</entry>
151 </row>
152 <row>
153 <entry><emphasis role="bold">Subsection</emphasis></entry>
154 <entry>submenu item</entry>
155 </row>
156 <row>
157 <entry>
158 <emphasis role="bold">Required parameter</emphasis></entry>
159 <entry>
160 the option could be either built-in or not selected: it must be
161 selected
162 </entry>
163 </row>
164 <row>
165 <entry>
166 <emphasis role="bold">Required parameter (not as
167 module)</emphasis>
168 </entry>
169 <entry>
170 the option could be either built-in, module, or not selected:
171 it must be selected as built-in
172 </entry>
173 </row>
174 <row>
175 <entry>
176 <emphasis role="bold">Required parameter (could be
177 a module)</emphasis>
178 </entry>
179 <entry>
180 the option could be either built-in, module, or not selected:
181 it must be selected, either as built-in or module
182 </entry>
183 </row>
184 <row>
185 <entry>
186 <emphasis role="bold">Optional parameter</emphasis>
187 </entry>
188 <entry>
189 rarely used: the option could be either built-in, module, or not
190 selected: it may be selected at will
191 </entry>
192 </row>
193 <row>
194 <entry>
195 <emphasis role="bold">Incompatible parameter</emphasis>
196 </entry>
197 <entry>
198 the option could be either built-in or not selected: it must
199 <emphasis>not</emphasis> be selected
200 </entry>
201 </row>
202 <row>
203 <entry>
204 <emphasis role="bold">Incompatible parameter (even as module)</emphasis>
205 </entry>
206 <entry>
207 the option could be either built-in, module, or not selected:
208 it must <emphasis>not</emphasis> be selected
209 </entry>
210 </row>
211 </tbody></tgroup></informaltable>
212 </blockquote>
213 </para>
215 <para>Note that, depending on other selections, the angle brackets
216 (&lt;&gt;) may appear as braces ({}), if the option cannot be unselected,
217 or even dashes (-*- or -M-), when the choice is imposed.
218 The help text about the option specifies the other selections on which this
219 option relies, and how those other selections are set.</para>
221 </sect2>
223 <sect2>
224 <title>SBU values in BLFS</title>
226 <para>As in LFS, each package in BLFS has a build time listed in Standard
227 Build Units (SBUs). These times are relative to the time it took to build
228 binutils in LFS and are intended to provide some insight into how long it
229 will take to build a package. Most times listed are for a single processor
230 or core to build the package. In some cases, large, long running builds
231 tested on multi-core systems have SBU times listed with comments such
232 as '(parallelism=4)'. These values indicate testing was done using
233 multiple cores. Note that while this speeds up the build on systems with
234 the appropriate hardware, the speedup is not linear and to some extent
235 depends on the individual package and specific hardware used. </para>
237 <para>For packages which use ninja (e.g. anything using meson) or rust, by
238 default all cores are used so similar comments will be seen on such packages
239 even when the build time is minimal.</para>
241 <para>Where even a parallel build takes more than 15 SBU, on certain
242 machines the time may be considerably greater even when the build does not
243 use swap. In particular, different micro-architectures will build some
244 files at different relative speeds and this can introduce delays when
245 certain make targets wait for another file to be created. Where a large
246 build uses a lot of C++ files, processors with Simultaneous Multi Threading
247 will share the Floating Point Unit and can take 45% longer than when using
248 four 'prime' cores (measured on an intel i7 using taskset and keeping the
249 other cores idle).</para>
251 <para>Some packages do not support parallel builds and using -j1 for the
252 make command is required. Packages that are known to have such limits are
253 marked as such in the text.</para>
255 </sect2>
Note: See TracBrowser for help on using the repository browser.