Small menu improvements; bug fixes & improvements to install.sh

[refind] / BUILDING.txt

diff --git a/BUILDING.txt b/BUILDING.txt
index f9fe9a29eb9e5e048196d7ff58097f7e019ccc39..7c14bf69e4503dcc53d485c6e9ea8a86d76d0ce3 100644 (file)
--- a/BUILDING.txt
+++ b/BUILDING.txt
@@ -15,17 +15,24 @@ rEFIt package (http://packages.debian.org/sid/refit) that includes
 extensive patches to enable the program to compile under Linux using the
 GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). Although
 GNU-EFI is less sophisticated than recent versions of TianoCore's toolkit,
 extensive patches to enable the program to compile under Linux using the
 GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). Although
 GNU-EFI is less sophisticated than recent versions of TianoCore's toolkit,

-GNU-EFI is my preferred environment because I prefer working in Linux and
-because TianoCore's toolkit relies on obsolete versions of Microsoft's
-Visual C++, and I had trouble tracking that down. For this reason, I used
-Debian's patched version of rEFIt as a starting point in forking rEFInd.
-The main down side to doing this is that a few rEFIt features got lost.
-Most notable among these is the ability to load filesystem drivers. I've
-also dropped ancillary programs, such as the ext2fs driver module and
+GNU-EFI is my preferred environment because versions of TianoCore that can
+build under Linux use a very different set of include files and support a
+somewhat different set of system calls than are used by rEFIt/rEFInd. Thus,
+converting to a new TianoCore toolkit would entail a lot of work. Using an
+older version would require building under Windows and using old versions
+of Microsoft's Visual C. I neither have this toolchain nor do I want to use
+it. For this reason, I used Debian's patched version of rEFIt as a starting
+point in forking rEFInd.
+
+I've dropped ancillary programs, such as the ext2fs driver module and

 gptsync program, from rEFInd. You can still use these tools with rEFInd,
 gptsync program, from rEFInd. You can still use these tools with rEFInd,

-but you'll need to install them separately; and in the case of filesystem
-drivers, you'll need to configure your EFI to load them before you launch
-rEFInd.
+but you'll need to install them separately.
+
+The patched version of rEFIt that I used as a starting point disabled the
+program's ability to load EFI drivers because of limitations in the GNU-EFI
+library. A combination of improvements in recent versions of the library
+and implementing a (now apparently abandoned) EFI function directly in
+rEFInd has enabled me to add this support back to rEFInd 0.2.7 and later.

 
 
 Requirements
 
 
 Requirements


@@ -41,8 +48,14 @@ To compile rEFInd, you'll need the following:
 
 * A standard set of Linux development tools, based on GCC.
 
 
 * A standard set of Linux development tools, based on GCC.
 

-* The GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). You
-  can usually install this from a package called "gnu-efi".
+* The GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). You can
+  install this from a package called "gnu-efi"; however, rEFInd relies on
+  features that were added in (I think) 3.0l to provide driver-loading
+  capabilities. The versions I've used and that work are 3.0p and 3.0q. As
+  of 5/2012, most Linux distributions seem to deliver rather elderly
+  versions of GNU-EFI, so you may need to download the latest source code,
+  compile it, and install it locally. Since rEFInd version 0.2.7, the
+  Makefiles assume this (see below).

 
 It's possible that you could use a non-Linux platform to compile rEFInd. To
 the best of my knowledge, the rEFInd code doesn't rely on anything
 
 It's possible that you could use a non-Linux platform to compile rEFInd. To
 the best of my knowledge, the rEFInd code doesn't rely on anything


@@ -74,13 +87,33 @@ With your development system set up, you can compile rEFInd as follows:
 If rEFInd doesn't compile correctly, you'll need to track down the source
 of the problem. Double-check that you've got all the necessary development
 tools installed, including GCC, make, and GNU-EFI. You may also need to
 If rEFInd doesn't compile correctly, you'll need to track down the source
 of the problem. Double-check that you've got all the necessary development
 tools installed, including GCC, make, and GNU-EFI. You may also need to

-adjust the Makefile or Make.common file for your system. For instance, on
-Fedora, you must  change the following variables in Make.common as shown:
-
-GNUEFILIB       = /usr/lib64
-EFILIB          = /usr/lib64
-EFICRT0         = /usr/lib64/gnuefi
-
+adjust the Makefile or Make.common file for your system. The most likely
+thing you'll need to change is the path to the various GNU-EFI include
+files and libraries. Since rEFInd 0.2.7, the default Make.common file
+includes the following definitions:
+
+EFIINC          = /usr/local/include/efi
+GNUEFILIB       = /usr/local/lib
+EFILIB          = /usr/local/lib
+EFICRT0         = /usr/local/lib
+
+If you've installed GNU-EFI from a distribution's package, you may need to
+remove "local" from those paths, and perhaps change references to "lib" to
+"lib64". As noted earlier, though, as of 5/2012, most distributions provide
+out-of-date GNU-EFI implementations that will not work with rEFInd 0.2.7
+and later.
+
+When I tried to compile rEFInd under Ubuntu 12.04 (i386), even with a
+locally-compiled GNU-EFI 3.0p or 3.0q, I got errors like this:
+
+main.o: In function `StartLegacy.isra.0':
+main.c:(.text+0x8b1): undefined reference to `__stack_chk_fail_local'
+lib.o: In function `ScanVolumeBootcode.part.3':
+lib.c:(.text+0xf2f): undefined reference to `__stack_chk_fail_local'
+lib.o: In function `ScanExtendedPartition.isra.4':
+
+The solution was to recompile GNU-EFI with the -fno-stack-protector GCC
+flag. In GNU-EFI, this can be added to the CFLAGS line in Make.defaults.

 
 Installing rEFInd
 =================
 
 Installing rEFInd
 =================


@@ -96,3 +129,11 @@ want to copy files on the ESP as follows:
 You'll then need to activate rEFInd in your EFI. This can be done with
 tools such as "efibootmgr" under Linux or "bless" under OS X. See the
 docs/installing.html file for details.
 You'll then need to activate rEFInd in your EFI. This can be done with
 tools such as "efibootmgr" under Linux or "bless" under OS X. See the
 docs/installing.html file for details.

+
+You may have noticed an install.sh script in the source package. This
+script is intended for distribution with my own binary packages of rEFInd,
+and it copies files from the "refind" subdirectory (relative to the
+script's location) -- namely refind_x64.efi or refind_ia32.efi,
+refind.conf-sample, and an icons subdirectory. You can rearrange your files
+to provide this layout, but it's no more work to copy the files as just
+described.