[PATCH RFC 2/4] doc: add CONFIGURATION file describing the cfgfile
jacob.e.keller at intel.com
Fri Mar 14 17:15:59 PDT 2014
This patch adds a CONFIGURATION file which describes the aiaiai
configuration file. This will be expanded upon in future commits which
introduce the aiaiai hooks.
Signed-off-by: Jacob Keller <jacob.e.keller at intel.com>
doc/README | 7 ++-
doc/email/CONFIGURATION | 158 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 164 insertions(+), 1 deletion(-)
create mode 100644 doc/email/CONFIGURATION
diff --git a/doc/README b/doc/README
index 544d365d365c..28e0bca3b820 100644
@@ -105,8 +105,13 @@ The 'aiaiai-test-patchset' script does all the testing work and outputs the
test results to stdout. 'aiaiai-email-test-patchset' captures the output and
sends it back to the patch submitter.
+1.2 Email Configuration
-1.2 Non-e-mail scripts
+aiaiai-email scripts use a common configuration file, which is documented in
+1.3 Non-e-mail scripts
diff --git a/doc/email/CONFIGURATION b/doc/email/CONFIGURATION
new file mode 100644
@@ -0,0 +1,158 @@
+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.
+ These settings change the name and email address which the scripts will
+ reply as.
+ 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.
+ Temporary location used to store kernel trees for compiling, as well as
+ other various temporary files generated by the aiaiai-email scripts
+ 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.
+ 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.
+ 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.
+ 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.
+ 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 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.
+ 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
+ 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.3 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 "aiaiai at aiaiai.net" then you can send the email to
+"aiaiai+project at aiaiai.net" which aiaiai can extract the +project to determine
+which project to use for that patch series. See the README for more information
+The per-project settings always override the default settings, and are not
+ 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.
+ 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.
+ 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.
+ A boolean (0 or 1) indicating whether to reply to all addresses or only the
+ original sender.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ A boolean (0 or 1) indicating whether to use the sparse tool during static
+ A boolean (0 or 1) indicating whether to use the smatch tool during static
+ A boolean (0 or 1) indicating whether to use the cppcheck tool during static
+ A boolean (0 or 1) indicating whether to use the coccinelle scripts during
+ static analysis.
+The following options do not have default settings per project and must be
+specified for each project.
+ A human readable name for the project
+ A short one line projet description, that should start with a lowercase letter.
+ 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.
More information about the aiaiai