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