contrib/kyua/doc/kyua.conf.5.in

   1 .\" Copyright 2012 The Kyua Authors.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions are
   6 .\" met:
   7 .\"
   8 .\" * Redistributions of source code must retain the above copyright
   9 .\"   notice, this list of conditions and the following disclaimer.
  10 .\" * Redistributions in binary form must reproduce the above copyright
  11 .\"   notice, this list of conditions and the following disclaimer in the
  12 .\"   documentation and/or other materials provided with the distribution.
  13 .\" * Neither the name of Google Inc. nor the names of its contributors
  14 .\"   may be used to endorse or promote products derived from this software
  15 .\"   without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  20 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  21 .\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  27 .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .Dd February 20, 2015
  29 .Dt KYUA.CONF 5
  30 .Os
  31 .Sh NAME
  32 .Nm kyua.conf
  33 .Nd Configuration file for the kyua tool
  34 .Sh SYNOPSIS
  35 .Fn syntax "int version"
  36 .Pp
  37 Variables:
  38 .Va architecture ,
  39 .Va platform ,
  40 .Va test_suites ,
  41 .Va unprivileged_user .
  42 .Sh DESCRIPTION
  43 The configuration of Kyua is a simple collection of key/value pairs called
  44 configuration variables.
  45 There are configuration variables that have a special meaning to the runtime
  46 engine implemented by
  47 .Xr kyua 1 ,
  48 and there are variables that only have meaning in the context of particular
  49 test suites.
  50 .Pp
  51 Configuration files are Lua scripts.
  52 In their most basic form, their whole purpose is to assign values to
  53 variables, but the user has the freedom to implement any logic he desires
  54 to compute such values.
  55 .Ss File versioning
  56 Every
  57 .Nm
  58 file starts with a call to
  59 .Fn syntax "int version" .
  60 This call determines the specific schema used by the file so that future
  61 backwards-incompatible modifications to the file can be introduced.
  62 .Pp
  63 Any new
  64 .Nm
  65 file should set
  66 .Fa version
  67 to
  68 .Sq 2 .
  69 .Ss Runtime configuration variables
  70 The following variables are internally recognized by
  71 .Xr kyua 1 :
  72 .Bl -tag -width XX -offset indent
  73 .It Va architecture
  74 Name of the system architecture (aka processor type).
  75 .It Va parallelism
  76 Maximum number of test cases to execute concurrently.
  77 .It Va platform
  78 Name of the system platform (aka machine type).
  79 .It Va unprivileged_user
  80 Name or UID of the unprivileged user.
  81 .Pp
  82 If set, the given user must exist in the system and his privileges will be
  83 used to run test cases that need regular privileges when
  84 .Xr kyua 1
  85 is executed as root.
  86 .El
  87 .Ss Test-suite configuration variables
  88 Each test suite is able to recognize arbitrary configuration variables, and
  89 their type and meaning is specific to the test suite.
  90 Because the existence and naming of these variables depends on every test
  91 suite, this manual page cannot detail them; please refer to the documentation
  92 of the test suite you are working with for more details on this topic.
  93 .Pp
  94 Test-suite specific configuration variables are defined inside the
  95 .Va test_suites
  96 dictionary.
  97 The general syntax is:
  98 .Bd -literal -offset indent
  99 test_suites.<test_suite_name>.<variable_name> = <value>
 100 .Ed
 101 .Pp
 102 where
 103 .Va test_suite_name
 104 is the name of the test suite,
 105 .Va variable_name
 106 is the name of the variable to set, and
 107 .Va value
 108 is a value.
 109 The value can be a string, an integer or a boolean.
 110 .Sh FILES
 111 .Bl -tag -width XX
 112 .It __EGDIR__/kyua.conf
 113 Sample configuration file.
 114 .El
 115 .Sh EXAMPLES
 116 The following
 117 .Nm
 118 shows a simple configuration file that overrides a bunch of the built-in
 119 .Xr kyua 1
 120 configuration variables:
 121 .Bd -literal -offset indent
 122 syntax(2)
 123
 124 architecture = 'x86_64'
 125 platform = 'amd64'
 126 .Ed
 127 .Pp
 128 The following is a more complex example that introduces the definition of
 129 per-test suite configuration variables:
 130 .Bd -literal -offset indent
 131 syntax(2)
 132
 133 -- Assign built-in variables.
 134 unprivileged_user = '_tests'
 135
 136 -- Assign test-suite variables.  All of these must be strings.
 137 test_suites.NetBSD.file_systems = 'ffs ext2fs'
 138 test_suites.X11.graphics_driver = 'vesa'
 139 .Ed
 140 .Sh SEE ALSO
 141 .Xr kyua 1