JPC Installation Guide

Introduction

This guide overviews how to install JPC, its drivers, compatible Prolog engines and examples.

Although this document covers the installation of all the distinct artefacts that may be required in an application using JPC, typically only a small subset of them are needed (e.g., only one Prolog engine and one JPC driver).

Requirements

To develop with JPC you require:

Java 8 or above.
A compatible Prolog engine.
Logtalk (optional for Java to Prolog, required for Prolog to Java).

JPC has been tested in:

Mac OS X: 10.8.5 (Mountain Lion) and 10.9.2 (Mavericks)
Linux: Ubuntu 12.0.4 and 13.0.4

At the moment, no tests have been accomplished under Windows, although it should also work there without major issues.

Before Starting

JPC currently uses Maven as its project management tool. Therefore, the easiest way to include JPC in a project, its drivers, other dependency libraries and examples is by means of Maven. Maven download and installation instructions are provided in its website.

Although JPC is still in alpha version, it is already available in the Maven Central repository. However, some JPC related components (experimental drivers or extensions) may only be available in the Maven Snapshots repository. To access components in the Snapshots repository, you may need to add the following to your Maven configuration file ~/.m2/settings.xml:

<profiles>
  <profile>
     <id>allow-snapshots</id>
        <activation><activeByDefault>true</activeByDefault></activation>
     <repositories>
       <repository>
         <id>snapshots-repo</id>
         <url>https://oss.sonatype.org/content/repositories/snapshots</url>
         <releases><enabled>false</enabled></releases>
         <snapshots><enabled>true</enabled></snapshots>
       </repository>
     </repositories>
   </profile>
</profiles>

Installing a Prolog Engine

This section gives pointers to the installation instructions of JPC compatible Prolog engines. There are many ways to install those engines. In certain cases, the best installation procedure for JPC is not the most obvious installation. Hence, this section often includes some example installation steps that ensure compatibility with our library.

Installing SWI Prolog

JPC is compatible with the latest SWI stable release (version 6.x at the time of writing). Installation instructions for multiple platforms are provided by the SWI website.

SWI Prolog in Mac OS X

The SWI version used to test JPC was installed using Mac Ports. SWI provides detailed instructions about how to accomplish a Mac Ports installation.

SWI Prolog in Linux

To generate the required Java interoperability library, SWI Prolog should be compiled from sources in Linux. The SWI site provides information about the required packages needed before starting the installation and how to download the sources. Afterwards, build and install both the SWI core and the tools according to the provided instructions. Note that for a 32-bits OS you may need to run the configuration script with --enable-shared.

Installing YAP Prolog

JPC is compatible with the latest YAP development version (version 6.3.3 at the time of writing). Installation instructions for multiple platforms are provided by the YAP website.

YAP Prolog in Mac OS X and Linux

Follow the instructions provided by the YAP website, taking care of adding the --with-java option when running the configuration script. For example, the following command (executed in the ARCH folder as described in the YAP manual) compiles and install YAP generating the required Java interoperability library:

../configure --prefix=/opt/local --with-java --enable-threads --enable-pthread-locking --enable-depth-limit --enable-coroutining --enable-clpbn-bp=no --enable-tabling --with-gmp=/opt/local && make && sudo make install

You may change these options as you wish, but remember to leave the --with-java option enabled. Also, you may need to add --enable-shared for 32-bits OS.

Installing XSB Prolog

JPC is compatible with the latest XSB development version. Installation instructions for multiple platforms are provided by the XSB website.

XSB Prolog in Mac OS X and Linux

To compile and install XSB go to the build directory in the source tree and execute the following command:

./configure -prefix=$SHARED_LIB && ./makexsb && sudo ./makexsb dynmodule && sudo ./makexsb install

Where $SHARED_LIB is the directory where you want to install XSB. For example: /opt/local/lib/. Note that you may need sudo depending on the chosen installation location.

Installing Logtalk

Although JPC requires just a plain Prolog engine, many optional advanced features rely on Logtalk. Logtalk is an object-oriented logic programming language implemented using Prolog as a backend compiler. The Logtalk website provides detailed installation instructions together with many other resources.

Adding JPC to a Project

In order to include JPC into a project, add the following dependency to your POM:

<dependency>
  <groupId>com.github.java-prolog-connectivity</groupId>
  <artifactId>jpc</artifactId>
  <version>0.0.1-alpha</version>
</dependency>

Note that including the JPC library may be enough for development, but for executing your application you still need one or more JPC drivers.

Configuring JPC Drivers

All the current JPC drivers are open source. For convenience, both installation instructions for Maven users and Uber-Jars containing each driver with its dependences are provided.

The JPL Based Driver

Driver Architecture

The JPL based driver is implemented on top of the JPL library. This driver is compatible with either SWI or YAP Prolog. Since JPL is based on JNI, it is composed of both a Java part and a native C part. You need to tell JPC (so it can tell in turn to JPL) where is located the C part. Depending on the platform, the native part may be a library with a name similar to libjpl.dylib (OSX), libjpl.jnilib (Linux) or libjpl.dll (Windows) in your SWI or YAP installation.

