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:

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