Skip to content

Build Configuration Examples

Sorecchione07435 edited this page Nov 8, 2026 · 12 revisions

Build Configuration Examples

This page provides example configurations for building the VNC-enabled VirtualBox version on Windows.

The build system uses a LocalConfig.kmk file to locate the required compilers, SDKs, libraries and development tools.

1. Overview

Before starting the build process, you must configure the paths to the tools installed on your system.

The configuration examples in this guide use the following environment:

  • Windows 10 / Windows 11 x64.
  • Microsoft Visual Studio 2022.
  • Windows SDK and WDK.
  • Qt 6 with MSVC 2022.
  • Python 3.
  • Additional VirtualBox build tools.

Important: The paths shown in this document are examples. Replace them with the actual installation paths on your computer.

2. Creating LocalConfig.kmk

Create a LocalConfig.kmk file using the provided example configuration:

build/LocalConfig.kmk.example

Copy the example and edit the paths according to your environment.

Keep your personal configuration separate from the tracked example file. Do not commit machine-specific paths or private signing information to the repository.

3. Complete Configuration Example

The following example shows a configuration for the VNC-enabled Windows build.

# ============================================================
# VirtualBox Windows Build Configuration
# VNC-enabled custom build
# ============================================================

# Build configuration
VBOX_OSE = 1
VBOX_WITHOUT_HARDENING = 1

# VNC Extension Pack
VBOX_WITH_EXTPACK_VNC = 1

# Python
VBOX_BLD_PYTHON = C:/PATH/TO/PYTHON/python.exe

# Driver signing
VBOX_SIGNING_MODE = test
VBOX_CERTIFICATE_SUBJECT_NAME = MyVirtualBoxCert

# Disable warnings as errors
VBOX_WITH_WARNINGS_AS_ERRORS :=

# ============================================================
# Windows SDK / WDK
# ============================================================

VBOX_PATH_WIN_SDK_ROOT = C:/PATH/TO/WINDOWS/SDK
VBOX_PATH_WIN_SDK10_ROOT = C:/PATH/TO/WINDOWS/SDK

PATH_SDK_WINDDK71 = C:/PATH/TO/WINDDK

# ============================================================
# Qt 6
# ============================================================

VBOX_PATH_QT = C:/PATH/TO/Qt/6.x.x/msvc2022_64
PATH_SDK_QT6 = C:/PATH/TO/Qt/6.x.x/msvc2022_64
PATH_TOOL_QT6_BIN = C:/PATH/TO/Qt/6.x.x/msvc2022_64/bin

# ============================================================
# JDK 17
# ============================================================

VBOX_JAVA_HOME = C:/PATH/TO/JDK/HOME

# ============================================================
# Build tools
# ============================================================

KBUILD_DEVTOOLS = C:/PATH/TO/virtualbox/tools

PATH_TOOL_YASM = C:/PATH/TO/YASM
PATH_TOOL_NASM = C:/PATH/TO/NASM

PATH_TOOL_OPENWATCOM = C:/PATH/TO/WATCOM

# ============================================================
# WiX Toolset
# ============================================================

VBOX_WIX_PATH = C:/PATH/TO/WIX/bin

# ============================================================
# Flex / Bison
# ============================================================

TOOL_BISON_YACC = C:/PATH/TO/BISON/bison.exe
TOOL_FLEX_LEX = C:/PATH/TO/FLEX/flex.exe

# ============================================================
# Microsoft Visual C++ 2022
# ============================================================

PATH_TOOL_VCC143 = C:/PATH/TO/MSVC/14.xx.xxxxx

4. Configuration Variables

Build configuration

Variable Description
VBOX_OSE Enables the Open Source Edition build configuration.
VBOX_WITHOUT_HARDENING Disables VirtualBox hardening in this custom build.
VBOX_WITH_EXTPACK_VNC Enables the VNC Extension Pack build configuration.
VBOX_WITH_WARNINGS_AS_ERRORS Controls whether compiler warnings are treated as errors. An empty assignment disables this option in this configuration.

Note

Disabling hardening changes VirtualBox's security characteristics. This configuration is intended for this custom experimental build and should not be treated as a general recommendation.

Python

Variable Description
VBOX_BLD_PYTHON Full path to the Python interpreter used by the build system.

Example:

VBOX_BLD_PYTHON = C:/Python313/python.exe

Driver signing

