boratanrikulu/gobee

Source: https://github.com/boratanrikulu/gobee

gobee

Write your BPF programs in Go, not C. gobee transpiles a strict subset of Go into BPF C, generates typed Go bindings for the userspace side, and gates loads against the running kernel.

The Go ecosystem has solid userspace tooling for BPF. The kernel side has always ended with “now write your program in C.” Aya brought eBPF to Rust by writing a new BPF backend in rustc. gobee gets there a different way: by transpiling to C and reusing clang’s mature backend.

A Go file in, a BPF program out

A tracepoint that streams every execve to userspace via a ringbuf:

//go:build ignore

package main

import "github.com/boratanrikulu/gobee/bpf"

//bpf:license GPL

type Event struct {
    Pid  uint32
    Comm [16]byte
}

var Events = bpf.RingBuf[Event]{
    MaxEntries: 4096,
}

//bpf:section tracepoint/syscalls/sys_enter_execve
func OnExec(ctx *bpf.ExecveEnterCtx) bpf.TpReturn {
    e, ok := Events.Reserve()
    if !ok {
        return bpf.TpOk
    }
    e.Pid = bpf.GetCurrentPid()
    bpf.GetTaskComm(&e.Comm)
    Events.Submit(e)
    return bpf.TpOk
}

func main() {}

// Code generated by gobee. DO NOT EDIT.

#include "vmlinux.h"
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_core_read.h>

char _license[] SEC("license") = "GPL";

struct Event {
    __u32 Pid;
    __u8 Comm[16];
};

struct {
    __uint(type, BPF_MAP_TYPE_RINGBUF);
    __uint(max_entries, 4096);
} Events SEC(".maps");

SEC("tracepoint/syscalls/sys_enter_execve")
int OnExec(struct trace_event_raw_sys_enter *ctx) {
    struct Event *e = bpf_ringbuf_reserve(
        &Events, sizeof(struct Event), 0);
    if (!e) {
        return 0;
    }
    e->Pid = (__u32)(
        bpf_get_current_pid_tgid() >> 32);
    bpf_get_current_comm(&e->Comm, 16);
    bpf_ringbuf_submit(e, 0);
    return 0;
}

gobee translate --bindings-dir ./bpf ./bpf/src produces both files, plus a sourcemap (events.bpf.c.map) so verifier errors map back to Go lines and a typed bindings file (bpf/events_bindings.go) so the userspace driver writes objs.Events, objs.AttachOnExec(), and decodes ringbuf payloads straight into bpf.Event (the same struct you see above, re-published in Go) instead of stringly-typed coll.Programs["..."] lookups.

The C is readable on purpose. If gobee emits something weird, you can see it. For tracepoints + kprobes + XDP combined into one binary, see example/sysmon/.

How it compares

If you’re already in a C / libbpf workflow, gobee is not trying to replace it wholesale. It’s for cases where you want the kernel side, the userspace side, and the build pipeline all in one Go module.

What’s supported today

See docs/status.md for the full matrix (Go subset, statements, expressions, every helper, every map type, every directive). Quick view:

What gobee does

• Transpiles a Go subset to BPF C (and runs go/types over your input first, so misuses surface at file:line:col).
• Generates a typed <Stem>_bindings.go next to the .bpf.c: bpf.LoadCounter(spec), objs.PerIface.Lookup(...), objs.AttachAll(ifindex), plus your kernel-side struct types and constants re-published in Go.
• Auto-annotates *ebpf.VerifierError from LoadAndAssign with Go source positions, no manual gobee diagnose pipe needed.
• Runs bpfvet inside Load<Stem> so old kernels fail fast with bpf program needs kernel >= 5.8, host is 5.4.
• Surfaces ~200 typed Go stubs for the libbpf v1.5.0 helper set, plus user-defined helper functions emitted as static __always_inline.

What gobee won’t do

• Replace clang. clang’s BPF backend gives us CO-RE, BTF, and verifier-friendly codegen for free. Reimplementing that costs years and gains nothing.
• Replace cilium/ebpf. The generated bindings sit on top of it.
• Hide BPF. The Go subset maps 1:1 to BPF C idioms. If you know BPF, gobee is thin sugar. If you don’t, the manual is still required reading.
• Run clang for you. Compile, embed, and load remain user-owned. Same pattern as bpf2go.

Why transpile, not generate BPF directly

gc, the Go compiler, has no LLVM-based BPF backend. Adding one is a multi-year compiler project. rustc is built on LLVM and that’s why Aya works. So gobee emits C and reuses clang’s BPF backend, which gives us mature codegen, BTF, and CO-RE relocations for free.

Quickstart

go install github.com/boratanrikulu/gobee/cmd/gobee@latest

cd example/helloworld
make build                     # gobee translate, clang, go build
sudo ./helloworld eth0

You’ll need clang with the BPF target. On Linux that’s the distro package; on macOS, brew install llvm. The transpiler itself is pure Go and runs anywhere.

Project layout (typical)

yourproject/
├── bpf/                      # Go package, importable from anywhere in your project
│   ├── embed_amd64.go        # //go:embed bin/x86/your.bpf.o
│   ├── embed_arm64.go
│   ├── your_bindings.go      # generated by gobee
│   ├── bin/{x86,arm64}/your.bpf.o
│   └── src/                  # not a Go package; clang lives here
│       ├── your.go           # //go:build ignore: BPF source
│       ├── your.bpf.c        # generated
│       ├── Makefile          # clang per arch
│       └── vmlinux.h         # vendored BTF dump
├── main.go                   # imports yourproject/bpf
└── Makefile

The split keeps bpf/ a clean importable Go package (Go rejects .c files in non-cgo packages). Kernel sources and clang artifacts live one level down in bpf/src/.

Examples

• example/helloworld/: the canonical XDP packet counter, ~40 lines BPF, ~80 lines userspace.
• example/sysmon/: XDP, two tracepoints, and a kprobe in one binary, sharing a ringbuf for events. Demonstrates per-syscall typed contexts, user-defined helper functions, and the AttachAll shortcut.

CI

GitHub Actions runs four layers on every push:

1. go test, go vet, transpiler golden tests
2. Coverage matrix: every map type and //bpf:section kind has at least one example
3. clang compile of every curated example, then bpfvet portability report
4. Real-kernel verifier acceptance: ebpf.NewCollectionWithOptions on each .bpf.o (Ubuntu 24.04 runner, kernel 6.x)

Docs

• docs/design.md: architecture and rationale
• docs/go-subset.md: accepted Go syntax in BPF source files
• docs/directives.md: //bpf:* reference
• docs/status.md: support matrix (single source of truth)

Toolchain

• The gobee binary builds anywhere (pure Go, no CGO).
• Compiling .bpf.o needs clang with the BPF target. Apple’s bundled clang doesn’t ship with it; on macOS use brew install llvm or build inside a Linux VM.
• Running the artifact needs Linux on arm64 or amd64.

Inspirations

• Solod: the Go-to-C transpiler that proved this pattern works.
• Aya: the Rust eBPF framework whose ergonomics gobee chases.

License

MIT. See LICENSE.

Copyright (c) 2026 Bora Tanrikulu <[email protected]>