1<a href=".github/assets/"> 2 <div> 3 <img src=".github/assets/bpftool_horizontal_color.svg" 4 alt="bpftool logo: Hannah the Honeyguide" 5 width=500px; /> 6 </div> 7</a> 8 9[![License BSD 2-Clause][bsd-badge]](LICENSE.BSD-2-Clause) 10[![License GPL 2.0][gpl-badge]](LICENSE.GPL-2.0) 11[![Build status][build-badge]][build] 12 13[bsd-badge]: https://img.shields.io/badge/License-BSD_2--Clause-blue.svg 14[gpl-badge]: https://img.shields.io/badge/License-GPL_2.0-blue.svg 15[build-badge]: https://github.com/libbpf/bpftool/actions/workflows/build.yaml/badge.svg 16[build]: https://github.com/libbpf/bpftool/actions/workflows/build.yaml 17 18This is the official home for bpftool. _Please use this Github repository for 19building and packaging bpftool and when using it in your projects through Git 20submodule._ 21 22The _authoritative source code_ of bpftool is developed as part of the 23[bpf-next Linux source tree][bpf-next] under [the `tools/bpf/bpftool` 24subdirectory][tools-bpf-bpftool] and is periodically synced to 25<https://github.com/libbpf/bpftool> on Github. As such, all changes for bpftool 26**should be sent to the [BPF mailing list][bpf-ml]**, **please don't open PRs 27here** unless you are changing some Github-specific components. 28 29[bpf-next]: https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git 30[tools-bpf-bpftool]: https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/tools/bpf/bpftool 31[bpf-ml]: http://vger.kernel.org/vger-lists.html#bpf 32 33Questions on bpftool and BPF general usage 34------------------------------------------ 35 36Check out [the manual pages](docs) for documentation about bpftool. A number of 37example invocations are also displayed in [this blog 38post](https://qmonnet.github.io/whirl-offload/2021/09/23/bpftool-features-thread/). 39 40All general BPF questions, including kernel functionality, bpftool features and 41usage, should be sent to [email protected] mailing list. You can subscribe to 42it [here][bpf-ml] and search its archives [here][lore]. 43 44The mailing list is monitored by many more people than this repo and they will 45happily try to help you with whatever issue you encounter. This repository's 46PRs and issues should be opened only for dealing with issues related to 47components specific to the bpftool mirror repository (such as the 48synchronization script or the CI workflows). The project maintainers also use 49GitHub issues as a generic tracker for bpftool, but issues should first be 50reported on the mailing list nonetheless. 51 52[lore]: https://lore.kernel.org/bpf/ 53 54Dependencies 55------------ 56 57Required: 58 59- libelf 60- zlib 61 62Optional: 63 64- libbfd (for dumping JIT-compiled program instructions) 65- libcap (for better feature probing) 66- kernel BTF information (for profiling programs or showing PIDs of processes 67 referencing BPF objects) 68- clang/LLVM (idem) 69 70Build 71----- 72 73### Initialize libbpf submodule 74 75This repository uses libbpf as a submodule. You can initialize it when cloning 76bpftool: 77 78```console 79$ git clone --recurse-submodules https://github.com/libbpf/bpftool.git 80``` 81 82Alternatively, if you have already cloned the repository, you can initialize 83the submodule by running the following command from within the repository: 84 85```console 86$ git submodule update --init 87``` 88 89### Build bpftool 90 91To build bpftool: 92 93```console 94$ cd src 95$ make 96``` 97 98To build and install bpftool on the system: 99 100```console 101$ cd src 102# make install 103``` 104 105Building bpftool in a separate directory is supported via the `OUTPUT` variable: 106 107```console 108$ mkdir /tmp/bpftool 109$ cd src 110$ OUTPUT=/tmp/bpftool make 111``` 112 113Most of the output is suppressed by default, but detailed building logs can be 114displayed by passing `V=1`: 115 116```console 117$ cd src 118$ make V=1 119``` 120 121Additional compilation flags can be passed to the command line if required. For 122example, we can create a static build with the following commands: 123 124```console 125$ cd src 126$ EXTRA_CFLAGS=--static make 127``` 128 129Note that to use the LLVM disassembler with static builds, we need a static 130version of the LLVM library installed on the system: 131 1321. Download a precompiled LLVM release or build it locally. 133 134 - Download the appropriate 135 [release of LLVM](https://releases.llvm.org/download.html) for your 136 platform, for example on x86_64 with LLVM 15.0.0: 137 138 ```console 139 $ curl -LO https://github.com/llvm/llvm-project/releases/download/llvmorg-15.0.0/clang+llvm-15.0.0-x86_64-linux-gnu-rhel-8.4.tar.xz 140 $ tar xvf clang+llvm-15.0.0-x86_64-linux-gnu-rhel-8.4.tar.xz 141 $ mv clang+llvm-15.0.0-x86_64-linux-gnu-rhel-8.4 llvm_build 142 ``` 143 144 - Alternatively, clone and build the LLVM libraries locally. 145 146 ```console 147 $ git clone https://github.com/llvm/llvm-project.git 148 $ mkdir llvm_build 149 $ cmake -S llvm-project/llvm -B llvm_build -DCMAKE_BUILD_TYPE=Release 150 $ make -j -C llvm_build llvm-config llvm-libraries 151 ``` 152 1532. Build bpftool with `EXTRA_CFLAGS` set to `--static`, and by passing the 154 path to the relevant `llvm-config`. 155 156 ```console 157 $ cd bpftool 158 $ LLVM_CONFIG=../../llvm_build/bin/llvm-config EXTRA_CFLAGS=--static make -j -C src 159 ``` 160 161### Build bpftool's man pages 162 163The man pages for bpftool can be built with: 164 165```console 166$ cd docs 167$ make 168``` 169 170They can be installed on the system with: 171 172```console 173$ cd docs 174# make install 175``` 176 177bpf-next to GitHub sync 178----------------------- 179 180This repository mirrors [bpf-next Linux source tree's 181`tools/bpf/bpftool`][tools-bpf-bpftool] directory, plus its few dependencies 182from under `kernel/bpf/`, and its supporting header files. Some of these header 183files, `include/linux/*.h` on the current repository, are reduced versions of 184their counterpart files at [bpf-next][bpf-next]'s `tools/include/linux/*.h` to 185make compilation successful. 186 187Synchronization between the two repositories happens every few weeks or so. 188Given that bpftool remains aligned on libbpf's version, its repository tends to 189follow libbpf's. When the libbpf repo syncs up with bpf-next, bpftool's repo 190usually follows within the next few days. 191 192The synchronization process is semi-automated: the script in 193`scripts/sync-kernel.sh` cherry-picks, adjusts and commits all changes from 194`bpf-next` to a local version of the bpftool repository. However, maintainers 195run this script manually and then create a pull request to merge the resulting 196commits. 197 198Take a look at [the script](scripts/sync-kernel.sh) for the technical details of the process. See also the documentation in [the accompanying README.md](scripts#sync-kernelsh) 199 200License 201------- 202 203This work is dual-licensed under the GNU GPL v2.0 (only) license and the BSD 2042-clause license. You can select either of them if you reuse this work. 205 206`SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)` 207
