source: chapter04/settingenviron.xml@ ac82b96

<?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="ch-preps-settingenviron">
  <?dbhtml filename="settingenvironment.html"?>

  <title>Setting Up the Environment</title>

  <para>Set up a good working environment by creating two new startup files
  for the <command>bash</command> shell. While logged in as user
  <systemitem class="username">lfs</systemitem>, issue the following command
  to create a new <filename>.bash_profile</filename>:</para>

<screen><userinput>cat &gt; ~/.bash_profile &lt;&lt; "EOF"
<literal>exec env -i HOME=$HOME TERM=$TERM PS1='\u:\w\$ ' /bin/bash</literal>
EOF</userinput></screen>

  <para>When logged on as user <systemitem class="username">lfs</systemitem>,
  or when switched to the &lfs-user; user using an <command>su</command> command
  with the <quote><parameter>-</parameter></quote> option,
  the initial shell is a <emphasis>login</emphasis> shell which reads
  the <filename>/etc/profile</filename> of the host (probably containing some
  settings and environment variables) and then <filename>.bash_profile</filename>.
  The <command>exec env -i.../bin/bash</command> command in the
  <filename>.bash_profile</filename> file replaces the running shell with a new
  one with a completely empty environment, except for the <envar>HOME</envar>,
  <envar>TERM</envar>, and <envar>PS1</envar> variables. This ensures that no
  unwanted and potentially hazardous environment variables from the host system
  leak into the build environment.</para>

  <para>The new instance of the shell is a <emphasis>non-login</emphasis>
  shell, which does not read, and execute, the contents of the <filename>/etc/profile</filename> or
  <filename>.bash_profile</filename> files, but rather reads, and executes, the
  <filename>.bashrc</filename> file instead. Create the
  <filename>.bashrc</filename> file now:</para>

