-From rEFIt to rEFInd
-====================
-
-rEFInd is derived from rEFIt (http://refit.sourceforge.net), but the two
-programs support different build environments. rEFIt was created with
-Intel's EFI Application Toolkit
-(http://www.intel.com/technology/efi/toolkit_overview.htm) or TianoCore's
-EFI Toolkit (https://efi-toolkit.tianocore.org), along with Microsoft's
-Visual C compiler.
-
-Compiling the source code provided on the rEFIt site under Linux never
-worked for me, although the documentation claimed it would. Apparently
-other Linux developers have run into the same problem; Debian provides a
-rEFIt package (http://packages.debian.org/sid/refit) that includes
-extensive patches to enable the program to compile under Linux using the
-GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). Although
-GNU-EFI is less sophisticated than recent versions of TianoCore's toolkit,
-GNU-EFI is my preferred environment because it's provided with many Linux
-distributions and it was easy to get started with rEFInd development by
-using GNU-EFI and the Debian rEFIt package as a starting point.
-
-Over time, though, I've found that the recent TianoCore EDK2 toolkit has
-its advantages. Two features, in particular, require the TianoCore EDK2
-toolkit:
-
-- The EFI filesystem drivers, added with rEFInd 0.4.0. This requirement is
- a consequence of the derivation of the drivers, which is via VirtualBox
- and the Clover boot loader, both of which are based on EDK2.
-
-- The legacy BIOS boot feature for UEFI-based PCs. EDK2 is needed in this
- case because of features unique to that environment. Note that the legacy
- BIOS boot feature for Macs works when rEFInd is built via either GNU-EFI
- or the TianoCore EDK2.
-
-For these reasons, effective with rEFInd 0.4.6, I've switched the primary
-build environment from GNU-EFI to TianoCore EDK2. The rEFInd binary itself
-still builds via GNU-EFI, but you must pass the "gnuefi" build target to
-make in order to build in this way, and the resulting binary can't boot
-BIOS-based OSes on UEFI PCs.
-
-I've dropped ancillary programs, such as the gptsync program, from rEFInd.
-You can still use these tools with rEFInd, but you'll need to install them
-separately.
-
-
Requirements
============
* One of the following:
* The TianoCore EDK2 package
- (http://sourceforge.net/projects/tianocore/). I've tested using the
- UDK2010.SR1 and UDK2010.SR1.UP1 variants
- (http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010),
- which are "frozen," rather than the main EDK2 development branch, which
- is changing as the developers add features, fix bugs, and so on. Using
- TianoCore EDK2 is supported in rEFInd version 0.4.3 and later (0.4.0
- and later for the filesystem drivers only). See below for TianoCore
- setup instructions.
+ (http://sourceforge.net/projects/tianocore/). I initially used the
+ UDK2010 package and others in that series, but beginning with rEFInd
+ 0.8.2, I've been using UDK2014
+ (http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2014).
+ All of the UDK release are "frozen," rather than the main EDK2
+ development branch, which is changing as the developers add features,
+ fix bugs, and so on. See below for TianoCore setup instructions.
* The GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). You can
install this from a package called "gnu-efi"; however, rEFInd relies on
- features that were added in (I think) 3.0l to provide driver-loading
- capabilities. The versions I've used and that work are 3.0p and 3.0q.
- As of 5/2012, most Linux distributions seem to deliver rather elderly
- versions of GNU-EFI, so you may need to download the latest source
- code, compile it, and install it locally. Since rEFInd version 0.2.7,
- the Makefiles assume this (see below). The legacy BIOS boot support on
- UEFI-based PCs doesn't work when GNU-EFI is compiled under GNU-EFI, so
- as of rEFInd 0.4.6, GNU-EFI is no longer the primary build environment,
- although it's easier to set up on a Linux system.
+ features that were added sometime between version 3.0s and 3.0u, so I
+ recommend using 3.0u (or conceivably later). You should check your
+ GNU-EFI version number; you may need to download the latest source
+ code, compile it, and install it locally. The Makefiles assume a
+ GNU-EFI package installed via a package manager. If you install from
+ source code, you may need to adjust those Makefiles' paths.
+
+Of the two toolkits, I prefer to use TianoCore because it produces binaries
+that are about 20-30KiB smaller than those made by GNU-EFI, and I can
+easily build 32-bit binaries on my 64-bit Linux installations. Also, I've
+had problems on a 32-bit Mac Mini with the drivers produced by GNU-EFI
+hanging the system if I try to load more than one of them. (I haven't
+encountered this problem on UEFI-based PCs.) That said, the TianoCore EDK2
+package is much harder to install, so you may prefer to use GNU-EFI unless
+you have a specific need for the TianoCore toolkit. Automated build tools
+like the OpenSUSE Build Service (OBS) and the Ubuntu Personal Package
+Archive (PPA) mechanism don't yet support TianoCore.
It's possible to use a non-Linux platform to compile rEFInd. To the best of
my knowledge, the rEFInd code doesn't rely on anything Linux-specific in
Preparing Your Development Kit
==============================
-If you want to build the rEFInd binary but not the drivers, if you don't
-care about booting BIOS-based OSes on UEFI PCs, and if you're using Linux,
-GNU-EFI is the easiest way to do the job. I don't describe its setup here
-because it's likely to be fairly easy. If your distribution provides a
-recent enough version, you should be able to install a package called
-gnu-efi and be done with it. If not, you'll need to download the source
-code tarball, build it, and install it. This process is fairly typical of
-Linux packages. Read the GNU-EFI documentation if you need help. If you're
-using GNU-EFI, you can skip the rest of this section.
-
-To build the EFI drivers, or if you want support for booting BIOS-based
-OSes on UEFI PCs, the TianoCore toolkit is required. You might also want to
-use it if you have problems with GNU-EFI or if you want to build rEFInd on
-a non-Linux platform. Unfortunately, the TianoCore toolkit is weird by
-Linux programming standards. It's also quite large -- it's intended as a
-means to develop a complete EFI firmware implementation, so it contains
-much more code than is needed to develop standalone EFI applications. I
-don't know of any Linux distribution packages for it in RPM, Debian package
-file, or other formats; you MUST install the kit from source code using its
-own unusual compilation procedure. The installation documentation also
-omits at least one step and is a bit unclear about others. Here's how I
-installed the toolkit:
-
-1) Download UDK2010.SR1.UP1 from
- https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010.
-
-2) Type "mkdir /usr/local/UDK2010". You can use another directory, but the
+If you're using Linux, GNU-EFI is the easiest way to compile rEFInd. I
+don't describe GNU-EFI's setup here because it's likely to be fairly easy.
+If your distribution provides a recent enough version, you should be able
+to install a package called gnu-efi and be done with it. If not, you'll
+need to download the source code tarball, build it, and install it. This
+process is fairly typical of Linux packages. Read the GNU-EFI documentation
+if you need help. If you're using GNU-EFI, you can skip the rest of this
+section.
+
+You might also want to use the TianoCore toolkit if you have problems with
+GNU-EFI or if you want to build rEFInd on a non-Linux platform.
+Unfortunately, the TianoCore toolkit is weird by Linux programming
+standards. It's also quite large -- it's intended as a means to develop a
+complete EFI firmware implementation, so it contains much more code than is
+needed to develop standalone EFI applications. I don't know of any Linux
+distribution packages for it in RPM, Debian package file, or other formats;
+you MUST install the kit from source code using its own unusual compilation
+procedure. The installation documentation also omits at least one step and
+is a bit unclear about others. Here's how I installed the toolkit:
+
+1) Download UDK2014.SR1.UP1.P1 from
+ https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2014.
+
+2) Type "mkdir /usr/local/UDK2014". You can use another directory, but the
Makefile for rEFInd's EFI drivers assumes this location. You'll need to
- edit the EDK2BASE line in the Make.common file if you install somewhere
+ edit the EDK2BASE line in the Make.tiano file if you install somewhere
else.
-3) Type "cd /usr/local/UDK2010".
+3) Type "cd /usr/local/UDK2014".
-3) Unzip the downloaded file (UDK2010.SR1.UP1.Complete.MyWorkSpace.zip) in
- the current directory (/usr/local/UDK2010). This creates a handful of
+4) Unzip the downloaded file (UDK2014.SR1.UP1.P1.Complete.MyWorkSpace.zip)
+ in the current directory (/usr/local/UDK2014). This creates a handful of
files, including a tarball and a couple of .zip files.
-4) Type "unzip UDK2010.SR1.UP1.MyWorkSpace.zip". This extracts the
+5) Type "unzip UDK2014.SR1.UP1.MyWorkSpace.zip". This extracts the
platform-neutral portion of the development kit.
-5) Type "cd MyWorkSpace".
+6) Type "cd MyWorkSpace".
-6) Type "tar xvf ../BaseTools\(Unix\).tar". This extracts the
+7) Type "tar xvf ../BaseTools\(Unix\).tar". This extracts the
Linux/Unix-specific portions of the toolkit.
-7) Follow the build instructions at
+8) Follow the build instructions at
https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Using_EDK_II_with_Native_GCC_4.4;
however, a few changes are required, as detailed below....
-8) Type "source edksetup.sh BaseTools". This sets up some environment
+9) Type "source edksetup.sh BaseTools". This sets up some environment
variables, so subsequent steps (NOT including compiling the rEFInd EFI
drivers) must be typed in the shell you use for this step.
-9) Edit Conf/target.txt and change the following:
- - ACTIVE_PLATFORM = MdePkg/MdePkg.dsc
- - TARGET = RELEASE (DEBUG might work, but I've not tested it).
- - TARGET_ARCH = X64 (on x86-64; leave this as IA32 on x86). If you plan
- to build both architectures on an x86-64 system, you can set this to
- "IA32 X64".
- - TOOL_CHAIN_TAG = GCC46 (or other value depending on your GCC version;
- type "gcc -v" to learn your GCC version number). Note that GCC 4.7
- doesn't have its own entry, so use GCC46 for GCC 4.7.
- The TianoCore Makefiles read some of these variables from this file
- and use them when accessing directories, so be sure to type these
- entries in the case specified.
-
-10) The documentation refers to editing Conf/tools_def.txt in addition to
+10) Edit Conf/target.txt and change the following:
+ - ACTIVE_PLATFORM = MdePkg/MdePkg.dsc
+ - TARGET = RELEASE (DEBUG might work, but I've not tested it).
+ - TARGET_ARCH = X64 (on x86-64; leave this as IA32 on x86). If you plan
+ to build both architectures on an x86-64 system, you can set this to
+ "IA32 X64".
+ - TOOL_CHAIN_TAG = GCC46 (or other value depending on your GCC version;
+ type "gcc -v" to learn your GCC version number). Note that GCC 4.7
+ and 4.8 don't have their own entries, so use GCC46 for them.
+ The TianoCore Makefiles read some of these variables from this file
+ and use them when accessing directories, so be sure to type these
+ entries in the case specified.
+
+11) The documentation refers to editing Conf/tools_def.txt in addition to
Conf/target.txt, but doesn't specify what to change in
Conf/tools_def.txt. I haven't found it necessary to make any changes in
Conf/tools_def.txt EXCEPT when using GCC 4.7 on a Fedora 17 system.
to:
*_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64
-11) Type "make -C /usr/local/UDK2010/MyWorkSpace/BaseTools/Source/C".
+12) Type "make -C /usr/local/UDK2014/MyWorkSpace/BaseTools/Source/C".
(This step is not documented on the EDK Web page.) Note that this
requires the g++ compiler and UUID development libraries.
-10) Type "build" to build the main set of EDK2 files. This process is
- likely to take a few minutes.
+13) Type "build" to build the main set of EDK2 files. This process is
+ likely to take a few minutes. This step requires Python 2; if you have
+ Python 3 installed, you may need to adjust the default python for this
+ build (for instance, by typing "eselect python set python2.7" in
+ Gentoo).
If you installed in a location other than the one I've specified, you must
edit the EDK2BASE variable in the Make.tiano and filesystems/Make.tiano
3) Change into the archive's main directory. You should see several files
including this BUILDING.txt file and several subdirectories such as
- "refind", "libeg", and "include".
+ "refind", "libeg", "mok", "filesystems", and "include".
4) Type "make gnuefi" to build with GNU-EFI, or either "make" alone or
"make tiano" to build with TianoCore EDK2. With any luck, rEFInd will
compile without error, leaving the "refind_ia32.efi" or "refind_x64.efi"
- file, depending on your platform, in the "refind" subdirectory. If you
- want to build IA32 binaries on an x86-64 (X64) system, type "ARCH=ia32
- make". This works only if you're using the TianoCore build kit, and only
- if you set TARGET_ARCH to either "IA32" or "IA32 X64" in target.txt when
- you set up the TianoCore. If you plan to build both architectures, be
- sure to copy the .efi file for the first build out of the refind
- subdirectory before building the second architecture.
+ file, depending on your platform, in the "refind" subdirectory. This same
+ step builds the "gptsync_x64.efi" or "gptsync_ia32.efi" program file, in
+ the "gptsync" subdirectory. If you want to build IA32 binaries on an
+ x86-64 (X64) system, type "ARCH=ia32 make". This works only if you're
+ using the TianoCore build kit, and only if you set TARGET_ARCH to either
+ "IA32" or "IA32 X64" in target.txt when you set up the TianoCore toolkit.
+ If you plan to build both architectures, be sure to copy the .efi file
+ for the first build out of the refind subdirectory before building the
+ second architecture.
5) The default build process does NOT build the filesystem drivers. If you
want to build them, you must type "make fs" in the main rEFInd source
- directory. (Typing "ARCH=ia32 make fs" builds IA32 filesystem drivers on
- an x86-64 system, provided TianoCore is properly configured, as
+ directory to build with the TianoCore EDK2, or "make fs_gnuefi" to build
+ with GNU-EFI. (Typing "ARCH=ia32 make fs" builds IA32 filesystem drivers
+ on an x86-64 system, provided TianoCore is properly configured, as
described earlier.) The result is filesystem drivers in the filesystems
subdirectory, and also copies placed in the drivers_{arch} subdirectory.
- You must install the TianoCore EDK2 to build the drivers.
If rEFInd doesn't compile correctly, you'll need to track down the source
of the problem. Double-check that you've got all the necessary development
file for your system. (The main Makefile controls the process for both
toolkits, while Make.common holds GNU-EFI options and Make.tiano holds
TianoCore options.) The most likely thing you'll need to change is the path
-to the various GNU-EFI include files and libraries. Since rEFInd 0.2.7, the
+to the various GNU-EFI include files and libraries. Since rEFInd 0.6.2, the
default Make.common file includes the following definitions:
-EFIINC = /usr/local/include/efi
-GNUEFILIB = /usr/local/lib
-EFILIB = /usr/local/lib
-EFICRT0 = /usr/local/lib
+EFIINC = /usr/include/efi
+GNUEFILIB = /usr/lib
+EFILIB = /usr/lib
+EFICRT0 = /usr/lib
-If you've installed GNU-EFI from a distribution's package, you may need to
-remove "local" from those paths, and perhaps change references to "lib" to
-"lib64". As noted earlier, though, as of 5/2012, most distributions provide
-out-of-date GNU-EFI implementations that will not work with rEFInd 0.2.7
-and later.
+If you've installed GNU-EFI from source code, you may need to add "local"
+to those paths, as in "/usr/local/include/efi". You might need to change
+references to "lib" to "lib32" or "lib64" on some systems. Recall that you
+need at least GNU-EFI version 3.0l to build rEFInd, and until very
+recently, most distributions provided out-of-date versions of this package.
If you're using TianoCore's EDK2, as noted earlier, you may need to adjust
the EDK2BASE variable in Make.tiano and filesystems/Make.tiano.
=================
With rEFInd compiled, you can install it. The easiest way to do this is
-with the install.sh script, which works on both Linux and Mac OS X.
+with the refind-install script, which works on both Linux and Mac OS X.
Alternatively, you can type "make install" to install using this script.
Note that this script copies files to the ESP and uses "efibootmgr" (on
Linux) or "bless" (on OS X) to add rEFInd to the firmware's boot loader
list. The docs/refind/installing.html file provides more details on this
script and its use.
-If install.sh doesn't work for you or if you prefer to do the job manually,
-you may. On a UEFI-based system, you'll want to copy files on the ESP as
-follows:
+If refind-install doesn't work for you or if you prefer to do the job
+manually, you may. On a UEFI-based system, you'll want to copy files on the
+ESP as follows:
* Create a directory for rEFInd, such as EFI/refind.
* Copy refind/refind_ia32.efi or refind_x64.efi to the ESP's EFI/refind
Note to Distribution Maintainers
================================
-The install.sh script, and therefore the "install" target in the Makefile,
-installs the program directly to the ESP and it modifies the *CURRENT
-COMPUTER's* NVRAM. Thus, you should *NOT* use this target as part of the
-build process for your binary packages (RPMs, Debian packages, etc.).
-(Gentoo could use it in an ebuild, though....) You COULD, however, install
-the files to a directory somewhere (/usr/share/refind or whatever) and then
-call install.sh as part of the binary package installation process. Placing
-the files directly in /boot/efi/EFI/{distname}/refind and then having a
-post-install script call efibootmgr is probably the better way to go,
-but this assumes that the ESP is mounted at /boot/efi.
+The refind-install script, and therefore the "install" target in the
+Makefile, installs the program directly to the ESP and it modifies the
+*CURRENT COMPUTER's* NVRAM. Thus, you should *NOT* use this target as part
+of the build process for your binary packages (RPMs, Debian packages,
+etc.). (Gentoo could use it in an ebuild, though....) You COULD, however,
+install the files to a directory somewhere (/usr/share/refind or whatever)
+and then call refind-install as part of the binary package installation
+process. Placing the files directly in /boot/efi/EFI/{distname}/refind and
+then having a post-install script call efibootmgr is probably the better
+way to go, but this assumes that the ESP is mounted at /boot/efi.
Compiling the EFI Filesystem Drivers
====================================
-To build all the drivers, you can type "make fs" from the main directory,
-which builds the drivers and places copies in both the filesystems and
-drivers_{arch} subdirectories. If you want to build just one driver, you
-can change into the "filesystems" directory and type "make {fsname}", where
-{fsname} is a filesystem name -- "ext2", "reiserfs", "iso9660", or "hfs".
+To build all the drivers, you can type "make fs" or "make fs_gnuefi" from
+the main directory, which builds the drivers and places copies in both the
+filesystems and drivers_{arch} subdirectories. If you want to build just
+one driver, you can change into the "filesystems" directory and type "make
+{fsname}" or "make {fsname}_gnuefi", where {fsname} is a filesystem name --
+"ext2", "ext4", "reiserfs", "iso9660", or "hfs". In all cases, the build
+target that appends "_gnuefi" builds with GNU-EFI and the one that doesn't
+builds with TianoCore.
To install drivers, you can type "make install" in the "filesystems"
directory. This copies all the drivers to the
"/boot/efi/EFI/refind/drivers" directory. Alternatively, you can copy the
-files you want manually. As of version 0.4.8, the install.sh script
-includes an optional "--drivers" option that will install the drivers along
-with the main rEFInd program, but to the drivers_{arch} subdirectory of the
-main rEFInd installation directory.
+files you want manually. The refind-install script includes an optional
+"--drivers" option that will install the drivers along with the main rEFInd
+program, but to the drivers_{arch} subdirectory of the main rEFInd
+installation directory.
*CAUTION:* Install drivers for your system's architecture *ONLY*.
Installing drivers for the wrong architecture causes some systems to hang
Oracle's VirtualBox project (https://www.virtualbox.org) and the Clover
boot loader project (https://sourceforge.net/projects/cloverefiboot/),
which I used as the source for this build.
+
+Adding Support for Network Boot
+===============================
+
+rEFInd provides EXPERIMENTAL support for booting over the network using
+iPXE (http://ipxe.org) as a means to receive the payload. In order to
+enable this feature you'll want to follow these instructions:
+
+* cd net/
+* make source
+* make netboot
+* copy bin/ipxe.efi and bin/ipxe_discover.efi to the EFI volume at EFI/tools/
+
+Note that you may need to install additional development packages, such as
+libiberty-dev and binutils-dev, in addition to those needed to build rEFInd
+itself.
+
+My own tests show this support to work under optimal conditions; however,
+architecture (EFI vs. BIOS) detection may not work, and some computers will
+hang or won't retrieve boot files from the network. For these reasons, this
+support is disabled by default in rEFInd, and I do not provide iPXE
+binaries.