This is an old revision of the document!
====== 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. ===== Building the cross toolchain ===== 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 at least a half 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. ===== Building gPXE ===== 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. ===== Running gPXE under PC BIOS emulation on a Mac ===== 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. ===== Running gPXE under native EFI on a Mac ===== There are two ways of booting with your shiny new EFI image: rEFIt and a "blessed" external drive. ==== rEFIt ==== 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. ==== Blessed external drive ==== 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.