Variable Description
VBOX_SIGNING_MODE Selects the driver signing mode used by the project's build configuration.
VBOX_CERTIFICATE_SUBJECT_NAME Specifies the certificate subject name expected by the signing configuration.

Example:

VBOX_SIGNING_MODE = test
VBOX_CERTIFICATE_SUBJECT_NAME = MyVirtualBoxCert

Warning

Official release signing requires an appropriate Microsoft-trusted code-signing certificate and compliance with Microsoft's driver signing requirements. Obtaining the necessary certificate and signing infrastructure may involve additional costs.

Since this project is a custom Open Source Edition (OSE) build, test signing is recommended instead of release signing.

Using test signing allows locally built drivers to be signed with a test certificate. However, Windows Test Mode must be enabled for Windows to load these test-signed drivers.

See Driver Signing Certificate for additional information.

Windows SDK / WDK

Variable Description
VBOX_PATH_WIN_SDK_ROOT Windows SDK installation directory.
VBOX_PATH_WIN_SDK10_ROOT Windows 10 SDK installation directory.
PATH_SDK_WINDDK71 Windows Driver Kit 7.1 installation directory.

Ensure that the installed SDK and WDK versions are compatible with the requirements of the source tree.

JDK 17

Variable Description
VBOX_JAVA_HOME The JDK Home installation directory

Qt 6

Variable Description
VBOX_PATH_QT Qt installation directory.
PATH_SDK_QT6 Qt 6 SDK directory.
PATH_TOOL_QT6_BIN Directory containing Qt executable tools.

Use the Qt package built for MSVC 2022 x64.

Build tools

Variable Description
KBUILD_DEVTOOLS Location of the VirtualBox build development tools.
PATH_TOOL_YASM Yasm installation directory.
PATH_TOOL_NASM NASM installation directory.
PATH_TOOL_OPENWATCOM Open Watcom installation directory.

WiX Toolset

Variable Description
VBOX_WIX_PATH Directory containing the WiX Toolset executables.

Example:

VBOX_WIX_PATH = C:/Program Files (x86)/WiX Toolset/bin

Use the WiX version required by the project's build scripts.

Flex / Bison

Variable Description
TOOL_BISON_YACC Full path to the Bison executable.
TOOL_FLEX_LEX Full path to the Flex executable.

Example:

TOOL_BISON_YACC = C:/Tools/WinFlexBison/bison.exe
TOOL_FLEX_LEX = C:/Tools/WinFlexBison/flex.exe

Make sure the executable names match the files actually installed.

Microsoft Visual C++ 2022

Variable Description
PATH_TOOL_VCC143 Location of the MSVC v143 compiler toolset.

Example:

PATH_TOOL_VCC143 = C:/Program Files/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/14.xx.xxxxx

The configured version must correspond to the MSVC toolset installed on the system.

5. Path Configuration Guidelines

When editing LocalConfig.kmk, keep the following recommendations in mind:

  • Use forward slashes (/) in Windows paths.
  • Replace every placeholder with an existing installation directory.
  • Avoid specifying directories that do not contain the expected executables or files.
  • Use absolute paths whenever possible.
  • Do not mix MSVC and MinGW Qt packages.
  • Make sure all configured tool versions are compatible with the project.

Warning

If any tools are installed in Program Files, Program Files (x86), or any other directory whose path contains spaces, it is recommended to use the corresponding 8.3 short path name, if available. This can be obtained using the dir /x command in Command Prompt.

A practical example:

From:

C:/Program Files (x86)

To:

C:/PROGRA~2

This is because kmk or some build scripts may encounter issues when handling paths containing spaces, potentially causing the build process to fail.

6. Common Configuration Issues

Problem Possible cause
Python not found Incorrect VBOX_BLD_PYTHON path.
Qt tools unavailable Incorrect Qt installation path or missing components.
MSVC compiler not found Incorrect PATH_TOOL_VCC143 configuration.
Yasm or NASM unavailable Incorrect assembler directory.
WiX tools unavailable Incorrect WiX installation path or incompatible version.
Flex/Bison errors Incorrect executable paths or filenames.
SDK/WDK errors Missing or incompatible SDK/WDK installation.
Driver signing errors Incorrect signing configuration or missing certificate setup.

7. Additional Build Configuration

Some build environments may require additional variables or modifications depending on the installed dependency versions.

Refer to the example configuration and the official VirtualBox build documentation before introducing additional settings.

8. Next Steps

After configuring LocalConfig.kmk, proceed to: