Step-by-step (walk-throughs) for building with edk2

This page contains some step-by-step guides in an attempt to give a highly detailed description of how to set up building on an edk2 system.  A few different operating systems are targeted.  It is hoped that these examples can either provide exact steps for setting up an edk2 build environment.  If instructions are not available for your exact system configuration, you may still be able to tweak the instructions to work on your system.

Getting started for UNIX-like operating systems

These instructions will be written as a series of commands executed from a command terminal.

Often these instructions will contain a command which needs to be executed in the terminal window.  For example:

bash$ echo this bold text is a sample command

To execute this command, highlight the bold text of the command in your web browser.  Most web browsers should be able to copy the text by selecting Copy under the Edit menu.  Now, change back to the terminal application, and there should be a Paste operation under the Edit menu.  After pasting the command into the shell, you may need to press the enter or return key to execute the command. 

Of course, there may be other ways to copy and paste the command into the terminal which are specific to the windowing environment and applications that you are using.  If all else fails, however, you can type the command by hand.

Some commands are very long, and we use the backslash character (\) to tell the shell program that the command is not finished.  For example:

bash$ echo this bold text is a sample command \
        which is broken into two lines

When you copy and paste, make sure you include all lines of the command (including the backslash (\) characters).  If you are typing the command, you can remove the backslash character (\) and combine the lines into a single line if you prefer.

If a command starts with the sudo command, then you may be prompted for your user password.  This will be the same password as you used to login to the system.

For the purposes of this set of instructions, we will be using the following paths. 

Edk2 source tree: ~/src/edk2
Buildtools source tree: ~/src/buildtools
gcc x64 cross-compiler installation: ~/programs/gcc/x64

You will need to change the commands if you want to use different locations, but this is not recommended unless you are sure that you know what you are doing.

Internet proxies

If your network utilizes a firewall with a web proxy, then you may need to configure your proxy information for various command line applications to work.  You may need to consult with your network administrator to find out the computer name and port to use for proxy setup.  The following commands are common examples of how you would configure your proxy by setting an environment variable:

bash$ export http_proxy=http://proxy.domain.com:proxy_port
bash$ export ftp_proxy=$http_proxy

To utilize the subversion source control command behind an internet firewall with a web proxy, you should configure the ~/.subversion/servers file.

Instructions for various UNIX-like systems

Red Hat Enterprise Linux 4 Desktop

Coming soon...

Mac OS X 10.5

Work in progress...

These instructions for OS X 10.5 are currently under construction.  Please do not try to use them until this notice is removed!

Xcode Tools

The first step is to install the Apple Xcode development environment:
  http://developer.apple.com/tools/xcode

To install Xcode, you must register as an Apple developer, and download the Xcode installation disk image (which is fairly large).  These instructions were verified with Xcode 3.0.  Within the Xcode Tools disk image, only the Xcode Tools.mpkg package needs to be installed.

Open OS X Terminal program

Past this point, the remaining instructions will utilize OS X's built in command shell (bash) via the Terminal application.  To open the command terminal application, open Finder, then press the Cmd-Shift-U key combination.  (This opens the Applications => Utilities folder.)  In the Utilities folder, you should see the Terminal application.

GMP & MPFR (if behind a web proxy)

The gmp and mpfr libraries are needed to build the gcc cross compiler at a later point in these instructions.  Building these libraries on OS X can present some difficulties, so if you are not behind a network firewall, then consider using the macports project to install these libraries. (see below)  Be sure to set the http_proxy and ftp_proxy environment variables before using the 'curl' commands below.

bash$ mkdir ~/src
bash$ cd ~/src
bash$ curl --remote-name \
  ftp://ftp.gnu.org/gnu/gmp/gmp-4.2.2.tar.bz2
bash$ tar jxvf gmp-4.2.2.tar.bz2
bash$ cd gmp-4.2.2
bash$ ./configure --prefix=/usr
bash$ make
bash$ make check
bash$ sudo make install

Note: This might be needed for 64-bit machines if
      the MPFR configure fails below.
bash$ export CFLAGS="-m64"

bash$ cd ~/src
bash$ curl --remote-name \
  http://www.mpfr.org/mpfr-current/mpfr-2.3.1.tar.bz2
bash$ tar jxvf mpfr-2.3.1.tar.bz2
bash$ cd mpfr-2.3.1
bash$ ./configure --prefix=/usr
bash$ make
bash$ make check
bash$ sudo make install

GMP & MPFR via Macports (if not behind web proxy)

If you are not behind a network firewall, then the http://www.macports.org project can greatly simlify the installation of gmp & mpfr.  (Macports does not work easily with web proxies at this time.) After installing macports you should be able to simply run this command at the shell prompt.

bash$ sudo port install gmp mpfr

Continue with common instructions

The remaining instructions are common for most UNIX-like systems.

SuSE Linux Enterprise 10 Desktop

Coming soon...

Ubuntu 8.04

Please note

The Ubuntu platform is not officially supported or tested by the edk2 project at this time.

Open the GNOME Terminal program

These instructions will utilize Ubuntu's built in command shell (bash) via the GNOME Terminal application.  To open the Terminal application, locate it under the Applications menu and the Accessories sub-menu.

Install required software from apt

Several ubuntu packages will be needed to fully set up an edk2 build environment.  In order to easily install all the requirements, you need to run this command.

bash$ sudo apt-get install build-essential uuid-dev \
        python-setuptools texinfo bison flex libgmp3-dev \
        libmpfr-dev subversion

Continue with common instructions

The remaining instructions are common for most UNIX-like systems.

Common instructions for UNIX-like systems

A significant portion of the steps are common on the various UNIX-like platforms.  You should start with the instructions for the operating system that most closely matches your platform, and it will direct you here at the appropriate time.

Install python antlr module

In order to install the python antlr module, we use the 'easy_install' command.  The following command is the latest version right now, but if you encounter difficulties, you may want to confirm the version at http://www.antlr.org/download/Python.  Be sure to set the http_proxy and ftp_proxy environment variables if you are behind a network firewall.

bash$ sudo easy_install \
  http://www.antlr.org/download/Python/antlr_python_runtime-3.0.1-py2.5.egg

Get and build the edk2 BaseTools

We will now check out the BaseTools source code using subversion.  (If you are behind a web proxy, then you may need to configure your proxy in the ~/.subversion/servers file.)  We will tell subversion to use the 'guest' username on tianocore.org.  The password for the 'guest' account is blank/empty.

bash$ mkdir ~/src
bash$ cd ~/src
bash$ svn co \
  https://buildtools.tianocore.org/svn/buildtools/trunk/BaseTools \
  --username guest
bash$ make -C BaseTools

Build gcc x64 UEFI cross compiler

In order to build UEFI images for x64, you will need to build a cross-compiler build of gcc.  This can take quite a while to complete, possibly several hours on older systems.  But, a Python script has been provided to automate this build process.

Note: This is only needed if behind a internet firewall!
bash$ export http_proxy=http://proxy.domain.com:proxy_port

To build gcc for x64, use these commands (this will take quite a while to complete):

bash$ cd ~/src/BaseTools/gcc
bash$ ./mingw-gcc-build.py --arch=x64 \
  --prefix=~/programs/gcc/x64

Get the edk2 source tree

bash$ cd ~/src
bash$ svn co \
  https://edk2.tianocore.org/svn/edk2/trunk/edk2 \
  --username guest

Setup build shell environment

bash$ cd ~/src/edk2
bash$ export EDK_TOOLS_PATH=~/src/BaseTools
bash$ . edksetup.sh BaseTools

Modify Conf files

You will need to edit the Conf/tools_def.txt and Conf/target.txt files. 

For the Conf/tools_def.txt file, find the following lines:

*_UNIXGCC_X64_CC_PATH               = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
*_UNIXGCC_X64_SLINK_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/ar
*_UNIXGCC_X64_DLINK_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/ld
*_UNIXGCC_X64_ASM_PATH              = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
*_UNIXGCC_X64_PP_PATH               = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
*_UNIXGCC_X64_VFRPP_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc

And change the cooresponding lines to match these:

*_UNIXGCC_X64_CC_PATH               = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
*_UNIXGCC_X64_SLINK_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-ar
*_UNIXGCC_X64_DLINK_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-ld
*_UNIXGCC_X64_ASM_PATH              = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
*_UNIXGCC_X64_PP_PATH               = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
*_UNIXGCC_X64_VFRPP_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc

For the Conf/target.txt file, find the following lines:

ACTIVE_PLATFORM       = Nt32Pkg/Nt32Pkg.dsc
TARGET_ARCH           = IA32
TOOL_CHAIN_TAG        = MYTOOLS

And change the cooresponding lines to match these:

ACTIVE_PLATFORM       = MdeModulePkg/MdeModulePkg.dsc
TARGET_ARCH           = X64
TOOL_CHAIN_TAG        = UNIXGCC

Build Hello World!  (and the rest of MdeModulePkg)

Now you should be able to simply run the build command to compile the MdeModulePkg.

bash$ build

As a tangible result of the build, you should have the HelloWorld UEFI X64 application.  If you have a X64 UEFI system available to you, then this application should be able to run successfully under the shell.

bash$ ls Build/MdeModule/DEBUG_UNIXGCC/X64/HelloWorld.efi