Skip to content

Building VirtualBox

Sorecchione07435 edited this page Nov 8, 2026 · 11 revisions

Building from Source

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:

1. Prepare the build environment

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.kmk file 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.

2. Configure PowerShell environment variables

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:PATH

Adjust these paths to match your local source tree and kBuild installation.

You can verify that KMK is accessible with:

Get-Command kmk.exe

3. Navigate to the VirtualBox source directory

Change the current directory to the root of your VirtualBox source tree.

cd C:\Dev\virtualbox

Make sure you are running the command from the correct source directory.

4. Apply the required source modifications

Before compiling VirtualBox, two modifications must be applied to the VNC extension source files.

4.1. Modify VBoxVNC.cpp

Open the following file:

virtualbox\src\VBox\ExtPacks\VNC\VBoxVNC.cpp

Add the following header includes at the beginning of the file, alongside the other system headers:

#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.

4.2. Modify Makefile.kmk

Open the following file:

virtualbox\src\VBox\ExtPacks\VNC\Makefile.kmk

Locate the existing definitions of the following variables:

  • VBoxVNC_INCS
  • VBoxVNC_LIBS
  • VBoxVNC_DEFS

Replace their existing definitions with the following lines:

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.

4.3. Verify the modifications

Before proceeding, verify that:

  1. VBoxVNC.cpp contains all three Windows headers in the correct order.
  2. Makefile.kmk contains the updated definitions, replacing the previous ones.
  3. The include directory points to the compiled LibVNCServer headers.
  4. The library path points to the actual compiled vncserver.lib file.
  5. ws2_32.lib is included in the linker dependencies.

Once both files have been modified and saved, proceed with the VirtualBox compilation.

5. Install the Mako Python package

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 Mako

To verify that the package is installed correctly, run:

python -m pip show Mako

Make sure that Mako is installed in the same Python environment used by the VirtualBox build system.

6. Start the compilation

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 8

This starts the VirtualBox build with up to eight parallel jobs.

KMK command-line options

Option Description
-k Continue building other targets when an error occurs, where possible.
-j 8 Run up to eight build jobs in parallel.

Adjusting the number of parallel jobs

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 12

You 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.

7. Check the build result

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.

Additional notes

  • 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.

Clone this wiki locally