<screen><userinput>cat &gt; ~/.bashrc &lt;&lt; "EOF"
<literal>set +h
umask 022
LFS=/mnt/lfs
LC_ALL=POSIX
LFS_TGT=<replaceable>x86_64</replaceable>-lfs-linux-gnu
PATH=/usr/bin
if [ ! -L /bin ]; then PATH=/bin:$PATH; fi
PATH=$LFS/tools/bin:$PATH
CONFIG_SITE=$LFS/usr/share/config.site
export LFS LC_ALL LFS_TGT PATH CONFIG_SITE</literal>
EOF</userinput></screen>

  <variablelist>
    <title>The meaning of the settings in <filename>.bashrc</filename></title>

    <varlistentry>
      <term><parameter>set +h</parameter></term>
      <listitem>
  <para>The <command>set +h</command> command turns off
  <command>bash</command>'s hash function. Hashing is ordinarily a useful
  feature&mdash;<command>bash</command> uses a hash table to remember the
  full path to executable files to avoid searching the <envar>PATH</envar>
  time and again to find the same executable. However, the new tools should
  be used as soon as they are installed. Switching off the hash function forces
  the shell to search the <envar>PATH</envar> whenever a program is to
  be run. As such, the shell will find the newly compiled tools in
  <filename class="directory">$LFS/tools/bin</filename> as soon as they are
  available without remembering a previous version of the same program
  provided by the host distro, in
  <filename class='directory'>/usr/bin</filename> or
  <filename class='directory'>/bin</filename>.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><parameter>umask 022</parameter></term>
      <listitem>
  <para>Setting the user file-creation mask (umask) to 022 ensures that newly
  created files and directories are only writable by their owner, but are
  readable and executable by anyone (assuming default modes are used by the
  <ulink role='man' url='&man;open.2'>open(2)</ulink> system call, new files
  will end up with permission mode 644 and directories with mode 755).</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><parameter>LFS=/mnt/lfs</parameter></term>
      <listitem>
  <para>The <envar>LFS</envar> variable should be set to the chosen mount
  point.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><parameter>LC_ALL=POSIX</parameter></term>
      <listitem>
  <para>The <envar>LC_ALL</envar> variable controls the localization of certain
  programs, making their messages follow the conventions of a specified country.
  Setting <envar>LC_ALL</envar> to <quote>POSIX</quote> or <quote>C</quote>
  (the two are equivalent) ensures that everything will work as expected in
  the cross-compilation environment.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><parameter>LFS_TGT=<replaceable>x86_64</replaceable>-lfs-linux-gnu</parameter></term>
      <listitem>
  <para>The <envar>LFS_TGT</envar> variable sets a non-default, but compatible machine
  description for use when building our cross-compiler and linker and when
  cross-compiling our temporary toolchain. More information is provided by
  <xref linkend="ch-tools-toolchaintechnotes" role=""/>.
  If you are not building for 64-bit x86, replace
  <replaceable>x86_64</replaceable> with some value suitable for your target
  machine, for example <literal>i686</literal> for 32-bit x86.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><parameter>PATH=/usr/bin</parameter></term>
      <listitem>
  <para>Many modern Linux distributions have merged <filename
  class="directory">/bin</filename> and <filename
  class="directory">/usr/bin</filename>. When this is the case, the standard
  <envar>PATH</envar> variable should be set to <filename
  class="directory">/usr/bin/</filename> for the <xref
  linkend="chapter-temporary-tools"/> environment. When this is not the
  case, the following line adds <filename class="directory">/bin</filename>
  to the path.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><parameter>if [ ! -L /bin ]; then PATH=/bin:$PATH; fi</parameter></term>
      <listitem>
  <para>If <filename class="directory">/bin</filename> is not a symbolic
  link, it must be added to the <envar>PATH</envar> variable.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><parameter>PATH=$LFS/tools/bin:$PATH</parameter></term>
      <listitem>
  <para>By putting <filename class="directory">$LFS/tools/bin</filename> ahead of the
  standard <envar>PATH</envar>, the cross-compiler installed at the beginning
  of <xref linkend="chapter-cross-tools"/> is picked up by the shell
  immediately after its installation. This, combined with turning off hashing,
  limits the risk that the compiler from the host is used instead of the
  cross-compiler.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><parameter>CONFIG_SITE=$LFS/usr/share/config.site</parameter></term>
      <listitem>
  <para>In <xref linkend="chapter-cross-tools"/> and
  <xref linkend="chapter-temporary-tools"/>, if this variable is not set,
  <command>configure</command> scripts
  may attempt to load configuration items specific to some distributions from
  <filename>/usr/share/config.site</filename> on the host system. Override
  it to prevent potential contamination from the host.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><parameter>export ...</parameter></term>
      <listitem>
        <para>While the preceding commands have set some variables, in order
        to make them visible within any sub-shells, we export them.</para>
      </listitem>
    </varlistentry>

  </variablelist>

  <important>

     <para>Several commercial distributions add an undocumented instantiation
     of <filename>/etc/bash.bashrc</filename> to the initialization of
     <command>bash</command>. This file has the potential to modify the
     <systemitem class="username">lfs</systemitem>
     user's environment in ways that can affect the building of critical LFS
     packages. To make sure the <systemitem class="username">lfs</systemitem>
     user's environment is clean, check for the
     presence of <filename>/etc/bash.bashrc</filename> and, if present, move it
     out of the way.  As the <systemitem class="username">root</systemitem>
     user, run:</para>

     <screen role="nodump"><userinput>[ ! -e /etc/bash.bashrc ] || mv -v /etc/bash.bashrc /etc/bash.bashrc.NOUSE</userinput></screen>

     <para>When the <systemitem class="username">lfs</systemitem>
     user is no longer needed (at the beginning of <xref
     linkend="chapter-chroot-temporary-tools"/>), you may safely restore
     <filename>/etc/bash.bashrc</filename> (if desired).</para>

     <para>Note that the LFS Bash package we will build in
     <xref linkend="ch-system-bash"/> is not configured to load or execute
     <filename>/etc/bash.bashrc</filename>, so this file is useless on a
     completed LFS system.</para>
  </important>

  <para>
    For many modern systems with multiple processors (or cores) the
    compilation time for a package can be reduced by performing a "parallel
    make" by telling the make program how many processors are available via
    a command line option or an environment variable.  For instance, an Intel
    Core i9-13900K processor has 8 P (performance) cores and
    16 E (efficiency) cores, and a P core can simultaneously run two threads
    so each P core are modeled as two logical cores by the Linux kernel.
    As the result there are 32 logical cores in total.  One obvious way to
    use all these logical cores is allowing <command>make</command> to spawn
    up to 32 build jobs.  This can be done by passing the
    <parameter>-j32</parameter> option to <command>make</command>:
  </para>

  <screen role='nodump'><userinput>make -j32</userinput></screen>

  <para>
    Or set the <envar>MAKEFLAGS</envar> environment variable and its
    content will be automatically used by <command>make</command> as
    command line options:
  </para>

  <screen role='nodump'><userinput>export MAKEFLAGS=-j32</userinput></screen>

  <important>
    <para>
      Never pass a <parameter>-j</parameter> option without a number to
      <command>make</command> or set such an option in
      <envar>MAKEFLAGS</envar>.  Doing so will allow <command>make</command>
      to spawn infinite build jobs and cause system stability problems.
    </para>
  </important>

  <para>
    To use all logical cores available for building packages in
    <xref linkend='chapter-cross-tools'/> and
    <xref linkend='chapter-temporary-tools'/>, set <envar>MAKEFLAGS</envar>
    now in <filename>.bashrc</filename>:
  </para>

<screen><userinput>cat &gt;&gt; ~/.bashrc &lt;&lt; "EOF"
<literal>export MAKEFLAGS=-j<replaceable>$(nproc)</replaceable></literal>
EOF</userinput></screen>

  <para>
    Replace <replaceable>$(nproc)</replaceable> with the number of logical
    cores you want to use if you don't want to use all the logical cores.
  </para>

  <para>Finally, to ensure the environment is fully prepared for building the
  temporary tools, force the <command>bash</command> shell to read
  the new user profile:</para>

<screen><userinput>source ~/.bash_profile</userinput></screen>

</sect1>