= Windows build instructions = As !VirtualBox is a cross platform project, we use a cross platform build system meaning that there won't be any Visual C++ project files that you can open and just build. Instead, you have to follow these steps but they aren't overly difficult. == Prerequisites == * '''Windows 10 x64''' or '''Windows 8.1 x64'''.[[BR]] Older versions of Windows might work. * '''Visual Studio 2010 with service pack 1''' (for trunk: '''Visual Studio 2019 Version 16.11''').[[BR]] ''Use `--with-vc=` to specify the path for configure.vbs.'' * '''Windows Platform SDK v7.1''' (just for building !VirtualBox 6.1.x). [[BR]] http://www.microsoft.com/en-us/download/details.aspx?id=8279 [[BR]] ''Use `--with-sdk=` to specify the path for configure.vbs.'' * '''Windows SDK 11 and WDK 11''' (just for building trunk). [[BR]] https://go.microsoft.com/fwlink/?linkid=2166460 and https://go.microsoft.com/fwlink/?linkid=2166289, see also https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk [[BR]] ''Use `--with-sdk10=` to specify the path for configure.vbs.'' * '''Windows Driver Development Kit (WDK) v7.1''' (needed primarily for building Guest Additions). [[BR]] http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=11800 [[BR]] ''Use `--with-ddk=` to specify the path for configure.vbs.'' * '''Qt v5.6.x or later''' [[BR]] Note! This has to be built with the Visual C++ compiler mentioned above. [[BR]] ''Use `--with-qt5=` to specify the path for configure.vbs.'' * '''SDL v1.2.7 or later''' development package (VC6): [[BR]]http://www.libsdl.org/download-1.2.php [[BR]] ''Use `--with-libsdl=` to specify the path for configure.vbs.'' [[BR]] ''Use `--disable-sdl` as parameter for configure.vbs to disable the SDL frontend and to remove the dependency to SDL.'' * the '''cURL''' library. Grab the binaries from: [[BR]] http://curl.haxx.se/download.html [[BR]] (use the devel version ''without'' SSL support) [[BR]] ''Use `--with-libcurl=` to specify the path for configure.vbs. For building the 64-bit target you need to add `--with-libcurl32=` to specify the path to the 32-bit cURL development package as both cURL variants (32-bit and 64-bit) are required then.'' * '''Yasm 1.3''', needed to build assembly code files. Grab the binaries from: [[BR]] https://yasm.tortall.net/Download.html [[BR]] ''You're all set if yasm.exe is found in PATH.'' * '''Python 2.7.x''', needed to build Python API bindings, both webservice and COM. Also required to build the 3D support. Grab the binaries from: [[BR]] http://www.python.org/download/releases/2.7.10/ [[BR]] ''Use `--with-python=` to specify the path for configure.vbs.'' * '''code signing utilities'''. [[BR]] Normally part of the WDK: `certmgr.exe`, `makecert.exe`, `signtool.exe` and so on.[[BR]] ''Use ''`VBOX_PATH_SIGN_TOOLS=\path\to\signtool.exe`'' in `LocalConfig.kmk` to set the path to `signtool.exe` tool.''[[BR]] ''Use ''`VBOX_INF2CAT=\path\to\inf2cat.exe`'' in `LocalConfig.kmk` to set the path to the `inf2cat.exe` tool.'' * ''Optional:'' '''NSIS 3.x''', only needed if you want to build the Guest Additions including the installer. Required plugins: `AccessControl`, `NsProcess`. Grab the sources or setup from: [[BR]] https://nsis.sourceforge.io/Download [[BR]] ''Use ''`VBOX_PATH_NSIS=`'' in `LocalConfig.kmk` to set the path to this package.'' * ''Optional:'' '''gSOAP 2.8.x''', only needed if you want to build the webservice API server. Grab the sources from: [[BR]] http://sourceforge.net/projects/gsoap2/files/gSOAP/gSOAP%202.8.72%20stable/ [[BR]] ''Add ''`VBOX_PATH_GSOAP=\path\to\gsoap-VERSION\gsoap`'' and ''`VBOX_GSOAP_INSTALLED=1`'' to your `LocalConfig.kmk` file (no autodetection from configure.vbs).''[[BR]] ''Add ''`VBOX_WITH_WEBSERVICES=`'' to `LocalConfig.kmk` to disable building + packing the webservice API server.'' * ''Optional:'' '''Java SE 6 JDK''', only needed if you want to build Java API bindings, both webservice and COM. Grab the binaries from: [[BR]] http://www.oracle.com/technetwork/java/javase/downloads/index.html * ''Optional:'' '''AutoIt v3 3.2.10''', only needed if you want to package the Guest Additions. Grab the binaries from: [[BR]] https://www.autoitscript.com/site/autoit/ [[BR]] ''Use ''`VBOX_PATH_AUTOIT3=\path\to\autoit3`'' in `LocalConfig.kmk` to set the path to this package. `PATH` should contain the Aut2Exe directory.'' * ''Optional:'' '''Driver Install Frameworks (DIFx) 2.1''', only needed if you want to package the Guest Additions. See[[BR]] https://support.microsoft.com/en-us/help/910189/information-about-updates-for-driver-install-frameworks-difx-tools [[BR]] ''Use ''`VBOX_PATH_DIFX=\path\to\DIFx`'' in `LocalConfig.kmk` to set the path to this package.'' * ''Optional:'' '''`mkisofs.exe`''', only needed if you want to package the Guest Additions. Grab the package from[[BR]] http://opensourcepack.blogspot.de/p/cdrtools.html [[BR]] ''Use ''`VBOX_MKISOFS=\path\to\mkisofs.exe`'' in `LocalConfig.kmk` to set the path to the `mkisofs.exe` binary.'' * ''Optional:'' '''`zip.exe`''', only needed if you want to package the Validation Kit (disable with `VBOX_WITH_VALIDATIONKIT=` in `LocalConfig.kmk`). Grab the package from[[BR]] http://gnuwin32.sourceforge.net/packages/zip.htm [[BR]] ''Use ''`VBOX_ZIP=\path\to\zip.exe`'' in `LocalConfig.kmk` to set the path to the `zip.exe` binary.'' * ''Optional:'' '''WIX toolset 3.8.1128''', only needed if you want to package !VirtualBox. Grab the binaries from [[BR]] http://wixtoolset.org/releases/ [[BR]] ''Use ''`VBOX_WIX_PATH=\path\to\WIX`'' in `LocalConfig.kmk` to set the path to this package.'' * ''Optional:'' '''WiSumInf.vbs SDK script''', only needed if you want to package !VirtualBox. The required script is[[BR]] `sdk-v7.1\Samples\sysmgmt\msi\scripts\WiSumInf.vbs` (see SDK 7.1 prerequisite above) [[BR]] ''Use ''`VBOX_PATH_WISUMINFO=\path\to\WiSumInf.vbs`'' in `LocalConfig.kmk` to set the path to this script.'' === Using other versions of libraries shipped with the VBox sources === * the '''libxml2''' library. Sources and 32bit binaries can be downloaded from: [[BR]] http://xmlsoft.org/downloads.html [[BR]] ''Use `--with-libxml2=` to specify the path for configure.vbs.'' * '''OpenSSL 1.1.1''' or later. Grab the binaries from: [[BR]] https://slproweb.com/products/Win32OpenSSL.html [[BR]] ''Use `--with-openssl=` to specify the path for configure.vbs. For building the 64-bit target you need to add `--with-openssl32=` to specify the path to the 32-bit OpenSSL development package as both OpenSSL variants (32-bit and 64-bit) are required then.'' * the '''zlib''' library. Grab the sources from: [[BR]] http://www.zlib.net/ [[BR]] Actually the tarball includes `zlib` in the '`src\libs`' directory so downloading this library is only necessary if you need a more recent version. In that case look for `SDK_VBOX_ZLIB_INCS` and `SDK_VBOX_ZLIB_LIBS` in `Config.kmk` and override these entries in your `LocalConfig.kmk` accordingly. See [#LocalConfig below] for some notes about using `LocalConfig.kmk` to override the default build configuration). === Manual compilation of certain prerequisites === If you don't find development packages of certain prerequisites it's also possible to manually compile them. For instance, there does not seem to be proper `libcurl` packages avaible for Windows which contain `libcurl.lib`, `libcurl.dll' files and the '`include`' directory. To manually build the cURL devel package on Windows you have to 1. Take care that the compiler binary path is part of the '''`PATH`''' environment variable, usually the '`bin`' directory of the installation directory. That directory has to contain `cl.exe`, `link.exe`, `lib.exe`, `nmake.exe` etc. Take care to specify the correct architecture path (amd64 or x86). 2. Set the '''`INCLUDE`''' environment variable to include the compilers '`atlmfc\include`' (ATL/MFC) and '`include`' directories. 3. Set the '''`LIB`''' environment variable to include the compilers '`atlmfc\lib`' (ATL/MFC) and '`lib`' directories. Take care to specify the correct architecture path (amd64 or x86). 4. Set the '''`LIBPATH`''' environment variable to include the compilers '`atlmfc\lib`' (ATL/MFC) directory. Take care to specify the correct architecture path (amd64 or x86). 5. Set the '''`PATH`''' environment variable to include the (7.1) SDK '`bin`' directory. Take care to point to the correct architecture path (amd64 or x86). 6. Set the '''`INCLUDE`''' environment variable to include the (7.1) SDK '`include`' directory. 7. Set the '''`LIB`''' environment variable to include the (7.1) SDK '`lib`' directory. Take care to specify the correct architecture path (amd64 or x86). After all these environment variables are set up, go to the '`curl-VERSION\winbuild`' directory and perform {{{ nmake /f Makefile.vc mode=dll VC=10 MACHINE=x64 or nmake /f Makefile.vc mode=dll VC=10 MACHINE=x86 }}} The resulting package can be found in the '`builds\libcurl-vc10-*-winssl`' directory. The configure.vbs script expects that libcurl.lib and libcurl.dll are located next to the '`include`' directory. It's a good idea to copy the '`libcurl-vc10-*-winssl`' directory to another place. Then use the `--with-libcurl=` parameter to specify the path for configure.vbs. == Building !VirtualBox == 1. Change to the root directory and execute our configure script to setup your build environment: {{{ cscript configure.vbs }}} If the script finds all the tools necessary, it will output two files: '''`AutoConfig.kmk`''' containing information where to find the tools on your system and '''`env.bat`''', a batch file to setup your environment for building !VirtualBox. You only have to execute this step once, unless something about your tools changes in which case you have to repeat the above step. Keep in mind that the script always overwrites the two generated files so you should not manually edit them. The '''default target''' will be the same target as the host, that is, on a 32-bit host the environment will be set up to compile the 32-bit !VirtualBox target (`x86`) while on a 64-bit host the environment will be set up to compile the 64-bit !VirtualBox target (`amd64`). The default setting can be overridden by using the `--target-arch=` parameter. 2. Change to the root directory of the sources and enter our build shell environment: `env.bat`. 3. To manually override any tool or change `Config.kmk` settings, create `LocalConfig.kmk` in the root directory of the sources and place the setting there. See [#LocalConfig below] for an incomplete list of possible settings. 4. To build a release package, type `kmk`. This produces the binaries in `out\win.x86\release\bin` (or `out\win.amd64\release\bin` on 64-bit hosts). If you want to build a debug version, enter `kmk KBUILD_TYPE=debug`. 5. To create an `.msi` package, type `kmk packing'.[[BR]] This step will fail for a 64-bit (`amd64`) target if the Guest Additions are part of the build process (which is the default, disable by adding `VBOX_WITH_ADDITIONS=` and `VBOX_WITH_ADDITIONS_PACKING=` to `LocalConfig.kmk`, see [#LocalConfig below]). It will complain about a dependency to `VBoxOGL*` libraries in `out\win.x86\release\bin\additions`. In that case, create the 32-bit Guest Additions by executing {{{ kmk VBOX_ONLY_ADDITIONS=1 KBUILD_TARGET_ARCH=x86 }}} After that, type `kmk packing` again and it should succeed. === Using Visual C++ 2010 Express === If you don't have a Visual C++ license you can use [http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express Visual C++ 2010 Express]. However, you will not be able to build any frontend because the !VirtualBox COM API - which all the other front ends program against - requires the Active Template Library (ATL) to build, and unfortunately the express edition doesn't include this (see http://msdn.microsoft.com/vstudio/express/support/faq/#vcpp). When doing the first build step, you have to add --with-VC-Express-Edition to the argument list: {{{ cscript configure.vbs --with-VC-Express-Edition }}} === Excluding certain features from building === #LocalConfig Here is an incomplete list of settings which could be added to '''`LocalConfig.kmk`''' to prevent certain features from building / packing: VBOX_WITH_ADDITIONS=:: VBOX_WITH_ADDITIONS_PACKING=:: Don't build + package the !VirtualBox Guest Additions. If only `VBOX_WITH_ADDITIONS=` is specified then the Guest Additions are not built but the `VBoxGuestAdditions.iso` file is expected to be present in the '`out\win.ARCH\release\bin\additions`' directory. VBOX_ONLY_ADDITIONS=1:: Build the Guest Additions exclusively. VBOX_WITH_VALIDATIONKIT=:: Don't build + package the !VirtualBox validation kit. The validation kit is not part of the final `.msi` package anyway. VBOX_WITH_WEBSERVICES=:: Don't build + package the webservices API server. VBOX_WITHOUT_HARDENING=1:: Disable Windows hardening. Useful for testing. Do '''not''' use this setting for production builds! Without hardening the binaries are not signed and !VirtualBox.exe can be started straight away from the out\...\bin directory (`kmk packing` + installation not required).[[BR]] Please note that it's still necessary to enable [#CodeSigning code signing] to be able to start VMs as Windows refuses to load unsigned kernel drivers. === Setting up self signing (64-bit Windows, 32-bit Windows 10)=== #CodeSigning Setting up test signing will allow to build signed binaries to make Windows happy. To use the test-signed binaries, the target machine has to run in test signing mode and the test certificate has to be installed on the target machine. '''Part 1:''' creating and installing the test certificate 1. Launch an elevated command line shell (Vista and later). 1. {{{makecert.exe -r -pe -ss my -eku 1.3.6.1.5.5.7.3.3 -n "CN=MyTestCertificate" mytestcert.cer}}} 1. {{{certmgr.exe -add mytestcert.cer -s -r localMachine root}}} 1. Start certmgr.exe and check that "!MyTestCertificate" is listed both under "Personal" and "Trusted Root Certification Authorities".[[BR]] ''If you have a self-signed certificate installed and upgrade to Windows 10 it might happen that the certificate is still listed under "Trusted Root Certification Authorities" but not under "Personal" anymore. In that case, remove the old certificate using certmgr.msc and create a new certificate (see above) and install it.'' 1. Keep the mytestcert.cer file in a safe place. '''Part 2:''' configuring the system to run test signed code (Vista and later) 1. Launch an elevated command line shell (Vista and later). 1. Run {{{Bcdedit.exe -set TESTSIGNING ON}}} on an elevated cmd.exe prompt. 1. {{{certmgr.exe -add mytestcert.cer -s -r localMachine root}}} 1. {{{certmgr.exe -add mytestcert.cer -s -r localMachine trustedpublisher}}} 1. Reboot. 1. Vista and later: "Test Mode" will appear in all four corners of the desktop and "Microsoft (R) Windows (R) (Build 6000)" will appear on the top. Windows 7 and later: "Test ModeWindows 7Build 7600" or equivalent will appear in the lower right corner. '''Part 3:''' building !VirtualBox with signing enabled 1. If you called the certificate something other than !MyTestCertificate you'll have make the appropriate overrides in `LocalConfig.kmk`. See the `Code Signing` section of `Config.kmk` for what can be overridden. 1. Add `VBOX_SIGNING_MODE=test` to `LocalConfig.kmk`. 1. Build (incremental is sufficient). == Running !VirtualBox == !VirtualBox requires devices drivers and COM classes to operate. Whenever these change, you will have to re-register them. In order to re-register the COM classes, execute {{{ comregister.cmd }}} which can be found in the output directory (`out\win.ARCH\release\bin`). Note that for this to work, `VBoxSVC.exe` must not be running, so use the Windows task manager to verify this. Usually `VBoxSVC.exe` terminates automatically after 5 seconds of inactivity (i.e. no client connection) but especially when developing, it might sometimes stay around. In case the COM classes change (this usually happens when the file `VirtualBox.xidl` is updated) and you forget to re-register the classes, weird problems may appear. Before you can start any binary from the output directory you have to make sure that external libraries (for example `libcurl.dll` or `libcrypto.dll`) are located in a directory which is accessible by the `PATH` variable or by copying these libraries to the output directory. In order to (re-)install the !VirtualBox kernel drivers ('''drivers have to be signed'''), issue the following: {{{ loadall.cmd }}} Starting !VirtualBox is accomplished by invoking one of its frontends, such as {{{ VirtualBox.exe }}} or {{{ VBoxHeadless.exe }}} == Frequently Asked Questions == I specified a prerequisite with `--with-xyz=PATH` but `configure.vbs` is unable to find it.:: Look at the `configure.log` file. The directory layout might be unexpected. For example the `OpenSSL` package should contain two directories, the '`lib`' directory which contains `libssl.lib` and `libcrypto.lib` and the '`include`' directory. Build stops immediately with ''!***You need to enable code signing for a hardened windows build to work''.:: The message is clear: Code signing must work as Windows will only work with properly signed drivers. If [#CodeSigning code signing] is not properly set up then a temporary workaround for testing is to add '''`VBOX_WITHOUT_HARDENING=1`''' to your `LocalConfig.kmk`. Never use this setting for production environments! Enabling code signing is still required to start VMs, see [#CodeSigning above]. Typing `kmk` raises a message box ''The application was unable to start correctly (0xc0000022). Click OK to close the application.'':: Error code `0xc0000022` means `STATUS_ACCESS_DENIED`. Most likely the `kmk.exe` binary or a DLL (e.g. kBuild\bin\win.x86\msvcr100.dll or kBuild\bin\win.amd64\msvcr100.dll) have the execute bit unset. This happens if the .tar.bz2 archive is unpacked using Cygwin binaries. Solution: Set the execute bit on all `.exe` and `.dll` files in the source tree. Of course the same applies to all `.exe` and `.dll` files in the prerequisites directories! How can I create the !VirtualBox.exe package similar to the one available on the official download page?:: This is controlled by adding `VBOX_WITH_COMBINED_PACKAGE=1`. Such a package combines two `.msi` packages: The 32-bit version and the 64-bit version.