Setting up the kernel development environment - Email
This article describes a possible email setup for your kernel development environment.
The Linux kernel development process is based on emails. Once you have a crafted a patch or a patch series, you sent an email upstream for review. Generally new patches are sent with git send-email. The patches need to be sent as inline text in the body and should have a content type of text/plain. The email requirements are discussed in the kernel doc.
The first step is to install the required Linux packages. To download the emails different programs can be used. This guide uses the mbsync package. To send emails it uses the msmtp package. Both packages need to store the password. To avoid storing the password in plain text, they use the gpg program.
Add the following setings to your git configuration. Replace firstname and lastname with your name. Make sure to use your real name, so that the patches can be accepted upstream. Make sure you specify your email address correctly. This specifies nvim as the default editor, other settings are certainly possible.
The git configuration is stored in ~/.gitconfig.
First store your password in a text file like below:
Encrypt the password with the following steps:
Afterwards the unencrypted password file mbsync.pw can be deleted. Only the encoded password is stored in the file ~/.mbsync-pw.gpg.
The mbsync program downloads the emails into a directory. By default the directory is called Maildir. Let’s create that directory.
The mbsync program is used to retrieve emails. Its default configuration file is stored under ~/.mbsyncrc. This configuration uses the email service fastmail. Other email services like gmail can be used. However it is important to pick an email service provider that doesn’t change (re-format) the content of the body of the email message.
In the below configuration file the Host and User has to be specified. Not all email services need a CertificateFile. In case your emaiil service doesn’t need one, simply remove the corresponding line. The example below is only a simple configuration. The mbsync program also supports setting up configurations with multiple accounts.
In case your email service provider requires a certificate file, the file can be created with the following command:
Of course this assumes, that the fastmail email service is used. For other email services the domain name needs to be adapted accordingly.
At this point we are able to retrieve the messages with:
The first time this is executed it will take longer as it will download all the emails. Future invocations will be faster and only download the new emails.
Mails are sent with the msmptp program. It is configured by default with the ~/.msmtprc configuration file.
In the above examples the values host and from need to be changed to the valid values for your email service provider. At this point you are able to send and retrieve emails.
In a lot of enterprise environments you don’t have a direct connection to the internet. Instead you are behind a firewall / proxy. If you are not behind a proxy, continue with “Discussing review comments”. In case you are behind a proxy, the socat program can be used. When using the socat program the mbsync and msmtprc configuration needs to be changed. The socat program is used to tunnel the mail retrieval as well as the mail sending.
The following script can be used for this:
In the above script I used the smtp and imap hostnames for the fastmail service. This needs to be changed for your email service provider. It maps thesee services to the ports 13776 amd 13777. In your configuration you need to change these ports if they are already used for exisiting services.
For the .mbsyncrc file the following changes need to be made:
This retrieves the emails through port 13777 on the local host. The request gets then proxied to imap.fastmail.com in the above case.
For the .msmtprc file the following changes need to be made:
The easiest way to test that everything works is to create a small patch and send it to yourself or a colleague. The following is a potential workflow (assuming you are in your base linux kernel directory):
The last command creates a patch file (file extension .patch) in your current directory. You can use this file to send yourself a patch with a command like the following:
The git format-patch command allows to create patch files for more than one patch. Here is a typical command.
It is good practive to specify the base=auto flag. So reviewers can see it is based on which commmit. The -v flag specifies the version of the patch. For the first version of the the patch the flag is not needed. However when updating the patch, the version needs to be specified. The -3 specifies that the top 3 commits should be part of the patch series and a patch file will be created for each commit. The –cover-letter flag is necessary to also create a cover letter template file. This template file needs to be edited before sending out the patch.
To determine to whom to send the patches, the get_maintainer.pl script can be used. Its generally sufficient to the mailing list and the key maintainers.
If you want to send a copy to other recipients or mailing lists they can be added with the -cc switch. More than one -cc switch can be specified.
Patch series contain more than one patch. Instead of a patch file, it specifies a patch directory. Patch series require a so-called cover letter. The cover letter can be specified with –to-cover switch. The cover letter is free form and describes the change.
Here is a typical command:
To discuss review comments email clients are used. It is important that email clients are used that don’t change the email content. Not all email clients can be used for replying to review comments or to reply to the kernel mailing lists. This document describes which email clients can be used and how they need to be configured.
The next sections describes how to configure the mu email client. Why mu? mu automatically indexes the emails and provides some advanced capabilities to search for emails. In addition there is also a very nice integration for emacs which is called mu4e. The advantage is that code can easily be copied from an editor window to an email message. Also the mu4e package provides vim keybindings.
For some Linux distributions mu packages are available. For arch this is not the case and mu needs to be downloaded and built. To be able to build mu the following packages need to be installed:
The next step is to clone the mu repository, build mu and install it.
The website also contains the documentation for the mu package.
To use mu, mu needs to index the emails and the user needs to specify the directory where the emails are stored.
The following sections describe the changes to the emacs configuration. Keep in mind that when you use a different email service provider some changes are necessary.
To be able to use the mu4e emacs integration, the package needs to be first enabled in the list of packages in init.el
The corresponding section in the file init.el should look like the above
snippet. The easiest way to open the file is to press
space-f-p and select
the file init.el. The same key combination can also be used for config.el
In the file packages.el add the following line, so that the package can be found (it was manually installed in the previous step). It also loads the pinentry package so it can read the encrypted password.
Finally configure the package in the file config.el. It firsts starts the pinentry program to be able to read the encrypted password and enables the gpg agent with ssh support. Then it configures how to send the email, and the key folders. The list of folders can easily be changed and extended as needed.
In case you are behind a proxy, the settings for smtpmail-smtp-server and smtp-mail-smtp-service need to be changed accordingly.
Update the emacs configuration with:
To be able to automatically download emails in the background, two systemd user services are defined: a timer service and a mbsync service. Let’s first create the timer service. Create the file mbsync.timer in the directory ~/.config/systemd/user.
Now lets create the file to define the mbsync service. The service definition file is called mbsync.service and is also stored in the directory ~/.config/systemd/user.
In addition also a post script can be defined that creates a desktop notification once new mail arrives. This should be added in the [Service] definition above after the ExecStart clause.
As an example a very simple script could look like this. The path to icon most likely needs to be adapted on your system.
Now its time to create the new services:
Depending on your linux version you might have to enable an entry in /etc/pinentry/prexec. On Arch Linux I have enabled pinentry-qt:
At this point new emails should be downloaded automatically. Once the user logs in, a dialog will be displayed to enter the passphrase. After that the credentials are cached.
This only gives a very brief overview of mu4e. The documentation does a very
good job of explaining the product. Once emacs is started, the email dashboard
can be opened with
m. It displays a screen similar to the following one:
New messages can be created and sent by pressing
C. Remember that vim key
bindings are enabled. Once you have created the email, it can be sent with the
ctrl-c. To abort sending an email,
ctrl-k can be
To retrieve the curent list of emails, the
J key can be used. This shows
the current list of emails in the selected folder. Emails can be read by pressing
return key. The cursor can be positioned to the next and previous with
vim users should feel at home).
If you want to reply to an email, press
R. It will ask you if you want to reply
to all users or only the sender. Once the reply has been composed, the email
can be sent with ctrl-c ctrl-c. A reply can be aborted with
When answering to emails use bottom posting. To make it obvious what your message is in response to, your message should be placed underneath the corresponding part in the previous email.
To make it easier to review patches, it helps to automatically colorize patches: removed lines are displayed in red and new lines are displayed in green. This is an example:
The following line needs to be added to the packages.el file:
and the following hook needs to be added to the config.el file: