installation

Overview

GProM is written in C and is build using the GNU suite of build tools. GProM can be compiled with support for different database backends and is linked against the C client libraries of these database backends. The system can be build on Linux and Mac OS X. Theoretically, it would be possible to build GProM using cygwin under Windows, but this build has not been tested so far.

Dependencies

• To build GProM you need the following build-tools and libraries
  • A C compiler: e.g., gcc
  • GNU autotools
  • libtool
  • flex and bison (2.7 or higher)

The following tools are optional, but useful for development:

• A debugger: e.g., gdb
• A profiler: e.g., gprof or google performance tools
• valgrind
• readline: to have a command history in the GProM shell
• ant: to build the Java bindings (currently not fully operational)

Optional dependencies (for backends)

To build with Oracle support you need to install:

• Oracle OCI library
• OCILIB library (open source library wrapping OCI)

To build with PostgreSQL support you need to install:

• PostgreSQL's libpq client library

To build with SQLite support you need to install

• SQLite3, install the development version as package sqlite3-dev

To build with MonetDB support you need the Mapi library

Quick Walk-through

1. Install dependencies
2. clone git repository
3. run autotools (autogen.sh)
4. run configure
5. run make

Detailed Guide

Install build tools

Use your package manager to install the necessary build-tools (e.g., apt-get) mentioned above.

Install and setup the Oracle OCI library (OPTIONAL)

The steps in this section have to be followed if you plan to install with Oracle backend support. Oracle deploys the required OIC library as part of their instantclient package.

1. Download the version for your operating system from http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html. You need to download at least the basic, sdk and sqlplus packages.
2. Extract these files into a directory of your choice.
3. Setup your environment to work with OCI

Setup environment and configure OCI lib

This library requires a few tweaks to work that depend on whether you run on Linux or Mac OS X.

Linux

• Move the extracted files to a directory of your choice. E.g., $HOME/instantclient. Now change to this directory and create symbolic links for the libraries. You should see several .so.XX.Y files in the directory where XX.Y is the oracle version.

• You need to create links libclntsh.so and libocci.so in this directory that link to the files libclntsh.so.XX.Y and libocci.so.XX.Y:

ln -s libclntsh.so.XX.Y libclntsh.so
ln -s libocci.so.XX.Y libocci.so

You need to tell your system where to find these libraries. There are several ways how to do this.

One option is to set the LD_LIBRARY_PATH path variable in your shell profile (e.g., .bashrc). Add your oracle instantclient path, e.g., $HOME/instantclient. Add the following line to the end of your .bashrc file:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/instantclient

Alternatively you can add the path to /etc/ld.so.conf and then run /sbin/ldconfig

Run sqlplus to test whether your OCI setup is operational.

Max OS X

On Mac OS X you have to use DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH. Furthermore, dynamic link libraries use the .dylib extension instead of .so on Linux. Thus, to create the symbolic links on Mac OS X use:

ln -s libclntsh.dylib.XX.Y libclntsh.dylib
ln -s libocci.dylib.XX.Y libocci.dylib

Install the OCILIB library (OPTIONAL)

OCILIB is an open-source library that provides a more convenient wrapper around OCI.

• Download the source from http://orclib.sourceforge.net/

Installation instruction can be found at http://orclib.sourceforge.net/doc/html/group__g__install.html

• Run configure:

Two important options are --with-oracle-headers-path (location of the Oracle OCI header files) and --with-oracle-lib-path (location of the Oracle OCI shared libraries)

The header files (.h) files are usually installed in the sdk/include/ subdirectory of your instantclient installation. The .so respective .dylib shared library files should be in the main folder of your instantclient installation. Thus, if you have installed the instantclient into $HOME/instantclient then you should call configure like this:

./configure --with-oracle-headers-path=$HOME/instantclient/sdk/include --with-oracle-lib-path=$HOME/instantclient

If you want to install the library in a non-standard location then use the prefix option of configure. E.g.:

./configure --with-oracle-headers-path=$HOME/instantclient/sdk/include --with-oracle-lib-path=$HOME/instantclient --prefix=$HOME/ocilib

• Run make:

make

• Run make install

sudo make install

Install Oracle (OPTIONAL)

