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.).
apm install @microsoft/build-ebpf
[](https://apm-p1ls2dz87-atlamors-projects.vercel.app/packages/@microsoft/build-ebpf)---
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:
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
```powershell
# 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
```powershell
# 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 |
## 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`:
```powershell
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:
```powershell
# 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"`
```powershell
# 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`.