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