INSTALL

   1 Introduction
   2 ============
   3
   4 Lutok uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as
   5 its build system.  These are used only when compiling the library from
   6 the source code package.  If you want to install Lutok 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 Lutok successfully you need:
  32
  33 * A standards-compliant C++ complier.
  34 * Lua 5.1 or greater.
  35 * pkg-config.
  36
  37 Optionally, if you want to build and run the tests (recommended), you
  38 need:
  39
  40 * Kyua 0.5 or greater.
  41 * ATF 0.15 or greater.
  42
  43 If you are building Lutok 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 Lutok from code extracted from
  58 the 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. Install the library by running 'make install'.  You may need to
  91    become root to issue this step.
  92
  93 4. Issue any manual installation steps that may be required.  These are
  94    described later in their own section.
  95
  96 5. Check that the installed library works by running 'make
  97    installcheck'.  You do not need to be root to do this.
  98
  99
 100 Configuration flags
 101 ===================
 102
 103 The most common, standard flags given to 'configure' are:
 104
 105 * --prefix=directory
 106   Possible values: Any path
 107   Default: /usr/local
 108
 109   Specifies where the library (binaries and all associated files) will
 110   be installed.
 111
 112 * --help
 113   Shows information about all available flags and exits immediately,
 114   without running any configuration tasks.
 115
 116 The following flags are specific to Lutok's 'configure' script:
 117
 118 * --enable-developer
 119   Possible values: yes, no
 120   Default: 'yes' in Git HEAD builds; 'no' in formal releases.
 121
 122   Enables several features useful for development, such as the inclusion
 123   of debugging symbols in all objects or the enforcement of compilation
 124   warnings.
 125
 126   The compiler will be executed with an exhaustive collection of warning
 127   detection features regardless of the value of this flag.  However, such
 128   warnings are only fatal when --enable-developer is 'yes'.
 129
 130 * --with-atf
 131   Possible values: yes, no, auto.
 132   Default: auto.
 133
 134   Enables usage of ATF to build (and later install) the tests.
 135
 136   Setting this to 'yes' causes the configure script to look for ATF
 137   unconditionally and abort if not found.  Setting this to 'auto' lets
 138   configure perform the best decision based on availability of ATF.
 139   Setting this to 'no' explicitly disables ATF usage.
 140
 141   When support for tests is enabled, the build process will generate the
 142   test programs and will later install them into the tests tree.
 143   Running 'make check' or 'make installcheck' from within the source
 144   directory will cause these tests to be run with Kyua (assuming it is
 145   also installed).
 146
 147 * --with-doxygen
 148   Possible values: yes, no, auto or a path.
 149   Default: auto.
 150
 151   Enables usage of Doxygen to generate documentation for internal APIs.
 152
 153   Setting this to 'yes' causes the configure script to look for Doxygen
 154   unconditionally and abort if not found.  Setting this to 'auto' lets
 155   configure perform the best decision based on availability of Doxygen.
 156   Setting this to 'no' explicitly disables Doxygen usage.  And, lastly,
 157   setting this to a path forces configure to use a specific Doxygen
 158   binary, which must exist.
 159
 160   When support for Doxygen is enabled, the build process will generate
 161   HTML documentation for the Lutok API.  This documentation will later
 162   be installed in the HTML directory specified by the configure script.
 163   You can change the location of the HTML documents by providing your
 164   desired override with the '--htmldir' flag to the configure script.
 165
 166
 167 Run the tests!
 168 ==============
 169
 170 Lastly, after a successful installation (and assuming you built the
 171 sources with support for ATF), you should periodically run the tests
 172 from the final location to ensure things remain stable.  Do so as
 173 follows:
 174
 175     $ kyua test -k /usr/local/tests/lutok/Kyuafile
 176
 177 And if you see any tests fail, do not hesitate to report them in:
 178
 179     https://github.com/jmmv/lutok/issues/
 180
 181 Thank you!