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 versions of TianoCore that can
-build under Linux use a very different set of include files and support a
-somewhat different set of system calls than are used by rEFIt/rEFInd. Thus,
-converting to a new TianoCore toolkit would entail a lot of work. Using an
-older version would require building under Windows and using old versions
-of Microsoft's Visual C. I neither have this toolchain nor do I want to use
-it. For this reason, I used Debian's patched version of rEFIt as a starting
-point in forking rEFInd.
-
-Note that the drivers, added with rEFInd 0.4.0, require use of the
-TianoCore tool kit. Driver compilation is described in more detail later.
+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.
-The patched version of rEFIt that I used as a starting point disabled the
-program's ability to load EFI drivers because of limitations in the GNU-EFI
-library. A combination of improvements in recent versions of the library
-and implementing a (now apparently abandoned) EFI function directly in
-rEFInd has enabled me to add this support back to rEFInd 0.2.7 and later.
-
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.
-* 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).
-
-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. Thus, you may be able
-to compile it on these platforms, but I've not tested it in this way. 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 Makefile in the latter case.
+* 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.
+
+ * 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.
+
+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. 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, 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
+ 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
+ else.
+
+3) Type "cd /usr/local/UDK2010".
+
+3) Unzip the downloaded file (UDK2010.SR1.UP1.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) Type "unzip UDK2010.SR1.UP1.MyWorkSpace.zip". This extracts the
+ platform-neutral portion of the development kit.
+
+5) Type "cd MyWorkSpace".
+
+6) Type "tar xvf ../BaseTools\(Unix\).tar". This extracts the
+ Linux/Unix-specific portions of the toolkit.
+
+7) 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
+ 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, 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
+ 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.
+ (I haven't used GCC 4.7 on other platforms, so this may well be
+ necessary on other systems, too.) With that setup, I found it
+ necessary to change the following line:
+ *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64 -melf_x86_64
+ 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.) 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.
+
+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
+files in the rEFInd source package. Once the toolkit is installed, you can
+build the filesystem drivers or rEFInd, as described below.
Compiling rEFInd
including this BUILDING.txt file and several subdirectories such as
"refind", "libeg", and "include".
-4) Type "make". 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.
+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.
+
+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.
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
-tools installed, including GCC, make, and GNU-EFI. You may also need to
-adjust the Makefile or Make.common file for your system. 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 default Make.common file
-includes the following definitions:
+tools installed, including GCC, make, and either GNU-EFI or TianoCore EDK2.
+You may also need to adjust the Makefile, Make.common file, or Make.tiano
+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
+default Make.common file includes the following definitions:
EFIINC = /usr/local/include/efi
GNUEFILIB = /usr/local/lib
out-of-date GNU-EFI implementations that will not work with rEFInd 0.2.7
and later.
-When I tried to compile rEFInd under Ubuntu 12.04 (i386), even with a
-locally-compiled GNU-EFI 3.0p or 3.0q, I got errors like this:
+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.
+
+When I tried to compile rEFInd under Ubuntu 12.04 (i386) using GNU-EFI,
+even with a locally-compiled GNU-EFI 3.0p or 3.0q, I got errors like this:
main.o: In function `StartLegacy.isra.0':
main.c:(.text+0x8b1): undefined reference to `__stack_chk_fail_local'
The solution was to recompile GNU-EFI with the -fno-stack-protector GCC
flag. In GNU-EFI, this can be added to the CFLAGS line in Make.defaults.
+
Installing rEFInd
=================
tools such as "efibootmgr" under Linux or "bless" under OS X. See the
docs/refind/installing.html file for details.
+
Note to Distribution Maintainers
================================
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
+(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,
-though.
+but this assumes that the ESP is mounted at /boot/efi.
+
Compiling the EFI Filesystem Drivers
====================================
-The EFI filesystem drivers in the filesystems subdirectory require the
-TianoCore UDK2010.SR1 toolkit. The drivers might compile with another
-version of the TianoCore toolkit, but I've not tested them with anything
-else. (My attempts to use GNU-EFI have failed; at best, I've gotten drivers
-that load but hang the system.)
+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".
-Unfortunately, the TianoCore toolkit is bulky and weird by Linux
-programming standards. 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 a few steps. 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
- Makefile for rEFInd's EFI drivers assumes this location. You'll need to
- edit the EDK2BASE line in the Makefile if you install somewhere else.
-
-3) Type "cd /usr/local/UDK2010".
-
-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) Type "unzip UDK2010.SR1.MyWorkSpace.zip". This extracts the
- platform-neutral portion of the development kit.
-
-5) Type "cd MyWorkSpace".
-
-6) Type "tar xvf ../BaseTools\(Unix\)_UDK2010.SR1.tar". This extracts the
- Linux/Unix-specific portions of the toolkit.
-
-7) 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)
- The Makefile for the drivers reads some of these variables from this
- file and uses them when accessing directories, so be sure to type these
- entries in the case specified.
-
-11) Type "make -C /usr/local/UDK2010/MyWorkSpace/BaseTools/Source/C".
- (This step is not documented on the EDK Web page.)
-
-10) Type "build" to build the main set of EDK2 files. This process is
- likely to take a few minutes.
+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.
-Once the toolkit is installed, you can build the filesystem drivers. If you
-installed in a location other than the one I've specified, you must edit
-the Makefile's EDK2BASE variable. You can then type "make" to build all the
-drivers, or specify a filesystem type to build just it.
+*CAUTION:* Install drivers for your system's architecture *ONLY*.
+Installing drivers for the wrong architecture causes some systems to hang
+at boot time.
The drivers all rely on filesystem wrapper code created by rEFIt's author,
Christoph Phisterer. 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/). Most
-of the drivers are based on code from the Linux kernel.
+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.