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

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)

DLLs and Services (User-Mode)

Libraries

Tools

Tests

Stress Tests and Fuzzers

Stress tests build in Debug/Release. Fuzzers require FuzzerDebug configuration.

External Dependencies

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:

Build Utilities and Installers

Common Build Patterns

Use these when the user describes what area they're working on:

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.