Did you know ... Search Documentation:
Creating and submitting extension packages for SWI-Prolog

What is a pack?

A pack is an archive (.zip or .tgz) file that (minimally) contains, two items:

A subdirectory prolog
If the pack is installed, this directory is added to the Prolog library. This directory contains Prolog files using the extension .pl.
A file pack.pl
This file provides meta-data for the pack.

Creating a pack that uses C or C++ code is described here

Creating a pack

A pack is created by creating a directory with the name of the pack and filling it with the content described above. Next, create an archive, which is either a gzipped tar file or a zip file from the file that must be named <pack>-<version>.tgz or <pack>-<version>.zip, where version is a list of digits, separated by dots (.). For example:

% tar zcvf mypack-1.0.tgz mypack

or

% zip -r mypack-1.0.zip mypack

Test the pack

The pack may be installed using pack_install/1 as illustrated below.

?- pack_install('mypack-1.0.tgz').

Make the pack available

To make the pack available, it must be downloadable from a publicly available HTTP server. To support package upgrading, the HTTP server must have enabled fetching an index of the directory. I.e., if the pack is located at http://www.example.com/swi-prolog/pack/mypack-1.0.tgz, fetching http://www.example.com/swi-prolog/pack/ must return an HTML document with links to available package files.

After uploading the package to e.g., http://www.example.com/swi-prolog/pack/mypack-1.0.tgz, it is made available to other users simply by installing it yourself:

?- pack_install('http://www.example.com/swi-prolog/pack/mypack-1.0.tgz').

After this, other people can install your package simply using

?- pack_install(mypack).

Using GitHub

Packages can be downloaded from GitHub in two ways:

  1. Using the GIT protocol. In this case, the URL looks like below. Be sure to add the =.git= extension. This is not needed for GIT, but it tells the SWI-Prolog package manager that this is a git repository rather than a file.
    https://github.com/<owner>/<pack>.git
  2. Using GitHub releases. These are created by adding and pushing a release tag or using the GitHub website. The resulting archive can be accessed at the URL below. Please use the =.zip= because the package manager does not understand the double extension =.tar.gz=. The tag must be dotted version number, optionally preceded by a v or V.
    https://github.com/<owner>/<pack>/archive/<tag>.zip

The advantage of using GitHub releases is that you decide when a new version is ready for public use. Using GitHub releases requires SWI-Prolog 7.1.22 or later. Automatic update checking can be enabled by setting the download attribute of the pack to:

https://github.com/<owner>/<pack>/releases/*.zip

Dos and Don'ts

To make packages work smoothly, package submitters need to take care of some rules:

  • Use a meaningful name for your package that is not likely to conflict. Check http://www.swi-prolog.org/pack/list to verify there is no name conflict.
  • All files in the prolog directory must be Prolog module files. Use names for the module files that are not likely to conflict with others.
  • Use consistent version numbers (e.g. 0.1, 0.2 ..., 1.0). Versions are compared by turning the version id into a list of integers that is compared using compare/3. Make sure that the version in pack.pl matches the version encoded in the archive name.
  • If you messed up, fix it and always increment the version number. Uploading a new file with the same name/version is interpreted as a possible security breach by the pack system.
See also
- PackInfo.md for a description of pack.pl
- ForeignPack.md for creating packs with C or C++ code
- list of submitted packages
- library(prolog_pack) for predicates to query, install and remove packs
- Status and TODO
- http://rlaanemets.com/post/show/prolog-pack-development-experience for some experience and best practices