source: introduction/welcome/conventions.xml@ 45ab6c7

11.0 lazarus qt5new trunk
Last change on this file since 45ab6c7 was 45ab6c7, checked in by Xi Ruoyao <xry111@…>, 5 months ago

more SVN prop clean up

Remove "$LastChanged$" everywhere, and also some unused $Date$

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