| name | build-ebpf |
| description | 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 | |
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/ |
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 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:clean will fail if cmake-generated projects don't exist yet — run initialize_ebpf_repo.ps1 firstgit 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.
