contrib/kyua/INSTALL.md

   1 Installation instructions
   2 =========================
   3
   4 Kyua uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as
   5 its build system.  These are used only when compiling the application
   6 from the source code package.  If you want to install Kyua from a binary
   7 package, you do not need to read this document.
   8
   9 For 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
  19 Or 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
  28 Dependencies
  29 ------------
  30
  31 To 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
  38 To 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
  43 If you are building Kyua from the code on the repository, you will also
  44 need the following tools:
  45
  46 * GNU Autoconf.
  47 * GNU Automake.
  48 * GNU Libtool.
  49
  50
  51 Regenerating the build system
  52 -----------------------------
  53
  54 This is not necessary if you are building from a formal release
  55 distribution file.
  56
  57 On the other hand, if you are building Kyua from code extracted from the
  58 repository, you must first regenerate the files used by the build
  59 system.  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
  61 run:
  62
  63     $ autoreconf -i -s
  64
  65 If ATF is installed in a different prefix than Autoconf, you will also
  66 need to tell autoreconf where the ATF M4 macros are located.  Otherwise,
  67 the configure script will be incomplete and will show confusing syntax
  68 errors mentioning, for example, `ATF_CHECK_SH`.  To fix this, you have
  69 to run autoreconf in the following manner, replacing `<atf-prefix>` with
  70 the appropriate path:
  71
  72     $ autoreconf -i -s -I <atf-prefix>/share/aclocal
  73
  74
  75 General build procedure
  76 -----------------------
  77
  78 To build and install the source package, you must follow these steps:
  79
  80 1. 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
  86 2. 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
  90 3. 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
  94 4. Install the program by running `make install`.  You may need to
  95    become root to issue this step.
  96
  97 5. Issue any manual installation steps that may be required.  These are
  98    described later in their own section.
  99
 100 6. 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
 105 Configuration flags
 106 -------------------
 107
 108 The 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
 130 The following environment variables are specific to Kyua's `configure`
 131 script:
 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
 182 The 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
 230 Post-installation steps
 231 -----------------------
 232
 233 Copy the `Kyuafile.top` file installed in the examples directory to the
 234 root 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
 239 This will allow you to simply go into `/usr/tests` and run the tests
 240 from there.
 241
 242
 243 Run the tests!
 244 --------------
 245
 246 Lastly, after a successful installation, you should periodically run the
 247 tests from the final location to ensure things remain stable.  Do so as
 248 follows:
 249
 250     $ cd /usr/local/kyua && kyua test
 251
 252 The following configuration variables are specific to the 'kyua' test
 253 suite 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
 264 If you see any tests fail, do not hesitate to report them in:
 265
 266     https://github.com/jmmv/kyua/issues/
 267
 268 Thank you!