= Mac OS X build instructions =

== Prerequisites on Mac OS X ==

 * 10.10.x (Yosemite) or later running on Intel hardware (PowerPC hardware is '''not''' supported nor is building an X11 variant).

 * Xcode matching your Mac OS X version (http://developer.apple.com/tools/download/).  Until recently the official builds were done using Xcode 6.2 (you may use the tools/darwin.amd64/bin/xcode-6.2-extractor.sh script to 'install' the necessary bits on later OS X versions).

 * Some things from !MacPorts (http://www.macports.org/). [[BR]]
 After installing !MacPorts, do not forget to make sure the following two lines are in your `~/.profile` or `~/.zprofile` file and actually loaded in the shell you're using:
{{{
export PATH=/opt/local/bin:/opt/local/sbin:$PATH
export MANPATH=/opt/local/share/man:$MANPATH
}}}

 Then perform the following command: [[BR]]
{{{
sudo port install libidl acpica yasm subversion doxygen texlive texlive-latex-extra texlive-fonts-extra x86_64-elf-gcc
}}}

 Doxygen, texlive* and x86_64-elf-gcc are optional (first two for documentation, latter for the validation kit).

 * Qt/Mac 5.6 or later (http://qt.nokia.com/downloads/qt-for-open-source-cpp-development-on-mac-os-x) [[BR]]

 * Loading self-built kernel extensions (kexts) on more recent OS X may require changes to the system config unless you have a kext signing certificate and is running 10.14 (High Sierra) or earlier.
   For 10.11 (El Capitan) and later boot to the recovery partition and either enabling loading of unsigned kexts:
{{{
csrutil enable --without kext
}}}
   or disable SIP all together: 
{{{
csrutil disable
}}}
   For 10.15 (Catalina) and later you also need to disable the reboot requirement (also from recovery partition):
{{{
spctl kext-consent disable
}}}
   If you are running 10.10 (Yosemite) there is a boot-args option for allowing the loading of unsigned kexts.  Run the following and reboot:
{{{
sudo nvram boot-args="kext-dev-mode=1"
}}}   

== Building !VirtualBox ==

 1. Change to the root directory of the sources and execute the configure script: 
{{{
./configure --disable-hardening
}}}
 You can manually set the target architecture with `--target-arch=x86` or `amd64`, if some architecture related problems occur.

 If it finds everything it needs, it will create a file called `!AutoConfig.kmk` containing paths to the various tools on your system. Also, it will create an environment setup script called env.sh. This step only has to be done once (if something changes in your build tool setup, you might have to repeat it but keep in mind that both output files will be overwritten).
 2. Whenever you want to build !VirtualBox, you have to open a shell and source the generated environment setup script `env.sh`, i.e. do
{{{
. ./env.sh
}}}

 3. To build type 
{{{
kmk
}}}
    The default is to a release build, should you wish to do a ''debug'' or ''profile'' build add {{{BUILD_TYPE=debug}}} or {{{BUILD_TYPE=profile}}} as argument to `kmk` or export it as an environment variable in your shell.

== Running !VirtualBox ==

 1. Load all the kernel extension modules. These can be found in `out/darwin.x86/release/dist` along with a small script (`loadall.sh`) to load them. Execute and make sure the modules loads successfully. 
 2. Enter {{{out/darwin.x86/release/dist/VirtualBox.app/Contents/MacOS/}}}.
 3. Run {{{./VirtualBox}}}

== Building OSE packages for distribution ==

'''Never''' disable hardening (see previous section) when creating packages for redistribution. 

Hardening needs some additional configuration and post-build steps. The default install directory of !VirtualBox is `/Applications/VirtualBox.app/`. If you like to change that, say into `/Applications/OpenSource/VirtualBox.app/`, you need to add the following to the `LocalConfig.kmk`:
{{{
VBOX_PATH_APP_PRIVATE      = "/Applications/OpenSource/VirtualBox.app/Contents/MacOS"
VBOX_PATH_APP_PRIVATE_ARCH = "/Applications/OpenSource/VirtualBox.app/Contents/MacOS"
VBOX_PATH_SHARED_LIBS      = "/Applications/OpenSource/VirtualBox.app/Contents/MacOS"
VBOX_PATH_APP_DOCS         = "/Applications/OpenSource/VirtualBox.app/Contents/MacOS"
}}}
It may also make sense to disable some of the development only stuff, like test cases. Add the following to `LocalConfig.kmk`:
{{{
VBOX_WITH_TESTSUITE=
VBOX_WITH_TESTCASES=
}}}
Starting with !VirtualBox 4.1, extra debug symbols are created. You can prevent that by adding the following to `LocalConfig.kmk`:
{{{
kBuildGlobalDefaults_LD_DEBUG=
}}}
Next rebuild !VirtualBox and install it into `/Applications/OpenSource/`. There isn't any support for installing !VirtualBox into a target directory. Just copy the files to the destination. Now make sure that the setuid stubs have the correct permissions: 
{{{
sudo chown -R root:admin /Applications/OpenSource/VirtualBox.app/
sudo chmod u+s /Applications/OpenSource/VirtualBox.app/Contents/MacOS/VirtualBox
sudo chmod u+s /Applications/OpenSource/VirtualBox.app/Contents/MacOS/VirtualBoxVM
sudo chmod u+s /Applications/OpenSource/VirtualBox.app/Contents/MacOS/VBoxHeadless
sudo chmod u+s /Applications/OpenSource/VirtualBox.app/Contents/MacOS/VBoxNetAdpCtl
sudo chmod u+s /Applications/OpenSource/VirtualBox.app/Contents/MacOS/VBoxNetDHCP
}}}
Another requirement of hardening is that every path component of the parent directory of `VirtualBox.app/` is owned by `root` and not `world` writable. Make sure this is the case.
=== Relative vs. absolute paths in the used libraries ===
If you see something like the following error when starting !VirtualBox you need to change the used libraries to use absolute paths.
{{{
VirtualBox: supR3HardenedMainGetTrustedMain: dlopen("/Applications/VirtualBox.app/Contents/MacOS/VirtualBox.dylib",) failed: \
 dlopen(/Applications/VirtualBox.app/Contents/MacOS/VirtualBox.dylib, 10): Library not loaded: QtCore.framework/Versions/4/QtCore
  Referenced from: /Applications/VirtualBox.app/Contents/MacOS/VirtualBox.dylib
  Reason: unsafe use of relative rpath QtCore.framework/Versions/4/QtCore in /Applications/VirtualBox.app/Contents/MacOS/VirtualBox.dylib with restricted binary
}}}
On Mac OS X it isn't allowed to use libraries with relative paths for referencing to other libraries when the executable is setuid. You can display all linked libraries by the following command:
{{{
otool -L /Applications/VirtualBox.app/Contents/MacOS/VirtualBox.dylib
}}}
Next, assuming Qt is installed in `/Applications/VirtualBox.app/Contents/Frameworks/`, you can change the path by using this:
{{{
install_name_tool -id /Applications/VirtualBox.app/Contents/Frameworks/QtGui.framework/Versions/4/QtGui \
 /Applications/VirtualBox.app/Contents/Frameworks/QtGui.framework/Versions/4/QtGui
install_name_tool -change @executable_path/../Frameworks/QtCore.framework/Versions/4/QtCore \
 /Applications/VirtualBox.app/Contents/Frameworks/QtCore.framework/Versions/4/QtCore \
 /Applications/VirtualBox.app/Contents/Frameworks/QtGui.framework/Versions/4/QtGui
}}}
The first command changes the identifier of the library itself. The second changes references to other libraries. There, the first path is the old referenced path, the second one is the new path and the last path is the file to change (see `man install_name_tool`). Note, you need to repeat this with every library involved (at least `VirtualBox.dylib`, `QtCore`, `QtGui`, `QtNetwork`, `QtOpenGl`).