X-Git-Url: https://code.delx.au/refind/blobdiff_plain/cee29bbe756d31c517f874c668e33305642a504d..fe53e20674a0f3dff46aa42d5676a5304dac92bf:/BUILDING.txt diff --git a/BUILDING.txt b/BUILDING.txt index 8140481..660057c 100644 --- a/BUILDING.txt +++ b/BUILDING.txt @@ -15,28 +15,23 @@ 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, -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. - -Note that the drivers, added with rEFInd 0.4.0, require use of the -TianoCore tool kit. Driver compilation is described in more detail later. +GNU-EFI is my preferred environment because it's provided with many Linux +distributions and it was easy to get started with rEFInd development by +using GNU-EFI and the Debian rEFIt package as a starting point. + +Over time, though, I've found that the recent TianoCore EDK2 toolkit has +its advantages. The most important of these is that the EFI filesystem +drivers, added with rEFInd 0.4.0, require this toolkit. This is a +consequence of their derivation, which is via VirtualBox and the Clover +boot loader, both of which are based on EDK2. I therefore use EDK2 for the +drivers, and I've added EDK2 support for rEFInd itself. In short, then, the +drivers require EDK2, whereas the main rEFInd binary can compile with +either EDK2 or GNU-EFI. I've dropped ancillary programs, such as the gptsync program, from rEFInd. You can still use these tools with 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 ============ @@ -51,23 +46,125 @@ To compile rEFInd, you'll need the following: * A standard set of Linux development tools, based on GCC. -* 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). +* One of the following: + + * 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). + + * The TianoCore EDK2 package + (http://sourceforge.net/projects/tianocore/). I've tested using the + UDK2010.SR1 variant + (http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010), + which is "frozen," rather than the main EDK2 development branch, which + is changing as the developers add features, fix bugs, and so on. Using + this package is supported in rEFInd version 0.4.3 and later (0.4.0 and + later for the filesystem drivers only). See below for TianoCore setup + instructions. 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 Linux-specific in its build requirements, and GNU-EFI's Sourceforge page -indicates that it works under Windows and OS X, too. Thus, you may be able -to compile it on these platforms, but I've not tested it in this way. Under -Windows, you would need to either create a project or Makefile for your -non-GCC compiler or use a GCC port, such as MinGW (http://www.mingw.org). -You'd probably need to adjust the Makefile in the latter case. +indicates that it works under Windows and OS X, too; however, my one +attempt to compile GNU-EFI under OS X failed. Using the TianoCore toolkit +might be more likely to work under OS X or Windows, but I haven't tested +it. Under Windows, you would need to either create a project or Makefile +for your non-GCC compiler or use a GCC port, such as MinGW +(http://www.mingw.org). You'd probably need to adjust the Makefiles in the +latter case. + + +Preparing Your Development Kit +============================== + +If you want to build the rEFInd binary but not the drivers and if you're +using Linux, GNU-EFI is the easiest way to do the job. I don't describe its +setup here because it's likely to be fairly easy. If your distribution +provides a recent enough version, you should be able to install a package +called gnu-efi and be done with it. If not, you'll need to download the +source code tarball, build it, and install it. This process is fairly +typical of Linux packages. Read the GNU-EFI documentation if you need help. +If you're using GNU-EFI, you can skip the rest of this section. + +To build the EFI drivers, the TianoCore toolkit is required. You might also +want to use it if you have problems with GNU-EFI or if you want to build +rEFInd on a non-Linux platform. Unfortunately, the TianoCore toolkit is +weird by Linux programming standards. It's also quite large -- it's +intended as a means to develop a complete EFI firmware implementation, so +it contains much more code than is needed to develop standalone EFI +applications. I don't know of any Linux distribution packages for it in +RPM, Debian package file, or other format; you MUST install the kit from +source code using its own unusual compilation procedure. The installation +documentation also omits at least one step and is a bit unclear about +others. Here's how I installed the toolkit: + +1) Download UDK2010.SR1 from + https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010. + +2) Type "mkdir /usr/local/UDK2010". You can use another directory, but the + Makefile for rEFInd's EFI drivers assumes this location. You'll need to + edit the EDK2BASE line in the Make.common file if you install somewhere + else. + +3) Type "cd /usr/local/UDK2010". + +3) Unzip the downloaded file (UDK2010.SR1.Complete.MyWorkSpace.zip) in the + current directory (/usr/local/UDK2010). This creates a handful of files, + including a tarball and a couple of .zip files. + +4) Type "unzip UDK2010.SR1.MyWorkSpace.zip". This extracts the + platform-neutral portion of the development kit. + +5) Type "cd MyWorkSpace". + +6) Type "tar xvf ../BaseTools\(Unix\)_UDK2010.SR1.tar". This extracts the + Linux/Unix-specific portions of the toolkit. + +7) Follow the build instructions at + https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Using_EDK_II_with_Native_GCC_4.4; + however, a few changes are required, as detailed below.... + +8) Type ". edksetup.sh BaseTools" (note the leading dot). This sets up some + environment variables, so subsequent steps (NOT including compiling the + rEFInd EFI drivers) must be typed in the shell you use for this step. + +9) Edit Conf/target.txt and change the following: + - ACTIVE_PLATFORM = MdeModulePkg/MdeModulePkg.dsc + - TARGET = RELEASE (DEBUG might work, but I've not tested it). + - TARGET_ARCH = X64 (on x86-64; leave this as IA32 on x86) + - TOOL_CHAIN_TAG = GCC45 (or other value depending on your GCC version; + type "gcc -v" to learn your GCC version number). Note that GCC 4.7 + doesn't have its own entry, so use GCC46 for GCC 4.7. + The TianoCore Makefiles read some of these variables from this file + and uses them when accessing directories, so be sure to type these + entries in the case specified. + +10) The documentation refers to editing Conf/tools_def.txt in addition to + Conf/target.txt, but doesn't specify what to change in + Conf/tools_def.txt. I haven't found it necessary to make any changes in + Conf/tools_def.txt EXCEPT when using GCC 4.7 on a Fedora 17 system. + (I haven't used GCC 4.7 on other platforms, so this may well be + necessary on other systems, too.) With that setup, I found it + necessary to change the following line: + *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64 -melf_x86_64 + to: + *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64 + +11) Type "make -C /usr/local/UDK2010/MyWorkSpace/BaseTools/Source/C". + (This step is not documented on the EDK Web page.) + +10) Type "build" to build the main set of EDK2 files. This process is + likely to take a few minutes. + +If you installed in a location other than the one I've specified, you must +edit the EDK2BASE variable in the Make.tiano and filesystems/Make.tiano +files in the rEFInd source package. Once the toolkit is installed, you can +build the filesystem drivers or rEFInd, as described below. Compiling rEFInd @@ -84,17 +181,26 @@ With your development system set up, you can compile rEFInd as follows: including this BUILDING.txt file and several subdirectories such as "refind", "libeg", and "include". -4) Type "make". With any luck, rEFInd will compile without error, leaving - the "refind_ia32.efi" or "refind_x64.efi" file, depending on your - platform, in the "refind" subdirectory. +4) Type "make" to build with GNU-EFI, or "make tiano" to build with + TianoCore EDK2. With any luck, rEFInd will compile without error, + leaving the "refind_ia32.efi" or "refind_x64.efi" file, depending on + your platform, in the "refind" subdirectory. + +5) The default build process does NOT build the filesystem drivers. If you + want to build them, you must type "make fs" in the main rEFInd source + directory. The result is filesystem drivers in the filesystems + subdirectory, and also copies placed in the drivers subdirectory. You + must install the TianoCore EDK2 to build the drivers. 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. 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: +tools installed, including GCC, make, and either GNU-EFI or TianoCore EDK2. +You may also need to adjust the Makefile, Make.common file, or Make.tiano +file for your system. (The main Makefile controls the process for both +toolkits, while Make.common holds GNU-EFI options and Make.tiano holds +TianoCore options.) 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 @@ -107,8 +213,11 @@ remove "local" from those paths, and perhaps change references to "lib" to 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: +If you're using TianoCore's EDK2, as noted earlier, you may need to adjust +the EDK2BASE variable in Make.tiano and filesystems/Make.tiano. + +When I tried to compile rEFInd under Ubuntu 12.04 (i386) using GNU-EFI, +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' @@ -119,6 +228,7 @@ 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 ================= @@ -144,6 +254,7 @@ 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/refind/installing.html file for details. + Note to Distribution Maintainers ================================ @@ -158,96 +269,15 @@ Placing the files in /boot/efi/EFI/{distname}/refind and then having a post-install script call efibootmgr is probably the better way to go, though. + Compiling the EFI Filesystem Drivers ==================================== -The EFI filesystem drivers in the filesystems subdirectory require the -TianoCore UDK2010.SR1 toolkit. The drivers might compile with another -version of the TianoCore toolkit, but I've not tested them with anything -else. My attempts to use GNU-EFI have failed; at best, I've gotten drivers -that load but then hang the computer. - -An important caveat: I suspect the TianoCore toolkit is responsible for an -inability to use the resulting drivers on a 32-bit Mac Mini. My suspicion -is that it produces binaries that work on UEFI 2.x systems but not on the -EFI 1.x that the Mac uses. If this suspicion is correct, you may be unable -to use the rEFInd binaries on at least some Macs, as well as on other older -EFI 1.x-based computers. - -Unfortunately, the TianoCore toolkit is bulky and weird by Linux -programming standards. I don't know of any Linux distribution packages for -it in RPM, Debian package file, or other format; you MUST install the kit -from source code using its own unusual compilation procedure. The -installation documentation also omits at least one step and is a bit -unclear about others. Here's how I installed the toolkit: - -1) Download UDK2010.SR1 from - https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=UDK2010. - -2) Type "mkdir /usr/local/UDK2010". You can use another directory, but the - Makefile for rEFInd's EFI drivers assumes this location. You'll need to - edit the EDK2BASE line in the Make.common file if you install somewhere - else. - -3) Type "cd /usr/local/UDK2010". - -3) Unzip the downloaded file (UDK2010.SR1.Complete.MyWorkSpace.zip) in the - current directory (/usr/local/UDK2010). This creates a handful of files, - including a tarball and a couple of .zip files. - -4) Type "unzip UDK2010.SR1.MyWorkSpace.zip". This extracts the - platform-neutral portion of the development kit. - -5) Type "cd MyWorkSpace". - -6) Type "tar xvf ../BaseTools\(Unix\)_UDK2010.SR1.tar". This extracts the - Linux/Unix-specific portions of the toolkit. - -7) Follow the build instructions at - https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Using_EDK_II_with_Native_GCC_4.4; - however, a few changes are required, as detailed below.... - -8) Type ". edksetup.sh BaseTools" (note the leading dot). This sets up some - environment variables, so subsequent steps (NOT including compiling the - rEFInd EFI drivers) must be typed in the shell you use for this step. - -9) Edit Conf/target.txt and change the following: - - ACTIVE_PLATFORM = MdeModulePkg/MdeModulePkg.dsc - - TARGET = RELEASE (DEBUG might work, but I've not tested it). - - TARGET_ARCH = X64 (on x86-64; leave this as IA32 on x86) - - TOOL_CHAIN_TAG = GCC45 (or other value depending on your GCC version; - type "gcc -v" to learn your GCC version number). Note that GCC 4.7 - doesn't have its own entry, so use GCC46 for GCC 4.7. - The Makefile for the drivers reads some of these variables from this - file and uses them when accessing directories, so be sure to type these - entries in the case specified. - -10) The documentation refers to editing Conf/tools_def.txt in addition to - Conf/target.txt, but doesn't specify what to change in - Conf/tools_def.txt. I haven't found it necessary to make any changes in - Conf/tools_def.txt EXCEPT when using GCC 4.7 on a Fedora 17 system. - (I haven't used GCC 4.7 on other platforms, so this may well be - necessary on other systems, too.) With that setup, I found it - necessary to change the following line: - *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64 -melf_x86_64 - to: - *_GCC46_X64_ASM_FLAGS = DEF(GCC46_ASM_FLAGS) -m64 - -11) Type "make -C /usr/local/UDK2010/MyWorkSpace/BaseTools/Source/C". - (This step is not documented on the EDK Web page.) - -10) Type "build" to build the main set of EDK2 files. This process is - likely to take a few minutes. - -Once the toolkit is installed, you can build the filesystem drivers. If you -installed in a location other than the one I've specified, you must edit -the EDK2BASE variable in the filesystems/Make.common file in the rEFInd -source package. You can then type "make" in the "filesystems" directory, -or "make fs" in the main source directory, to build all the drivers. If you -want to build just one driver, you can change into the "filesystems" -directory and type "make {fsname}", where {fsname} is a filesystem name -- -"ext2", "reiserfs", "iso9660", or "hfs". The drivers will appear in the -"filesystems" directory, and also be copied to the "drivers" directory. +To build all the drivers, you can type "make fs" from the main directory, +which builds the drivers and places copies in both the filesystems and +drivers subdirectories. If you want to build just one driver, you can +change into the "filesystems" directory and type "make {fsname}", where +{fsname} is a filesystem name -- "ext2", "reiserfs", "iso9660", or "hfs". To install drivers, you can type "make install" in the "filesystems" directory. This copies all the drivers to the