Building the software

This page gives information about how to build the software. More...

This page gives information about how to build the software.

Page content:

Introduction

Dependencies are limited (see below), no 'cmake/autoconf' provided.
It does not use at present any C++11 features, so should compile using any recent/decent compiler. However, only GCC (Linux or Windows platforms) has been used and tested.
A custom makefile is provided, with several targets. It has been carefully adjusted so that is should run equally on Linux based systems and Windows (only XP-SP3 has been tested). Depending on your local machine, makefile might need some minor editing (paths).
For editing purposes only, several Codeblocks (http://www.codeblocks.org/) project files are provided, but don't try to use them for building, they are not maintained any more. Building capabilities (search paths, ...) are not maintained any more. For editing, the easiest is to load the codeblocks workspace that's in the root folder, it holds all the code.

Build timing: on a quad-core standard Linux/Ubuntu desktop, the following have been measured, following a make cleanall:

make app -j: 0m50.365s
make app: 1m21.056s

Build targets

The makefile has a lot of targets, some of them are dedicated to debugging and/or development tasks, here are only the ones that the end-user will find useful.

The most complete way to build the whole thing, assuming you have all that is required, is:

make all
make install

On Linux, you will need to 'sudo' the second line, of course. On Windows, you might need administrative privileges, as the default installation path is c:\program files.

This latter target also associates the .fis file extension to a mime type "Slifis-FIS", that itself is associated to the try-fis application.

Alternatively, if you don't want/need to rebuild the documentation, nor want to build'n'run the test suite, you can do:

make app
make install

This will only build the libraries and the demos and applications, and install it on the local machine, so it is available for the users apps. Replace app with lib to build only the two libraries (core + gapi).

If you don't have the graphical back-end library available on your machine and only want the core library, then it will be:

make core
make install

If you want to run the test suite:

make test

To build the documentation, html + pdf (assuming you have doxygen, latex and gnuplot installed):

make doc

Beware, this target needs

the graphical back-end library (as plots included in documentation are generated at run-time),
gnuplot, used to produce the sample 3d plots,
a valid Latex installation on local machine.

For a list of available targets, just run:

make

This should give the output below, showing all the targets. Please note that most of these are dev-oriented, the most important ones are listed above.

Please specify one of these targets:
 -core   : builds core library only (gapi lib not needed)
 -lib    : builds all the libraries (core + gapi)
 -app-cl : builds the command-line demos and applications (gapi lib not needed)
 -app    : builds the demos and applications (needs the gapi lib)
 -doc      : builds html and pdf documentation (needs the gapi lib)
 -doc-html : builds html documentation (needs the gapi lib)
 -doc-pdf  : builds pdf documentation (needs the gapi lib)
 -test   : builds and runs the unit tests (needs only the core lib)
 -all    : all of the above

 -clean-obj : removes object files
 -clean-lib : removes all produced libraries
 -clean-bin : removes all produced binaries
 -clean-doc : removes all produced documentation (html and latex/pdf)
 -clean-gen : removes all run-time generated files (log files, images, ...)
 -clean-gapi: removes all 'gapi' related files (lib, demos and apps)
 -clean-app : removes binaries and obj files of demos and applications
 -cleanall  : all of the above 'clean-xxx' targets

 -archive   : produces an archive with binaries and documentation
 -install   : install library and headers on local machine

* build general options:
 -XML_SUPPORT={yes|no} : if yes, integrates TinyXML library to enable XML I/O support (default is 'yes').
 -USE_EIGEN={yes|no} : if yes, integrates Eigen library to enable linear lest squares fitting for Takagi-Sugeno Fis type (default is 'yes').
 -SHORTDOC={yes|no} : generates web-type (short) html documentation (default is 'no').
 -GRAPHICS={cairo|opencv} : back-end graphical library to use: cairo+GTK or Opencv  (default is 'cairo').
 -DO_CHECKING={yes|no} : builds with runtime checks enables (default is 'yes).
 -NDEBUG={yes|no} : removes all assertions from code  (default is 'no').
 -SHARED={yes|no} : demo/apps use shared version of library (default is 'no').

* build dev/debug options:
 -DEBUG={yes|no} : builds debug version (default is 'no')
 -DO_LOGGING={yes|no} : add (useful) information on run-time to log file. Debug usage only, default is 'no'.
 -TRACELEVEL=n : add tracing of function calls up to level 'n'. Debug usage only, default is 0, no build overhead.

* makefile options:
 -SHOW={yes|no} : if yes, shows each command run by makefile (default is 'no').

In case of trouble, you can try:

make info

that will list the current options (the default ones if typed "as-is", or the ones you give, if any), and

make showpath

that will print the current search paths for dependencies. If they are wrong, you need to edit some makefile variables in the makefile (see top lines).

Finally, to speed up building, note that you can use the -j option of Gnu Make that enables parallel processing and speeds up the build process.

Build options

The makefile can be called with the following options. Note that only the DEBUG option compiles object files in a separate path. This means that when compiling the whole thing with a given set of options, then editing a .cpp file, then calling make with a different option set, then only this last edited file will be compiled with the second option set. If you want to rebuild all with the second option set, you need to call make clean-obj before.

Options list:

User options
- SHARED={yes|no}: uses the shared/dynamic build of library to build demos and applications. Default is presently 'yes' on Linux, 'no' on Windows. Only relevant for make targets 'app', 'install' and 'archive'. If enabled, the shared library needs to be installed at runtime on local machine (this is done with make target 'install').
- USE_EIGEN={yes|no}: Uses the Eigen math library for implementing fitting of TS coefficients from data, see Learning rules from data. Default is yes. If 'no', then calling SLIFIS::BuildRuleBaseFromData() will fail.
- SHORTDOC={yes|no} : if yes, generates the doc in short form (no cross-references, only users guide and some related pages). This can be useful if web hosting is limited, as doxygen generates a lot of files. Default is no. Please note that the building of the pdf file can fail in that case, as all the required (generated) plots may not be available.
- GRAPHICS={cairo|opencv} : builds gapi with given backend library. Default is Cairo/Gtk2
- DO_CHECKING={yes|no} : if no, *might* speed up some processing, as all the run-time checks are disabled. Default is yes, meaning all necessary checks are performed at run-time. Removing these run-time checks reduces static library size by about 15%.
- XML_SUPPORT={yes|no} : if yes, library will integrate TinyXML to enable XML I/O support, see File Storage. Default is yes.
Dev/debug options:
- DEBUG={yes|no} : enables or not debug build. Default is no. Basically, just adds the -g flag, and stores object files in separate folder.
- DO_LOGGING={yes|no} : if yes, adds logging information to log file. Only for debugging purposes. Default is no.
- TRACELEVEL=n : enables tracing of function calls in log file (stderr), default is 0, with no overhead at all. This is only used for debugging purposes. If you want full tracing, just put a really high level, say TRACELEVEL=20. This option defines at compile-time the two symbols SLIFIS_TRACE and SLIFIS_TRACE_DEPTH, see debug.h

Dependencies

For the core library, the following are mandatory:
- standard C++ library (containers and algorithms).
- Boost (foreach, tokenizer, shared_ptr, ...). See http://www.boost.org. On Linux Debian-based platform, it should be ok with:
```
    sudo apt-get install libboost
```
- pline lib, a small library I have written, designed for doing basic computational geometry with lines and points. It is included here in 'pline' folder (static library file, and source). See doc here.

If you intend to use the graphical part, you need a back-end graphical library, both to compile and to run programs. Currently, the default one is Cairo for drawing and GTK for windowing. Previously, it used OpenCv 2.X (can still be built with it). None of these are included, however Cairo and GTK are very common and can be installed on a standard Linux box. On Linux Debian-based platform, this can be done with the following (beware, large download):
```
sudo apt-get install libgtk+2
```
For more info, check http://www.cairographics.org and http://www.gtk.org/.
Please note that the 'make doc' target needs this dependency, as it generates most of the example plots.
Additional optional targets/dependencies
- For Takagi-Sugeno (TS) coefficients fitting (see Takagi-Sugeno learning), it relies on the Eigen library (currently version 3.1.2). A build option enables this or not, see Build options. Eigen is a matrix algebra library with a free licence (MPL), see here: http://eigen.tuxfamily.org/. Is NOT included, you need to download it separatly. Installation is really easy as this is a header-only library, nothing to link with, just put it somewhere where it is accessible by your compiler (on a GNU/Linux system, typically in /usr/local/include).
  If not needed, then the build will succeed only if corresponding build option is disabled.
- Tinyxml (currently version 2.6) for xml support, is included in folder 'other'. For xml usage, see XML format. For more about this library, see http://sourceforge.net/projects/tinyxml or http://www.grinninglizard.com/tinyxml
- At present, unit-testing (regression tests) are done using a set of macros I have developped ("kut" package). Is included in folder 'other'.
- Some functionalities (histogram files) are designed to output data files designed to be used with gnuplot (currently version 4.4). However, works also well without, not needed for running.
- The applications in folder src/app needs GetPot (LGPL, currently version 1.1.17 used) as command-line parser: straight forward, and all the code is inlined in a single header file. Is included in folder 'other'.
- Doxygen needed to (re)build doc. A valid Latex install is also required if you wish to rebuild the pdf doc file.

Build insides

All files in the 'bin' folder are generated, except those under the folders sample_data and test_data. For cleaning them, just run:
- make clean-gen, for removing log files, gnuplot data and command files, and generated image files,
- make clean-bin, for removing all produced binaries. This will restore the "bin" folder as it was on download.

Building on Windows

On Windows, building the software is a bit more complicated then it is on Linux, but it is actually only a matter of downloading and installing additional pieces of FOSS. Build is based on the same makefile, that has been specially adapted to run both on Linux and Windows.

You will only need the following requirements to build the 'core' and the 'test' target:

Mingw, with the binaries accessible on the path. You can download it from http://www.mingw.org/, but is is also provided with some IDEs installation packages (Codeblocks, for instance).
Gnu Make. You can fetch it from http://gnuwin32.sourceforge.net/

To build the GAPI part of library (and the demo applications and documentation), you will need one of these back-end libraries:

OpenCv: download a recent (2.4.?) OpenCv bundle (with binaries), install it somewhere, and adjust the makefile variables (path) in the first lines of the makefile.
Cairo+Gtk2: you will need:
1. pkg-config. You can get it from http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/
2. a Gtk2 bundle (large, but its the simplest solution. Else, it would require installing a lot of separate packages). Checkout http://www.gtk.org/download/ and/or http://www.gtk.org/download/win32.php).

To make pkg-config work with Gtk2 and its associated libraries, you need to tell it where it shall search. This is done with the environment variable PKG_CONFIG_PATH that needs to be set to the correct path. For instance, if you install the Gtk2 bundle to C:\libs\gtk2, then you need to declare ("system properties") PKG_CONFIG_PATH=C:\libs\lib\pkgconfig.
That way, it will find all those .pc files. Don't forget to copy also all the .dll files that are in bin folder of Gtk2 to c:\windows\system32.

To build the html-doc, you will also need:
- sed, also available from http://gnuwin32.sourceforge.net/
- gnuplot, available from the path (1). Please note that currently, the plotting scripts uses the pngcairo terminal (much nicer that the older png terminal), but this terminal is available only with recent versions of gnuplot (4.6 presently), so please upgrade if you have an older version. See http://gnuplot.sourceforge.net/
- and of course, doxygen, also available from the path (1)
  Warning:
  when doc building, strange behaviour of sed (fails...), so some sed commands have been disabled at present on the Windows build.
pdf doc not checked on Windows (no Latex environment currently installed)

To build archive, (make archive) the following is needed:
- 7-zip (4.6.3 tested). See http://www.7-zip.org/. Its command-line version is assumed to be located at c:\program files\7-zip\7z.exe. If this isn't the case, you will need to edit that location in makefile.
- a command-line version of SVN (TortoiseSVN has NO command-line binaries).

Final remarks:

at present, only the static version of library is build, not the shared one (dll).
If you don't install Eigen on your machine, don't forget to disable the corresponding flag at build (make <TARGET> USE_EIGEN=no). However, the provided binaries have been built with Eigen included.

(1) On Windows, to make a program available on the path, you need to go into "system properties", and add (for instance) "c:\program files\gnuplot\bin" to the PATH environment variable.