Repository navigation
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.
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.
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.
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| 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.
| Variable | Description |
|---|---|
VBOX_BLD_PYTHON |
Full path to the Python interpreter used by the build system. |
Example:
VBOX_BLD_PYTHON = C:/Python313/python.exe| 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 = MyVirtualBoxCertWarning
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.
| 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.
| Variable | Description |
|---|---|
VBOX_JAVA_HOME |
The JDK Home installation directory |
| 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.
| 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. |
| Variable | Description |
|---|---|
VBOX_WIX_PATH |
Directory containing the WiX Toolset executables. |
Example:
VBOX_WIX_PATH = C:/Program Files (x86)/WiX Toolset/binUse the WiX version required by the project's build scripts.
| 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.exeMake sure the executable names match the files actually installed.
| 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.xxxxxThe configured version must correspond to the MSVC toolset installed on the system.
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~2This is because kmk or some build scripts may encounter issues when handling paths containing spaces, potentially causing the build process to fail.
| 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. |
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.
After configuring LocalConfig.kmk, proceed to: