Building gPXE on a Mac

You can build gPXE on a Mac running OS X, either targeting the Mac's EFI interface or the normal PC BIOS interface. The Mac's EFI interface is generally trickier to set up, since the restrictions of running under EFI prevent us from providing real-mode interfaces like that required by PXELINUX; you can only load EFI images like elilo.

In either case, since the native OS X toolchain doesn't produce ELF executables, it's necessary to acquire or build a cross-compiling one.

This page formerly contained information about how to build the cross toolchain manually, but it was incomplete and new versions of the compiler often break it. We therefore now advise you to install the toolchain using MacPorts; they've already done all the work for you.

Download the disk image for the latest version of MacPorts corresponding to your OS X version from http://svn.macports.org/repository/macports/downloads/MacPorts-1.7.1/, mount it, and run the installer located on it. The package being installed is tiny, but the installer script takes a while as it must download ports information via rsync.

Open a new terminal window and type

  $ sudo port install i386-elf-gcc

Find something else to do for a while; it will take over an hour hour to install, depending on your machine.

With the toolchain installed, you should be able to run e.g. i386-elf-gcc -v and get version information.

If you have a recent Mac with 64-bit EFI, and intend on making an EFI binary to run on it, you will need a 64-bit cross compiler. I don't know of any automated way of getting one, so you'll have to build it yourself following the instructions at http://wiki.osdev.org/GCC_Cross-Compiler_for_x86_64 — good luck!

Get the latest gPXE from git (as of this writing the OS X build fixes are not in any numbered release) and go to the src/ subdirectory as you normally would for a build from source.

To compile a PC bios gPXE, use your normal make commandline with CROSS_COMPILE=i386-elf- (don't forget the trailing dash!) on the end. For instance,

  $ make bin/gpxe.dsk CROSS_COMPILE=i386-elf-

To compile an EFI gPXE suitable for running on the Mac:

  $ make bin-i386-efi/sky2.efi CROSS_COMPILE=i386-elf- BINUTILS_DIR=/usr/local BFD_DIR=/usr/local/i386-apple-darwin9.6.0/i386-elf

It's necessary to be specific with the driver to exclude undionly, since that requires 16-bit code support that's not present in EFI targets. The sky2 driver is used by some Macs, and forcedeth by others; you can also make bin-i386-efi/sky2--forcedeth.efi for a gPXE that will support both.

If you have a recent Mac, it may use a 64-bit EFI environment. You can compile gPXE for that too, but you need a 64-bit cross-compiler (x86_64-elf-gcc). If you've got one,

  $ make bin-x86_64-efi/sky2.efi CROSS_COMPILE=x86_64-elf- BINUTILS_DIR=/usr/local BFD_DIR=/usr/local/i386-apple-darwin9.6.0/x86_64-elf

Some recent Macs have Intel Ethernet chipsets. Try the e1000e driver instead of sky2.

For most purposes, the PC-BIOS gPXE will be best, because it is capable of booting almost all supported image types while the EFI gPXE can only boot other EFI images. EFI gPXE cannot SAN boot, load PXELINUX, etc.

PC BIOS emulation on a Mac is provided by Boot Camp, which is included in the firmware of all recent Macs. Without it, you may need a firmware upgrade. While there may be a way to embed gPXE into Boot Camp in the manner of an option ROM, this would require a fair bit of reverse engineering which no one has yet undertaken. Thus, your options involve a hard disk partition, CD-ROM, or USB memory stick. Whichever medium you choose should be prepared just like for a PC, using e.g. SYSLINUX to boot or burning gpxe.iso to a CD. Just putting gPXE onto the partition raw might work, but it's not been tested.

You can set the system boot device in the Startup Disk control panel, using bless on the command line: assuming /dev/disk0s3 is your gPXE partition,

  $ sudo bless --device /dev/disk0s3 --legacy --setBoot

You can also select the partition at boot time by holding down the Option key, though it will probably be called “Windows”.

Or you can use rEFIt (see below) as a bootloader.

There are two ways of booting with your shiny new EFI image: rEFIt and a “blessed” external drive.

rEFIt is an EFI bootloader; while its main purpose is to choose between operating systems at startup, it also includes an EFI shell that you can use to test gPXE. Download it from http://refit.sourceforge.net/#download and install following the directions on that site, then place driver.efi in the newly created /efi/tools directory. After two reboots if you used the provided installer, or one if you used enable.sh, you should be presented with a boot menu. Navigate to the “shell” option and type the basename of your gPXE EFI image at the prompt. If all went well, you should be able to use gPXE—though be aware that some EFI versions on the Mac don't pass the Control key, so “Press Ctrl+B for shell prompt…” may not.

Using rEFIt's installer installs a tool called “rEFItBlesser” that runs at system shutdown to “bless” the rEFIt image to run on next startup, and “unblesses” it as OS X is starting up. That means rEFIt won't run after a hard reboot or when waking from sleep. Using enable.sh causes the rEFIt image to be blessed permanently until you change the blessing back with the Startup Disk preference pane. It's up to you which you'd rather use; rEFIt's website has good documentation.

Mount your USB or FireWire external drive, create an efi folder therein, and copy driver.efi to that folder. Assuming it's mounted at /Volumes/gPXE, run

  $ sudo bless --folder /Volumes/gPXE/efi --file /Volumes/gPXE/efi/driver.efi

You can add –setBoot to set that external drive as the default for all future boots, –setBoot –nextonly to set it as the default only for the next startup, or use the Startup Disk preference pane after driver.efi (replace it with the actual name of your EFI image) has been blessed.

Use bless –info mountpoint to see what, if anything, is blessed on the partition mounted at mountpoint, or bless –getBoot to see the default boot device.

If you're feeling particularly daring, you can mount and use the “EFI System Partition”, /dev/disk0s1, for gPXE. This may be a good long-term solution once gPXE on Macs is running stably.

Note that the blessing method is thus far untested.