% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(prolog_pack): A package manager for Prolog}

\label{sec:prologpack}

\begin{tags}
\mtag{See also}- Installed packages can be inspected using \verb$?- doc_browser.$ \\- \file{library(build/tools)}\mtag{To be done}- Version logic \\- Find and resolve conflicts \\- Upgrade git packages \\- Validate git packages \\- Test packages: run tests from directory `test'.
\end{tags}

The \file{library(prolog_pack)} provides the SWI-Prolog package manager. This
library lets you inspect installed packages, install packages, remove
packages, etc. It is complemented by the built-in \predref{attach_packs}{0} that
makes installed packages available as libraries.

To make changes to a package:

\begin{itemize}
    \item Clone the git repo,t go into the repo and run:
\verb$?- pack_install(.).$
This builds the pack locally and creates a symlink to make it available.
    \item \verb$?- pack_rebuild(package_name).$
This runs `make distclean\verb$ and $make` with the right environment. It will also
write a file \verb$buildendv.sh$ that you can source to get the environment
for running a normal \const{make} (this is done only if there is a \const{configure}
step; i.e., if there is a \verb$configure.in$ or \const{configure}.
    \item The build process also supports \const{cmake}.
\end{itemize}

Once you have made the changes, you should edit the \verb$pack.pl$ file
to change the \const{version} item. After updating the git repo, issue
a \verb$pack_install(package_name, [upgrade(true), test(true), rebuild(make)])$
to cause the repository to refresh.\vspace{0.7cm}

\begin{description}
    \predicate[det]{pack_list_installed}{0}{}
List currently installed packages. Unlike \predref{pack_list}{1}, only
locally installed packages are displayed and no connection is
made to the internet.

\begin{tags}
    \tag{See also}
Use \predref{pack_list}{1} to find packages.
\end{tags}

    \predicate{pack_info}{1}{+Pack}
Print more detailed information about \arg{Pack}.

    \predicate[det]{pack_search}{1}{+Query}
\nodescription
    \predicate[det]{pack_list}{1}{+Query}
\arg{Query} package server and installed packages and display results.
\arg{Query} is matches case-insensitively against the name and title
of known and installed packages. For each matching package, a
single line is displayed that provides:

\begin{itemize}
    \item Installation status

\begin{itemize}
    \item \textbf{p}: package, not installed
    \item \textbf{i}: installed package; up-to-date with public version
    \item \textbf{U}: installed package; can be upgraded
    \item \textbf{A}: installed package; newer than publically available
    \item \textbf{l}: installed package; not on server
\end{itemize}

    \item Name@Version
    \item Name@Version(ServerVersion)
    \item Title
\end{itemize}

Hint: \verb$?- pack_list('').$ lists all packages.

The predicates \predref{pack_list}{1} and \predref{pack_search}{1} are synonyms. Both
contact the package server at \url{http://www.swi-prolog.org} to find
available packages.

\begin{tags}
    \tag{See also}
\predref{pack_list_installed}{0} to list installed packages without
contacting the server.
\end{tags}

    \predicate[det]{pack_install}{1}{+Spec:atom}
Install a package. \arg{Spec} is one of

\begin{itemize}
    \item Archive file name
    \item HTTP URL of an archive file name. This URL may contain a
star (*) for the version. In this case pack_install asks
for the directory content and selects the latest version.
    \item GIT URL (not well supported yet)
    \item A local directory name given as \verb$file://$ URL or \verb$'.'$
    \item A package name. This queries the package repository
at \url{http://www.swi-prolog.org}
\end{itemize}

After resolving the type of package, \predref{pack_install}{2} is used to
do the actual installation.

    \predicate[det]{pack_install}{2}{+Name, +Options}
Install package \arg{Name}. Processes the options below. Default
options as would be used by \predref{pack_install}{1} are used to complete
the provided \arg{Options}.

\begin{description}
    \termitem{url}{+URL}
Source for downloading the package
    \termitem{package_directory}{+Dir}
Directory into which to install the package.
    \termitem{global}{+Boolean}
If \const{true}, install in the XDG common application data path, making
the pack accessible to everyone. If \const{false}, install in the XDG
user application data path, making the pack accessible for the
current user only. If the option is absent, use the first
existing and writable directory. If that doesn't exist find
locations where it can be created and prompt the user to do
so.
    \termitem{interactive}{+Boolean}
Use default answer without asking the user if there
is a default action.
    \termitem{silent}{+Boolean}
If \const{true} (default false), suppress informational progress
messages.
    \termitem{upgrade}{+Boolean}
If \const{true} (default \const{false}), upgrade package if it is already
installed.
    \termitem{rebuild}{Condition}
Rebuild the foreign components. \arg{Condition} is one of
\verb$if_absent$ (default, do nothing if the directory with foreign
resources exists), \const{make} (run \const{make}) or \const{true} (run `make
distclean` followed by the default configure and build steps).
    \termitem{test}{Boolean}
If \const{true} (default), run the pack tests.
    \termitem{git}{+Boolean}
If \const{true} (default \const{false} unless \arg{URL} ends with =.git=),
assume the URL is a GIT repository.
    \termitem{link}{+Boolean}
Can be used if the installation source is a local directory
and the file system supports symbolic links. In this case
the system adds the current directory to the pack registration
using a symbolic link and performs the local installation steps.
\end{description}

Non-interactive installation can be established using the option
\verb$interactive(false)$. It is adviced to install from a particular
\textit{trusted} URL instead of the plain pack name for unattented
operation.

    \predicate[det]{pack_url_file}{2}{+URL, -File}
True if \arg{File} is a unique id for the referenced pack and version.
Normally, that is simply the base name, but GitHub archives
destroy this picture. Needed by the pack manager.

    \predicate{ssl_verify}{5}{+SSL, +ProblemCert, +AllCerts, +FirstCert, +Error}
Currently we accept all certificates. We organise our own
security using SHA1 signatures, so we do not care about the
source of the data.

    \predicate[det]{pack_rebuild}{1}{+Pack}
Rebuild possible foreign components of \arg{Pack}.

    \predicate[det]{pack_rebuild}{0}{}
Rebuild foreign components of all packages.

    \predicate[semidet]{pack_upgrade}{1}{+Pack}
Try to upgrade the package \arg{Pack}.

\begin{tags}
    \tag{To be done}
Update dependencies when updating a pack from git?
\end{tags}

    \predicate[det]{pack_remove}{1}{+Name}
Remove the indicated package.

    \predicate[nondet]{pack_property}{2}{?Pack, ?Property}
True when \arg{Property} is a property of an installed \arg{Pack}. This
interface is intended for programs that wish to interact with the
package manager. Defined properties are:

\begin{description}
    \termitem{directory}{Directory}
\arg{Directory} into which the package is installed
    \termitem{version}{Version}
Installed version
    \termitem{title}{Title}
Full title of the package
    \termitem{author}{Author}
Registered author
    \termitem{download}{URL}
Official download \arg{URL}
    \termitem{readme}{File}
Package \file{README} file (if present)
    \termitem{todo}{File}
Package \file{TODO} file (if present)
\end{description}

    \predicate{atom_version}{2}{?Atom, ?Version}
Translate between atomic version representation and term
representation. The term representation is a list of version
components as integers and can be compared using \verb$@>$

    \predicate[det]{pack_attach}{2}{+Dir, +Options}
Attach a single package in \arg{Dir}. The \arg{Dir} is expected to contain
the file \verb$pack.pl$ and a \const{prolog} directory. \arg{Options} processed:

\begin{description}
    \termitem{duplicate}{+Action}
What to do if the same package is already installed in a different
directory. \arg{Action} is one of

\begin{description}
    \termitem{warning}{}
Warn and ignore the package
    \termitem{keep}{}
Silently ignore the package
    \termitem{replace}{}
Unregister the existing and insert the new package
\end{description}

    \termitem{search}{+Where}
Determines the order of searching package library directories.
Default is \const{last}, alternative is \const{first}.
\end{description}

\begin{tags}
    \tag{See also}
\predref{attach_packs}{2} to attach multiple packs from a directory.
\end{tags}
\end{description}