Newer Older
okuji's avatar
okuji committed
1 2
-*- Text -*-

This is the GRUB.  Welcome.
okuji's avatar
okuji committed

This file contains instructions for compiling and installing the GRUB.
okuji's avatar
okuji committed
6 7 8 9

The Requirements

GRUB depends on some software packages installed into your system. If
okuji's avatar
okuji committed
you don't have any of them, please obtain and install them before
configuring the GRUB.
okuji's avatar
okuji committed

* GCC 4.1.3 or later
  Note: older versions may work but support is limited
16 17

  Experimental support for clang 3.3 or later (results in much bigger binaries)
  for i386, x86_64, arm (including thumb), arm64, mips(el), powerpc, sparc64
19 20
  Note: clang 3.2 or later works for i386 and x86_64 targets but results in
        much bigger binaries.
	earlier versions not tested
  Note: clang 3.2 or later works for arm
	earlier versions not tested
24 25
  Note: clang on arm64 is not supported due to
  Note: clang 3.3 or later works for mips(el)
27 28
	earlier versions fail to generate .reginfo and hence gprel relocations
29 30
  Note: clang 3.2 or later works for powerpc
	earlier versions not tested
31 32
  Note: clang 3.5 or later works for sparc64
        earlier versions return "error: unable to interface with target machine"
33 34
  Note: clang has no support for ia64 and hence you can't compile GRUB
	for ia64 with clang
okuji's avatar
okuji committed
* GNU Make
* GNU Bison 2.3 or later
* GNU gettext 0.17 or later
okuji's avatar
okuji committed
* GNU binutils or later
* Flex 2.5.35 or later
* pkg-config
okuji's avatar
okuji committed
* Other standard GNU/Unix tools
* a libc with large file support (e.g. glibc 2.1 or later)

44 45
On GNU/Linux, you also need:

* libdevmapper 1.02.34 or later (recommended)

For optional grub-emu features, you need:
49 50

* SDL (recommended)
51 52
* libpciaccess (optional)
* libusb (optional)
53 54 55

To build GRUB's graphical terminal (gfxterm), you need:

* FreeType 2.1.5 or later
57 58
* GNU Unifont

59 60 61
If you use a development snapshot or want to hack on GRUB you may
need the following.

* Python 2.6 or later
* Autoconf 2.60 or later
* Automake 1.10.1 or later
okuji's avatar
okuji committed

66 67 68
Prerequisites for make-check:

* qemu, specifically the binary 'qemu-system-i386'
* xorriso 1.2.9 or later, for grub-mkrescue and grub-shell

Configuring the GRUB
okuji's avatar
okuji committed
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94

