diff options
Diffstat (limited to 'INSTALL.md')
| -rw-r--r-- | INSTALL.md | 268 |
1 files changed, 268 insertions, 0 deletions
diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 000000000000..d3dcab49cb74 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,268 @@ +Installation instructions +========================= + +Kyua uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as +its build system. These are used only when compiling the application +from the source code package. If you want to install Kyua from a binary +package, you do not need to read this document. + +For the impatient: + + $ ./configure + $ make + $ make check + Gain root privileges + # make install + Drop root privileges + $ make installcheck + +Or alternatively, install as a regular user into your home directory: + + $ ./configure --prefix ~/local + $ make + $ make check + $ make install + $ make installcheck + + +Dependencies +------------ + +To build and use Kyua successfully you need: + +* A standards-compliant C and C++ complier. +* Lutok 0.4. +* pkg-config. +* SQLite 3.6.22. + +To build the Kyua tests, you optionally need: + +* The Automated Testing Framework (ATF), version 0.15 or greater. This + is required if you want to create a distribution file. + +If you are building Kyua from the code on the repository, you will also +need the following tools: + +* GNU Autoconf. +* GNU Automake. +* GNU Libtool. + + +Regenerating the build system +----------------------------- + +This is not necessary if you are building from a formal release +distribution file. + +On the other hand, if you are building Kyua from code extracted from the +repository, you must first regenerate the files used by the build +system. You will also need to do this if you modify `configure.ac`, +`Makefile.am` or any of the other build system files. To do this, simply +run: + + $ autoreconf -i -s + +If ATF is installed in a different prefix than Autoconf, you will also +need to tell autoreconf where the ATF M4 macros are located. Otherwise, +the configure script will be incomplete and will show confusing syntax +errors mentioning, for example, `ATF_CHECK_SH`. To fix this, you have +to run autoreconf in the following manner, replacing `<atf-prefix>` with +the appropriate path: + + $ autoreconf -i -s -I <atf-prefix>/share/aclocal + + +General build procedure +----------------------- + +To build and install the source package, you must follow these steps: + +1. Configure the sources to adapt to your operating system. This is + done using the `configure` script located on the sources' top + directory, and it is usually invoked without arguments unless you + want to change the installation prefix. More details on this + procedure are given on a later section. + +2. Build the sources to generate the binaries and scripts. Simply run + `make` on the sources' top directory after configuring them. No + problems should arise. + +3. Check that the built programs work by running `make check`. You do + not need to be root to do this, but if you are not, some checks will + be skipped. + +4. Install the program by running `make install`. You may need to + become root to issue this step. + +5. Issue any manual installation steps that may be required. These are + described later in their own section. + +6. Check that the installed programs work by running `make + installcheck`. You do not need to be root to do this, but if you are + not, some checks will be skipped. + + +Configuration flags +------------------- + +The most common, standard flags given to `configure` are: + +* `--prefix=directory`: + **Possible values:** Any path. + **Default:** `/usr/local`. + + Specifies where the program (binaries and all associated files) will + be installed. + +* `--sysconfdir=directory`: + **Possible values:** Any path. + **Default:** `/usr/local/etc`. + + Specifies where the installed programs will look for configuration + files. `/kyua` will be appended to the given path unless + `KYUA_CONFSUBDIR` is redefined as explained later on. + +* `--help`: + + Shows information about all available flags and exits immediately, + without running any configuration tasks. + +The following environment variables are specific to Kyua's `configure` +script: + +* `GDB`: + **Possible values:** empty, absolute path to GNU GDB. + **Default:** empty. + + Specifies the path to the GNU GDB binary that Kyua will use to gather a + stack trace of a crashing test program. If empty, the configure script + will try to find a suitable binary for you and, if not found, Kyua will + attempt to do the search at run time. + +* `KYUA_ARCHITECTURE`: + **Possible values:** name of a CPU architecture (e.g. `x86_64`, `powerpc`). + **Default:** autodetected; typically the output of `uname -p`. + + Specifies the name of the CPU architecture on which Kyua will run. + This value is used at run-time to determine tests that are not + applicable to the host system. + +* `KYUA_CONFSUBDIR`: + **Possible values:** empty, a relative path. + **Default:** `kyua`. + + Specifies the subdirectory of the configuration directory (given by + the `--sysconfdir` argument) under which Kyua will search for its + configuration files. + +* `KYUA_CONFIG_FILE_FOR_CHECK`: + **Possible values:** none, an absolute path to an existing file. + **Default:** none. + + Specifies the `kyua.conf` configuration file to use when running any + of the `check`, `installcheck` or `distcheck` targets on this source + tree. This setting is exclusively used to customize the test runs of + Kyua itself and has no effect whatsoever on the built product. + +* `KYUA_MACHINE`: + **Possible values:** name of a machine type (e.g. `amd64`, `macppc`). + **Default:** autodetected; typically the output of `uname -m`. + + Specifies the name of the machine type on which Kyua will run. This + value is used at run-time to determine tests that are not applicable + to the host system. + +* `KYUA_TMPDIR`: + **Possible values:** an absolute path to a temporary directory. + **Default:** `/tmp`. + + Specifies the path that Kyua will use to create temporary directories + in by default. + +The following flags are specific to Kyua's `configure` script: + +* `--enable-developer`: + **Possible values:** `yes`, `no`. + **Default:** `yes` in Git `HEAD` builds; `no` in formal releases. + + Enables several features useful for development, such as the inclusion + of debugging symbols in all objects or the enforcement of compilation + warnings. + + The compiler will be executed with an exhaustive collection of warning + detection features regardless of the value of this flag. However, such + warnings are only fatal when `--enable-developer` is `yes`. + +* `--with-atf`: + **Possible values:** `yes`, `no`, `auto`. + **Default:** `auto`. + + Enables usage of ATF to build (and later install) the tests. + + Setting this to `yes` causes the configure script to look for ATF + unconditionally and abort if not found. Setting this to `auto` lets + configure perform the best decision based on availability of ATF. + Setting this to `no` explicitly disables ATF usage. + + When support for tests is enabled, the build process will generate the + test programs and will later install them into the tests tree. + Running `make check` or `make installcheck` from within the source + directory will cause these tests to be run with Kyua. + +* `--with-doxygen`: + **Possible values:** `yes`, `no`, `auto` or a path. + **Default:** `auto`. + + Enables usage of Doxygen to generate documentation for internal APIs. + This documentation is *not* installed and is only provided to help the + developer of this package. Therefore, enabling or disabling Doxygen + causes absolutely no differences on the files installed by this + package. + + Setting this to `yes` causes the configure script to look for Doxygen + unconditionally and abort if not found. Setting this to `auto` lets + configure perform the best decision based on availability of Doxygen. + Setting this to `no` explicitly disables Doxygen usage. And, lastly, + setting this to a path forces configure to use a specific Doxygen + binary, which must exist. + + +Post-installation steps +----------------------- + +Copy the `Kyuafile.top` file installed in the examples directory to the +root of your tests hierarchy and name it `Kyuafile`. For example: + + # cp /usr/local/share/kyua/examples/Kyuafile.top \ + /usr/local/tests/Kyuafile + +This will allow you to simply go into `/usr/tests` and run the tests +from there. + + +Run the tests! +-------------- + +Lastly, after a successful installation, you should periodically run the +tests from the final location to ensure things remain stable. Do so as +follows: + + $ cd /usr/local/kyua && kyua test + +The following configuration variables are specific to the 'kyua' test +suite and can be given to Kyua with arguments of the form +`-v test_suites.kyua.<variable_name>=<value>`: + +* `run_coredump_tests`: + **Possible values:** `true` or `false`. + **Default:** `true`. + + Avoids running tests that crash subprocesses on purpose to make them + dump core. Such tests are particularly slow on macOS, and it is + sometimes handy to disable them for quicker development iteration. + +If you see any tests fail, do not hesitate to report them in: + + https://github.com/jmmv/kyua/issues/ + +Thank you! |