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

- a c++11 conforming compiler
    gcc version 4.9 (earlier versions will not work)
    clang version 3.1 (using either libstdc++ provided by gcc 4.9 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

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

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

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

For enabling lua/python/threading support, please see the Enabling Scripting
Support Section.

Troubleshooting
---------------

If configuration fails, always inspect the build log, e.g.:
    build/release.log

It contains all the compiler invocations performed when testing the
configuration, along with generated error messages.  Typically, this makes it
very easy to fix the problem.


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

The scons scripts try to automatically find libraries using python-config and
pkg-config.  Relevant parts of the configuration are:
    $ grep "PYTHON_CONFIG\|PKG_CONFIG" build/release.py
    PYTHON_CONFIG = None
    PKG_CONFIG = 'pkg-config'

By default python-config is used to obtain compile and link flags for building
with python.  This can be disabled by setting PYTHON_CONFIG to None to always
use pkg-config.


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

By default the build script tries to automatically detect available libraries
on the system and sets the configuration accordingly.  If detection fails, 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.

Building the Python Module
--------------------------

If python support is enabled, the additional target pyclingo is available.
    scons --build-dir=release pyclingo

This will build a library called clingo that can be imported in python. Make
sure it is put somewhere under the PYTHONPATH. Then import clingo in your
python script. The module itself is documented using python's docstrings.
    build/release/python/clingo.{so,dll,dylib}

The documentation for the clingo module is available online:
    https://potassco.org/clingo/

Building the Lua Module
-----------------------

If lua support is enabled, the additional target pyclingo is available.
    scons --build-dir=release luaclingo

This will build a library called clingo that can be imported in lua:
    build/release/lua/clingo.{so,dll,dylib}

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

By default multi-threading is enabled using posix threads.  The relevant part
in the configuration is:
    $ grep "WITH_THREADS" build/release.py
    WITH_THREADS = 'posix'

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
=======

The test target can be used to run unit and acceptance tests:
    $ scons --build-dir=release test

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.  All
additional software is available via cygwin and cygwinports.  I cannot test
this myself because I do not have a Windows installation.  You might encounter
problems.  Patches to improve compatibility are welcome.

Note that I had problems with cygwin's bison and had to resort to another bison
port (for some reason I had to delete the last line of the generated parser):
    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\|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)

Relevant parts of the configuration:
    $ grep "CXX\|CPPPATH\|WITH_PYTHON\|WITH_LUA\|LIBPATH\|WITH_THREADS\|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_THREADS = 'posix'

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 github
page are built using these.


Links
=====

http://clang.llvm.org/
http://cygwin.com/
http://cygwinports.com/
http://gcc.gnu.org/
http://libcxx.llvm.org/
http://llvm.org/
http://mingw-w64.sourceforge.net/
https://potassco.org/
https://potassco.org/clingo/
https://github.com/potassco/
https://github.com/potassco/clingo
http://re2c.org/
https://github.com/philsquared/Catch
http://sourceforge.net/projects/winflexbison/
http://virtualenv.pypa.io
http://www.gnu.org/software/bison/
http://www.lua.org/
http://www.macports.org/
http://www.python.org/
http://www.scons.org/
