Skip to content

Latest commit

 

History

History
232 lines (185 loc) · 9.24 KB

INSTALL.md

File metadata and controls

232 lines (185 loc) · 9.24 KB

Table of Contents

Requirements

This document is about installing clingo from source. We also provide precompiled packages for various package managers: https://potassco.org/clingo/#packages.

  • a c++14 conforming compiler
    • at least gcc version 4.9
    • clang version 3.1 (using either libstdc++ provided by gcc 4.9 or libc++)
    • at least msvc++ 14.0 (Visual Studio 2015 Update 3)
    • other compilers might work
  • the cmake build system
    • at least version 3.3 is recommended
    • at least version 3.1 is required

Development Dependencies

The following dependencies are only required when compiling a development branch. Releases already include the necessary generated files.

  • the bison parser generator
    • at least version 2.5
    • version 3.0 produces harmless warnings (to stay backwards-compatible)
  • the re2c lexer generator
    • at least version 0.13
    • version 0.13.5 is used for development

Optional Dependencies

  • the Python script language
    • version 2.7 is tested
  • the Lua script language
    • version 5.1 is used for development
    • version 5.2 and 5.3 should work

Build, Install, and Test

When cloning the git repository, do not forget to update the submodules (with source releases, you can skip this step):

git submodule update --init --recursive

To build gringo, clingo, and reify in their default configurations in release mode, run:

cmake -H<SOURCE_DIR> -B<BUILD_DIR> -DCMAKE_BUILD_TYPE=Release
cmake --build <BUILD_DIR>

The resulting binaries and shared libraries will be in <BUILD_DIR>/bin and are ready to use.

To install all binaries and development files under cmake's install prefix (see the build options), run:

cmake --build <BUILD_DIR> --target install

To run the tests, enable option CLINGO_BUILD_TESTS (see build options) and run:

cmake --build <BUILD_DIR> --target test

Build Options

Cmake's -L option can be used to get an overview over the variables that can be set for building gringo/clingo. To get gringo/clingo specific options, run

cmake -H<SOURCE_DIR> -B<BUILD_DIR> -DCMAKE_BUILD_TYPE=Release -LH

or, to also print important cmake specific configuration variables

cmake -H<SOURCE_DIR> -B<BUILD_DIR> -DCMAKE_BUILD_TYPE=Release -LAH

Options and variables can be passed to cmake on the command line using -D<VARIABLE>=<VALUE> or by editing <BUILD_DIR>/CMakeCache.txt after running cmake.

The build scripts by default try to detect optional dependencies, like Python and Lua scripting support.

Clingo uses libpotassco and clasp. Both components have their own sets of configuration variables:

In the following, the most important options to control the build are listed.

Generic Options

  • Variable CMAKE_BUILD_TYPE should be set to Release.
  • Variable CMAKE_INSTALL_PREFIX controls where to install clingo.
  • Option CLINGO_BUILD_APPS controls whether to build the applications gringo, clingo, and reify. (Default: ON)
  • Option CLINGO_BUILD_EXAMPLES controls whether to build the clingo API examples. (Default: OFF)
  • Option CLINGO_BUILD_TESTS controls whether to build the clingo tests and enable the test target running unit as well as acceptance tests. (Default: OFF)
  • Option CLINGO_MANAGE_RPATH controls how to find libraries on platforms where this is supported, like Linux, macOS, or BSD but not Windows. This option should be enabled if clingo is installed in a non-default location, like the users home directory; otherwise it has no effect. (Default: ON)

Python Support

With the default configuration, Python support will be auto-detected if the Python development packages are installed.

  • Option CLINGO_BUILD_WITH_PYTHON can be used to enable or disable Python support. (Default: ON)
  • If option CLINGO_REQUIRE_PYTHON is enabled, configuration will fail if no Python support is detected; otherwise, Python support will simply be disabled if not detected. (Default: OFF)
  • The variable CLINGO_PYTHON_VERSION can be used to select a specific python version. For example, passing -DCLINGO_PYTHON_VERSION:LIST="3.6;EXACT" to cmake requires python version 3.6 to be available. Starting with cmake 3.15, variable Python_ROOT can be used to specify where to search for a python installation (the documentation of cmake's FindPython module has further information).
  • If option PYCLINGO_USER_INSTALL is enabled, the clingo Python module is installed in the users home directory; otherwise it is installed in the system's Python library directory. (Default: ON)
  • Variable PYCLINGO_INSTALL_DIR can be used to customize where to install the python module. (Default: automatically detected)
  • Variable PYCLINGO_USE_CFFI can be used to build and install the clingo packages using Python's cffi package instead of using Python's C API. (Default: OFF)

Note that it can happen that the found Python interpreter does not match the found Python libraries if the development headers for the interpreter are not installed. Make sure to install them before running cmake (or remove or adjust the CMakeCache.txt file).

Lua Support

With the default configuration, Lua support will be auto-detected if the Lua development packages are installed.

  • Option CLINGO_BUILD_WITH_LUA can be used to enable or disable Lua support. (Default: ON)
  • If option CLINGO_REQUIRE_LUA is enabled, configuration will fail if no Lua support is detected; otherwise, Lua support will simply be disabled if not detected. (Default: OFF)
  • The variable CLINGO_LUA_VERSION can be used to select a specific Lua version. For example, passing -DCLINGO_LUA_VERSION:LIST="5.2;EXACT" to only find Lua 5.2.
  • If variable LUACLINGO_INSTALL_DIR is set, the clingo lua module will be installed there. (Default: not set)

Compilation to JavaScript

Clingo can be compiled to JavaScript with Empscripten. The following notes assume that Emscripten has been installed. Only the web target and a subset of clingo's configuration are supported when compiling to JavaScript:

emcmake cmake -H<SOURCE_DIR> -B<BUILD_DIR> \
    -DCLINGO_BUILD_WEB=On \
    -DCLINGO_BUILD_WITH_PYTHON=Off \
    -DCLINGO_BUILD_WITH_LUA=Off \
    -DCLINGO_BUILD_SHARED=Off \
    -DCLASP_BUILD_WITH_THREADS=Off \
    -DCMAKE_VERBOSE_MAKEFILE=On \
    -DCMAKE_BUILD_TYPE=release \
    -DCMAKE_CXX_FLAGS="-std=c++11 -Wall -s DISABLE_EXCEPTION_CATCHING=0" \
    -DCMAKE_CXX_FLAGS_RELEASE="-Os -DNDEBUG" \
    -DCMAKE_EXE_LINKER_FLAGS="" \
    -DCMAKE_EXE_LINKER_FLAGS_RELEASE=""
cmake --build <BUILD_DIR> --target web

Note that is is possible to enable Lua support. Therefore Lua has to be compiled with emscripten, too. See Lua Support for information about pointing clingo to a custom Lua installation.

For examples how to use the resulting JavaScript code, check out one of the following:

Troubleshooting

After installing the required packages clingo should compile on most *nixes. If a dependency is missing or a software version too old, then there are typically community repositories that provide the necessary packages. To list a few:

  • the ToolChain repository for Ubuntu 14.04 and earlier (later versions should include all required packages)
  • the Developer Toolset for CentOS
  • the Cygwin project under Windows (re2c must be compiled by hand)
  • both Homebrew and MacPorts provide all the software necessary to compile clingo

And, well, you can compile a recent gcc version yourself. Even on ancient Linux systems. ;)

Notes for Windows Users

clingo can be compiled using the Mingw-w64 compiler, the Cygwin project, or Visual Studio 2015 Update 3. For development, bison from the Win flex-bison project and a self compiled re2c executable can be used.