Repository navigation
Building VirtualBox
This guide explains how to compile the custom VNC-enabled VirtualBox build on Windows using Microsoft Visual Studio 2022, KMK, and PowerShell.
Before starting, make sure you have completed the steps described in:
Make sure the required build tools and dependencies are installed and configured.
In particular, verify that:
- Visual Studio 2022 and the required C++ components are installed.
- The Windows SDK and WDK are available.
- Python, Qt, Yasm/NASM, and the other required tools are configured.
- The
LocalConfig.kmkfile contains the correct paths and build options. - The libvncserver dependency is available if required by your source configuration.
It is recommended to start PowerShell from the Visual Studio 2022 x64 Native Tools environment, so that the appropriate MSVC compiler and linker tools are available.
Set the kBuild directory and add its executable directory to the PATH environment variable.
Example:
$env:KBUILD_PATH = "C:\Dev\virtualbox\kBuild\kBuild"
$env:PATH = "C:\Dev\virtualbox\kBuild\kBuild\bin\win.amd64;" + $env:PATHAdjust these paths to match your local source tree and kBuild installation.
You can verify that KMK is accessible with:
Get-Command kmk.exeChange the current directory to the root of your VirtualBox source tree.
cd C:\Dev\virtualboxMake sure you are running the command from the correct source directory.
Before compiling VirtualBox, two modifications must be applied to the VNC extension source files.
Open the following file:
text
virtualbox\src\VBox\ExtPacks\VNC\VBoxVNC.cpp
Add the following header includes at the beginning of the file, alongside the other system headers:
cpp
#include <winsock2.h>
#include <ws2tcpip.h>
#include <windows.h>Important: Make sure that winsock2.h is included before windows.h to avoid conflicts with legacy Winsock definitions.
These headers provide the Windows API and Winsock declarations required by the VNC implementation.
Save the modified file before proceeding.
Open the following file:
text
virtualbox\src\VBox\ExtPacks\VNC\Makefile.kmk
Locate the existing definitions of the following variables:
VBoxVNC_INCSVBoxVNC_LIBSVBoxVNC_DEFS
Replace their existing definitions with the following lines:
makefile
VBoxVNC_INCS = VNCBuild/install/include
VBoxVNC_LIBS = VNCBuild/install/lib/vncserver.lib ws2_32.lib
VBoxVNC_DEFS =Important: The path VNCBuild/install/lib/vncserver.lib is an example relative path. Make sure it points to the actual location of the vncserver.lib library generated during the previous LibVNCServer compilation.
If LibVNCServer was installed in a different directory, update both the include and library paths accordingly.
The ws2_32.lib entry links the Windows Winsock library, which is required for network communication.
Save the modified Makefile.kmk before proceeding with the VirtualBox compilation.
Before proceeding, verify that:
-
VBoxVNC.cppcontains all three Windows headers in the correct order. -
Makefile.kmkcontains the updated definitions, replacing the previous ones. - The include directory points to the compiled LibVNCServer headers.
- The library path points to the actual compiled
vncserver.libfile. -
ws2_32.libis included in the linker dependencies.
Once both files have been modified and saved, proceed with the VirtualBox compilation.
The VirtualBox build system requires Mako, a Python-based template engine used during the source generation and compilation process.
Install Mako in your local system Python environment using PowerShell:
python -m pip install MakoTo verify that the package is installed correctly, run:
python -m pip show MakoMake sure that Mako is installed in the same Python environment used by the VirtualBox build system.
Once the environment is configured, the source modifications have been applied, and Mako is installed, you can start compiling VirtualBox.
Run KMK using the following command:
kmk.exe -k -j 8This starts the VirtualBox build with up to eight parallel jobs.
| Option | Description |
|---|---|
-k |
Continue building other targets when an error occurs, where possible. |
-j 8 |
Run up to eight build jobs in parallel. |
The number after -j can be changed according to your system's available CPU and memory resources.
For example, to use 12 parallel jobs:
kmk.exe -k -j 12You can increase or decrease this value depending on your hardware and available memory.
Note: The -j value specifies the number of parallel build jobs, not the number of physical CPU cores. Using more jobs can improve compilation speed, but also increases CPU and memory usage.
Wait for KMK to finish compiling the requested targets.
If the build completes successfully, the generated binaries and VNC Extension Pack will be available in the corresponding build output directories.
If compilation fails, review the error messages in the PowerShell output and check the relevant configuration, dependencies, and toolchain versions.
For known problems and possible workarounds, see Common Issues.
- The environment variables configured with
$env:apply only to the current PowerShell session. - If you open a new PowerShell window, you must configure them again.
- Make sure all required Python packages are installed in the Python environment used by the build system.
- Do not distribute your private code-signing certificate or private key.
- This is an unofficial custom build of VirtualBox and is not supported or endorsed by Oracle.