doc/vlunnr.cfg.5.scd

   1 VLUNNER.CFG(5) "" "Configuration for vlunner(1)"
   2
   3 # NAME
   4
   5 The file must be named 'vlunner.cfg' within the working directory of the
   6 vlunner process.
   7
   8 # SYNTAX
   9
  10 The file must be written in valid UTF-8.
  11
  12 The syntax follows generic TOML syntax. As a general overview:
  13
  14 ```
  15 root_element = "abc"
  16
  17 [table]
  18 table_element = [
  19         "array_value"
  20 ]
  21
  22 [[array]]
  23 a = "x"
  24
  25 [[array]]
  26 b = "y"
  27
  28 [[array]]
  29 c = "z"
  30 ```
  31
  32 Would be roughly equivalent to the following JSON:
  33
  34 ```
  35 {
  36         "root_element": "abc",
  37         "table": {
  38                 "table_element": [
  39                         "array_value"
  40                 ]
  41         },
  42         "array": [
  43                 {
  44                         "a": "x"
  45                 },
  46                 {
  47                         "y": "b"
  48                 },
  49                 {
  50                         "c": "z"
  51                 }
  52         ]
  53 }
  54 ```
  55
  56 ## Valid values
  57
  58 There are several types for valid values in TOML:
  59
  60 - String
  61 - Number
  62 - Boolean
  63 - Array
  64 - Table
  65
  66 Arrays and Tables are special since they can contain more TOML data within them.
  67 However, the exact TOML spec will not be listed here.
  68
  69 # CONFIGURATION
  70
  71 *vlunnr.cfg* is used to configure *vlunnr*(1), which uses the configuration to
  72 determine default behaviour and file inclusion processes.
  73
  74 *run_cmd*: Array of Strings
  75
  76         Each item within this array denotes an argument to pass, with the first one
  77         being the equivalent of *argv[0]* in C, or *$0* in Bash. *String
  78         Substitution* is done on these parameters.
  79
  80         Example: '["qemu-system-i386", "{disk}", "-serial", "stdio"]'
  81
  82 *limine_path*: String (optional)
  83
  84         Path to the Limine EFI binaries. If not specified, it defaults to
  85         *./limine*. The path may be relative or absolute.
  86
  87         Example: '/usr/share/limine'
  88
  89 *limine_conf*: String (optional)
  90
  91         Path to *limine.conf* file. This will be placed in the root of the EFI
  92         system partition of the generated image. Default is *./limine.conf*. The
  93         path may be relative or absolute.
  94
  95         Example: './limine.conf'
  96
  97 *test_cmd*: Array of Strings (optional)
  98
  99         As *run_cmd*, but only used when using *cargo test*. The default is the
 100         same as *run_cmd*.
 101
 102         Example: '["qemu-system-i386", "{disk}", "-serial", "stdio", "-s", "-S"]'
 103
 104 *disk_path*: String (optional)
 105
 106         A path to place a copy of the disk image for later inspection. Default is
 107         empty, which means no image copy is generated.
 108
 109 *target_name*: String (optional)
 110
 111         What to name the target when placed onto the disk image, which is primarily
 112         used to keep a consistent *limine_conf*. Defaults to empty, which means no
 113         renaming is performed, and the filename is retained from *cargo*.
 114
 115 *test_timeout*: Integer (optional)
 116
 117         How long the runner should wait on the test before timing out and failing
 118         the test. This is measured in seconds. The default is 300, which gives 5
 119         minutes before timeout. A value of 0 means vlunnr will never timeout the
 120         test.
 121
 122 *test_success_status*: Integer (optional)
 123
 124         The return status that is expected when running a test, which indicates
 125         success. Default is 0.
 126
 127 *extra_items*: Array of Paths (optional)
 128
 129         Any extra files or directories to copy onto the image. These will first be
 130         copied to a temporary directory, which will then be used to create the disk
 131         image. If nothing is specified, nothing is copied onto the disk image except
 132         for the Limine bootloader, binary image, and Limine configuration.
 133
 134         For perserving a file tree, it's best to put that file tree into a
 135         directory, since *vlunnr*(1) will then preserve it by doing a recursive
 136         copy.
 137
 138 # STRING SUBSTITUTION
 139
 140 A number of parameters must be specified at the time of execution of *vlunnr*.
 141 For example, *cargo*(1) will pass the target binary's path to *vlunnr*, which
 142 might not be the same each time. To get around this, string substitution may be
 143 used for certain variable paths or strings. Defining custom variables is NOT
 144 supported.
 145
 146 Each variable may be substituted into *run_cmd* or *test_cmd*, at any point
 147 within any index except the 0th index (i.e, the program name). To do this,
 148 surround the variable name with *{}*.
 149
 150 ## VARIABLES
 151
 152         *disk*: The path to the generated disk image.
 153
 154         *bin*: The path to the renamed target binary.
 155
 156         *target*: The path that *cargo* passed to *vlunnr* for the binary.
 157
 158 # SEE ALSO
 159
 160 *vlunnr*(1), *cargo*(1)
 161
 162 # AUTHORS
 163
 164 *vlunnr*(1), and *vlunnr.cfg* syntax are maintained by _Ayzee Patton
 165 <vlpatton@vlpatton.gay>_. You may find sources at
 166 _<https://git.vlpatton.gay/?p=vlunner.git>_.