4 rEFInd is derived from rEFIt (http://refit.sourceforge.net), but the two
5 programs support different build environments. rEFIt was created with
6 Intel's EFI Application Toolkit
7 (http://www.intel.com/technology/efi/toolkit_overview.htm) or TianoCore's
8 EFI Toolkit (https://efi-toolkit.tianocore.org), along with Microsoft's
11 Compiling the source code provided on the rEFIt site under Linux never
12 worked for me, although the documentation claimed it would. Apparently
13 other Linux developers have run into the same problem; Debian provides a
14 rEFIt package (http://packages.debian.org/sid/refit) that includes
15 extensive patches to enable the program to compile under Linux using the
16 GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). Although
17 GNU-EFI is less sophisticated than recent versions of TianoCore's toolkit,
18 GNU-EFI is my preferred environment because it's provided with many Linux
19 distributions and it was easy to get started with rEFInd development by
20 using GNU-EFI and the Debian rEFIt package as a starting point.
22 Over time, though, I've found that the recent TianoCore EDK2 toolkit has
23 its advantages. The most important of these is that the EFI filesystem
24 drivers, added with rEFInd 0.4.0, require this toolkit. This is a
25 consequence of their derivation, which is via VirtualBox and the Clover
26 boot loader, both of which are based on EDK2. I therefore use EDK2 for the
27 drivers, and I've added EDK2 support for rEFInd itself. In short, then, the
28 drivers require EDK2, whereas the main rEFInd binary can compile with
29 either EDK2 or GNU-EFI.
31 I've dropped ancillary programs, such as the gptsync program, from rEFInd.
32 You can still use these tools with rEFInd, but you'll need to install them
39 To compile rEFInd, you'll need the following:
41 * A Linux installation. Note that this installation does NOT need to be
42 EFI-based. It can be 32- or 64-bit, but unless you use a cross-compiler
43 (which I've not tested), it must be the appropriate bit width for your
44 EFI implementation. (Normally that means 64-bit.) If you don't normally
45 run Linux, you can run it in a VirtualBox or similar virtual machine.
47 * A standard set of Linux development tools, based on GCC.
49 * One of the following:
51 * The GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). You can
52 install this from a package called "gnu-efi"; however, rEFInd relies on
53 features that were added in (I think) 3.0l to provide driver-loading
54 capabilities. The versions I've used and that work are 3.0p and 3.0q. As
55 of 5/2012, most Linux distributions seem to deliver rather elderly
56 versions of GNU-EFI, so you may need to download the latest source code,
57 compile it, and install it locally. Since rEFInd version 0.2.7, the
58 Makefiles assume this (see below).
60 * The TianoCore EDK2 package
61 (http://sourceforge.net/projects/tianocore/). I've tested using the
63 (http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010),
64 which is "frozen," rather than the main EDK2 development branch, which
65 is changing as the developers add features, fix bugs, and so on. Using
66 this package is supported in rEFInd version 0.4.3 and later (0.4.0 and
67 later for the filesystem drivers only). See below for TianoCore setup
70 It's possible that you could use a non-Linux platform to compile rEFInd. To
71 the best of my knowledge, the rEFInd code doesn't rely on anything
72 Linux-specific in its build requirements, and GNU-EFI's Sourceforge page
73 indicates that it works under Windows and OS X, too; however, my one
74 attempt to compile GNU-EFI under OS X failed. I've received one report that
75 rEFInd compiles successfully with Clang and the TianoCore toolkit under OS
76 X by adding the refind.inf file to a .dsc file that you use for your own
77 projects, but I don't have more details than this. Under Windows, you would
78 need to either create a project or Makefile for your non-GCC compiler or
79 use a GCC port, such as MinGW (http://www.mingw.org). You'd probably need
80 to adjust the Makefiles in the latter case.
83 Preparing Your Development Kit
84 ==============================
86 If you want to build the rEFInd binary but not the drivers and if you're
87 using Linux, GNU-EFI is the easiest way to do the job. I don't describe its
88 setup here because it's likely to be fairly easy. If your distribution
89 provides a recent enough version, you should be able to install a package
90 called gnu-efi and be done with it. If not, you'll need to download the
91 source code tarball, build it, and install it. This process is fairly
92 typical of Linux packages. Read the GNU-EFI documentation if you need help.
93 If you're using GNU-EFI, you can skip the rest of this section.
95 To build the EFI drivers, the TianoCore toolkit is required. You might also
96 want to use it if you have problems with GNU-EFI or if you want to build
97 rEFInd on a non-Linux platform. Unfortunately, the TianoCore toolkit is
98 weird by Linux programming standards. It's also quite large -- it's
99 intended as a means to develop a complete EFI firmware implementation, so
100 it contains much more code than is needed to develop standalone EFI
101 applications. I don't know of any Linux distribution packages for it in
102 RPM, Debian package file, or other format; you MUST install the kit from
103 source code using its own unusual compilation procedure. The installation
104 documentation also omits at least one step and is a bit unclear about
105 others. Here's how I installed the toolkit:
107 1) Download UDK2010.SR1 from
108 https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010.
109 (Note that UDK2010.SR1.UP1 was released in June of 2012. I have yet to
112 2) Type "mkdir /usr/local/UDK2010". You can use another directory, but the
113 Makefile for rEFInd's EFI drivers assumes this location. You'll need to
114 edit the EDK2BASE line in the Make.common file if you install somewhere
117 3) Type "cd /usr/local/UDK2010".
119 3) Unzip the downloaded file (UDK2010.SR1.Complete.MyWorkSpace.zip) in the
120 current directory (/usr/local/UDK2010). This creates a handful of files,
121 including a tarball and a couple of .zip files.
123 4) Type "unzip UDK2010.SR1.MyWorkSpace.zip". This extracts the
124 platform-neutral portion of the development kit.
126 5) Type "cd MyWorkSpace".
128 6) Type "tar xvf ../BaseTools\(Unix\)_UDK2010.SR1.tar". This extracts the
129 Linux/Unix-specific portions of the toolkit.
131 7) Follow the build instructions at
132 https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Using_EDK_II_with_Native_GCC_4.4;
133 however, a few changes are required, as detailed below....
135 8) Type ". edksetup.sh BaseTools" (note the leading dot). This sets up some
136 environment variables, so subsequent steps (NOT including compiling the
137 rEFInd EFI drivers) must be typed in the shell you use for this step.
139 9) Edit Conf/target.txt and change the following:
140 - ACTIVE_PLATFORM = MdeModulePkg/MdeModulePkg.dsc
141 - TARGET = RELEASE (DEBUG might work, but I've not tested it).
142 - TARGET_ARCH = X64 (on x86-64; leave this as IA32 on x86)
143 - TOOL_CHAIN_TAG = GCC45 (or other value depending on your GCC version;
144 type "gcc -v" to learn your GCC version number). Note that GCC 4.7
145 doesn't have its own entry, so use GCC46 for GCC 4.7.
146 The TianoCore Makefiles read some of these variables from this file
147 and uses them when accessing directories, so be sure to type these
148 entries in the case specified.
150 10) The documentation refers to editing Conf/tools_def.txt in addition to
151 Conf/target.txt, but doesn't specify what to change in
152 Conf/tools_def.txt. I haven't found it necessary to make any changes in
153 Conf/tools_def.txt EXCEPT when using GCC 4.7 on a Fedora 17 system.
154 (I haven't used GCC 4.7 on other platforms, so this may well be
155 necessary on other systems, too.) With that setup, I found it
156 necessary to change the following line:
157 *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64 -melf_x86_64
159 *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64
161 11) Type "make -C /usr/local/UDK2010/MyWorkSpace/BaseTools/Source/C".
162 (This step is not documented on the EDK Web page.)
164 10) Type "build" to build the main set of EDK2 files. This process is
165 likely to take a few minutes.
167 If you installed in a location other than the one I've specified, you must
168 edit the EDK2BASE variable in the Make.tiano and filesystems/Make.tiano
169 files in the rEFInd source package. Once the toolkit is installed, you can
170 build the filesystem drivers or rEFInd, as described below.
176 With your development system set up, you can compile rEFInd as follows:
178 1) Download and uncompress the rEFInd source code archive. (If you're
179 reading this file, you've probably already done this task.)
181 2) Open a Linux shell prompt
183 3) Change into the archive's main directory. You should see several files
184 including this BUILDING.txt file and several subdirectories such as
185 "refind", "libeg", and "include".
187 4) Type "make" to build with GNU-EFI, or "make tiano" to build with
188 TianoCore EDK2. With any luck, rEFInd will compile without error,
189 leaving the "refind_ia32.efi" or "refind_x64.efi" file, depending on
190 your platform, in the "refind" subdirectory.
192 5) The default build process does NOT build the filesystem drivers. If you
193 want to build them, you must type "make fs" in the main rEFInd source
194 directory. The result is filesystem drivers in the filesystems
195 subdirectory, and also copies placed in the drivers subdirectory. You
196 must install the TianoCore EDK2 to build the drivers.
198 If rEFInd doesn't compile correctly, you'll need to track down the source
199 of the problem. Double-check that you've got all the necessary development
200 tools installed, including GCC, make, and either GNU-EFI or TianoCore EDK2.
201 You may also need to adjust the Makefile, Make.common file, or Make.tiano
202 file for your system. (The main Makefile controls the process for both
203 toolkits, while Make.common holds GNU-EFI options and Make.tiano holds
204 TianoCore options.) The most likely thing you'll need to change is the path
205 to the various GNU-EFI include files and libraries. Since rEFInd 0.2.7, the
206 default Make.common file includes the following definitions:
208 EFIINC = /usr/local/include/efi
209 GNUEFILIB = /usr/local/lib
210 EFILIB = /usr/local/lib
211 EFICRT0 = /usr/local/lib
213 If you've installed GNU-EFI from a distribution's package, you may need to
214 remove "local" from those paths, and perhaps change references to "lib" to
215 "lib64". As noted earlier, though, as of 5/2012, most distributions provide
216 out-of-date GNU-EFI implementations that will not work with rEFInd 0.2.7
219 If you're using TianoCore's EDK2, as noted earlier, you may need to adjust
220 the EDK2BASE variable in Make.tiano and filesystems/Make.tiano.
222 When I tried to compile rEFInd under Ubuntu 12.04 (i386) using GNU-EFI,
223 even with a locally-compiled GNU-EFI 3.0p or 3.0q, I got errors like this:
225 main.o: In function `StartLegacy.isra.0':
226 main.c:(.text+0x8b1): undefined reference to `__stack_chk_fail_local'
227 lib.o: In function `ScanVolumeBootcode.part.3':
228 lib.c:(.text+0xf2f): undefined reference to `__stack_chk_fail_local'
229 lib.o: In function `ScanExtendedPartition.isra.4':
231 The solution was to recompile GNU-EFI with the -fno-stack-protector GCC
232 flag. In GNU-EFI, this can be added to the CFLAGS line in Make.defaults.
238 With rEFInd compiled, you can install it. The easiest way to do this is
239 with the install.sh script, which works on both Linux and Mac OS X.
240 Alternatively, you can type "make install" to install using this script.
241 Note that this installation copies files to the ESP and uses "efibootmgr"
242 (on Linux) or "bless" (on OS X) to add rEFInd to the firmware's boot loader
243 list. The docs/refind/installing.html file provides more details on this
246 If install.sh doesn't work for you or if you prefer to do the job manually,
247 you may. On a UEFI-based system, you'll want to copy files on the ESP as
250 * Create a directory for rEFInd, such as EFI/refind.
251 * Copy refind/refind_ia32.efi or refind_x64.efi to the ESP's EFI/refind
253 * Copy refind.conf-sample to the EFI/refind directory as refind.conf.
254 * Copy the icons subdirectory, including all its files, to EFI/refind.
256 You'll then need to activate rEFInd in your EFI. This can be done with
257 tools such as "efibootmgr" under Linux or "bless" under OS X. See the
258 docs/refind/installing.html file for details.
261 Note to Distribution Maintainers
262 ================================
264 The install.sh script, and therefore the "install" target in the Makefile,
265 installs the program directly to the ESP and it modifies the *CURRENT
266 COMPUTER's* NVRAM. Thus, you should *NOT* use this target as part of the
267 build process for your binary packages (RPMs, Debian packages, etc.).
268 (Gentoo could use it in an ebuild, though....) You COULD, however, copy the
269 files to a directory somewhere (/usr/share/refind or whatever) and then
270 call install.sh as part of the binary package installation process.
271 Placing the files in /boot/efi/EFI/{distname}/refind and then having a
272 post-install script call efibootmgr is probably the better way to go,
276 Compiling the EFI Filesystem Drivers
277 ====================================
279 To build all the drivers, you can type "make fs" from the main directory,
280 which builds the drivers and places copies in both the filesystems and
281 drivers subdirectories. If you want to build just one driver, you can
282 change into the "filesystems" directory and type "make {fsname}", where
283 {fsname} is a filesystem name -- "ext2", "reiserfs", "iso9660", or "hfs".
285 To install drivers, you can type "make install" in the "filesystems"
286 directory. This copies all the drivers to the
287 "/boot/efi/EFI/refind/drivers" directory. Alternatively, you can copy the
288 files you want manually.
290 *CAUTION:* Install drivers for your system's architecture *ONLY*.
291 Installing drivers for the wrong architecture causes some systems to hang
294 The drivers all rely on filesystem wrapper code created by rEFIt's author,
295 Christoph Phisterer. Most of the drivers seem to have passed through
296 Oracle's VirtualBox project (https://www.virtualbox.org) and the Clover
297 boot loader project (https://sourceforge.net/projects/cloverefiboot/),
298 which I used as the source for this build.