README.md
1bpftool
2=======
3
4This is a mirror of [bpf-next Linux source tree's
5`tools/bpf/bpftool`](https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/tools/bpf/bpftool)
6directory, plus its few dependencies from under `kernel/bpf/`, and its
7supporting header files.
8
9All the gory details of syncing can be found in `scripts/sync-kernel.sh`
10script.
11
12Some header files in this repo (`include/linux/*.h`) are reduced versions of
13their counterpart files at
14[bpf-next](https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/)'s
15`tools/include/linux/*.h` to make compilation successful.
16
17BPF/bpftool usage and questions
18-------------------------------
19
20Please check out [the manual pages](docs) for documentation about bpftool. A
21number of example invocations are also displayed in [this blog
22post](https://qmonnet.github.io/whirl-offload/2021/09/23/bpftool-features-thread/).
23
24All general BPF questions, including kernel functionality, bpftool features and
25usage, should be sent to bpf@vger.kernel.org mailing list. You can subscribe to
26it [here](http://vger.kernel.org/vger-lists.html#bpf) and search its archive
27[here](https://lore.kernel.org/bpf/). Please search the archive before asking
28new questions. It very well might be that this was already addressed or
29answered before.
30
31bpf@vger.kernel.org is monitored by many more people and they will happily try
32to help you with whatever issue you have. This repository's PRs and issues
33should be opened only for dealing with issues pertaining to specific way this
34bpftool mirror repo is set up and organized.
35
36Dependencies
37------------
38
39Required:
40
41- libelf
42- zlib
43
44Optional:
45
46- libbfd (for dumping JIT-compiled program instructions)
47- libcap (for better feature probing)
48- kernel BTF information (for profiling programs or showing PIDs of processes
49 referencing BPF objects)
50- clang/LLVM (idem)
51
52Build
53[](https://github.com/libbpf/bpftool/actions/workflows/build.yaml)
54-----
55
56### Initialize libbpf submodule
57
58This repository uses libbpf as a submodule. You can initialize it when cloning
59bpftool:
60
61```console
62$ git clone --recurse-submodules https://github.com/libbpf/bpftool.git
63```
64
65Alternatively, if you have already cloned the repository, you can initialize
66the submodule by running the following command from within the repository:
67
68```console
69$ git submodule update --init
70```
71
72### Build bpftool
73
74To build bpftool:
75
76```console
77$ cd src
78$ make
79```
80
81To build and install bpftool on the system:
82
83```console
84$ cd src
85# make install
86```
87
88Building bpftool in a separate directory is supported via the `OUTPUT` variable:
89
90```console
91$ mkdir /tmp/bpftool
92$ cd src
93$ OUTPUT=/tmp/bpftool make
94```
95
96Most of the output is suppressed by default, but detailed building logs can be
97displayed by passing `V=1`:
98
99```console
100$ cd src
101$ make V=1
102```
103
104Additional compilation flags can be passed to the command line if required. For
105example, we can create a static build with the following commands:
106
107```console
108$ cd src
109$ EXTRA_CFLAGS=--static make
110```
111
112Note that to use the LLVM disassembler with static builds, we need a static
113version of the LLVM library installed on the system:
114
1151. Download a precompiled LLVM release or build it locally.
116
117 - Download the appropriate
118 [release of LLVM](https://releases.llvm.org/download.html) for your
119 platform, for example on x86_64 with LLVM 15.0.0:
120
121 ```console
122 $ 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
123 $ tar xvf clang+llvm-15.0.0-x86_64-linux-gnu-rhel-8.4.tar.xz
124 $ mv clang+llvm-15.0.0-x86_64-linux-gnu-rhel-8.4 llvm_build
125 ```
126
127 - Alternatively, clone and build the LLVM libraries locally.
128
129 ```console
130 $ git clone https://github.com/llvm/llvm-project.git
131 $ mkdir llvm_build
132 $ cmake -S llvm-project/llvm -B llvm_build -DCMAKE_BUILD_TYPE=Release
133 $ make -j -C llvm_build llvm-config llvm-libraries
134 ```
135
1362. Build bpftool with `EXTRA_CFLAGS` set to `--static`, and by passing the
137 path to the relevant `llvm-config`.
138
139 ```console
140 $ cd bpftool
141 $ LLVM_CONFIG=../../llvm_build/bin/llvm-config EXTRA_CFLAGS=--static make -j -C src
142 ```
143
144### Build bpftool's man pages
145
146The man pages for bpftool can be built with:
147
148```console
149$ cd docs
150$ make
151```
152
153They can be installed on the system with:
154
155```console
156$ cd docs
157# make install
158```
159
160License
161-------
162
163This work is dual-licensed under the GNU GPL v2.0 (only) license and the
164BSD 2-clause license. You can choose between one of them if you use this work.
165
166`SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)`
167
){kind=link}