The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, a
file `config.cache' that saves the results of its tests to speed up
reconfiguring, and a file `config.log' containing compiler output
(useful mainly for debugging `configure').

If you need to do unusual things to compile the package, please try to
figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If at some point `config.cache'
contains results you don't want to keep, you may remove or edit it.

The file `' is used to create `configure' by a program
called `autoconf'.  You only need `' if you want to change
it or regenerate `configure' using a newer version of `autoconf'.

Building the GRUB
okuji's avatar
okuji committed
96 97 98 99

The simplest way to compile this package is:

100 101 102 103 104 105 106
  1. `cd' to the directory containing the package's source code.

  2. Skip this and following step if you use release tarball and proceed to
     step 4. If you want translations type `./'.
  3. Type `./'.

107 108 109
     * uses python. By default invocation is "python" but can be
       overriden by setting variable $PYTHON.

  4. Type `./configure' to configure the package for your system.
111 112 113
     If you're using `csh' on an old version of System V, you might
     need to type `sh ./configure' instead to prevent `csh' from trying
     to execute `configure' itself.
okuji's avatar
okuji committed
114 115 116 117

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.

  6. Type `make' to compile the package.
okuji's avatar
okuji committed

  7. Optionally, type `make check' to run any self-tests that come with
okuji's avatar
okuji committed
121 122
     the package.

  8. Type `make install' to install the programs and any data files and
okuji's avatar
okuji committed
124 125

  9. You can remove the program binaries and object files from the
okuji's avatar
okuji committed
127 128 129 130 131 132 133 134
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.  There is
     also a `make maintainer-clean' target, but that is intended mainly
     for the package's developers.  If you use it, you may have to get
     all sorts of other programs in order to regenerate files that came
     with the distribution.

135 136 137 138 139 140 141 142 143 144 145 146 147
Cross-compiling the GRUB

GRUB defines 3 platforms:

  - "Build" is the one which build systems runs on.
  - "Host" is where you execute GRUB utils.
  - "Target" is where GRUB itself runs.

For grub-emu host and target must be the same but may differ from build.

If build and host are different make check isn't available.

148 149
If build and host are different man pages are not generated.

As an example imagine you have a build system running on FreeBSD on sparc
which prepares packages for developers running amd64 GNU/Linux laptop and
152 153 154 155 156 157 158 159
they need to make images for ARM board running U-boot. In this case:


For this example the configure line might look like (more details below)
(some options are optional and included here for completeness but some rarely
used options are omitted):

162 163
./configure BUILD_CC=gcc BUILD_PKG_CONFIG=pkg-config --host=amd64-linux-gnu
CC=amd64-linux-gnu-gcc CFLAGS="-g -O2" PKG_CONFIG=amd64-linux-gnu-pkg-config
164 165 166
--target=arm --with-platform=uboot TARGET_CC=arm-elf-gcc
TARGET_CFLAGS="-Os -march=armv6" TARGET_CCASFLAGS="-march=armv6"
TARGET_OBJCOPY="arm-elf-objcopy" TARGET_STRIP="arm-elf-strip"
TARGET_NM=arm-elf-nm TARGET_RANLIB=arm-elf-ranlib LEX=gflex
168 169 170 171 172 173 174 175 176 177 178

You need to use following options to specify tools and platforms. For minimum
version look at prerequisites. All tools not mentioned in this section under
corresponding platform are not needed for the platform in question.

  - For build
    1. BUILD_CC= to gcc able to compile for build. This is used, for
       example, to compile build-gentrigtables which is then run to
       generate sin and cos tables.
    2. BUILD_CFLAGS= for C options for build.
    3. BUILD_CPPFLAGS= for C preprocessor options for build.
    4. BUILD_LDFLAGS= for linker options for build.
    5. BUILD_PKG_CONFIG= for pkg-config for build (optional).
181 182 183 184

  - For host
    1. --host= to autoconf name of host.
    2. CC= for gcc able to compile for host
185 186 187
    3. HOST_CFLAGS= for C options for host.
    4. HOST_CPPFLAGS= for C preprocessor options for host.
    5. HOST_LDFLAGS= for linker options for host.
    6. PKG_CONFIG= for pkg-config for host (optional).
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
    7. Libdevmapper if any must be in standard linker folders (-ldevmapper) (optional).
    8. Libfuse if any must be in standard linker folders (-lfuse) (optional).
    9. Libzfs if any must be in standard linker folders (-lzfs) (optional).
    10. Liblzma if any must be in standard linker folders (-llzma) (optional).

  - For target
    1. --target= to autoconf cpu name of target.
    2. --with-platform to choose firmware.
    3. TARGET_CC= for gcc able to compile for target
    4. TARGET_CFLAGS= for C options for target.
    5. TARGET_CPPFLAGS= for C preprocessor options for target.
    6. TARGET_CCASFLAGS= for assembler options for target.
    7. TARGET_LDFLAGS= for linker options for target.
    8. TARGET_OBJCOPY= for objcopy for target.
    9. TARGET_STRIP= for strip for target.
    10. TARGET_NM= for nm for target.
    11. TARGET_RANLIB= for ranlib for target.
206 207

  - Additionally for emu, for host and target.
208 209 210
    1. SDL is looked for in standard linker directories (-lSDL) (optional)
    2. libpciaccess is looked for in standard linker directories (-lpciaccess) (optional)
    3. libusb is looked for in standard linker directories (-lusb) (optional)
211 212 213 214 215 216

  - Platform-agnostic tools and data.
    1. make is the tool you execute after ./configure.
    2. Bison is specified in YACC= variable
    3. Flex is specified in LEX= variable
    4. GNU unifont and Djvu sans are looked for in standard directories.
okuji's avatar
okuji committed
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250

Compiling For Multiple Architectures

You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory.  `cd' to the directory where you want the object files
and executables to go and run the `configure' script.  `configure'
automatically checks for the source code in the directory that
`configure' is in and in `..'.

Installation Names

By default, `make install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc.  You can specify an
installation prefix by giving `configure' the option `--prefix=PATH'.

You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If
you give `configure' the option `--exec-prefix=PATH', the package will
use PATH as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.

In addition, if you use an unusual directory layout you can give
options like `--bindir=PATH' to specify different values for
particular kinds of files.  Run `configure --help' for a list of the
directories you can set and what kinds of files go in them.

If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure'
the option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

Please note, however, that the GRUB knows where it is located in the
okuji's avatar
okuji committed
252 253
filesystem.  If you have installed it in an unusual location, the
system might not work properly, or at all.  The chief utility of these
options for the GRUB is to allow you to "install" in some alternate
okuji's avatar
okuji committed
255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
location, and then copy these to the actual root filesystem later.

Sharing Defaults

If you want to set default values for `configure' scripts to share,
you can create a site shell script called `' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/' if it exists, then
`PREFIX/etc/' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.

Operation Controls

   `configure' recognizes the following options to control how it

     Use and save the results of the tests in FILE instead of
     `./config.cache'.  Set FILE to `/dev/null' to disable caching, for
     debugging `configure'.

     Print a summary of the options to `configure', and exit.

     Do not print messages saying which checks are being made.

     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

     Print the version of Autoconf used to generate the `configure'
     script, and exit.