blob: e9e7fa46c8ffc851b01e68dab64eb89f2f00dfab [file] [log] [blame]
1 Overview
aiaiai-email scripts can be configured using the configuration file, which
includes many options for customizing the behavior of the aiaiai testing
process. Most of these values are specified "per-project" which allows the
ability for a single aiaiai-email setup to handle multiple different
repositories or kernels. This document describes and explains each
configuration option, and also includes some sections specific to complex
The configuration file is in INI format, and generally is designed to be human
editable. Each section will be described below.
2.1 Global Settings
The global configuration settings are recognized by various email scripts,
though mostly have to deal with aiaiai-email-test-patchset.
* ownname
* ownmail
These settings change the name and email address which the scripts will
reply as.
* adminname
* adminmail
The address to reply to when attempting to contact a real person about the
aiaiai-email setup. It will also modify the reply-to email header so that
replies by default go to the administrator.
* workdir
Temporary location used to store kernel trees for compiling, as well as
other various temporary files generated by the aiaiai-email scripts
* max_validators
The maximum number of validators to run in parallel. This can be used to
allow concurrent validation of different patches or patch series at the
same time. Be careful to ensure your test machine has enough CPU to handle
extra validators.
* jobs
Passed directly into the make commands, which allows make to parallelize
its proccess. Not to be confused with the max_validators parameter. Be
careful to ensure you have enough CPU for this.
* preamble
Location of a file which contains text. This text is used to supply the
start of every email sent by the aiaiai-email-scripts. Useful to customize
the header of each email, or to provide information for users about what
the system is for.
* signature
A line of text to end every email sent by aiaiai. Don't end with
punctuation, as the email script will add suitable punctuation for you.
* built_preamble
A line of text that is inserted if the patch or series passes the
validation without error. Don't end with puncuation as aiaiai does this for
2.2 LDA Settings
These settings are used to configure the LDA aiaiai-email-lda program which is
used to process incoming emails and set up so that aiaiai-email-dispatcher can
find them via inotify. These replace the older --reap* options passed to
aiaiai-email-lda by hand.
* reap_archive
This option will cause the LDA to reap (remove) all archived email older
than the specified number of minutes. Useful if you want to save some disk
space and don't want to retain archived emails.
* reap_incomplete
This option will cause the LDA to reap (remove) all incomplete series older
than the specified number of minutes. Useful if people keep sending
incomplete series or other internal issues cause series to remain for long
2.3 Debug Settings
These settings are generally not useful, but can be helpful for debugging
issues with aiaiai email scripts. These have replaced options which used to
perform the same behavior.
* disable_notifications
This option disables all emails sent by the email scripts. Their contents
will still be displayed in the stdout of the respective process, but no
actual replies will be sent. This replaces the old "--test-mode" command line
option. This is useful to prevent spam emails from being generated when
testing changes to aiaiai
* preserve_files
This option modifies the behavior so that no files will be cleaned up on
exit. Very useful if you need to inspect individual results or generated
files. This replaces the old "-p" option.
2.4 Default Project Settings
Settings described here can either appear in the [defaults] section or in the
[prj_<project>] sections, where <project> specifies a project name. A project
is specified when sending the email to a special address. For example, if the
aiaiai address is "" then you can send the email to
"" which aiaiai can extract the +project to determine
which project to use for that patch series. See the README for more information
about projects.
The per-project settings always override the default settings, and are not
* configs
A space seperated list of defconfig,arch,cross-compiler (no spaces). The
arch and cross-compiler are optional. Defconfig name should reside inside
the kernel, or possibly inside the defconfigdir as specified by other
option. Multiple configs are supported by seperating with spaces. Each
config will be tested. See the example-aiaiai.cfg for details and examples.
* always_cc
A comma seperated list of addresses to always Cc when creating replies. For
example, it could be a mailing list to which all aiaiai replies go.
* reply_to_all
A boolean (0 or 1) indicating whether to reply to all addresses or only the
original sender.
* accept_notify
A boolean (0 or 1) indicating whether to send an acceptance mail which
tells the submitter that aiaiai has begun work on the patch or series.
* unwanted_keywords
Path to a file containing unwanted keywords (one keyword per line). Aiaiai
will check the patch against this list and notify if any keywords were
found. This might be useful to help prevent some internal confidential
names don't leak through commit messages or commentaries.
* kmake_opts
A list of additional kernel build options which are appended to the make
command used to compile the kernel. Useful to change the level of warnings,
for example.
* targets
A list of kernel build targets, space seperated. Note that all is only
implicit if the target lits is empty. If you assign a value, such as
namespacecheck, then all is not included by default and you will have to
add it to the list.
* defconfigdir
Path to a directory containing the defconfigs. Useful if your
configurations are not included in the kernel tree. If you specify a
defconfigdir, then all configurations must reside in it, as aiaiai will not
check the kernel directory for configs.
* bisectability
A boolean (0 or 1) indicating whether to check if patch series can be
compiled inbetween each patch. Useful to ensure that patch series don't
break git-bisect.
* sparse
A boolean (0 or 1) indicating whether to use the sparse tool during static
* smatch
A boolean (0 or 1) indicating whether to use the smatch tool during static
* cppcheck
A boolean (0 or 1) indicating whether to use the cppcheck tool during static
* coccinelle
A boolean (0 or 1) indicating whether to use the coccinelle scripts during
static analysis.
* checkpatch
A boolean (0 or 1) indicating whether to use for testing
patches. Requires kernel project with checkpatch provided.
The following options do not have default settings per project and must be
specified for each project.
* name
A human readable name for the project
* description
A short one line projet description, that should start with a lowercase letter.
* path
Path to the kernel source tree of the project. Note aiaiai does not treat
this directory as read-only, and never changes anything htere. This does
mean that aiaiai does not automatically update the tree for you. You could
use something like a cronjob to update the tree, or any other method. It
also does not depend on the tree being (or not) bare, so you can feel free
to make this a bare remote or a local tree. Generally, aiaiai works best if
the tree is locally stored on the same machine as the aiaiai process.
* branch
What git refspec to validate against. Usually this should be a remote
branch ie: origin/master, but can actually be any refspec. Note that the
defconfigs specified in the config option must actually be available from
the refspec.
* canonical_url
The url to use when displaying a url for user consumption. Intended to be a
patch-submitter visible mirror of the local path used internally. If not
supplied, aiaiai will display the path instead.
2.5 Hooks
The [hooks] section contains settings for various points where a hook can be
run to customize the behavior of aiaiai. Generally, hooks should output
mbox-style headers, which the aiaiai program will parse for required
information. Only certain headers are supported, outlined below.
A hook is expected to return zero for successful runs, 127 for patch rejection,
and any other non zero value at run-time error. In addition, for a zero return
status, the output should be a list of headers outlined below, (one per line)
which will be parsed by aiaiai for customizing behavior. For 127 exit status,
the stdout will be used for creating a subsequent response email, and it should
contain information explaining to the user why the hook rejected the patch. For
other non-zero exit status, the output is ignored.
Hooks are passed the configuration file, and the mbox file for processing and
therefor have full access to the configuration file. Discretion should be used
if adding custom variables to the configuration file such that the hook won't
have a namespace collission with regular aiaiai configuration options.
The only currently supported hook is the email hook configured by setting to the path of an executable script.
2.5.1 Email Hook
This hook is run from within aiaiai-email-test-patchset, and is run just prior
to determining the project. This hook can be used to customize the behavior and
settings of aiaiai-email-test-patchset. Primarily it can be used to implement
any kind of patch-rejection scheme desired, as well as use the following
headers to customize various aspects of aiaiai.
* X-Aiaiai-Project
This header indicates to email-test-patchset which project the patch series
belongs to. This overrides the default +prj format from the cfg_ownmail
address. This can be used to implement any elaborate scheme desired for
determining the project, instead of relying on users mailing patches to the
correct email address.
* X-Aiaiai-Commit
This header indicates what commit to test against instead of the default
refspec supplied by the project. It can be used to implement some form of
patch-version detection, or other setup. It likely should be used in tandem
with the X-Aiaiai-Project setting.