15 Packs: community add-ons
All Application Manual Name SummaryHelp

15.5 Developing a pack

We recommend using GIT for developing SWI-Prolog packages. To start a new package, invent a name and verify that the name is not yet in use at The pack landing page. Create a directory with this name, a sub-directory prolog and a the metadata file pack.pl that contains at least the name and version of the pack. Below is a simple example. See section 15.5.1 for all possible metadata fields. 

name(hello).
version('1.0.0').
title('Hello world').
keywords([demo]).
author( 'Bob Programmer, 'bob123@programmer.me. ).
download('https://github/bob123/hello.git').

Now, add the Prolog libraries provided to the prolog directory. While doing so, please pay attention to the points below. If your are looking for examples of well structured libraries, please look at the system libraries.

Once the pack is ready for a very first test, we can make it accessible using the command below. On non-Windows systems, this makes the pack accessible using a symbolic link from your personal pack directory to this directory. 

swipl pack install .

After this command the new libraries should be available when you start a new SWI-Prolog process. Another way to make the pack accessible is by using the pack search path (see file_search_path/2). The command (from the pack directory) is 

swipl -p pack=..

15.5.1 The pack meta data

A pack must have a file pack.pl in its root directory. The file contains Prolog terms. Defined terms are below. The argument types are types registered with must_be/2 and described in the running text.

name(atom)
Name of the pack. This should be the same as the directory name. Names can be constructed from the ASCII letters, underscore and digits, e.g., [a-zA-Z9-0_]+
title(atom)
Short summary of the package. Do not use line breaks and limit respect at maximum length of about 40 characters.
keywords(list(atom))
List of keywords that help finding your pack. There is no fixed set of keywords to choose from.
description(list(atom))
Longer description as a list of lines.
version(version)
Current version of the pack. This is a list of integers separated by dots. There is no limit to the number of sub revisions.
author(atom, email_or_url_or_empty)
Original author of the code. If the contact address is unknown it may be omitted (empty atom). Repeat this term for multiple authors.
maintainer(atom, email_or_url)
packager(atom, email_or_url)
As author, but the contact cannot be empty. May be repeated.
pack_version(nonneg)
Package convention number. Currently 1 (default) or 2. Version 2 provides better support for building foreign extensions.
home(atom)
Location of th home page. This is typically a URL.
download(atom)
Location for downloading. This is either the URL of the GIT repository or a wildcard URL for downloading the archive, e.g., https://me.com/packs/mypack-*.zip. An upgrade request fetches the https://me.com/packs/, expecting an HTML page with links to the available versions. It then selects the latest version.
provides(atom)
Announce that the pack provides facilities identified by the given token. Optionally, the token may be given a version using @(Token,Version). A pack implicitly provides @(PackName,PackVersion). The supplied tokens operate in the same name space as packages and thus the same care must be taken to select a name. Multiple of these claims may be present.
requires(dependency)
The pack depends on the availability of Dependency. The Dependency is a token, normally the name of another package. See provides. The dependency may be further refined by writing Token Cmp Version, where Cmp is one of Prolog's standard numerical comparison operators. See cmp_versions/3. This metadata is also used to state requirements on Prolog. See section 15.5.1.1. Multiple requirements are expressed with multiple claims.
conflicts(dependency)
The pack cannot be use together with the indicated Dependency. This is the negation of requires.
replaces(atom)
This pack replaces some other pack.
autoload(boolean)
If true, add the library for the package as autoload library. This implies that the exported predicates may be used without explicitly importing the library. Use with care.

15.5.1.1 Pack requirements on Prolog

The file pack.pl may contain requires(Requirement) statements. Normally, Requirement is a pack or token, optionally with a version requirement. The requirement prolog is reserved for requirements on the Prolog version while prolog:Feature may be used to demand specific features. Feature matching is described with require_prolog_version/2. Multiple requirements on Prolog must all be true. Below are some examples 

requires(prolog >= '9.2').        % 9.2.0 or later
requires(prolog:threads).         % flag threads = true
requires(prolog:library(socket)). % library(socket) exists
requires(prolog:bounded(false)).  % flag bounded = false

15.5.2 Packs with foreign code

