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:
- 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
- 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.txt for a description of
pack.pl
- - ForeignPack.txt 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