| 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 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 |
| times. |
| |
| 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 "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. |
| * 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. |
| * checkpatch |
| A boolean (0 or 1) indicating whether to use checkpatch.pl 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 |
| hooks.email 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. |
| |