Maven users

Add this dependency to your POM:

<dependency>
  <groupId>com.github.java-prolog-connectivity</groupId>
  <artifactId>jpc-jpl</artifactId>
  <version>0.0.1-alpha</version>
</dependency>

Download the Driver Uber-Jar

Installation Instructions

To enable this driver follow these steps:

Configure the environment variable JPLPATH_SWI (in case you want to connect to SWI) with the SWI directory containing the native part of the JPL library.
Configure the environment variable JPLPATH_YAP (in case you want to connect to YAP) with the YAP directory containing the native part of the JPL library.

The OS specific instructions below are only relevant in Prolog to Java applications.

OSX Installation Instructions

Locate the directory where the JVM library libjvm is located and add it to the DYLD_LIBRARY_PATH environment variable. The path should be similar to $JAVA_HOME/Contents/Home/jre/lib. If you prefer to not modify such environment variable, alternatively you may use the otool utility. To do that, follow these steps:

Open a terminal and go to the directory where are located the dynamic SWI libraries. For example, if using the SWI-Prolog.app bundle, the path may be something similar to /Applications/SWI-Prolog.app/Contents/swipl/lib/x86_64-darwin13.0.0. You should see a file named libjpl.dylib in that directory.
Execute otool libjpl.dylib -L to see a list of the libraries currently linked with libjpl.dylib. You may see an entry similar to /System/Library/Frameworks/JavaVM.framework/Versions/A/JavaVM, pointing to the native OSX JVM.
Change this entry to point to the libjvm.dylib file in your preferred Java installation. To do this, type: install_name_tool -change <OLD_ENTRY> <NEW_ENTRY> libjpl.dylib. For example, you may execute something like: install_name_tool -change /System/Library/Frameworks/JavaVM.framework/Versions/A/JavaVM $JAVA_HOME/jre/lib/server/libjvm.dylib libjpl.dylib.

Linux Installation Instructions

Locate the directory where the JVM library libjvm is located. The path should be similar to $JAVA_HOME/jre/lib/amd64/server (assuming a 64 bits installation). In several Linux distributions you will have to add that path to the LD_LIBRARY_PATH environment variable. That is not correct for Ubuntu. For Ubuntu, you can create a swipl.conf file in the /etc/ld.so.conf.d directory. In that file, write the path to the directory containing the JVM library. Do not forget to execute ldconfig afterwards.

Driver Features

With this driver, only one Prolog session can be opened per JVM in Java to Prolog applications.

The InterProlog Based Driver

Driver Architecture

The InterProlog based driver is implemented on top of the InterProlog library. This driver is compatible with XSB Prolog.

Installation Instructions

In order to include this driver in your project follow these steps:

Download and unzip the InterProlog bundle.

Go to the directory where the interprolog.jar file is located and install it in your Maven local repository with this command:

mvn install:install-file -Dfile=interprolog.jar -DgroupId=com.declarativa.interprolog -DartifactId=interprolog -Dversion=2.2a4 -Dpackaging=jar

Add this dependency to your POM:

<dependency>
  <groupId>com.github.java-prolog-connectivity</groupId>
  <artifactId>jpc-interprolog</artifactId>
  <version>0.0.1-alpha-SNAPSHOT</version>
</dependency>

Configure the environment variable XSB_BIN_DIRECTORY with the directory where the XSB binary is located.

Driver Features

This driver supports multiple Prolog sessions.

The PDT Connector Based Driver

Driver Architecture

The PDT Connector based driver is implemented on top of the PDT Connector library. This driver is compatible with SWI Prolog.

Installation Instructions

In order to include this driver in your project follow these steps:

Download the PDT connector jar.

Go to the directory where the jar was downloaded and install it in your Maven local repository with this command:

mvn install:install-file -Dfile=org.cs3.prolog.connector-2.1.0.jar -DgroupId=org.cs3.roots -DartifactId=org.cs3.prolog.connector -Dversion=2.1.0 -Dpackaging=jar

Add this dependency to your POM:

<dependency>
  <groupId>com.github.java-prolog-connectivity</groupId>
  <artifactId>jpc-pdtconnector</artifactId>
  <version>0.0.1-alpha-SNAPSHOT</version>
</dependency>

Configure the environment variable SWI_BIN_DIRECTORY with the directory where the SWI binary is located.

Note that configuring the last environment variable is optional in most cases. If no provided, JPC will not pass any path to PDT (the underlying library of this driver) and the latter will attempt to find the SWI location.

Driver Features

This driver supports multiple Prolog sessions.

Installing the JPC Examples

You can download some usage examples of JPC adding the following dependency to your POM:

<dependency>
  <groupId>com.github.java-prolog-connectivity</groupId>
  <artifactId>jpc-examples</artifactId>
  <version>0.0.1-alpha</version>
</dependency>