diff --git a/README.md b/README.md index 4b59484..e50c500 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,49 @@ bpftool +[![License BSD 2-Clause][bsd-badge]](LICENSE.BSD-2-Clause) +[![License GPL 2.0][gpl-badge]](LICENSE.GPL-2.0) +[![Build status][build-badge]][build] ======= -This is a mirror of [bpf-next Linux source tree's -`tools/bpf/bpftool`](https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/tools/bpf/bpftool) -directory, plus its few dependencies from under `kernel/bpf/`, and its -supporting header files. +[bsd-badge]: https://img.shields.io/badge/License-BSD_2--Clause-blue.svg +[gpl-badge]: https://img.shields.io/badge/License-GPL_2.0-blue.svg +[build-badge]: https://github.com/libbpf/bpftool/actions/workflows/build.yaml/badge.svg +[build]: https://github.com/libbpf/bpftool/actions/workflows/build.yaml -All the gory details of syncing can be found in `scripts/sync-kernel.sh` -script. +This is the official home for bpftool. _Please use this Github repository for +building and packaging bpftool and when using it in your projects through Git +submodule._ -Some header files in this repo (`include/linux/*.h`) are reduced versions of -their counterpart files at -[bpf-next](https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/)'s -`tools/include/linux/*.h` to make compilation successful. +The _authoritative source code_ of bpftool is developed as part of the +[bpf-next Linux source tree][bpf-next] under [the `tools/bpf/bpftool` +subdirectory][tools-bpf-bpftool] and is periodically synced to + on Github. As such, all changes for bpftool +**should be sent to the [BPF mailing list][bpf-ml]**, **please don't open PRs +here** unless you are changing some Github-specific components. -BPF/bpftool usage and questions -------------------------------- +[bpf-next]: https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git +[tools-bpf-bpftool]: https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/tools/bpf/bpftool +[bpf-ml]: http://vger.kernel.org/vger-lists.html#bpf -Please check out [the manual pages](docs) for documentation about bpftool. A -number of example invocations are also displayed in [this blog +Questions on bpftool and BPF general usage +------------------------------------------ + +Check out [the manual pages](docs) for documentation about bpftool. A number of +example invocations are also displayed in [this blog post](https://qmonnet.github.io/whirl-offload/2021/09/23/bpftool-features-thread/). All general BPF questions, including kernel functionality, bpftool features and usage, should be sent to bpf@vger.kernel.org mailing list. You can subscribe to -it [here](http://vger.kernel.org/vger-lists.html#bpf) and search its archive -[here](https://lore.kernel.org/bpf/). Please search the archive before asking -new questions. It very well might be that this was already addressed or -answered before. +it [here][bpf-ml] and search its archives [here][lore]. + +The mailing list is monitored by many more people than this repo and they will +happily try to help you with whatever issue you encounter. This repository's +PRs and issues should be opened only for dealing with issues related to +components specific to the bpftool mirror repository (such as the +synchronization script or the CI workflows). The project maintainers also use +GitHub issues as a generic tracker for bpftool, but issues should first be +reported on the mailing list nonetheless. -bpf@vger.kernel.org is monitored by many more people and they will happily try -to help you with whatever issue you have. This repository's PRs and issues -should be opened only for dealing with issues pertaining to specific way this -bpftool mirror repo is set up and organized. +[lore]: https://lore.kernel.org/bpf/ Dependencies ------------ @@ -50,7 +62,6 @@ Optional: - clang/LLVM (idem) Build -[![build](https://github.com/libbpf/bpftool/actions/workflows/build.yaml/badge.svg)](https://github.com/libbpf/bpftool/actions/workflows/build.yaml) ----- ### Initialize libbpf submodule @@ -157,10 +168,33 @@ $ cd docs # make install ``` +bpf-next to GitHub sync +----------------------- + +This repository mirrors [bpf-next Linux source tree's +`tools/bpf/bpftool`][tools-bpf-bpftool] directory, plus its few dependencies +from under `kernel/bpf/`, and its supporting header files. Some of these header +files, `include/linux/*.h` on the current repository, are reduced versions of +their counterpart files at [bpf-next][bpf-next]'s `tools/include/linux/*.h` to +make compilation successful. + +Synchronization between the two repositories happens every few weeks or so. +Given that bpftool remains aligned on libbpf's version, its repository tends to +follow libbpf's. When the libbpf repo syncs up with bpf-next, bpftool's repo +usually follows within the next few days. + +The synchronization process is semi-automated: the script in +`scripts/sync-kernel.sh` cherry-picks, adjusts and commits all changes from +`bpf-next` to a local version of the bpftool repository. However, maintainers +run this script manually and then create a pull request to merge the resulting +commits. + +Take 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) + License ------- -This work is dual-licensed under the GNU GPL v2.0 (only) license and the -BSD 2-clause license. You can choose between one of them if you use this work. +This work is dual-licensed under the GNU GPL v2.0 (only) license and the BSD +2-clause license. You can select either of them if you reuse this work. `SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)`