-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. The most important of these is that the EFI filesystem
-drivers, added with rEFInd 0.4.0, require this toolkit. This is a
-consequence of their derivation, which is via VirtualBox and the Clover
-boot loader, both of which are based on EDK2. I therefore use EDK2 for the
-drivers, and I've added EDK2 support for rEFInd itself. In short, then, the
-drivers require EDK2, whereas the main rEFInd binary can compile with
-either EDK2 or GNU-EFI.
-
-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
============
EFI-based. It can be 32- or 64-bit, but unless you use a cross-compiler
(which I've not tested), it must be the appropriate bit width for your
EFI implementation. (Normally that means 64-bit.) If you don't normally
- run Linux, you can run it in a VirtualBox or similar virtual machine.
+ run Linux, you can run it in a VirtualBox or similar virtual machine. (I
+ describe some unsupported non-Linux build options shortly.)
* A standard set of Linux development tools, based on GCC.
* One of the following:
+ * The TianoCore EDK2 package
+ (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 TianoCore EDK2 package
- (http://sourceforge.net/projects/tianocore/). I've tested using the
- UDK2010.SR1 variant
- (http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010),
- which is "frozen," rather than the main EDK2 development branch, which
- is changing as the developers add features, fix bugs, and so on. Using
- this package 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.
-
-It's possible that you could 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 its build requirements, and GNU-EFI's Sourceforge page
-indicates that it works under Windows and OS X, too; however, my one
-attempt to compile GNU-EFI under OS X failed. Using the TianoCore toolkit
-might be more likely to work under OS X or Windows, but I haven't tested
-it. Under Windows, you would need to either create a project or Makefile
-for your non-GCC compiler or use a GCC port, such as MinGW
+ 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
+its build requirements, and GNU-EFI's Sourceforge page indicates that it
+works under Windows and OS X, too; however, my one attempt to compile
+GNU-EFI under OS X failed. I've received one report that rEFInd compiles
+successfully with Clang and the TianoCore toolkit under OS X by adding the
+refind.inf file to a .dsc file that you use for your own projects. You can
+find brief instructions here (note that this is not my documentation):
+
+https://github.com/snarez/refind-edk2
+
+Under Windows, you would need to either create a project or Makefile for
+your non-GCC compiler or use a GCC port, such as MinGW
(http://www.mingw.org). You'd probably need to adjust the Makefiles in the
-latter case.
+latter case. A procedure similar to that used under OS X might work using
+GCC or Microsoft's C compiler, but I haven't tested this.
Preparing Your Development Kit
==============================
-If you want to build the rEFInd binary but not the drivers 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, 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 format; 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 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.Complete.MyWorkSpace.zip) in the
- current directory (/usr/local/UDK2010). This creates a handful of files,
- including a tarball and a couple of .zip files.
+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.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\)_UDK2010.SR1.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 ". edksetup.sh BaseTools" (note the leading dot). 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 = MdeModulePkg/MdeModulePkg.dsc
- - TARGET = RELEASE (DEBUG might work, but I've not tested it).
- - TARGET_ARCH = X64 (on x86-64; leave this as IA32 on x86)
- - TOOL_CHAIN_TAG = GCC45 (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 uses 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
+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.
+
+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".
- (This step is not documented on the EDK Web page.)
+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".
-
-4) Type "make" to build with GNU-EFI, 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.
+ "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. 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. The result is filesystem drivers in the filesystems
- subdirectory, and also copies placed in the drivers subdirectory. You
- must install the TianoCore EDK2 to build the drivers.
+ 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.
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 installation copies files to the ESP and uses "efibootmgr"
-(on Linux) or "bless" (on OS X) to add rEFInd to the firmware's boot loader
+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, copy 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 in /boot/efi/EFI/{distname}/refind and then having a
-post-install script call efibootmgr is probably the better way to go,
-though.
+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 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.
+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
-at boot time.
+at boot time. This risk can be minimized by including the architecture code
+in the drivers subdirectory name (drivers_x64 or drivers_ia32).
The drivers all rely on filesystem wrapper code created by rEFIt's author,
-Christoph Phisterer. Most of the drivers seem to have passed through
+Christoph Pfisterer. Most of the drivers seem to have passed through
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.