Build and Bytecode Assets ​

Purpose and Scope ​

This page details the build system, architecture variants, CO-RE (Compile Once – Run Everywhere) versus non-CO-RE bytecode generation strategies, and toolchain prerequisites required to compile ecapture and its core modules (tls for OpenSSL/BoringSSL, gotls for Go native TLS, and gnutls for GnuTLS). It explains how eBPF C programs are compiled into architecture-specific object files and embedded into the Go binary.

Sources: Makefile:4-16, variables.mk:1-120, docs/compilation.md:1-36

1. Supported Build Environments and Prerequisites ​

Building ecapture requires a modern Linux development environment (Ubuntu 20.04 or later is officially supported via helper scripts) with specific toolchain versions docs/compilation.md:28-44.

Required Toolchain Versions ​

• Golang: Version 1.26.0 or newer (go.mod:3 [], functions.mk:25-34 []).
• Clang/LLVM: Version 9.0 or newer (Clang 14 or 18 recommended for advanced architectures) docs/compilation.md:34-36.
• Libraries & Headers: libelf-dev, pkgconf, linux-tools-common, linux-tools-generic, and target kernel header files docs/compilation.md:52-55.

Environment initialization can be automated via the provided bootstrap script:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/gojue/ecapture/master/builder/init_env.sh)"

This script detects the host OS release builder/init_env.sh:10-40, installs required system packages builder/init_env.sh:73-75, configures symlinks for clang, llc, and llvm-strip builder/init_env.sh:76-80, and sets up the Go toolchain builder/init_env.sh:95-98.

Sources: builder/init_env.sh:1-108, functions.mk:13-36, docs/compilation.md:24-57

2. Architecture Variants and Toolchain Mapping ​

The build system (variables.mk) normalizes target architectures into specific target triples, architecture build directories, and C compilation flags variables.mk:72-120.

Cross-Compilation and Loong64 Support ​

Cross-compilation is driven by setting the CROSS_ARCH environment variable (e.g., CROSS_ARCH=arm64 make) docs/compilation.md:107-112. For loong64, strict requirements apply: it must be built on Ubuntu 24.04 x86_64 using LLVM 18 (CLANG_NUM=18) and requires LOONG64_VMLINUX and kernel headers variables.mk:91-117, docs/compilation.md:114-131.

Sources: variables.mk:72-120, docs/compilation.md:79-131

3. CO-RE and Non-CO-RE Bytecode Asset Generation ​

eBPF bytecode is compiled from C source files under kern/ into architecture-specific object files (_core.o or non-CO-RE equivalents) and subsequently packed into Go source files via asset generation Makefile:174-190.

Build Targets ​

• make all (or make build): Compiles both CO-RE and non-CO-RE bytecode assets and builds the ecapture binary Makefile:4-6.
• make core: Builds eCapture with CO-RE (Compile Once – Run Everywhere) assets only Makefile:9-11.
• make nocore: Builds eCapture with non-CO-RE assets only, bypassing BTF dependencies for older kernels Makefile:13-15, docs/compilation.md:69-77.

Compilation Flow ​

The Makefile targets each source file in kern/ matching KERN_OBJECTS, invoking clang with appropriate target flags (-target bpfel), debug symbols (-g), and dependency generation Makefile:174-185.

Sources: Makefile:1-190, variables.mk:140-176

4. Build Prerequisites for TLS, GoTLS, and GnuTLS ​

The core TLS probes (tls, gotls, gnutls) depend on statically linked libpcap and CGO configurations defined in functions.mk functions.mk:47-57.

CGO and Linker Configuration ​

The gobuild macro defines the precise environment variables and build flags passed to the Go compiler functions.mk:47-57:

• CGO_ENABLED=1 functions.mk:49 ensures packet capture features (pcapng mode) can link against the bundled libpcap archive located at LIBPCAP_BUILD_DIR functions.mk:50-51.
• Build tags include netgo, ebpfassets, dynamic, and module-specific tags like ecap_android variables.mk:152-176, functions.mk:54.
• Ldflags strip binary symbols (-w -s) and inject the git version and bytecode configuration functions.mk:54.

Sources: functions.mk:47-57, variables.mk:52-124