1Installation instructions 2========================= 3 4Kyua uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as 5its build system. These are used only when compiling the application 6from the source code package. If you want to install Kyua from a binary 7package, you do not need to read this document. 8 9For the impatient: 10 11 $ ./configure 12 $ make 13 $ make check 14 Gain root privileges 15 # make install 16 Drop root privileges 17 $ make installcheck 18 19Or alternatively, install as a regular user into your home directory: 20 21 $ ./configure --prefix ~/local 22 $ make 23 $ make check 24 $ make install 25 $ make installcheck 26 27 28Dependencies 29------------ 30 31To build and use Kyua successfully you need: 32 33* A standards-compliant C and C++ complier. 34* Lutok 0.4. 35* pkg-config. 36* SQLite 3.6.22. 37 38To build the Kyua tests, you optionally need: 39 40* The Automated Testing Framework (ATF), version 0.15 or greater. This 41 is required if you want to create a distribution file. 42 43If you are building Kyua from the code on the repository, you will also 44need the following tools: 45 46* GNU Autoconf. 47* GNU Automake. 48* GNU Libtool. 49 50 51Regenerating the build system 52----------------------------- 53 54This is not necessary if you are building from a formal release 55distribution file. 56 57On the other hand, if you are building Kyua from code extracted from the 58repository, you must first regenerate the files used by the build 59system. You will also need to do this if you modify `configure.ac`, 60`Makefile.am` or any of the other build system files. To do this, simply 61run: 62 63 $ autoreconf -i -s 64 65If ATF is installed in a different prefix than Autoconf, you will also 66need to tell autoreconf where the ATF M4 macros are located. Otherwise, 67the configure script will be incomplete and will show confusing syntax 68errors mentioning, for example, `ATF_CHECK_SH`. To fix this, you have 69to run autoreconf in the following manner, replacing `<atf-prefix>` with 70the appropriate path: 71 72 $ autoreconf -i -s -I <atf-prefix>/share/aclocal 73 74 75General build procedure 76----------------------- 77 78To build and install the source package, you must follow these steps: 79 801. Configure the sources to adapt to your operating system. This is 81 done using the `configure` script located on the sources' top 82 directory, and it is usually invoked without arguments unless you 83 want to change the installation prefix. More details on this 84 procedure are given on a later section. 85 862. Build the sources to generate the binaries and scripts. Simply run 87 `make` on the sources' top directory after configuring them. No 88 problems should arise. 89 903. Check that the built programs work by running `make check`. You do 91 not need to be root to do this, but if you are not, some checks will 92 be skipped. 93 944. Install the program by running `make install`. You may need to 95 become root to issue this step. 96 975. Issue any manual installation steps that may be required. These are 98 described later in their own section. 99 1006. Check that the installed programs work by running `make 101 installcheck`. You do not need to be root to do this, but if you are 102 not, some checks will be skipped. 103 104 105Configuration flags 106------------------- 107 108The most common, standard flags given to `configure` are: 109 110* `--prefix=directory`: 111 **Possible values:** Any path. 112 **Default:** `/usr/local`. 113 114 Specifies where the program (binaries and all associated files) will 115 be installed. 116 117* `--sysconfdir=directory`: 118 **Possible values:** Any path. 119 **Default:** `/usr/local/etc`. 120 121 Specifies where the installed programs will look for configuration 122 files. `/kyua` will be appended to the given path unless 123 `KYUA_CONFSUBDIR` is redefined as explained later on. 124 125* `--help`: 126 127 Shows information about all available flags and exits immediately, 128 without running any configuration tasks. 129 130The following environment variables are specific to Kyua's `configure` 131script: 132 133* `GDB`: 134 **Possible values:** empty, absolute path to GNU GDB. 135 **Default:** empty. 136 137 Specifies the path to the GNU GDB binary that Kyua will use to gather a 138 stack trace of a crashing test program. If empty, the configure script 139 will try to find a suitable binary for you and, if not found, Kyua will 140 attempt to do the search at run time. 141 142* `KYUA_ARCHITECTURE`: 143 **Possible values:** name of a CPU architecture (e.g. `x86_64`, `powerpc`). 144 **Default:** autodetected; typically the output of `uname -p`. 145 146 Specifies the name of the CPU architecture on which Kyua will run. 147 This value is used at run-time to determine tests that are not 148 applicable to the host system. 149 150* `KYUA_CONFSUBDIR`: 151 **Possible values:** empty, a relative path. 152 **Default:** `kyua`. 153 154 Specifies the subdirectory of the configuration directory (given by 155 the `--sysconfdir` argument) under which Kyua will search for its 156 configuration files. 157 158* `KYUA_CONFIG_FILE_FOR_CHECK`: 159 **Possible values:** none, an absolute path to an existing file. 160 **Default:** none. 161 162 Specifies the `kyua.conf` configuration file to use when running any 163 of the `check`, `installcheck` or `distcheck` targets on this source 164 tree. This setting is exclusively used to customize the test runs of 165 Kyua itself and has no effect whatsoever on the built product. 166 167* `KYUA_MACHINE`: 168 **Possible values:** name of a machine type (e.g. `amd64`, `macppc`). 169 **Default:** autodetected; typically the output of `uname -m`. 170 171 Specifies the name of the machine type on which Kyua will run. This 172 value is used at run-time to determine tests that are not applicable 173 to the host system. 174 175* `KYUA_TMPDIR`: 176 **Possible values:** an absolute path to a temporary directory. 177 **Default:** `/tmp`. 178 179 Specifies the path that Kyua will use to create temporary directories 180 in by default. 181 182The following flags are specific to Kyua's `configure` script: 183 184* `--enable-developer`: 185 **Possible values:** `yes`, `no`. 186 **Default:** `yes` in Git `HEAD` builds; `no` in formal releases. 187 188 Enables several features useful for development, such as the inclusion 189 of debugging symbols in all objects or the enforcement of compilation 190 warnings. 191 192 The compiler will be executed with an exhaustive collection of warning 193 detection features regardless of the value of this flag. However, such 194 warnings are only fatal when `--enable-developer` is `yes`. 195 196* `--with-atf`: 197 **Possible values:** `yes`, `no`, `auto`. 198 **Default:** `auto`. 199 200 Enables usage of ATF to build (and later install) the tests. 201 202 Setting this to `yes` causes the configure script to look for ATF 203 unconditionally and abort if not found. Setting this to `auto` lets 204 configure perform the best decision based on availability of ATF. 205 Setting this to `no` explicitly disables ATF usage. 206 207 When support for tests is enabled, the build process will generate the 208 test programs and will later install them into the tests tree. 209 Running `make check` or `make installcheck` from within the source 210 directory will cause these tests to be run with Kyua. 211 212* `--with-doxygen`: 213 **Possible values:** `yes`, `no`, `auto` or a path. 214 **Default:** `auto`. 215 216 Enables usage of Doxygen to generate documentation for internal APIs. 217 This documentation is *not* installed and is only provided to help the 218 developer of this package. Therefore, enabling or disabling Doxygen 219 causes absolutely no differences on the files installed by this 220 package. 221 222 Setting this to `yes` causes the configure script to look for Doxygen 223 unconditionally and abort if not found. Setting this to `auto` lets 224 configure perform the best decision based on availability of Doxygen. 225 Setting this to `no` explicitly disables Doxygen usage. And, lastly, 226 setting this to a path forces configure to use a specific Doxygen 227 binary, which must exist. 228 229 230Post-installation steps 231----------------------- 232 233Copy the `Kyuafile.top` file installed in the examples directory to the 234root of your tests hierarchy and name it `Kyuafile`. For example: 235 236 # cp /usr/local/share/kyua/examples/Kyuafile.top \ 237 /usr/local/tests/Kyuafile 238 239This will allow you to simply go into `/usr/tests` and run the tests 240from there. 241 242 243Run the tests! 244-------------- 245 246Lastly, after a successful installation, you should periodically run the 247tests from the final location to ensure things remain stable. Do so as 248follows: 249 250 $ cd /usr/local/kyua && kyua test 251 252The following configuration variables are specific to the 'kyua' test 253suite and can be given to Kyua with arguments of the form 254`-v test_suites.kyua.<variable_name>=<value>`: 255 256* `run_coredump_tests`: 257 **Possible values:** `true` or `false`. 258 **Default:** `true`. 259 260 Avoids running tests that crash subprocesses on purpose to make them 261 dump core. Such tests are particularly slow on macOS, and it is 262 sometimes handy to disable them for quicker development iteration. 263 264If you see any tests fail, do not hesitate to report them in: 265 266 https://github.com/jmmv/kyua/issues/ 267 268Thank you! 269