Developing JPL

At this point you have SWI + JPL for development. However, you cannot commit changes to neither repositories. You need to do the changes in your own fork of JPL and once happy probably propose a pull request for the SWI+JPL developers to adopt (by merging your code into the main JPL repo).

So, as an example, I have my own fork of JPL at https://github.com/ssardina-research/packages-jpl and in that repo I have, say, a branch called proposal where I will do changes to later issue as pull requests to the main JPL repo.

Because packages in the SWI distribution are independent git submodules, we can “attach” our JPL fork in the whole development set-up we build above:

<we assume we are at the main SWI local git repo, that is, swipl-devel/
cd packages/jpl/
git remote add ssardina git@github.com:ssardina-research/packages-jpl.git
git fetch --all      // will fetch all the info of branches in the new remote ssardina
git branch --track proposal ssardina/proposal // local branch proposal will start tracking ssardina/proposal
<do all your changes>
git push ssardina // assuming you are happy with the changes

Now we build:

cd ../../build
cmake -DINSTALL_DOCUMENTATION=OFF ..
make -C packages/jpl clean // clean the JPL previous compile
make
ctest -V -R jpl  // run tests to check nothing broke

Of course, the first time you will probably not have your proposal branch in your fork. So you can create one as follows:

<we assume we are at the main SWI local git repo, that is, swipl-devel/
cd packages/jpl/
git remote add ssardina git@github.com:ssardina-research/packages-jpl.git
git checkout -b proposal
<do all your changes>
git push -u ssardina proposal  // push new branch to remote ssardina and start tracking

Now you have a local branch proposal tracking a remote branch in ssardina for it.

NOTE: If you are only expecting to change the Java API, then you can just work with the packages-jpl distribution in isolation. This will compile just the Java classes and produce a corresponding JAR file for use. However, in this case you would have to have an SWI system installed system-wide and make sure your application uses your updated JPL JAR file and not the system installed one.

Developing from an IDE

Most probably one develops the Java-API of JPL from an IDE, for example IntelliJ or ECLIPSE and would like to run and test from the IDE itself, rather than from the CLI via CMAKE for the whole SWIPL framework (the C library libjpl.so most of often won’t change).

To do so, we need to configure the IDE to make sure the correct resources under development, including native libraries libswipl.so and libjpl.so, are found and used. It may also be necessary to pre-load libswipl.so to avoid certain run-time errors with libraries that are not crossed-linked and specify the jpl.jar in the CLASSPATH for those Prolog tests that call Prolog.

In a nutshell, assuming we are develping JPL in its usual location with SWIPL (packages/jpl) and the SWIPL non-installed build is in build/, we would set-up the following environment variables:

SWI_HOME_DIR=../../build/home/
SWIPL_BOOT_FILE=../../build/home/boot.prc   # to setup SWIPL engine
LD_LIBRARY_PATH=../../build/packages/jpl    # to find libjpl.so
CLASSPATH=target/classes/	        # for calls from Prolog to Java
LD_PRELOAD=../../build/src/libswipl.so	    # avoid run-time errors

In IntelliJ, for example, this is done by modifying the Java/JUnit Template in “Run/Debug Configuration” to include the environment variables.

For instance, modify the JUnit template by just enter this string in “Environment variables”:

LD_LIBRARY_PATH=../../build/packages/jpl;SWI_HOME_DIR=../../build/home;SWIPL_BOOT_FILE=../../build/home/boot.prc;CLASSPATH=target/classes;LD_PRELOAD=../../build/src/libswipl.so

Note this assumes your IDE will compile the JPL classes into target/classes dir, as default in a Maven project.

Finally, you can create a new Run from the template, it will already inherit the environment variables. The whole JUNIT testing framework is aggregated by class org.jpl7.test.JPLTestSuite.