source: postlfs/filesystems/uefi-bootloaders/grub-efi.xml@ 552bf36

<?xml version="1.0" encoding="ISO-8859-1"?>
<!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;

  <!ENTITY grub-efi-download-http "https://ftp.gnu.org/gnu/grub/grub-&grub-version;.tar.xz">
  <!ENTITY grub-efi-download-ftp  " ">
  <!ENTITY grub-efi-md5sum        "cf0fd928b1e5479c8108ee52cb114363">
  <!ENTITY grub-efi-size          "6.3 MB">
  <!ENTITY grub-efi-buildsize     "137 MB">
  <!ENTITY grub-efi-time          "1.0 SBU">

  <!ENTITY unifont-download-http  "https://unifoundry.com/pub/unifont/unifont-&unifont-version;/font-builds/unifont-&unifont-version;.pcf.gz">
  <!ENTITY unifont-md5sum         "8191ca4fce0eb6073d47c7573e6babc1">
  <!ENTITY unifont-size           "1.3 MB">
]>

<sect1 id="grub-efi" xreflabel="GRUB-&grub-version; for EFI">
  <?dbhtml filename="grub-efi.html"?>

  <sect1info>
    <date>$Date$</date>
  </sect1info>

  <title>GRUB-&grub-version; for EFI</title>

  <indexterm zone="grub-efi">
    <primary sortas="a-grub-efi">grub-efi</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to GRUB</title>

    <para>
      The <application>GRUB</application> package provides GRand Unified
      Bootloader.  In this page it will be built with UEFI support, which
      is not enabled for GRUB built in LFS.
    </para>

    &lfs111_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&grub-efi-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&grub-efi-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &grub-efi-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &grub-efi-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &grub-efi-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &grub-efi-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>

    <itemizedlist spacing="compact">
      <title>Unicode font data used to display GRUB menu</title>
      <listitem>
        <para>
          Download (HTTP): <ulink url="&unifont-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &unifont-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &unifont-size;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">GRUB Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required (runtime)</bridgehead>
    <para role="runtime">
      <xref linkend="efibootmgr"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="freetype2"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="lvm2"/>
    </para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/grub-efi"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of GRUB</title>

    <warning>
      <para>
        The instruction does not work correctly on 32-bit LFS system
        at now.
      </para>
    </warning>

    <para>
      First, install font data as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>mkdir -pv /usr/share/fonts/unifont &amp;&amp;
gunzip -c ../unifont-&unifont-version;.pcf.gz > /usr/share/fonts/unifont/unifont.pcf</userinput></screen>

    <warning>
      <para>Unset any environment variables which may affect the build:</para>

      <screen><userinput>unset {C,CPP,CXX,LD}FLAGS</userinput></screen>

      <para>Don't try <quote>tuning</quote> this package with custom
      compilation flags: this package is a bootloader, with low-level
      operations in the source code which is likely to be broken by some
      aggressive optimizations.</para>
    </warning>

    <para>
      Build <application>GRUB</application> with the following commands:
    </para>

<screen><userinput>./configure --prefix=/usr        \
            --sysconfdir=/etc    \
            --disable-efiemu     \
            --enable-grub-mkfont \
            --with-platform=efi  \
            --disable-werror     &amp;&amp;
make</userinput></screen>

    <para>
      This package does not have a test suite providing meaningful results.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install &amp;&amp;
mv -v /etc/bash_completion.d/grub /usr/share/bash-completion/completions</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <parameter>--enable-grub-mkfont</parameter>: Build the tool named
      <command>grub-mkfont</command> to generate the font file for the boot
      loader from the font data we've installed.
    </para>

    <warning>
      <para>If the recommended dependency <xref linkend="freetype2"/> is not
      installed, it is possible to omit this option and build GRUB.  However,
      if <command>grub-mkfont</command> is not built, or the unicode font
      data is not available at the time GRUB is built, GRUB won't install
      any font for the boot loader.  The GRUB boot menu will be displayed
      using a coarse font and the early stage of kernel initialization will be
      in <quote>blind mode</quote> &mdash; you can't see any kernel messages before
      the graphics card driver is initialized.  It will be very difficult to
      diagnose some boot issues, especially if the graphics driver is
      built as module.</para>
    </warning>

    <para>
      <parameter>--with-platform=efi</parameter>: Ensures building GRUB with
      EFI enabled.
    </para>

    <para>
      <option>--target=i386</option>: Some x86_64 systems have 32-bit UEFI
      implementation, but they are very old and rare.
      Do <emphasis role='bold'>not</emphasis> use this option unless you are
      absolutely sure that LFS is running on such a system.
    </para>

  </sect2>

  <sect2>
    <title>Configuring GRUB</title>

    <para>
      Using GRUB to make the LFS system bootable on UEFI platform will be
      discussed in <xref linkend="grub-setup"/>.
    </para>
  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <para>See the page for GRUB in LFS book.</para>
  </sect2>

</sect1>