Requirements
============

- a c++11 conforming compiler
    gcc version 4.8 (earlier versions will not work)
    clang version 3.1 (using either libstdc++ provided by gcc 4.8 or libc++)
    other compilers might work
- the bison parser generator
    version 3.0 is tested (produces warnings to stay backwards-compatible)
    version 2.5 and newer should work (earlier versions will not work)
- the re2c lexer generator
    version 0.13.5 is tested
    newer versions should work
- the scons build system
    version 2.2 is tested
    version 2.1 and newer should work

Optional Dependencies
---------------------

- the python script language (optional)
    version 2.7 is tested
- the lua script language (optional)
    version 5.1 is tested
    version 5.2 should work
- the tbb library (optional)
    version 4.0+r233 is tested
    newer versions should work
- the cppunit library (optional)
    version 1.12 is tested
    newer versions should work


Compilation
===========

Note that for building gringo/clingo, you need a very recent C++ compiler. To
build gringo and clingo in their default configurations in release mode, run:
    scons --build-dir=release gringo clingo

There is no installation target. To use gringo or clingo, use the binaries in
the build/release folder:
    build/release/gringo
    build/release/clingo

For enabling lua/python/threading support, please see the next section.


Build Options
=============

To get an overview over the variables that can be set for building
gringo/clingo, please run:
    scons --help

You can edit build/release.py to edit these values. Make sure to generate the
file beforehand:
    scons configure --build-dir=release

Note that the scons scripts do not try to automatically find libraries. To
enable additional features, you have to do this explicitly.

Enabling Scripting Support
--------------------------

To enable python or lua support, you have to set the respective library names
and (typically) the paths to the includes. The relevant portions of the
configuration file are:
    $ grep "CPPPATH\|WITH_PYTHON\|WITH_LUA" build/release.py
    CPPPATH     = ['/usr/include/python2.7', '/usr/include/lua5.1']
    WITH_PYTHON = 'python2.7'
    WITH_LUA    = 'lua5.1'

Make sure to match the version numbers above with what is installed on your
system.  Depending on your system further paths might have to be adjusted -
e.g., LIBPATH if libraries are installed in non-default locations.

Enabling Threading
------------------

To enable threading support, please adjust the following portion of the config:
    $ grep "WITH_TBB" build/release.py
    WITH_TBB = 'tbb'

Depending on your system further paths might have to be adjusted - e.g.,
CPPPATH, LIBPATH if the library is installed in a non-default location.

Testing
=======

If gringo/clingo has been configured with cppunit support a test target is
available to run unit tests:
    $ grep "WITH_CPPUNIT" build/release.py
    WITH_CPPUNIT = 'cppunit'
    $ scons --build-dir=release test

Furthermore, there are some acceptance tests for clingo. These tests require
clingo to be configured with python, lua, and cppunit support. Additionally,
the following programs have to be available: zsh, and the GNU core- and
diffutils.  To run the tests, execute:
    $ scons --build-dir=release test-clingo


Notes for Windows Users
=======================

With a few tweaks gringo/clingo can be compiled using the Mingw-w64 compiler.
The binaries on Sourceforge have been compiled with a Mingw-w64 based
cross-compiler.

Additionally, gringo can be compiled under Windows using cygwin.  Except for
the tbb library, all additional software is available via cygwin and
cygwinports.

Note that I had problems with cygwin's bison and had to resort to another bison
port: win flex-bison

Relevant parts of the configuration:
$ grep "CXX\|CPPPATH\|WITH_PYTHON\|WITH_LUA" build/release.py
CXX          = 'g++'
CPPPATH      = ['/usr/include/python2.7']
WITH_PYTHON  = 'python2.7.dll'
WITH_LUA     = 'lua.dll'


Notes for Mac Users
===================

gringo/clingo has successfully been built using software provided by macports.

This are the relevant installed packages:
    $ port installed \
        | grep "lua\|clang-3.3\|tbb\|bison\|re2c\|scons\| python27" \
        | grep active
    bison @2.7.1_0+universal (active)
    clang-3.3 @3.3_1+analyzer+python27+universal (active)
    python27 @2.7.5_1+universal (active)
    lua @5.2.2_1+universal (active)
    re2c @0.13.5_0 (active)
    scons @2.3.0_0 (active)
    tbb @4.2-20130725_0 (active)

Relevant parts of the configuration:
    $ grep "CXX\|CPPPATH\|WITH_PYTHON\|WITH_LUA\|LIBPATH\|WITH_TBB\|BISON\|RE2C" build/release.py
    CXX         = '/opt/local/bin/clang++-mp-3.3'
    CPPPATH     = ['/opt/local/Library/Frameworks/Python.framework/Versions/2.7/include/python2.7', '/opt/local/include']
    LIBPATH     = ['/opt/local/lib']
	BISON       = '/opt/local/bin/bison'
	RE2C        = '/opt/local/bin/re2c'
    WITH_PYTHON = 'python2.7'
    WITH_LUA    = 'lua'
    WITH_TBB    = 'tbb'

Note that the clang and python versions provided by the latest Xcode release
can be used to compile gringo/clingo. The binaries provided on the sourceforge
page are built using these.


Links
=====

http://clang.llvm.org/
http://gcc.gnu.org/
http://libcxx.llvm.org/
http://llvm.org/
http://re2c.org/
http://sourceforge.net/projects/cppunit/
http://www.gnu.org/software/bison/
http://www.lua.org/
http://www.python.org/
http://www.scons.org/
http://www.threadingbuildingblocks.org/
http://www.macports.org/
http://mingw-w64.sourceforge.net/
http://potassco.sourceforge.net/
http://cygwin.com/
http://cygwinports.com/
http://sourceforge.net/projects/winflexbison/
