What is a pack?

A pack is a community contributed extension. Packs provide additional Prolog libraries, often including foreign (C,C++) libraries. A pack can be installed system-wide, user-wide or as part of a specific application. SWI-Prolog searches for packs in sub-directories of directories in the file search path (see file_search_path/2) pack. Each pack is a directory 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.

Packs that use foreign code (C,C++) is described here.

How do I install a pack?

After finding a suitable pack, usually from SWI-Prolog web site listed here, it may be installed from the command line using the pack app:

swipl pack install <pack>

The pack app provides many commands for managing packs. Use the command below for help

swipl pack --help

A few common commands are:

• swipl pack search <pattern>
  Find published packs by name.
• swipl pack install <from>
  Install a pack from its name, URL, archive file or directory.
• swipl pack remove <pack>
  Remove a pack.
• swipl pack list --installed
  List installed packages and their update status.
• swipl pack info <pack>
  List details on a specific pack.

All these commands are also available as Prolog predicates from the library(prolog_pack). See for example pack_install/1,2

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. For local testing, the pack can be installed from the directory using the command below. On systems that support it, this creates a symbolic link. On other systems the directory is copied to one of the directories where packs are searched. After that, possible foreign extensions are built and the pack is made available.

swipl pack install .

Publishing a pack

A pack can be published in two ways: as a link to a GIT repository or by creating an archive file. We recommend using a GIT repository on e.g., github or gitlab. Using a git repository provides a stable download location as well as easy tracking of changes and releasing versions. swipl pack install can be asked to install at a specific tag or commit hash, providing precise version control to the user.

When using an archive file, this file is either a gzipped tar file or a zip 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

For downloading from their registered name, the pack must be hosted on a public web 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 https://www.example.com/swi-prolog/pack/mypack-1.0.tgz, fetching https://www.example.com/swi-prolog/pack/ must return an HTML document with links to available package files. Although not yet enforced, we strongly advice to use https for security.

Registering the pack

Once the pack is available from a public location, it may registered with the package list using

swipl pack publish <url>

This will

1. Download the pack to a temporary directory
2. Build and test it (if needed)
3. Establish the meta data
4. Register the pack.

Updating a pack

To update a pack

1. Update the version in the pack.pl meta data
2. For a git repository
   • Commit the final changes
   • Tag the repository using V<version> (see git tag). It is strongly recommended to sign the version tag.
   • Push the result (including the tag)
   • Use swipl pack publish <url>
3. For a file
   • Create a new archive following the naming conventions above (<pack>-<version>.tgz or <pack>-<version>.zip)
   • Upload it to the same directory as the previous version
   • Use swipl pack publish <url>

Moving a pack

Once registered, packs cannot be moved to a different location. This implies that if you have exclusive control of the git repository or directory holding the archives, nobody can hijack your pack. If there is a need to move the pack anyway, contact the site administrator.

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 https://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. For example, do not use util as file or module name.
• 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