source: chapter04/settingenviron.xml

Last change on this file was ea93c11, checked in by Xi Ruoyao <xry111@…>, 3 months ago

treewide: Use <ulink> instead of <filename> for man pages

"gcc(1)" is really not a file name.

Use <ulink> and link to the online man page on so the user can refer to the man pages more

The change is done via a sed command and long lines are wrapped

  • Property mode set to 100644
File size: 10.8 KB
1<?xml version="1.0" encoding="UTF-8"?>
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="ch-preps-settingenviron">
9 <?dbhtml filename="settingenvironment.html"?>
11 <title>Setting Up the Environment</title>
13 <para>Set up a good working environment by creating two new startup files
14 for the <command>bash</command> shell. While logged in as user
15 <systemitem class="username">lfs</systemitem>, issue the following command
16 to create a new <filename>.bash_profile</filename>:</para>
18<screen><userinput>cat &gt; ~/.bash_profile &lt;&lt; "EOF"
19<literal>exec env -i HOME=$HOME TERM=$TERM PS1='\u:\w\$ ' /bin/bash</literal>
22 <para>When logged on as user <systemitem class="username">lfs</systemitem>,
23 or when switched to the &lfs-user; user using an <command>su</command> command
24 with the <quote><parameter>-</parameter></quote> option,
25 the initial shell is a <emphasis>login</emphasis> shell which reads
26 the <filename>/etc/profile</filename> of the host (probably containing some
27 settings and environment variables) and then <filename>.bash_profile</filename>.
28 The <command>exec env -i.../bin/bash</command> command in the
29 <filename>.bash_profile</filename> file replaces the running shell with a new
30 one with a completely empty environment, except for the <envar>HOME</envar>,
31 <envar>TERM</envar>, and <envar>PS1</envar> variables. This ensures that no
32 unwanted and potentially hazardous environment variables from the host system
33 leak into the build environment.</para>
35 <para>The new instance of the shell is a <emphasis>non-login</emphasis>
36 shell, which does not read, and execute, the contents of the <filename>/etc/profile</filename> or
37 <filename>.bash_profile</filename> files, but rather reads, and executes, the
38 <filename>.bashrc</filename> file instead. Create the
39 <filename>.bashrc</filename> file now:</para>
41<screen><userinput>cat &gt; ~/.bashrc &lt;&lt; "EOF"
42<literal>set +h
43umask 022
46LFS_TGT=$(uname -m)-lfs-linux-gnu
48if [ ! -L /bin ]; then PATH=/bin:$PATH; fi
54 <variablelist>
55 <title>The meaning of the settings in <filename>.bashrc</filename></title>
57 <varlistentry>
58 <term><parameter>set +h</parameter></term>
59 <listitem>
60 <para>The <command>set +h</command> command turns off
61 <command>bash</command>'s hash function. Hashing is ordinarily a useful
62 feature&mdash;<command>bash</command> uses a hash table to remember the
63 full path to executable files to avoid searching the <envar>PATH</envar>
64 time and again to find the same executable. However, the new tools should
65 be used as soon as they are installed. Switching off the hash function forces
66 the shell to search the <envar>PATH</envar> whenever a program is to
67 be run. As such, the shell will find the newly compiled tools in
68 <filename class="directory">$LFS/tools/bin</filename> as soon as they are
69 available without remembering a previous version of the same program
70 provided by the host distro, in
71 <filename class='directory'>/usr/bin</filename> or
72 <filename class='directory'>/bin</filename>.</para>
73 </listitem>
74 </varlistentry>
76 <varlistentry>
77 <term><parameter>umask 022</parameter></term>
78 <listitem>
79 <para>Setting the user file-creation mask (umask) to 022 ensures that newly
80 created files and directories are only writable by their owner, but are
81 readable and executable by anyone (assuming default modes are used by the
82 <ulink role='man' url='&man;open.2'>open(2)</ulink> system call, new files
83 will end up with permission mode 644 and directories with mode 755).</para>
84 </listitem>
85 </varlistentry>
87 <varlistentry>
88 <term><parameter>LFS=/mnt/lfs</parameter></term>
89 <listitem>
90 <para>The <envar>LFS</envar> variable should be set to the chosen mount
91 point.</para>
92 </listitem>
93 </varlistentry>
95 <varlistentry>
96 <term><parameter>LC_ALL=POSIX</parameter></term>
97 <listitem>
98 <para>The <envar>LC_ALL</envar> variable controls the localization of certain
99 programs, making their messages follow the conventions of a specified country.
100 Setting <envar>LC_ALL</envar> to <quote>POSIX</quote> or <quote>C</quote>
101 (the two are equivalent) ensures that everything will work as expected in
102 the cross-compilation environment.</para>
103 </listitem>
104 </varlistentry>
106 <varlistentry>
107 <term><parameter>LFS_TGT=$(uname -m)-lfs-linux-gnu</parameter></term>
108 <listitem>
109 <para>The <envar>LFS_TGT</envar> variable sets a non-default, but compatible machine
110 description for use when building our cross-compiler and linker and when
111 cross-compiling our temporary toolchain. More information is provided by
112 <xref linkend="ch-tools-toolchaintechnotes" role=""/>.</para>
113 </listitem>
114 </varlistentry>
116 <varlistentry>
117 <term><parameter>PATH=/usr/bin</parameter></term>
118 <listitem>
119 <para>Many modern Linux distributions have merged <filename
120 class="directory">/bin</filename> and <filename
121 class="directory">/usr/bin</filename>. When this is the case, the standard
122 <envar>PATH</envar> variable should be set to <filename
123 class="directory">/usr/bin/</filename> for the <xref
124 linkend="chapter-temporary-tools"/> environment. When this is not the
125 case, the following line adds <filename class="directory">/bin</filename>
126 to the path.</para>
127 </listitem>
128 </varlistentry>
130 <varlistentry>
131 <term><parameter>if [ ! -L /bin ]; then PATH=/bin:$PATH; fi</parameter></term>
132 <listitem>
133 <para>If <filename class="directory">/bin</filename> is not a symbolic
134 link, it must be added to the <envar>PATH</envar> variable.</para>
135 </listitem>
136 </varlistentry>
138 <varlistentry>
139 <term><parameter>PATH=$LFS/tools/bin:$PATH</parameter></term>
140 <listitem>
141 <para>By putting <filename class="directory">$LFS/tools/bin</filename> ahead of the
142 standard <envar>PATH</envar>, the cross-compiler installed at the beginning
143 of <xref linkend="chapter-cross-tools"/> is picked up by the shell
144 immediately after its installation. This, combined with turning off hashing,
145 limits the risk that the compiler from the host is used instead of the
146 cross-compiler.</para>
147 </listitem>
148 </varlistentry>
150 <varlistentry>
151 <term><parameter>CONFIG_SITE=$LFS/usr/share/</parameter></term>
152 <listitem>
153 <para>In <xref linkend="chapter-cross-tools"/> and
154 <xref linkend="chapter-temporary-tools"/>, if this variable is not set,
155 <command>configure</command> scripts
156 may attempt to load configuration items specific to some distributions from
157 <filename>/usr/share/</filename> on the host system. Override
158 it to prevent potential contamination from the host.</para>
159 </listitem>
160 </varlistentry>
162 <varlistentry>
163 <term><parameter>export ...</parameter></term>
164 <listitem>
165 <para>While the preceding commands have set some variables, in order
166 to make them visible within any sub-shells, we export them.</para>
167 </listitem>
168 </varlistentry>
170 </variablelist>
172 <important>
174 <para>Several commercial distributions add an undocumented instantiation
175 of <filename>/etc/bash.bashrc</filename> to the initialization of
176 <command>bash</command>. This file has the potential to modify the
177 <systemitem class="username">lfs</systemitem>
178 user's environment in ways that can affect the building of critical LFS
179 packages. To make sure the <systemitem class="username">lfs</systemitem>
180 user's environment is clean, check for the
181 presence of <filename>/etc/bash.bashrc</filename> and, if present, move it
182 out of the way. As the <systemitem class="username">root</systemitem>
183 user, run:</para>
185 <screen role="nodump"><userinput>[ ! -e /etc/bash.bashrc ] || mv -v /etc/bash.bashrc /etc/bash.bashrc.NOUSE</userinput></screen>
187 <para>When the <systemitem class="username">lfs</systemitem>
188 user is no longer needed (at the beginning of <xref
189 linkend="chapter-chroot-temporary-tools"/>), you may safely restore
190 <filename>/etc/bash.bashrc</filename> (if desired).</para>
192 <para>Note that the LFS Bash package we will build in
193 <xref linkend="ch-system-bash"/> is not configured to load or execute
194 <filename>/etc/bash.bashrc</filename>, so this file is useless on a
195 completed LFS system.</para>
196 </important>
198 <para>
199 For many modern systems with multiple processors (or cores) the
200 compilation time for a package can be reduced by performing a "parallel
201 make" by telling the make program how many processors are available via
202 a command line option or an environment variable. For instance, an Intel
203 Core i9-13900K processor has 8 P (performance) cores and
204 16 E (efficiency) cores, and a P core can simultaneously run two threads
205 so each P core are modeled as two logical cores by the Linux kernel.
206 As the result there are 32 logical cores in total. One obvious way to
207 use all these logical cores is allowing <command>make</command> to spawn
208 up to 32 build jobs. This can be done by passing the
209 <parameter>-j32</parameter> option to <command>make</command>:
210 </para>
212 <screen role='nodump'><userinput>make -j32</userinput></screen>
214 <para>
215 Or set the <envar>MAKEFLAGS</envar> environment variable and its
216 content will be automatically used by <command>make</command> as
217 command line options:
218 </para>
220 <screen role='nodump'><userinput>export MAKEFLAGS=-j32</userinput></screen>
222 <important>
223 <para>
224 Never pass a <parameter>-j</parameter> option without a number to
225 <command>make</command> or set such an option in
226 <envar>MAKEFLAGS</envar>. Doing so will allow <command>make</command>
227 to spawn infinite build jobs and cause system stability problems.
228 </para>
229 </important>
231 <para>
232 To use all logical cores available for building packages in
233 <xref linkend='chapter-cross-tools'/> and
234 <xref linkend='chapter-temporary-tools'/>, set <envar>MAKEFLAGS</envar>
235 now in <filename>.bashrc</filename>:
236 </para>
238<screen><userinput>cat &gt;&gt; ~/.bashrc &lt;&lt; "EOF"
239<literal>export MAKEFLAGS=-j<replaceable>$(nproc)</replaceable></literal>
242 <para>
243 Replace <replaceable>$(nproc)</replaceable> with the number of logical
244 cores you want to use if you don't want to use all the logical cores.
245 </para>
247 <para>Finally, to ensure the environment is fully prepared for building the
248 temporary tools, force the <command>bash</command> shell to read
249 the new user profile:</para>
251<screen><userinput>source ~/.bash_profile</userinput></screen>
Note: See TracBrowser for help on using the repository browser.