From: Jacob Keller Date: Sat, 15 Mar 2014 00:15:59 +0000 (-0700) Subject: doc: add CONFIGURATION file describing the cfgfile X-Git-Url: https://www.infradead.org/git/?a=commitdiff_plain;h=2fd02fa2933a106e7e6d7ca8f5f77fd6f2ef3d57;p=users%2Fdedekind%2Faiaiai.git doc: add CONFIGURATION file describing the cfgfile 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 Signed-off-by: Artem Bityutskiy --- diff --git a/doc/README b/doc/README index 544d365..28e0bca 100644 --- a/doc/README +++ b/doc/README @@ -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 +doc/email/example-aiaiai.cfg + +1.3 Non-e-mail scripts ~~~~~~~~~~~~~~~~~~~~~~ * aiaiai-test-patchset diff --git a/doc/email/CONFIGURATION b/doc/email/CONFIGURATION new file mode 100644 index 0000000..7e7af5b --- /dev/null +++ b/doc/email/CONFIGURATION @@ -0,0 +1,158 @@ +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 +settings. + +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 + you. + +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. + +* 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.3 Default Project Settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Settings described here can either appear in the [defaults] section or in the +[prj_] sections, where specifies a project name. A project +is specified when sending the email to a special address. For example, if the +aiaiai address is "aiaiai@aiaiai.net" then you can send the email to +"aiaiai+project@aiaiai.net" 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 +additive. + +* 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. +* 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. +* 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 + analysis. +* smatch + A boolean (0 or 1) indicating whether to use the smatch tool during static + analysis. +* cppcheck + A boolean (0 or 1) indicating whether to use the cppcheck tool during static + analysis. +* coccinelle + 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. + +* 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. +