= Installing and Configuring b4
:page-parent: Working with Patches
:page-grand_parent: Contributing
:page-nav_order: 1

// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
// SPDX-FileCopyrightText: 2022 Unikie
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0

https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] is a utility
for working with patches sent to a mailing list, such as
https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os.org].

NOTE: If you run `nix-shell` in the root of the Spectrum source tree,
you'll be dropped into a development shell that has b4 set up
correctly, and you don't need to do anything else.  You only need to
configure it manually as described here if you want it to work outside
of the Spectrum root's nix-shell.

== Installing b4

You should be able to install b4 from your package manager.

Using Nix, you can start a shell with b4 available by running:

[listing]
[source,shell]
nix-shell -p b4

== Configuring b4

As b4 was originally written for Linux development, it will default to
searching for patches on the Linux mailing lists.  So to use it for
Spectrum, it needs to be configured to search the Spectrum mailing
lists instead.

To do this, in a checkout of the appropriate git repository
(https://spectrum-os.org/git/spectrum[Spectrum] or
https://spectrum-os.org/git/nixpkgs[Spectrum Nixpkgs]), run:

[listing]
[source,shell]
git config b4.midmask https://spectrum-os.org/lists/archives/spectrum-devel/%s

From now on, any b4 command run in Spectrum repositories will search
the Spectrum devel mailing list.

== Using b4

Using b4 to fetch and apply a patch from the Spectrum mailing list is
described in the xref:testing-patches.adoc[Testing Patches] how-to guide.