4 To compile rEFInd, you'll need the following:
6 * A Linux installation. Note that this installation does NOT need to be
7 EFI-based. It can be 32- or 64-bit, but unless you use a cross-compiler
8 (which I've not tested), it must be the appropriate bit width for your
9 EFI implementation. (Normally that means 64-bit.) If you don't normally
10 run Linux, you can run it in a VirtualBox or similar virtual machine. (I
11 describe some unsupported non-Linux build options shortly.)
13 * A standard set of Linux development tools, based on GCC.
15 * One of the following:
17 * The TianoCore EDK2 package
18 (http://sourceforge.net/projects/tianocore/). I've tested using the
19 UDK2010.SR1 and UDK2010.SR1.UP1 variants
20 (http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010),
21 which are "frozen," rather than the main EDK2 development branch, which
22 is changing as the developers add features, fix bugs, and so on. Using
23 TianoCore EDK2 is supported in rEFInd version 0.4.3 and later (0.4.0
24 and later for the filesystem drivers only). See below for TianoCore
27 * The GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). You can
28 install this from a package called "gnu-efi"; however, rEFInd relies on
29 features that were added in (I think) 3.0l to provide driver-loading
30 capabilities. The versions I've used and that work are 3.0p, 3.0q,
31 3.0r, and 3.0s, with the caveat that 3.0s works when I installed it via
32 a Gentoo package, but not when I installed it by compiling the source
33 code locally. Through mid-to-late 2012, most Linux distributions
34 delivered rather elderly versions of GNU-EFI, but many are catching up
35 by late 2012. You should check your GNU-EFI version number; you may
36 need to download the latest source code, compile it, and install it
37 locally. Between rEFInd version 0.2.7 and 0.6.1, the Makefiles assumed
38 a locally-compiled GNU-EFI package, but older and more recent versions
39 assume GNU-EFI installation in typical locations for
40 distribution-provided packages. The legacy BIOS boot support on
41 UEFI-based PCs doesn't work when rEFInd is compiled under GNU-EFI, so
42 as of rEFInd 0.4.6, GNU-EFI is no longer the primary build environment,
43 although it's easier to set up on a Linux system.
45 Of the two toolkits, I prefer to use TianoCore because it produces binaries
46 that can boot BIOS/legacy-mode OSes and because the TianoCore-produced
47 binaries are about 20-30KiB smaller than those made by GNU-EFI. Also, I've
48 had problems on a 32-bit Mac Mini with the drivers produced by GNU-EFI
49 hanging the system if I try to load more than one of them. (I haven't
50 encountered this problem on UEFI-based PCs.) That said, the TianoCore EDK2
51 package is much harder to install, so if you don't need the ability to boot
52 BIOS/legacy OSes from rEFInd, GNU-EFI can work as well.
54 It's possible to use a non-Linux platform to compile rEFInd. To the best of
55 my knowledge, the rEFInd code doesn't rely on anything Linux-specific in
56 its build requirements, and GNU-EFI's Sourceforge page indicates that it
57 works under Windows and OS X, too; however, my one attempt to compile
58 GNU-EFI under OS X failed. I've received one report that rEFInd compiles
59 successfully with Clang and the TianoCore toolkit under OS X by adding the
60 refind.inf file to a .dsc file that you use for your own projects. You can
61 find brief instructions here (note that this is not my documentation):
63 https://github.com/snarez/refind-edk2
65 Under Windows, you would need to either create a project or Makefile for
66 your non-GCC compiler or use a GCC port, such as MinGW
67 (http://www.mingw.org). You'd probably need to adjust the Makefiles in the
68 latter case. A procedure similar to that used under OS X might work using
69 GCC or Microsoft's C compiler, but I haven't tested this.
72 Preparing Your Development Kit
73 ==============================
75 If you don't care about booting BIOS-based OSes on UEFI PCs and if you're
76 using Linux, GNU-EFI is the easiest way to compile rEFInd. I don't describe
77 GNU-EFI's setup here because it's likely to be fairly easy. If your
78 distribution provides a recent enough version, you should be able to
79 install a package called gnu-efi and be done with it. If not, you'll need
80 to download the source code tarball, build it, and install it. This process
81 is fairly typical of Linux packages. Read the GNU-EFI documentation if you
82 need help. If you're using GNU-EFI, you can skip the rest of this section.
84 If you need support for booting BIOS-based OSes on UEFI PCs, the TianoCore
85 toolkit is required. You might also want to use it if you have problems
86 with GNU-EFI or if you want to build rEFInd on a non-Linux platform.
87 Unfortunately, the TianoCore toolkit is weird by Linux programming
88 standards. It's also quite large -- it's intended as a means to develop a
89 complete EFI firmware implementation, so it contains much more code than is
90 needed to develop standalone EFI applications. I don't know of any Linux
91 distribution packages for it in RPM, Debian package file, or other formats;
92 you MUST install the kit from source code using its own unusual compilation
93 procedure. The installation documentation also omits at least one step and
94 is a bit unclear about others. Here's how I installed the toolkit:
96 1) Download UDK2010.SR1.UP1.P1 from
97 https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010.
99 2) Type "mkdir /usr/local/UDK2010". You can use another directory, but the
100 Makefile for rEFInd's EFI drivers assumes this location. You'll need to
101 edit the EDK2BASE line in the Make.tiano file if you install somewhere
104 3) Type "cd /usr/local/UDK2010".
106 4) Unzip the downloaded file (UDK2010.SR1.UP1.P1.Complete.MyWorkSpace.zip)
107 in the current directory (/usr/local/UDK2010). This creates a handful of
108 files, including a tarball and a couple of .zip files.
110 5) Type "unzip UDK2010.SR1.UP1.MyWorkSpace.zip". This extracts the
111 platform-neutral portion of the development kit.
113 6) Type "cd MyWorkSpace".
115 7) Type "tar xvf ../BaseTools\(Unix\).tar". This extracts the
116 Linux/Unix-specific portions of the toolkit.
118 8) Follow the build instructions at
119 https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Using_EDK_II_with_Native_GCC_4.4;
120 however, a few changes are required, as detailed below....
122 9) Type "source edksetup.sh BaseTools". This sets up some environment
123 variables, so subsequent steps (NOT including compiling the rEFInd EFI
124 drivers) must be typed in the shell you use for this step.
126 10) Edit Conf/target.txt and change the following:
127 - ACTIVE_PLATFORM = MdePkg/MdePkg.dsc
128 - TARGET = RELEASE (DEBUG might work, but I've not tested it).
129 - TARGET_ARCH = X64 (on x86-64; leave this as IA32 on x86). If you plan
130 to build both architectures on an x86-64 system, you can set this to
132 - TOOL_CHAIN_TAG = GCC46 (or other value depending on your GCC version;
133 type "gcc -v" to learn your GCC version number). Note that GCC 4.7
134 and 4.8 don't have their own entries, so use GCC46 for them.
135 The TianoCore Makefiles read some of these variables from this file
136 and use them when accessing directories, so be sure to type these
137 entries in the case specified.
139 11) The documentation refers to editing Conf/tools_def.txt in addition to
140 Conf/target.txt, but doesn't specify what to change in
141 Conf/tools_def.txt. I haven't found it necessary to make any changes in
142 Conf/tools_def.txt EXCEPT when using GCC 4.7 on a Fedora 17 system.
143 (I haven't used GCC 4.7 on other platforms, so this may well be
144 necessary on other systems, too.) With that setup, I found it
145 necessary to change the following line:
146 *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64 -melf_x86_64
148 *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64
150 12) Type "make -C /usr/local/UDK2010/MyWorkSpace/BaseTools/Source/C".
151 (This step is not documented on the EDK Web page.) Note that this
152 requires the g++ compiler and UUID development libraries.
154 13) Type "build" to build the main set of EDK2 files. This process is
155 likely to take a few minutes.
157 If you installed in a location other than the one I've specified, you must
158 edit the EDK2BASE variable in the Make.tiano and filesystems/Make.tiano
159 files in the rEFInd source package. Once the toolkit is installed, you can
160 build the filesystem drivers or rEFInd, as described below.
166 With your development system set up, you can compile rEFInd as follows:
168 1) Download and uncompress the rEFInd source code archive. (If you're
169 reading this file, you've probably already done this task.)
171 2) Open a Linux shell prompt
173 3) Change into the archive's main directory. You should see several files
174 including this BUILDING.txt file and several subdirectories such as
175 "refind", "libeg", "mok", "filesystems", and "include".
177 4) Type "make gnuefi" to build with GNU-EFI, or either "make" alone or
178 "make tiano" to build with TianoCore EDK2. With any luck, rEFInd will
179 compile without error, leaving the "refind_ia32.efi" or "refind_x64.efi"
180 file, depending on your platform, in the "refind" subdirectory. This same
181 step builds the "gptsync_x64.efi" or "gptsync_ia32.efi" program file, in
182 the "gptsync" subdirectory. If you want to build IA32 binaries on an
183 x86-64 (X64) system, type "ARCH=ia32 make". This works only if you're
184 using the TianoCore build kit, and only if you set TARGET_ARCH to either
185 "IA32" or "IA32 X64" in target.txt when you set up the TianoCore toolkit.
186 If you plan to build both architectures, be sure to copy the .efi file
187 for the first build out of the refind subdirectory before building the
190 5) The default build process does NOT build the filesystem drivers. If you
191 want to build them, you must type "make fs" in the main rEFInd source
192 directory to build with the TianoCore EDK2, or "make fs_gnuefi" to build
193 with GNU-EFI. (Typing "ARCH=ia32 make fs" builds IA32 filesystem drivers
194 on an x86-64 system, provided TianoCore is properly configured, as
195 described earlier.) The result is filesystem drivers in the filesystems
196 subdirectory, and also copies placed in the drivers_{arch} subdirectory.
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.6.2, the
206 default Make.common file includes the following definitions:
208 EFIINC = /usr/include/efi
209 GNUEFILIB = /usr/lib64
213 If you've installed GNU-EFI from source code, you may need to add "local"
214 to those paths, as in "/usr/local/include/efi". You might need to change
215 references to "lib64" to "lib32" or "lib" on some systems. Recall that you
216 need at least GNU-EFI version 3.0l to build rEFInd, and until very
217 recently, most distributions provided out-of-date versions of this package.
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 script copies files to the ESP and uses "efibootmgr" (on
242 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, install
269 the files to a directory somewhere (/usr/share/refind or whatever) and then
270 call install.sh as part of the binary package installation process. Placing
271 the files directly in /boot/efi/EFI/{distname}/refind and then having a
272 post-install script call efibootmgr is probably the better way to go,
273 but this assumes that the ESP is mounted at /boot/efi.
276 Compiling the EFI Filesystem Drivers
277 ====================================
279 To build all the drivers, you can type "make fs" or "make fs_gnuefi" from
280 the main directory, which builds the drivers and places copies in both the
281 filesystems and drivers_{arch} subdirectories. If you want to build just
282 one driver, you can change into the "filesystems" directory and type "make
283 {fsname}" or "make {fsname}_gnuefi", where {fsname} is a filesystem name --
284 "ext2", "ext4", "reiserfs", "iso9660", or "hfs". In all cases, the build
285 target that appends "_gnuefi" builds with GNU-EFI and the one that doesn't
286 builds with TianoCore.
288 To install drivers, you can type "make install" in the "filesystems"
289 directory. This copies all the drivers to the
290 "/boot/efi/EFI/refind/drivers" directory. Alternatively, you can copy the
291 files you want manually. As of version 0.4.8, the install.sh script
292 includes an optional "--drivers" option that will install the drivers along
293 with the main rEFInd program, but to the drivers_{arch} subdirectory of the
294 main rEFInd installation directory.
296 *CAUTION:* Install drivers for your system's architecture *ONLY*.
297 Installing drivers for the wrong architecture causes some systems to hang
298 at boot time. This risk can be minimized by including the architecture code
299 in the drivers subdirectory name (drivers_x64 or drivers_ia32).
301 The drivers all rely on filesystem wrapper code created by rEFIt's author,
302 Christoph Pfisterer. Most of the drivers seem to have passed through
303 Oracle's VirtualBox project (https://www.virtualbox.org) and the Clover
304 boot loader project (https://sourceforge.net/projects/cloverefiboot/),
305 which I used as the source for this build.