Many packs include C or C++ resources. Such packs include the C or C++ resources in a subdirectory of the pack. There are no restrictions for naming this subdirectory or structuring the source files in this directory. The build process must create native modules in the directory lib/<arch>, where <arch> is the architecture as obtained by the Prolog flag arch.

The build process identifies control files that tell the package manager which build tool to use. The package manager populates the process environment with variables that provide details about the running Prolog instance. This environment is saved in a file buildenv.sh in the pack root or build directory. By sourcing this file, the user may run the build tools by hand for debugging purposes.

The build process consists of five steps that are described below

dependencies
This step currently only supports conan. It is executed if either conanfile.txt or conanfile.py is found in the root directory of the pack.
configure
This preparation step is executed if one of CMakeLists.txt (cmake), configure, configure.in (autoconf), configure.ac or Makefile.am (automake) are found. The program to manage them is in parenthesis.
build
Build the process. When configured using (cmake) this will use (cmake). Otherwise either Makefile or makefile is expected and Unix make is used to build the process.
test
Test the project. Either uses cmake or the GNU convention make check.
install
Install the project. Either uses cmake or the GNU convention make install.

While running the above tools, the environment is populated. The names of the variables provided depends on the pack_version(Version) metadata. We give the names for version 2, with the names for version 1 in parenthesis if this differs from the version 2 name.

PATH
Contains the environment path with the directory holding the currently running SWI-Prolog instance prepended in front of it. As a result, swipl is always present and runs the same SWI-Prolog instance as the current Prolog process.
SWIPL
Contains the absolute file name of the running executable.
SWIPL_PACK_VERSION
Version of the pack system (1 or 2). If not present we must assume‘1’.
SWIPL_VERSION (SWIPLVERSION)
Contains the numeric SWI-Prolog version defined as Major × 10000 + Minor × 100 + Patch
SWIPL_HOME_DIR (SWIHOME)
Contains the directory holding the SWI-Prolog home.
SWIPL_ARCH (SWIARCH)
contains the machine architecture identifier.
SWIPL_MODULE_DIR (PACKSODIR)
constains the destination directory for shared objects/DLLs relative to a Prolog pack, i.e., lib/$SWIARCH.
SWIPL_MODULE_LIB (SWISOLIB)
The SWI-Prolog library or an empty string when it is not required to link modules against this library (e.g., ELF systems)
SWIPL_LIB (SWILIB)
The SWI-Prolog library we need to link to for programs that embed SWI-Prolog (normally -lswipl)
SWIPL_INCLUDE_DIRS
CMake style variable that contains the directory holding SWI-Prolog.h, SWI-Stream.h and SWI-cpp2.h.
SWIPL_LIBRARIES_DIR
CMake style variable that contains the directory holding libswipl
SWIPL_CC (CC)
C compiler used to build SWI-Prolog.
SWIPL_LD (LD)
Linker used to link SWI-Prolog.
SWIPL_CFLAGS (CFLAGS)
C-Flags for building extensions. Always contains -ISWIPL-INCLUDE-DIR.
SWIPL_MODULE_LDFLAGS (LDSOFLAGS)
Link flags for linking modules.
SWIPL_MODULE_EXT (SOEXT)
File name extension for modules (e.g., .so or .dll)
SWIPL_PREFIX (PREFIX)
Install prefix for global binaries, libraries and include files.

15.5.2.1 Compiling a foreign extension using a simple Makefile

If the package requires some C code to be compiled that has no dependencies and needs no configuration it is probably easiest to use a simple Unix make file. We assume pack_version(2). Here is a simple Makefile. We assume the pack contains a file c/environ.c that contains the C source. Following the GNU guidelines, the Makefile must define the following targets:

all (default)
Build the foreign extension. In this very simple case we build the resulting module directly in the target directory.
check
Test the package. This is executed after the default build target.
install
Install the package. In this case this does nothing.
clean
Clean the package. This target disposes intermediate build products.
distclean
Restore the package to its fully clean state. This implies that all built products and intermediate build products are removed. The distclean target is used by pack_rebuild/1.
MODULE= $(SWIPL_MODULE_DIR)/environ.$(SOEXT)
CFLAGS= $(SWIPL_CFLAGS)

all:    $(MODULE)

OBJ=c/environ.o

