build-ebpf

Build the eBPF for Windows repository — entire solution or specific components. Use this skill when asked to build, compile, rebuild, restore, or clean the project or any of its components (drivers, libraries, tools, tests, etc.).

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:

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

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

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