1Introduction 2============ 3 4Lutok uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as 5its build system. These are used only when compiling the library from 6the source code package. If you want to install Lutok 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 Lutok successfully you need: 32 33* A standards-compliant C++ complier. 34* Lua 5.1 or greater. 35* pkg-config. 36 37Optionally, if you want to build and run the tests (recommended), you 38need: 39 40* Kyua 0.5 or greater. 41* ATF 0.15 or greater. 42 43If you are building Lutok 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 Lutok from code extracted from 58the repository, you must first regenerate the files used by the build 59system. You will also need to do this if you modify configure.ac, 60Makefile.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. Install the library by running 'make install'. You may need to 91 become root to issue this step. 92 934. Issue any manual installation steps that may be required. These are 94 described later in their own section. 95 965. Check that the installed library works by running 'make 97 installcheck'. You do not need to be root to do this. 98 99 100Configuration flags 101=================== 102 103The 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 116The 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 167Run the tests! 168============== 169 170Lastly, after a successful installation (and assuming you built the 171sources with support for ATF), you should periodically run the tests 172from the final location to ensure things remain stable. Do so as 173follows: 174 175 $ kyua test -k /usr/local/tests/lutok/Kyuafile 176 177And if you see any tests fail, do not hesitate to report them in: 178 179 https://github.com/jmmv/lutok/issues/ 180 181Thank you! 182