% 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}
    \tag{See also}
Installed packages can be inspected using \verb$?- doc_browser.$\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 \verb$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 libaries.\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.
    \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{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{git}{+Boolean}
If \const{true} (default \const{false} unless \arg{URL} ends with =.git=),
assume the URL is a GIT repository.
\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[det]{pack_rebuild}{1}{+Pack}
Rebuilt possible foreign components of \arg{Pack}.

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

    \predicate[nondet,multifile]{environment}{2}{-Name, -Value}
Hook to define the environment for building packs. This
Multifile hook extends the process environment for building
foreign extensions. A value provided by this hook overrules
defaults provided by \predref{def_environment}{2}. In addition to changing
the environment, this may be used to pass additional values to
the environment, as in:

\begin{code}
prolog_pack:environment('USER', User) :-
    getenv('USER', User).
\end{code}

\begin{arguments}
\arg{Name} & is an atom denoting a valid variable name \\
\arg{Value} & is either an atom or number representing the
value of the variable. \\
\end{arguments}

    \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}
\end{description}

