code.delx.au - refind/blob - BUILDING.txt

   1 From rEFIt to rEFInd
   2 ====================
   3
   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
   9 Visual C compiler.
  10
  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 versions of TianoCore that can
  19 build under Linux use a very different set of include files and support a
  20 somewhat different set of system calls than are used by rEFIt/rEFInd. Thus,
  21 converting to a new TianoCore toolkit would entail a lot of work. Using an
  22 older version would require building under Windows and using old versions
  23 of Microsoft's Visual C. I neither have this toolchain nor do I want to use
  24 it. For this reason, I used Debian's patched version of rEFIt as a starting
  25 point in forking rEFInd.
  26
  27 I've dropped ancillary programs, such as the ext2fs driver module and
  28 gptsync program, from rEFInd. You can still use these tools with rEFInd,
  29 but you'll need to install them separately.
  30
  31 The patched version of rEFIt that I used as a starting point disabled the
  32 program's ability to load EFI drivers because of limitations in the GNU-EFI
  33 library. A combination of improvements in recent versions of the library
  34 and implementing a (now apparently abandoned) EFI function directly in
  35 rEFInd has enabled me to add this support back to rEFInd 0.2.7 and later.
  36
  37
  38 Requirements
  39 ============
  40
  41 To compile rEFInd, you'll need the following:
  42
  43 * A Linux installation. Note that this installation does NOT need to be
  44   EFI-based. It can be 32- or 64-bit, but unless you use a cross-compiler
  45   (which I've not tested), it must be the appropriate bit width for your
  46   EFI implementation. (Normally that means 64-bit.) If you don't normally
  47   run Linux, you can run it in a VirtualBox or similar virtual machine.
  48
  49 * A standard set of Linux development tools, based on GCC.
  50
  51 * The GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). You can
  52   install this from a package called "gnu-efi"; however, rEFInd relies on
  53   features that were added in (I think) 3.0l to provide driver-loading
  54   capabilities. The versions I've used and that work are 3.0p and 3.0q. As
  55   of 5/2012, most Linux distributions seem to deliver rather elderly
  56   versions of GNU-EFI, so you may need to download the latest source code,
  57   compile it, and install it locally. Since rEFInd version 0.2.7, the
  58   Makefiles assume this (see below).
  59
  60 It's possible that you could use a non-Linux platform to compile rEFInd. To
  61 the best of my knowledge, the rEFInd code doesn't rely on anything
  62 Linux-specific in its build requirements, and GNU-EFI's Sourceforge page
  63 indicates that it works under Windows and OS X, too. Thus, you may be able
  64 to compile it on these platforms, but I've not tested it in this way. Under
  65 Windows, you would need to either create a project or Makefile for your
  66 non-GCC compiler or use a GCC port, such as MinGW (http://www.mingw.org).
  67 You'd probably need to adjust the Makefile in the latter case.
  68
  69
  70 Compiling rEFInd
  71 ================
  72
  73 With your development system set up, you can compile rEFInd as follows:
  74
  75 1) Download and uncompress the rEFInd source code archive. (If you're
  76    reading this file, you've probably already done this task.)
  77
  78 2) Open a Linux shell prompt
  79
  80 3) Change into the archive's main directory. You should see several files
  81    including this BUILDING.txt file and several subdirectories such as
  82    "refind", "libeg", and "include".
  83
  84 4) Type "make". With any luck, rEFInd will compile without error, leaving
  85    the "refind_ia32.efi" or "refind_x64.efi" file, depending on your
  86    platform, in the "refind" subdirectory.
  87
  88 If rEFInd doesn't compile correctly, you'll need to track down the source
  89 of the problem. Double-check that you've got all the necessary development
  90 tools installed, including GCC, make, and GNU-EFI. You may also need to
  91 adjust the Makefile or Make.common file for your system. The most likely
  92 thing you'll need to change is the path to the various GNU-EFI include
  93 files and libraries. Since rEFInd 0.2.7, the default Make.common file
  94 includes the following definitions:
  95
  96 EFIINC          = /usr/local/include/efi
  97 GNUEFILIB       = /usr/local/lib
  98 EFILIB          = /usr/local/lib
  99 EFICRT0         = /usr/local/lib
 100
 101 If you've installed GNU-EFI from a distribution's package, you may need to
 102 remove "local" from those paths, and perhaps change references to "lib" to
 103 "lib64". As noted earlier, though, as of 5/2012, most distributions provide
 104 out-of-date GNU-EFI implementations that will not work with rEFInd 0.2.7
 105 and later.
 106
 107 When I tried to compile rEFInd under Ubuntu 12.04 (i386), even with a
 108 locally-compiled GNU-EFI 3.0p or 3.0q, I got errors like this:
 109
 110 main.o: In function `StartLegacy.isra.0':
 111 main.c:(.text+0x8b1): undefined reference to `__stack_chk_fail_local'
 112 lib.o: In function `ScanVolumeBootcode.part.3':
 113 lib.c:(.text+0xf2f): undefined reference to `__stack_chk_fail_local'
 114 lib.o: In function `ScanExtendedPartition.isra.4':
 115
 116 The solution was to recompile GNU-EFI with the -fno-stack-protector GCC
 117 flag. In GNU-EFI, this can be added to the CFLAGS line in Make.defaults.
 118
 119 Installing rEFInd
 120 =================
 121
 122 With rEFInd compiled, you can install it. The easiest way to do this is
 123 with the install.sh script, which works on both Linux and Mac OS X.
 124 Alternatively, you can type "make install" to install using this script.
 125 Note that this installation copies files to the ESP and uses "efibootmgr"
 126 (on Linux) or "bless" (on OS X) to add rEFInd to the firmware's boot loader
 127 list. The docs/refind/installing.html file provides more details on this
 128 script and its use.
 129
 130 If install.sh doesn't work for you or if you prefer to do the job manually,
 131 you may. On a UEFI-based system, you'll want to copy files on the ESP as
 132 follows:
 133
 134 * Create a directory for rEFInd, such as EFI/refind.
 135 * Copy refind/refind_ia32.efi or refind_x64.efi to the ESP's EFI/refind
 136   directory.
 137 * Copy refind.conf-sample to the EFI/refind directory as refind.conf.
 138 * Copy the icons subdirectory, including all its files, to EFI/refind.
 139
 140 You'll then need to activate rEFInd in your EFI. This can be done with
 141 tools such as "efibootmgr" under Linux or "bless" under OS X. See the
 142 docs/refind/installing.html file for details.
 143
 144 Note to Distribution Maintainers
 145 ================================
 146
 147 The install.sh script, and therefore the "install" target in the Makefile,
 148 installs the program directly to the ESP and it modifies the *CURRENT
 149 COMPUTER's* NVRAM. Thus, you should *NOT* use this target as part of the
 150 build process for your binary packages (RPMs, Debian packages, etc.).
 151 (Gentoo could use it in an ebuild, though....) You COULD, however, copy the
 152 files to a directory somewhere (/usr/share/refind or whatever) and then
 153 call install.sh as part of the binary package installation process.