$(MODULE): $(OBJ)
        mkdir -p $(SWIPL_MODULE_DIR)
        $(SWIPL_LD) $(SWIPL_MODULE_LDFLAGS) -o $@ $(OBJ) $(SWIPL_MODULE_LIB)

check::
        $(SWIPL) -g run_tests -t halt test/test_environ.pl
install::
clean:
        rm -f $(OBJ)
distclean: clean
        rm -f $(MODULE)

15.5.2.2 Publishing a pack

As described in section 15.4, a pack is distributed either as an archive file or as a GIT repository. We strongly encourage using a GIT repository as that gives good version and provenance support. Packs may be published by hand by making the archive or git repository available from a globally accessible place on the internet and installing the pack from this location. This process is streamlined, notably for GIT packs using pack_publish/2 and the app pack. To publish a pack a local GIT repository that has publicly accessible origin,

  1. Update version(Version) in pack.pl
  2. Commit all changes, make sure the the repository is clean.
  3. Run 
    swipl pack publish .

This will

  1. Verify the repository is clean and on the default branch.
  2. Tag the repository with V<version>. By default, the tag will be signed. Please setup signing for GIT or use the “--no-sign`` option.
  3. Push the repository and release tag.
  4. Figure out the download location, either from the download(URL) metadata or the GIT remote information.
  5. Install the package and its dependencies in a temporary isolated pack environment.
  6. On success, register the pack with the server.
  7. Delete the isolated pack environment.

Similarly, a pack can be published from a public archive using the command below. When using an archive, never change the content of the archive but, instead, create a new archive with a new version. 

swipl pack publish URL

15.5.2.3 Compiling a foreign extension using CMake

If the package is more complicated, a simple Makefile typically does not suffice. In this case we have two options. One is to use the GNU autoconf or automake. However, cmake is getting more popular and provides much better support for non-POSIX platforms, e.g., Windows. This section discusses building the same package as section 15.5.2.1 using cmake.

To use cmake, add the content below as the file CMakeLists.txt to the root directory of the pack. SWI-Prolog ships with a cmake include file named swipl.cmake that deals with most of the configuration issues. Comments in the file below explain the various steps of the process. 

cmake_minimum_required(VERSION 3.5)
project(swipl-pack-environ)

# Include swipl.cmake from the running SWI-Prolog's home
list(INSERT CMAKE_MODULE_PATH 0 $ENV{SWIPL_HOME_DIR}/cmake)
include(swipl)

# Create the library as a CMake module
add_library(environ MODULE c/environ.c)

# Link the library to SWI-Prolog.  This also removes the `lib` prefix
# from the target on systems that define a common library file prefix
target_link_swipl(environ)

# Install the foreign taget. `${swipl_module_dir}` contains the
# directory for installing modules for this architecture.

install(TARGETS environ
        DESTINATION ${CMAKE_CURRENT_SOURCE_DIR}/${swipl_module_dir})

# Run  tests.  This  is  executed   before    the   pack  is  installed.
# swipl_test(name) runs Prolog with the command line below.
#
#    swipl -p foreign=${CMAKE_CURRENT_SOURCE_DIR}/${swipl_module_dir} \
#          -p library=${CMAKE_CURRENT_SOURCE_DIR}/prolog \
#          --on-error=status \
#          -g test_${name} \
#          -t halt \
#          ${CMAKE_CURRENT_SOURCE_DIR}/test/test_${name}.pl
#
# This  implies  that  a  test  `name`  must    be  defined  in  a  file
# `test/test_${name}.pl`, which exports a  predicate `test_${name}`. The
# test succeeds if this predicate  succeeds   and  no error messages are
# printed.

enable_testing()
swipl_add_test(environ)

15.5.3 Updating a package

If a package needs a revision to fix bugs or add functionality it needs to be updated. First, we create a development environment using

  1. Clone the git repository that provides the pack.
  2. Install the pack as a link using the command below. If the pack contains foreign build scripts, this creates a file buildenv.sh that contains the environment variables for building the pack. 
    ?- pack_install(.).

Next, we can edit the pack sources and rebuild it the chosen build tools after running source buildenv.sh to set the appropriate environment variables. After validating that the pack works as expected follow the instructions in section 15.5.2.2 to publish the new version.

ClioPatria (version V3.1.1-51-ga0b30a5)