If you do not have access to an Oracle database to be used with GProM, consider installing one. Some versions of the database are available for download here http://www.oracle.com/technetwork/database/enterprise-edition/downloads/index.html.

Install and setup the PostgreSQL libpq (OPTIONAL)

The steps in this section have to be followed if you plan to install with PostgreSQL backend support. On most systems you can use the package manager to install libpq. For example, on Ubuntu or Debian

sudo apt-get install libpq-dev

Unless you plan to connect to an existing Postgres database server, you may also want to install PostgreSQL itself:

sudo apt-get install postgresql

On Mac OS X you can use a package manager like fink, homebrew, or macports. Alternatively, you can build PostgreSQL from source or install one of the prepackaged binaries: https://www.postgresql.org/download/.

Install and setup SQLite (OPTIONAL)

If you want to install with SQLite backend support, then you need to install the sqlite3 development version. Using a package manager install sqlite3-dev

For example, on Ubuntu or Debian

sudo apt-get install sqlite3-dev

On Mac OS X you can use a package manager like fink, homebrew, or macports. Alternatively, build SQLite from source: https://sqlite.org/download.html.

Install and setup MonetDB (OPTIONAL)

Please have a look at https://www.monetdb.org/Downloads to see how to install and setup MonetDB.

Build GProM

Clone the repository from github and switch to the directory you cloned the git repository into, e.g.,

cd $HOME/gprom

• First you need to run autotools. We provide a script that you can use:

./autogen.sh

• Then you need to run configure. We support several configuration options. All supported options are shown at this end of this page. The most important ones are the options that tell our system where to find the OCI and OCILIB libraries and options that determine which backends should be supported. These are:
  • --with-oci-lib=X - set location of Oracle OCI library shared library files
  • --with-oci-headers=X - set location of Oracle OCI library header files
  • --with-ocilib=X - set location of OCILIB library
  • --with-libpq=X - set location of PostgreSQL libpq library
  • --disable-oracle - do not build with support for Oracle backends
  • --disable-postgres - do not build with support for Postgres backends
  • --disable-sqlite - do not build with support for SQLite backends
  • --disable-monetdb - do not build with support for MonetDB backends

Assuming you have installed OCILIB into $HOME/ocilib and OCI into $HOME/instantclient, you would run configure like this:

./configure --with-oci-lib=$HOME/instantclient --with-oci-headers=$HOME/instantclient/sdk/include --with-ocilib=$HOME/ocilib

If you are building with Oracle backend support and configure does not find either OCI or OCILIB then there will be an error message. In this case you need to make sure that the paths you provide are correct and the your environment is set up correctly (e.g., LD_LIBRARY_PATH respective DYLD_LIBRARY_PATH). Same applies for libpq (PostgreSQL backends) and sqlite3-dev (SQLite backends).

• Now you can build the system by calling make:

make

• Run make install to install the gprom binary and manual file

sudo make install

Now you should be able to run the GProM shell:

gprom

Next Steps

Run gprom -help to see available commandline options or have a look at the man page that describes these options in detail by running man gprom. Folder ./scripts has several convenience scripts that wrap gprom.

Configure Options

Below is a description of all GProM-specific configure options.

• --disable-assert - Turn off assertions
• --disable-oracle - Disable compilation with support for Oracle backends
• --disable-postgres - Disable compilation with support for Postgres backends
• --disable-sqlite - Disable compilation with support for SQLite backends
• --disable-monetdb - Disable compilation with support for MonetDB backends
• --disable-java - Disable building of Java bindings
• --disable-readline - Disable compilation with support for readline library in the client
• --disable-logging - Disable logging
• --enable-link-perftools - Link against google perftools library
• --enable-gprof - Activate profiling with gprof
• --disable-assert - Disable assertions
• --disable-debug - Disable compilation with debugging symbols
• --disable-timing - Disable compilation with timing instrumentation
• --with-oci-lib=X - set location of Oracle OCI library shared library files
• --with-oci-headers=X - set location of Oracle OCI library header files
• --with-ocilib=X - set location of OCILIB library
• --with-libpq=X - set location of PostgreSQL libpq library
• --with-mapi=X - set location of MonetDB mapi library