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. Two features, in particular, require the TianoCore EDK2
26 - The EFI filesystem drivers, added with rEFInd 0.4.0. This requirement is
27 a consequence of the derivation of the drivers, which is via VirtualBox
28 and the Clover boot loader, both of which are based on EDK2.
30 - The legacy BIOS boot feature for UEFI-based PCs. EDK2 is needed in this
31 case because of features unique to that environment. Note that the legacy
32 BIOS boot feature for Macs works when rEFInd is built via either GNU-EFI
33 or the TianoCore EDK2.
35 For these reasons, effective with rEFInd 0.4.6, I've switched the primary
36 build environment from GNU-EFI to TianoCore EDK2. The rEFInd binary itself
37 still builds via GNU-EFI, but you must pass the "gnuefi" build target to
38 make in order to build in this way, and the resulting binary can't boot
39 BIOS-based OSes on UEFI PCs.
41 I've dropped ancillary programs, such as the gptsync program, from rEFInd.
42 You can still use these tools with rEFInd, but you'll need to install them
49 To compile rEFInd, you'll need the following:
51 * A Linux installation. Note that this installation does NOT need to be
52 EFI-based. It can be 32- or 64-bit, but unless you use a cross-compiler
53 (which I've not tested), it must be the appropriate bit width for your
54 EFI implementation. (Normally that means 64-bit.) If you don't normally
55 run Linux, you can run it in a VirtualBox or similar virtual machine. (I
56 describe some unsupported non-Linux build options shortly.)
58 * A standard set of Linux development tools, based on GCC.
60 * One of the following:
62 * The TianoCore EDK2 package
63 (http://sourceforge.net/projects/tianocore/). I've tested using the
64 UDK2010.SR1 and UDK2010.SR1.UP1 variants
65 (http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010),
66 which are "frozen," rather than the main EDK2 development branch, which
67 is changing as the developers add features, fix bugs, and so on. Using
68 TianoCore EDK2 is supported in rEFInd version 0.4.3 and later (0.4.0
69 and later for the filesystem drivers only). See below for TianoCore
72 * The GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). You can
73 install this from a package called "gnu-efi"; however, rEFInd relies on
74 features that were added in (I think) 3.0l to provide driver-loading
75 capabilities. The versions I've used and that work are 3.0p and 3.0q.
76 As of 5/2012, most Linux distributions seem to deliver rather elderly
77 versions of GNU-EFI, so you may need to download the latest source
78 code, compile it, and install it locally. Since rEFInd version 0.2.7,
79 the Makefiles assume this (see below). The legacy BIOS boot support on
80 UEFI-based PCs doesn't work when GNU-EFI is compiled under GNU-EFI, so
81 as of rEFInd 0.4.6, GNU-EFI is no longer the primary build environment,
82 although it's easier to set up on a Linux system.
84 It's possible to use a non-Linux platform to compile rEFInd. To the best of
85 my knowledge, the rEFInd code doesn't rely on anything Linux-specific in
86 its build requirements, and GNU-EFI's Sourceforge page indicates that it
87 works under Windows and OS X, too; however, my one attempt to compile
88 GNU-EFI under OS X failed. I've received one report that rEFInd compiles
89 successfully with Clang and the TianoCore toolkit under OS X by adding the
90 refind.inf file to a .dsc file that you use for your own projects. You can
91 find brief instructions here (note that this is not my documentation):
93 https://github.com/snarez/refind-edk2
95 Under Windows, you would need to either create a project or Makefile for
96 your non-GCC compiler or use a GCC port, such as MinGW
97 (http://www.mingw.org). You'd probably need to adjust the Makefiles in the
98 latter case. A procedure similar to that used under OS X might work using
99 GCC or Microsoft's C compiler, but I haven't tested this.
102 Preparing Your Development Kit
103 ==============================
105 If you want to build the rEFInd binary but not the drivers, if you don't
106 care about booting BIOS-based OSes on UEFI PCs, and if you're using Linux,
107 GNU-EFI is the easiest way to do the job. I don't describe its setup here
108 because it's likely to be fairly easy. If your distribution provides a
109 recent enough version, you should be able to install a package called
110 gnu-efi and be done with it. If not, you'll need to download the source
111 code tarball, build it, and install it. This process is fairly typical of
112 Linux packages. Read the GNU-EFI documentation if you need help. If you're
113 using GNU-EFI, you can skip the rest of this section.
115 To build the EFI drivers, or if you want support for booting BIOS-based
116 OSes on UEFI PCs, the TianoCore toolkit is required. You might also want to
117 use it if you have problems with GNU-EFI or if you want to build rEFInd on
118 a non-Linux platform. Unfortunately, the TianoCore toolkit is weird by
119 Linux programming standards. It's also quite large -- it's intended as a
120 means to develop a complete EFI firmware implementation, so it contains
121 much more code than is needed to develop standalone EFI applications. I
122 don't know of any Linux distribution packages for it in RPM, Debian package
123 file, or other formats; you MUST install the kit from source code using its
124 own unusual compilation procedure. The installation documentation also
125 omits at least one step and is a bit unclear about others. Here's how I
126 installed the toolkit:
128 1) Download UDK2010.SR1.UP1 from
129 https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010.
131 2) Type "mkdir /usr/local/UDK2010". You can use another directory, but the
132 Makefile for rEFInd's EFI drivers assumes this location. You'll need to
133 edit the EDK2BASE line in the Make.common file if you install somewhere
136 3) Type "cd /usr/local/UDK2010".
138 3) Unzip the downloaded file (UDK2010.SR1.UP1.Complete.MyWorkSpace.zip) in
139 the current directory (/usr/local/UDK2010). This creates a handful of
140 files, including a tarball and a couple of .zip files.
142 4) Type "unzip UDK2010.SR1.UP1.MyWorkSpace.zip". This extracts the
143 platform-neutral portion of the development kit.
145 5) Type "cd MyWorkSpace".
147 6) Type "tar xvf ../BaseTools\(Unix\).tar". This extracts the
148 Linux/Unix-specific portions of the toolkit.
150 7) Follow the build instructions at
151 https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Using_EDK_II_with_Native_GCC_4.4;
152 however, a few changes are required, as detailed below....
154 8) Type "source edksetup.sh BaseTools". This sets up some environment
155 variables, so subsequent steps (NOT including compiling the rEFInd EFI
156 drivers) must be typed in the shell you use for this step.
158 9) Edit Conf/target.txt and change the following:
159 - ACTIVE_PLATFORM = MdePkg/MdePkg.dsc
160 - TARGET = RELEASE (DEBUG might work, but I've not tested it).
161 - TARGET_ARCH = X64 (on x86-64; leave this as IA32 on x86). If you plan
162 to build both architectures on an x86-64 system, you can set this to
164 - TOOL_CHAIN_TAG = GCC46 (or other value depending on your GCC version;
165 type "gcc -v" to learn your GCC version number). Note that GCC 4.7
166 doesn't have its own entry, so use GCC46 for GCC 4.7.
167 The TianoCore Makefiles read some of these variables from this file
168 and use them when accessing directories, so be sure to type these
169 entries in the case specified.
171 10) The documentation refers to editing Conf/tools_def.txt in addition to
172 Conf/target.txt, but doesn't specify what to change in
173 Conf/tools_def.txt. I haven't found it necessary to make any changes in
174 Conf/tools_def.txt EXCEPT when using GCC 4.7 on a Fedora 17 system.
175 (I haven't used GCC 4.7 on other platforms, so this may well be
176 necessary on other systems, too.) With that setup, I found it
177 necessary to change the following line:
178 *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64 -melf_x86_64
180 *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64
182 11) Type "make -C /usr/local/UDK2010/MyWorkSpace/BaseTools/Source/C".
183 (This step is not documented on the EDK Web page.) Note that this
184 requires the g++ compiler and UUID development libraries.
186 10) Type "build" to build the main set of EDK2 files. This process is
187 likely to take a few minutes.
189 If you installed in a location other than the one I've specified, you must
190 edit the EDK2BASE variable in the Make.tiano and filesystems/Make.tiano
191 files in the rEFInd source package. Once the toolkit is installed, you can
192 build the filesystem drivers or rEFInd, as described below.
198 With your development system set up, you can compile rEFInd as follows:
200 1) Download and uncompress the rEFInd source code archive. (If you're
201 reading this file, you've probably already done this task.)
203 2) Open a Linux shell prompt
205 3) Change into the archive's main directory. You should see several files
206 including this BUILDING.txt file and several subdirectories such as
207 "refind", "libeg", and "include".
209 4) Type "make gnuefi" to build with GNU-EFI, or either "make" alone or
210 "make tiano" to build with TianoCore EDK2. With any luck, rEFInd will
211 compile without error, leaving the "refind_ia32.efi" or "refind_x64.efi"
212 file, depending on your platform, in the "refind" subdirectory. If you
213 want to build IA32 binaries on an x86-64 (X64) system, type "ARCH=ia32
214 make". This works only if you're using the TianoCore build kit, and only
215 if you set TARGET_ARCH to either "IA32" or "IA32 X64" in target.txt when
216 you set up the TianoCore. If you plan to build both architectures, be
217 sure to copy the .efi file for the first build out of the refind
218 subdirectory before building the second architecture.
220 5) The default build process does NOT build the filesystem drivers. If you
221 want to build them, you must type "make fs" in the main rEFInd source
222 directory. (Typing "ARCH=ia32 make fs" builds IA32 filesystem drivers on
223 an x86-64 system, provided TianoCore is properly configured, as
224 described earlier.) The result is filesystem drivers in the filesystems
225 subdirectory, and also copies placed in the drivers_{arch} subdirectory.
226 You must install the TianoCore EDK2 to build the drivers.
228 If rEFInd doesn't compile correctly, you'll need to track down the source
229 of the problem. Double-check that you've got all the necessary development
230 tools installed, including GCC, make, and either GNU-EFI or TianoCore EDK2.
231 You may also need to adjust the Makefile, Make.common file, or Make.tiano
232 file for your system. (The main Makefile controls the process for both
233 toolkits, while Make.common holds GNU-EFI options and Make.tiano holds
234 TianoCore options.) The most likely thing you'll need to change is the path
235 to the various GNU-EFI include files and libraries. Since rEFInd 0.2.7, the
236 default Make.common file includes the following definitions:
238 EFIINC = /usr/local/include/efi
239 GNUEFILIB = /usr/local/lib
240 EFILIB = /usr/local/lib
241 EFICRT0 = /usr/local/lib
243 If you've installed GNU-EFI from a distribution's package, you may need to
244 remove "local" from those paths, and perhaps change references to "lib" to
245 "lib64". As noted earlier, though, as of 5/2012, most distributions provide
246 out-of-date GNU-EFI implementations that will not work with rEFInd 0.2.7
249 If you're using TianoCore's EDK2, as noted earlier, you may need to adjust
250 the EDK2BASE variable in Make.tiano and filesystems/Make.tiano.
252 When I tried to compile rEFInd under Ubuntu 12.04 (i386) using GNU-EFI,
253 even with a locally-compiled GNU-EFI 3.0p or 3.0q, I got errors like this:
255 main.o: In function `StartLegacy.isra.0':
256 main.c:(.text+0x8b1): undefined reference to `__stack_chk_fail_local'
257 lib.o: In function `ScanVolumeBootcode.part.3':
258 lib.c:(.text+0xf2f): undefined reference to `__stack_chk_fail_local'
259 lib.o: In function `ScanExtendedPartition.isra.4':
261 The solution was to recompile GNU-EFI with the -fno-stack-protector GCC
262 flag. In GNU-EFI, this can be added to the CFLAGS line in Make.defaults.
268 With rEFInd compiled, you can install it. The easiest way to do this is
269 with the install.sh script, which works on both Linux and Mac OS X.
270 Alternatively, you can type "make install" to install using this script.
271 Note that this script copies files to the ESP and uses "efibootmgr" (on
272 Linux) or "bless" (on OS X) to add rEFInd to the firmware's boot loader
273 list. The docs/refind/installing.html file provides more details on this
276 If install.sh doesn't work for you or if you prefer to do the job manually,
277 you may. On a UEFI-based system, you'll want to copy files on the ESP as
280 * Create a directory for rEFInd, such as EFI/refind.
281 * Copy refind/refind_ia32.efi or refind_x64.efi to the ESP's EFI/refind
283 * Copy refind.conf-sample to the EFI/refind directory as refind.conf.
284 * Copy the icons subdirectory, including all its files, to EFI/refind.
286 You'll then need to activate rEFInd in your EFI. This can be done with
287 tools such as "efibootmgr" under Linux or "bless" under OS X. See the
288 docs/refind/installing.html file for details.
291 Note to Distribution Maintainers
292 ================================
294 The install.sh script, and therefore the "install" target in the Makefile,
295 installs the program directly to the ESP and it modifies the *CURRENT
296 COMPUTER's* NVRAM. Thus, you should *NOT* use this target as part of the
297 build process for your binary packages (RPMs, Debian packages, etc.).
298 (Gentoo could use it in an ebuild, though....) You COULD, however, install
299 the files to a directory somewhere (/usr/share/refind or whatever) and then
300 call install.sh as part of the binary package installation process. Placing
301 the files directly in /boot/efi/EFI/{distname}/refind and then having a
302 post-install script call efibootmgr is probably the better way to go,
303 but this assumes that the ESP is mounted at /boot/efi.
306 Compiling the EFI Filesystem Drivers
307 ====================================
309 To build all the drivers, you can type "make fs" from the main directory,
310 which builds the drivers and places copies in both the filesystems and
311 drivers_{arch} subdirectories. If you want to build just one driver, you
312 can change into the "filesystems" directory and type "make {fsname}", where
313 {fsname} is a filesystem name -- "ext2", "ext4", "reiserfs", "iso9660",
316 To install drivers, you can type "make install" in the "filesystems"
317 directory. This copies all the drivers to the
318 "/boot/efi/EFI/refind/drivers" directory. Alternatively, you can copy the
319 files you want manually. As of version 0.4.8, the install.sh script
320 includes an optional "--drivers" option that will install the drivers along
321 with the main rEFInd program, but to the drivers_{arch} subdirectory of the
322 main rEFInd installation directory.
324 *CAUTION:* Install drivers for your system's architecture *ONLY*.
325 Installing drivers for the wrong architecture causes some systems to hang
326 at boot time. This risk can be minimized by including the architecture code
327 in the drivers subdirectory name (drivers_x64 or drivers_ia32).
329 The drivers all rely on filesystem wrapper code created by rEFIt's author,
330 Christoph Pfisterer. Most of the drivers seem to have passed through
331 Oracle's VirtualBox project (https://www.virtualbox.org) and the Clover
332 boot loader project (https://sourceforge.net/projects/cloverefiboot/),
333 which I used as the source for this build.