Build the eBPF for Windows solution or individual components using MSBuild.
When to Use
- User asks to build, compile, rebuild, or clean the project
- User asks to build a specific component (driver, library, tool, test, etc.)
- User asks to restore NuGet packages
- User asks to do a full or partial build with a specific configuration
- After making code changes that need to be compiled
Environment Requirements
- Visual Studio Developer PowerShell (required — regular PowerShell lacks build environment variables)
- MSBuild from VS Build Tools
- Must run from the solution root directory (
ebpf-for-windows.slnlocation)
Build Instructions
Step 1: Determine What to Build
Ask the user (or infer from context) what they want to build. Options:
- Full solution — build everything
- Specific component(s) — use the target map below to select
/t:targets - Restore only — just restore NuGet packages
Step 2: Determine Configuration and Platform
| Parameter | Options | Default |
|---|---|---|
| Configuration | Debug, Release, NativeOnlyDebug, NativeOnlyRelease, FuzzerDebug |
Debug |
| Platform | x64, ARM64 |
x64 |
If the user doesn't specify, use Debug and x64.
Step 3: Construct and Run the MSBuild Command
CRITICAL RULES:
- Always use the solution file:
msbuild ebpf-for-windows.sln— never build.vcxprojfiles directly - Always run from the solution root directory
- Use
/mfor parallel builds - For first-time or fresh builds, add
-Restoreto restore NuGet packages - For clean rebuilds, use
/t:"target:clean,target"syntax
Full Solution Build
# Standard build
msbuild ebpf-for-windows.sln /m /p:Configuration=Debug /p:Platform=x64
# With NuGet restore (first-time or after package changes)
msbuild ebpf-for-windows.sln /m /p:Configuration=Debug /p:Platform=x64 -Restore
# Clean the solution
msbuild ebpf-for-windows.sln /m /p:Configuration=Debug /p:Platform=x64 /t:clean
# With static analysis
msbuild ebpf-for-windows.sln /m /p:Configuration=Release /p:Platform=x64 /p:Analysis=True
Targeted Component Build
# Single target
msbuild ebpf-for-windows.sln /m /p:Configuration=Debug /p:Platform=x64 /t:drivers\EbpfCore
# Multiple targets
msbuild ebpf-for-windows.sln /m /p:Configuration=Debug /p:Platform=x64 /t:"drivers\EbpfCore,drivers\netebpfext,tests\unit_tests"
# Clean + rebuild a target (use semicolon or comma separator)
msbuild ebpf-for-windows.sln /m /p:Configuration=Debug /p:Platform=x64 /t:"tools\bpf2c:Clean;tools\bpf2c"
Step 4: Analyze Results
- If the build succeeds, report success with the output path (e.g.,
x64\Debug\) - If the build fails, show the first error(s) and suggest fixes
- Common issues:
- Missing NuGet packages → suggest adding
-Restore - Missing environment → suggest using Visual Studio Developer PowerShell
- Header/linker errors → suggest checking dependencies and rebuilding prerequisite targets
- Missing NuGet packages → suggest adding
MSBuild Target Map
Use this map to translate component names to MSBuild /t: targets.
Solution targets use solution folder paths, not filesystem paths.
Drivers (Kernel Components)
| Component | Target | Source |
|---|---|---|
| EbpfCore (kernel execution context) | drivers\EbpfCore |
ebpfcore/ |
| EbpfCore_Usersim (usersim variant) | drivers\EbpfCore_Usersim |
ebpfcore/usersim/ |
| netebpfext (WFP network hooks) | drivers\netebpfext |
netebpfext/sys/ |
| sample_ebpf_ext (sample extension) | undocked\drivers\sample_ebpf_ext |
undocked/tests/sample/ext/drv/ |
DLLs and Services (User-Mode)
| Component | Target | Source |
|---|---|---|
| EbpfApi (libbpf-compatible API) | dlls\EbpfApi |
ebpfapi/ |
| eBPFSvc (JIT/verification service) | service\ebpfsvc |
ebpfsvc/ |
| ebpfnetsh (netsh plugin) | dlls\ebpfnetsh |
tools/netsh/ |
Libraries
| Component | Target | Source |
|---|---|---|
| API library | libs\user\api |
libs/api/ |
| Service library | libs\user\service |
libs/service/ |
| Execution context (kernel) | libs\kernel\execution_context_kernel |
libs/execution_context/kernel/ |
| Execution context (user) | libs\user\execution_context_user |
libs/execution_context/user/ |
| uBPF (kernel) | libs\kernel\ubpf_kernel |
libs/ubpf/kernel/ |
| uBPF (user) | libs\user\ubpf_user |
libs/ubpf/user/ |
| Runtime (kernel) | libs\kernel\runtime_kernel |
libs/runtime/kernel/ |
| Runtime (user) | libs\user\runtime_user |
libs/runtime/user/ |
| API common | libs\user\api_common |
libs/api_common/ |
| Shared (kernel) | libs\kernel\shared_kernel |
libs/shared/kernel/ |
| Shared (user) | libs\user\shared_user |
libs/shared/user/ |
| PE parse | libs\user\pe-parse |
libs/pe-parse/ |
| ELF spec | libs\user\elf_spec |
libs/elf_spec/ |
| Store helper | libs\user\ebpf_store_helper |
libs/store_helper/user/ |
| Netsh static | libs\user\netsh_static |
libs/ebpfnetsh/ |
| PREVAIL verifier | libs\user\prevail |
external/ebpf-verifier/build/ |
| libbtf | libs\user\libbtf |
external/ebpf-verifier/build/external/libbtf/ |
| netebpfext (user) | libs\user\netebpfext_user |
netebpfext/user/ |
| cxplat (kernel) | libs\kernel\cxplat_winkernel |
external/usersim/cxplat/ |
| cxplat (user) | libs\user\cxplat_winuser |
external/usersim/cxplat/ |
| usersim | libs\user\usersim |
external/usersim/src/ |
| usersim_dll_skeleton | libs\user\usersim_dll_skeleton |
external/usersim/usersim_dll_skeleton/ |
Tools
| Component | Target | Source |
|---|---|---|
| bpf2c (native code generator) | tools\bpf2c |
tools/bpf2c/ |
| bpftool | tools\bpftool |
tools/bpftool/ |
| export_program_info | tools\export_program_info |
tools/export_program_info/ |
| dnsflood | tools\dnsflood |
tools/dnsflood/ |
| port_quota | tools\port_quota |
tools/port_quota/ |
| port_leak | tools\port_leak |
tools/port_leak/ |
| Setup build | tools\setup_build |
scripts/setup_build/ |
| OneBranch | tools\onebranch |
tools/onebranch/ |
| export_program_info_sample | undocked\tools\export_program_info_sample |
undocked/tools/export_program_info_sample/ |
Tests
| Component | Target | Source |
|---|---|---|
| API tests | tests\api_test |
tests/api_test/ |
| Unit tests | tests\unit_tests |
tests/unit/ |
| bpf2c tests | tests\bpf2c_tests |
tests/bpf2c_tests/ |
| Performance tests | tests\performance |
tests/performance/ |
| Socket tests | tests\socket_tests |
tests/socket/ |
| Cilium tests | tests\cilium_tests |
tests/cilium/ |
| Connect redirect tests | tests\connect_redirect_tests |
tests/connect_redirect/ |
| Common tests | tests\common_tests |
tests/libs/common/ |
| netebpfext unit tests | tests\netebpfext_unit |
tests/netebpfext_unit/ |
| Sample programs | tests\sample |
tests/sample/ |
| bpftool tests | installer\bpftool_tests |
tests/bpftool_tests/ |
| bpf2c plugin | tests\bpf2c_plugin |
tests/bpf2c_plugin/ |
| Test utilities | tests\test_util |
tests/libs/util/ |
| Sample ext app | tests\sample_ext_app |
tests/sample/ext/app/ |
| TCP/UDP listener | tests\tcp_udp_listener |
tests/tcp_udp_listener/ |
| export_program_info test | tests\export_program_info_test |
tests/export_program_info_test/ |
| Restart test controller | tests\ebpf_restart_test_controller |
tests/stress/restart_test_controller/ |
| Restart test helper | tests\ebpf_restart_test_helper |
tests/stress/restart_test_helper/ |
Stress Tests and Fuzzers
Stress tests build in Debug/Release. Fuzzers require FuzzerDebug configuration.
| Component | Target | Config | Source |
|---|---|---|---|
| Stress tests (user-mode) | tests\ebpf_stress_tests_um |
Debug | tests/stress/um/ |
| Stress tests (kernel-mode) | tests\ebpf_stress_tests_km |
Debug | tests/stress/km/ |
| Execution context fuzzer | tests\libfuzzer\execution_context_fuzzer |
FuzzerDebug | tests/libfuzzer/execution_context/ |
| bpf2c fuzzer | tests\libfuzzer\bpf2c_fuzzer |
FuzzerDebug | tests/libfuzzer/bpf2c_fuzzer/ |
| Verifier fuzzer | tests\libfuzzer\verifier_fuzzer |
FuzzerDebug | tests/libfuzzer/verifier_fuzzer/ |
| Core helper fuzzer | tests\libfuzzer\core_helper_fuzzer |
FuzzerDebug | tests/libfuzzer/core_helper_fuzzer/ |
| netebpfext fuzzer | tests\libfuzzer\netebpfext_fuzzer |
FuzzerDebug | tests/libfuzzer/netebpfext_fuzzer/ |
External Dependencies
| Component | Target | Source |
|---|---|---|
| Catch2 | tests\Catch2 |
external/Catch2/ |
| Catch2WithMain | tests\Catch2WithMain |
external/Catch2/ |
Note: The PREVAIL verifier for normal builds is
libs\user\prevail. Theubpf_fuzzer\*targets (ebpfverifier, ubpf, libbtf, win-c, ubpf_fuzzer, ubpf_fuzzer_post_build) are only built inFuzzerDebugconfiguration and will fail with MSB4057 errors in Debug/Release.
ubpf_fuzzer Targets (FuzzerDebug Only)
These targets only build in FuzzerDebug configuration:
| Component | Target | Source |
|---|---|---|
| ebpfverifier (fuzzer copy) | ubpf_fuzzer\ebpfverifier |
external/ubpf/build_fuzzer/external/ebpf-verifier/ |
| ubpf (fuzzer copy) | ubpf_fuzzer\ubpf |
external/ubpf/build_fuzzer/vm/ |
| ubpf_fuzzer | ubpf_fuzzer\ubpf_fuzzer |
external/ubpf/build_fuzzer/libfuzzer/ |
| libbtf (fuzzer copy) | ubpf_fuzzer\libbtf |
external/ubpf/build_fuzzer/.../libbtf/ |
| win-c (fuzzer copy) | ubpf_fuzzer\win-c |
external/ubpf/build_fuzzer/.../win-c/ |
| ubpf_fuzzer_post_build | ubpf_fuzzer\ubpf_fuzzer_post_build |
scripts/ubpf_fuzzer_post_build/ |
Build Utilities and Installers
| Component | Target | Config Notes | Source |
|---|---|---|---|
| RPC interface | idl\rpc_interface |
All configs | rpc_interface/ |
| NuGet package | tools\nuget |
All configs | tools/nuget/ |
| Redist package | tools\redist-package |
NativeOnly/Release only (not Debug) | tools/redist-package/ |
| Installer (WiX) | installer\ebpf-for-windows |
All configs | installer/ebpf-for-windows/ |
Common Build Patterns
Use these when the user describes what area they're working on:
| Working On | Targets to Build |
|---|---|
| API changes | libs\user\api,dlls\EbpfApi,tests\api_test |
| bpf2c / native code generation | tools\bpf2c,tests\bpf2c_tests,tests\sample |
| Kernel driver changes | drivers\EbpfCore,drivers\netebpfext,tests\unit_tests |
| Service changes | libs\user\service,service\ebpfsvc,tests\ebpf_stress_tests_um |
| Execution context changes | libs\kernel\execution_context_kernel,libs\user\execution_context_user,tests\api_test |
| Network extension changes | drivers\netebpfext,tests\netebpfext_unit |
| Verifier changes | libs\user\prevail,tests\unit_tests |
| Shared library changes | Rebuild all dependents — prefer full solution build |
bpf2c Expected Output Regeneration
If bpf2c output changes and tests\bpf2c_tests expected files must be updated:
- Build
x64\Debug. - Run:
.\scripts\generate_expected_bpf2c_output.ps1 x64\Debug
Dependency Chain
When building specific components, be aware of the dependency order:
tools\setup_build(build utilities — runs first)libs\kernel\shared_kernel/libs\user\shared_user(fundamental utilities)libs\kernel\runtime_kernel/libs\user\runtime_user(platform abstractions)libs\kernel\execution_context_kernel/libs\user\execution_context_user(core eBPF execution)drivers\EbpfCore,drivers\netebpfext(kernel drivers)libs\user\api,dlls\EbpfApi(user-mode APIs)- Tests and tools
MSBuild handles dependency resolution within the solution, so you typically only need to specify the top-level target(s) you want built.
Output Locations
Build artifacts are placed under:
x64\Debug\— Debug x64 buildsx64\Release\— Release x64 buildsx64\NativeOnlyDebug\— NativeOnly Debug buildsx64\NativeOnlyRelease\— NativeOnly Release buildsARM64\Debug\— ARM64 Debug builds (if applicable)
Quieting Build Output
For targeted builds where you only need to see errors, use /v:q /nologo:
msbuild ebpf-for-windows.sln /m /p:Configuration=Debug /p:Platform=x64 /t:"tools\bpf2c" /v:q /nologo
Pipe through | Select-Object -Last N to see just the tail when checking for success/failure.
Repository Initialization
After cloning, changing submodule pointers, or resetting submodules, run the initialization script before building:
# From solution root — initializes submodules, generates cmake projects, restores NuGet
.\scripts\initialize_ebpf_repo.ps1
# Or with ARM64
.\scripts\initialize_ebpf_repo.ps1 -Architecture ARM64
This script:
- Runs
git submodule update --init --recursive - Generates cmake projects for ebpf-verifier, Catch2, and ubpf in their respective
build/dirs - Restores NuGet packages for the solution
IMPORTANT: If cmake-generated project files are missing (e.g., external/ebpf-verifier/build/prevail.vcxproj), MSBuild will error with MSB3202. Run initialize_ebpf_repo.ps1 to regenerate them.
Submodule Gotchas
msbuild /t:cleanwill fail if cmake-generated projects don't exist yet — runinitialize_ebpf_repo.ps1firstgit stashin the parent repo does NOT affect submodule working trees — stash separately in each submodule if needed- After resetting submodules (
git submodule update --init --recursive), re-runinitialize_ebpf_repo.ps1
BPF Program Compilation (clang → .o)
When manually compiling BPF C programs with clang, use the full set of include paths
from the tests\sample\sample.vcxproj CustomBuild rules.
Locate clang.exe — use the first existing path (highest priority first):
packages\llvm.tools\clang.exe, "$env:ProgramFiles\LLVM\bin\clang.exe",
"$(& "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -latest -property installationPath)\VC\Tools\Llvm\bin\clang.exe"
# Standard sample programs (tests\sample\*.c)
& '<clang-path>' -g -target bpf -O2 -Werror `
-Iinclude -Iexternal\bpftool `
-Itests\xdp -Itests\socket -Itests\sample\ext\inc -Itests\include `
-c tests\sample\<name>.c -o x64\Debug\<name>.o
# Undocked sample programs (tests\sample\undocked\*.c) — add extra includes
& '<clang-path>' -g -target bpf -O2 -Werror `
-Iinclude -Iexternal\bpftool `
-Itests\xdp -Itests\socket -Itests\sample\ext\inc -Itests\include `
-Itests\sample -Iundocked\tests\sample\ext\inc `
-c tests\sample\undocked\<name>.c -o x64\Debug\<name>.o
Common mistake: Using only -Iinclude will fail for programs that include
socket_tests_common.h, xdp_common.h, or sample_ext_helpers.h.