Fixed uninitialized-pointer bug that manifested as a crash with
[refind] / BUILDING.txt
1 Requirements
2 ============
3
4 To compile rEFInd, you'll need the following:
5
6 * A Linux installation. Note that this installation does NOT need to be
7 EFI-based. It can use IA32 (aka x86, i386, or other things), X64 (aka
8 x86-64, AMD64, or EM64T), or AA64 (aka AARCH64 or ARM64), but unless you
9 use a cross-compiler, it must use the same CPU type and bit depth as your
10 EFI implementation. (Normally that means 64-bit X64.) If you don't
11 normally run Linux, you can run it in a VirtualBox or similar virtual
12 machine. (I describe some unsupported non-Linux build options shortly.)
13
14 * A standard set of Linux development tools, based on GCC. (I've tried
15 using clang 3.4 under Ubuntu, with partial success. The main rEFInd
16 binary, gptsync, and some drivers compile successfully; but only gptsync
17 runs normally. The drivers I've tried and the main rEFInd binary crash.)
18
19 * One of the following:
20
21 * The TianoCore EDK2 package
22 (http://sourceforge.net/projects/tianocore/). I initially used the
23 UDK2010 package and others in that series, but beginning with rEFInd
24 0.8.2, I've been using UDK2014
25 (http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2014).
26 All of the UDK are "frozen," rather than the main EDK2 development
27 branch, which is changing as the developers add features, fix bugs, and
28 so on. See below for TianoCore setup instructions.
29
30 * The GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). You can
31 install this from a package called "gnu-efi"; however, rEFInd relies on
32 features that were added sometime between version 3.0s and 3.0u, so I
33 recommend using 3.0u (or conceivably later). You should check your
34 GNU-EFI version number; you may need to download the latest source
35 code, compile it, and install it locally. The Makefiles assume a
36 GNU-EFI package installed via a package manager. If you install from
37 source code, you may need to adjust those Makefiles' paths.
38
39 Of the two toolkits, I prefer to use TianoCore because it produces binaries
40 that are about 5-30KiB smaller than those made by GNU-EFI, and I can easily
41 build 32-bit binaries on my 64-bit Linux installations. Also, I've had
42 problems on a 32-bit Mac Mini with the drivers produced by GNU-EFI hanging
43 the system. (I haven't encountered this problem on UEFI-based PCs.) That
44 said, the TianoCore EDK2 package is much harder to install, so you may
45 prefer to use GNU-EFI unless you have a specific need for the TianoCore
46 toolkit. Automated build tools like the OpenSUSE Build Service (OBS) and
47 the Ubuntu Personal Package Archive (PPA) mechanism don't yet support
48 TianoCore.
49
50 It's possible to use a non-Linux platform to compile rEFInd. To the best of
51 my knowledge, the rEFInd code doesn't rely on anything Linux-specific in
52 its build requirements, and GNU-EFI's Sourceforge page indicates that it
53 works under Windows and OS X, too; however, my one attempt to compile
54 GNU-EFI under OS X failed. I've received one report that rEFInd compiles
55 successfully with Clang and the TianoCore toolkit under OS X by adding the
56 refind.inf file to a .dsc file that you use for your own projects. You can
57 find brief instructions here (note that this is not my documentation):
58
59 https://github.com/snarez/refind-edk2
60
61 Under Windows, you would need to either create a project or Makefile for
62 your non-GCC compiler or use a GCC port, such as MinGW
63 (http://www.mingw.org). You'd probably need to adjust the Makefiles in the
64 latter case. A procedure similar to that used under OS X might work using
65 GCC or Microsoft's C compiler, but I haven't tested this.
66
67
68 Preparing Your Development Kit
69 ==============================
70
71 If you're using Linux, GNU-EFI is the easiest way to compile rEFInd. I
72 don't describe GNU-EFI's setup here because it's likely to be fairly easy.
73 If your distribution provides a recent enough version, you should be able
74 to install a package called gnu-efi and be done with it. If not, you'll
75 need to download the source code tarball, build it, and install it. This
76 process is fairly typical of Linux packages. Read the GNU-EFI documentation
77 if you need help. If you're using GNU-EFI, you can skip the rest of this
78 section.
79
80 You might want to use the TianoCore toolkit if you have problems with
81 GNU-EFI or if you want to build rEFInd on a non-Linux platform.
82 Unfortunately, the TianoCore toolkit is weird by Linux programming
83 standards. It's also quite large -- it's intended as a means to develop a
84 complete EFI firmware implementation, so it contains much more code than is
85 needed to develop standalone EFI applications. I don't know of any Linux
86 distribution packages for it in RPM, Debian package file, or other formats;
87 you MUST install the kit from source code using its own unusual compilation
88 procedure. The installation documentation also omits at least one step and
89 is a bit unclear about others. Here's how I installed the toolkit:
90
91 1) Download UDK2014.SR1.UP1.P1 from
92 https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2014.
93 Note that UDK2015 is now available, but I have not yet adapted rEFInd to
94 build with it. (UDK2015 has made changes that require matching changes
95 to rEFInd.)
96
97 2) Type "mkdir /usr/local/UDK2014". You can use another directory, but the
98 rEFInd Makefile assumes this location. You'll need to edit the EDK2BASE
99 variable in the top-level Makefile if you install somewhere else.
100
101 3) Type "cd /usr/local/UDK2014".
102
103 4) Unzip the downloaded file (UDK2014.SR1.UP1.P1.Complete.MyWorkSpace.zip)
104 in the current directory (/usr/local/UDK2014). This creates a handful of
105 files, including a tarball and a couple of .zip files.
106
107 5) Type "unzip UDK2014.SR1.UP1.MyWorkSpace.zip". This extracts the
108 platform-neutral portion of the development kit.
109
110 6) Type "cd MyWorkSpace".
111
112 7) Type "tar xvf ../BaseTools\(Unix\).tar". This extracts the
113 Linux/Unix-specific portions of the toolkit.
114
115 8) Follow the build instructions at
116 https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Using_EDK_II_with_Native_GCC_4.4;
117 however, a few changes are required, as detailed below....
118
119 9) Type "source edksetup.sh BaseTools". This sets up some environment
120 variables, so subsequent steps (NOT including compiling rEFInd or its
121 drivers) must be typed in the shell you use for this step.
122
123 10) Edit Conf/target.txt and change the following:
124 - ACTIVE_PLATFORM = MdePkg/MdePkg.dsc
125 - TARGET = RELEASE (DEBUG might work, but I've not tested it).
126 - TARGET_ARCH = X64 (on x86-64; leave this as IA32 on x86 or change it
127 to AARCH64 on ARM64). If you plan to build multiple architectures,
128 you can set this to "IA32 X64" or some other combination.
129 - TOOL_CHAIN_TAG = GCC48 (or other value depending on your GCC version;
130 type "gcc -v" to learn your GCC version number). Note that support
131 for the latest GCC version takes a while to make it into the
132 TianoCore toolkit, so if you're using a very recent GCC, you may need
133 to specify an earlier version and hope for the best or modify
134 Conf/target.txt, as described shortly.
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.
138
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 with
143 the original UDK2014. With this setup, GCC 4.7 was newer than the most
144 recent GCC that TianoCore supported at that time. With that setup, I
145 found it necessary to change the following line:
146 *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64 -melf_x86_64
147 to:
148 *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64
149 Something similar may be necessary if you're using a very recent
150 GCC or some other compiler.
151
152 12) Type "make -C /usr/local/UDK2014/MyWorkSpace/BaseTools/Source/C".
153 (This step is not documented on the EDK Web page.) Note that this
154 requires the g++ compiler and UUID development libraries.
155
156 13) Type "build" to build the main set of EDK2 files. This process is
157 likely to take a few minutes. This step requires Python 2; if you have
158 Python 3 installed, you may need to adjust the default python for this
159 build (for instance, by typing "eselect python set python2.7" in
160 Gentoo).
161
162 If you installed in a location other than the one I've specified, you must
163 edit the EDK2BASE variable in the top-level Makefile in the rEFInd source
164 package. Once the toolkit is installed, you can build the filesystem
165 drivers or rEFInd, as described below.
166
167
168 Compiling rEFInd
169 ================
170
171 With your development system set up, you can compile rEFInd as follows:
172
173 1) Download and uncompress the rEFInd source code archive. (If you're
174 reading this file, you've probably already done this task.)
175
176 2) Open a Linux shell prompt
177
178 3) Change into the archive's main directory. You should see several files
179 including this BUILDING.txt file and several subdirectories such as
180 "refind", "libeg", "mok", "filesystems", and "include".
181
182 4) Type "make" to build rEFInd. The Makefile checks for the TianoCore
183 toolkit and tries to use it if it's present. If both toolkits are
184 installed, you can specify the toolkit name -- "make gnuefi" to build
185 with GNU-EFI, or either "make tiano" to build with TianoCore. With any
186 luck, rEFInd will compile without error, leaving the "refind_ia32.efi",
187 "refind_x64.efi", or "refind_aa64.efi" file, depending on your platform,
188 in the "refind" subdirectory. This same step builds the
189 "gptsync_ia32.efi", "gptsync_x64.efi", or "gptsync_aa64.efi" program
190 file, in the "gptsync" subdirectory. (When cross-compiling with
191 TianoCore, "gptsync_aa64.efi" is not built because the cross-compiler
192 failed for me. Since gptsync is likely to be useless on ARM64, this is
193 no great loss.) If you want to build IA32 binaries on an x86-64 (X64)
194 system, type "ARCH=ia32 make". Similarly, you can specify "ARCH=aarch64"
195 to cross-compile for ARM64. This works only if you're using the
196 TianoCore build kit, and only if you set TARGET_ARCH to the appropriate
197 value in target.txt when you set up the TianoCore toolkit. If you plan
198 to build multiple architectures, be sure to copy the .efi file for the
199 first build out of the refind subdirectory before building the second
200 architecture.
201
202 5) The default build process does NOT build the filesystem drivers. If you
203 want to build them, you must type "make fs" in the main rEFInd source
204 directory. This command builds with the TianoCore toolkit if it's
205 available and with GNU-EFI if it's not. Alternatively, you can type
206 "make fs_gnuefi" to build with GNU-EFI or "make fs_tiano" to build with
207 TianoCore. (You can prepend "ARCH=ia32" or "ARCH=aarch64" to
208 cross-compile for those architectures, as when building the main rEFInd
209 binary.) The result is filesystem drivers in the filesystems
210 subdirectory, and also copies placed in the drivers_{arch} subdirectory.
211
212 If rEFInd doesn't compile correctly, you'll need to track down the source
213 of the problem. Double-check that you've got all the necessary development
214 tools installed, including GCC, make, and either GNU-EFI or TianoCore EDK2.
215 You may also need to adjust the Makefile or Make.common file; or possibly
216 Make* files in code subdirectories. (The main Makefile controls the process
217 for both toolkits, while Make.common holds most common options.) The most
218 likely thing you'll need to change is the path to the various GNU-EFI
219 include files and libraries. Since rEFInd 0.6.2, the default Make.common
220 file includes the following definitions:
221
222 EFIINC = /usr/include/efi
223 GNUEFILIB = /usr/lib
224 EFILIB = /usr/lib
225 EFICRT0 = /usr/lib
226
227 If you've installed GNU-EFI from source code, you may need to add "local"
228 to those paths, as in "/usr/local/include/efi". You might need to change
229 references to "lib" to "lib32" or "lib64" on some systems. Recall that you
230 need at least GNU-EFI version 3.0l to build rEFInd, and until very
231 recently, most distributions provided out-of-date versions of this package.
232
233 If you're using TianoCore's EDK2, as noted earlier, you may need to adjust
234 the EDK2BASE variable in Makefile.
235
236 When I tried to compile rEFInd under Ubuntu 12.04 (i386) using GNU-EFI,
237 even with a locally-compiled GNU-EFI 3.0p or 3.0q, I got errors like this:
238
239 main.o: In function `StartLegacy.isra.0':
240 main.c:(.text+0x8b1): undefined reference to `__stack_chk_fail_local'
241 lib.o: In function `ScanVolumeBootcode.part.3':
242 lib.c:(.text+0xf2f): undefined reference to `__stack_chk_fail_local'
243 lib.o: In function `ScanExtendedPartition.isra.4':
244
245 The solution was to recompile GNU-EFI with the -fno-stack-protector GCC
246 flag. In GNU-EFI, this can be added to the CFLAGS line in Make.defaults.
247
248
249 Installing rEFInd
250 =================
251
252 With rEFInd compiled, you can install it. The easiest way to do this is
253 with the refind-install script, which works on both Linux and Mac OS X.
254 Alternatively, you can type "make install" to install using this script.
255 Note that this script copies files to the ESP and uses "efibootmgr" (on
256 Linux) or "bless" (on OS X) to add rEFInd to the firmware's boot loader
257 list. The docs/man/refind-install.8 file (and its HTML conversion,
258 docs/refind/refind-install.html) provides more details on this script and
259 its use.
260
261 If refind-install doesn't work for you or if you prefer to do the job
262 manually, you may. On a UEFI-based system, you'll want to copy files on the
263 ESP as follows:
264
265 * Create a directory for rEFInd, such as EFI/refind.
266 * Copy refind/refind_ia32.efi or refind_x64.efi to the ESP's EFI/refind
267 directory.
268 * Copy refind.conf-sample to the EFI/refind directory as refind.conf.
269 * Copy the icons subdirectory, including all its files, to EFI/refind.
270
271 You'll then need to activate rEFInd in your EFI. This can be done with
272 tools such as "efibootmgr" under Linux or "bless" under OS X. See the
273 docs/refind/installing.html file for details.
274
275
276 Note to Distribution Maintainers
277 ================================
278
279 The refind-install script, and therefore the "install" target in the
280 Makefile, installs the program directly to the ESP and it modifies the
281 *CURRENT COMPUTER's* NVRAM. Thus, you should *NOT* use this target as part
282 of the build process for your binary packages (RPMs, Debian packages,
283 etc.). (Gentoo could use it in an ebuild, though....) You COULD, however,
284 install the files to a directory somewhere (/usr/share/refind or whatever)
285 and then call refind-install as part of the binary package installation
286 process. Placing the files directly in /boot/efi/EFI/{distname}/refind and
287 then having a post-install script call efibootmgr is probably the better
288 way to go, but this assumes that the ESP is mounted at /boot/efi.
289
290
291 Compiling the EFI Filesystem Drivers
292 ====================================
293
294 To build all the drivers, you can type "make fs", "make fs_tiano", or "make
295 fs_gnuefi" from the main directory, which builds the drivers and places
296 copies in both the filesystems and drivers_{arch} subdirectories.
297
298 To install drivers, you can type "make install" in the "filesystems"
299 directory. This copies all the drivers to the
300 "/boot/efi/EFI/refind/drivers" directory. Alternatively, you can copy the
301 files you want manually. The refind-install script includes an optional
302 "--drivers" option that will install the drivers along with the main rEFInd
303 program, but to the drivers_{arch} subdirectory of the main rEFInd
304 installation directory.
305
306 *CAUTION:* Install drivers for your system's architecture *ONLY*.
307 Installing drivers for the wrong architecture causes some systems to hang
308 at boot time. This risk can be minimized by including the architecture code
309 in the drivers subdirectory name (drivers_x64 or drivers_ia32).
310
311 The drivers all rely on filesystem wrapper code created by rEFIt's author,
312 Christoph Pfisterer. Most of the drivers seem to have passed through
313 Oracle's VirtualBox project (https://www.virtualbox.org) and the Clover
314 boot loader project (https://sourceforge.net/projects/cloverefiboot/),
315 which I used as the source for this build.
316
317 Adding Support for Network Boot
318 ===============================
319
320 rEFInd provides EXPERIMENTAL support for booting over the network using
321 iPXE (http://ipxe.org) as a means to receive the payload. In order to
322 enable this feature you'll want to follow these instructions:
323
324 * cd net/
325 * make source
326 * make netboot
327 * copy bin/ipxe.efi and bin/ipxe_discover.efi to the EFI volume at EFI/tools/
328
329 Note that you may need to install additional development packages, such as
330 libiberty-dev and binutils-dev, in addition to those needed to build rEFInd
331 itself.
332
333 My own tests show this support to work under optimal conditions; however,
334 architecture (EFI vs. BIOS) detection may not work, and some computers will
335 hang or won't retrieve boot files from the network. For these reasons, this
336 support is disabled by default in rEFInd, and I do not provide iPXE
337 binaries.