build-ebpf

Build eBPF for Windows

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.sln location)

Build Instructions

Step 1: Determine What to Build

Ask the user (or infer from context) what they want to build. Options:

1. Full solution — build everything
2. Specific component(s) — use the target map below to select /t: targets
3. 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 .vcxproj files directly
• Always run from the solution root directory
• Use /m for parallel builds
• For first-time or fresh builds, add -Restore to 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

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. The ubpf_fuzzer\* targets (ebpfverifier, ubpf, libbtf, win-c, ubpf_fuzzer, ubpf_fuzzer_post_build) are only built in FuzzerDebug configuration 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:

1. Build x64\Debug.
2. Run:

.\scripts\generate_expected_bpf2c_output.ps1 x64\Debug

Dependency Chain

When building specific components, be aware of the dependency order:

1. tools\setup_build (build utilities — runs first)
2. libs\kernel\shared_kernel / libs\user\shared_user (fundamental utilities)
3. libs\kernel\runtime_kernel / libs\user\runtime_user (platform abstractions)
4. libs\kernel\execution_context_kernel / libs\user\execution_context_user (core eBPF execution)
5. drivers\EbpfCore, drivers\netebpfext (kernel drivers)
6. libs\user\api, dlls\EbpfApi (user-mode APIs)
7. 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 builds
• x64\Release\ — Release x64 builds
• x64\NativeOnlyDebug\ — NativeOnly Debug builds
• x64\NativeOnlyRelease\ — NativeOnly Release builds
• ARM64\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:

1. Runs git submodule update --init --recursive
2. Generates cmake projects for ebpf-verifier, Catch2, and ubpf in their respective build/ dirs
3. 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:clean will fail if cmake-generated projects don't exist yet — run initialize_ebpf_repo.ps1 first
• git stash in 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-run initialize_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.