1 Installation instructions
2 =========================
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.
19 Or alternatively, install as a regular user into your home directory:
21 $ ./configure --prefix ~/local
31 To build and use Kyua successfully you need:
33 * A standards-compliant C and C++ complier.
38 To build the Kyua tests, you optionally need:
40 * The Automated Testing Framework (ATF), version 0.15 or greater. This
41 is required if you want to create a distribution file.
43 If you are building Kyua from the code on the repository, you will also
44 need the following tools:
51 Regenerating the build system
52 -----------------------------
54 This is not necessary if you are building from a formal release
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
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
72 $ autoreconf -i -s -I <atf-prefix>/share/aclocal
75 General build procedure
76 -----------------------
78 To build and install the source package, you must follow these steps:
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.
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.
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
94 4. Install the program by running `make install`. You may need to
95 become root to issue this step.
97 5. Issue any manual installation steps that may be required. These are
98 described later in their own section.
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.
108 The most common, standard flags given to `configure` are:
110 * `--prefix=directory`:
111 **Possible values:** Any path.
112 **Default:** `/usr/local`.
114 Specifies where the program (binaries and all associated files) will
117 * `--sysconfdir=directory`:
118 **Possible values:** Any path.
119 **Default:** `/usr/local/etc`.
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.
127 Shows information about all available flags and exits immediately,
128 without running any configuration tasks.
130 The following environment variables are specific to Kyua's `configure`
134 **Possible values:** empty, absolute path to GNU GDB.
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.
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`.
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.
151 **Possible values:** empty, a relative path.
154 Specifies the subdirectory of the configuration directory (given by
155 the `--sysconfdir` argument) under which Kyua will search for its
158 * `KYUA_CONFIG_FILE_FOR_CHECK`:
159 **Possible values:** none, an absolute path to an existing file.
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.
168 **Possible values:** name of a machine type (e.g. `amd64`, `macppc`).
169 **Default:** autodetected; typically the output of `uname -m`.
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
176 **Possible values:** an absolute path to a temporary directory.
179 Specifies the path that Kyua will use to create temporary directories
182 The following flags are specific to Kyua's `configure` script:
184 * `--enable-developer`:
185 **Possible values:** `yes`, `no`.
186 **Default:** `yes` in Git `HEAD` builds; `no` in formal releases.
188 Enables several features useful for development, such as the inclusion
189 of debugging symbols in all objects or the enforcement of compilation
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`.
197 **Possible values:** `yes`, `no`, `auto`.
200 Enables usage of ATF to build (and later install) the tests.
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.
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.
213 **Possible values:** `yes`, `no`, `auto` or a path.
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
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.
230 Post-installation steps
231 -----------------------
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:
236 # cp /usr/local/share/kyua/examples/Kyuafile.top \
237 /usr/local/tests/Kyuafile
239 This will allow you to simply go into `/usr/tests` and run the tests
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
250 $ cd /usr/local/kyua && kyua test
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>`:
256 * `run_coredump_tests`:
257 **Possible values:** `true` or `false`.
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.
264 If you see any tests fail, do not hesitate to report them in:
266 https://github.com/jmmv/kyua/issues/