prolog_pack.pl -- A package manager for Prolog

The 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 attach_packs/0 that makes installed packages available as libraries.

See also: - Installed packages can be inspected using ?- doc_browser.
To be done: - Version logic; - Find and resolve conflicts; - Upgrade git packages; - Validate git packages; - Test packages: run tests from directory `test'.

current_pack(?Pack) is nondet[private]

True if Pack is a currently installed pack.

pack_list_installed is det

List currently installed packages. Unlike pack_list/1, only locally installed packages are displayed and no connection is made to the internet.

See also: - Use pack_list/1 to find packages.

pack_info(+Pack)

Print more detailed information about Pack.

pack_info_term(+PackDir, ?Info) is nondet[private]

True when Info is meta-data for the package PackName.

pack_info_term(?Term) is nondet[private]

True when Term describes name and arguments of a valid package info term.

pack_search(+Query) is det

pack_list(+Query) is det

Query package server and installed packages and display results. 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:

Installation status
- p: package, not installed
- i: installed package; up-to-date with public version
- U: installed package; can be upgraded
- A: installed package; newer than publically available
- l: installed package; not on server
Name@Version
Name@Version(ServerVersion)
Title

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

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

See also: - pack_list_installed/0 to list installed packages without contacting the server.

pack_install(+Spec:atom) is det

Install a package. Spec is one of

Archive file name
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.
GIT URL (not well supported yet)
A local directory name given as file:// URL.
A package name. This queries the package repository at http://www.swi-prolog.org

After resolving the type of package, pack_install/2 is used to do the actual installation.

pack_default_options(+Spec, -Pack, +OptionsIn, -Options) is det[private]

Establish the pack name (Pack) and install options from a specification and options (OptionsIn) provided by the user.

pack_select_candidate(+Pack, +AvailableVersions, +OptionsIn, -Options)[private]

Select from available packages.

pack_install(+Name, +Options) is det

Install package Name. Processes the options below. Default options as would be used by pack_install/1 are used to complete the provided Options.

url(+URL): Source for downloading the package
package_directory(+Dir): Directory into which to install the package
interactive(+Boolean): Use default answer without asking the user if there is a default action.
silent(+Boolean): If true (default false), suppress informational progress messages.
upgrade(+Boolean): If true (default false), upgrade package if it is already installed.
git(+Boolean): If true (default false unless URL ends with =.git=), assume the URL is a GIT repository.

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

pack_install(+Pack, +PackDir, +Options)[private]

Install package Pack into PackDir. Options:

url(URL): Install from the given URL, URL is either a file://, a git URL or a download URL.
upgrade(Boolean): If Pack is already installed and Boolean is true, update the package to the latest version. If Boolean is false print an error and fail.

pack_install_from_local(+Source, +PackTopDir, +Name, +Options)[private]

Install a package from a local media.

To be done: - Provide an option to install directories using a link (or file-links).

pack_unpack(+SourceFile, +PackDir, +Pack, +Options)[private]

Unpack an archive to the given package dir.

pack_archive_info(+Archive, +Pack, -Info, -Strip)[private]

True when Archive archives Pack. Info is unified with the terms from pack.pl in the pack and Strip is the strip-option for archive_extract/3.

Requires library(archive), which is lazily loaded when needed.

Errors: - existence_error(pack_file, 'pack.pl') if the archive doesn't contain pack.pl; - Syntax errors if pack.pl cannot be parsed.

pack_git_info(+GitDir, -Hash, -Info) is det[private]

Retrieve info from a cloned git repository that is compatible with pack_archive_info/4.

download_file_sanity_check(+Archive, +Pack, +Info) is semidet[private]

Perform basic sanity checks on DownloadFile

prepare_pack_dir(+Dir, +Options)[private]

Prepare for installing the package into Dir. This should create Dir if it does not exist and warn if the directory already exists, asking to make it empty.

empty_directory(+Directory) is semidet[private]

True if Directory is empty (holds no files or sub-directories).

pack_install_from_url(+Scheme, +URL, +PackDir, +Pack, +Options)[private]

Install a package from a remote source. For git repositories, we simply clone. Archives are downloaded. We currently use the built-in HTTP client. For complete coverage, we should consider using an external (e.g., curl) if available.

download_file(+URL, +Pack, -File, +Options) is det[private]

pack_url_file(+URL, -File) is det

True if 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.

ssl_verify(+SSL, +ProblemCert, +AllCerts, +FirstCert, +Error)[private]

Currently we accept all certificates. We organise our own security using SHA1 signatures, so we do not care about the source of the data.

download_url(+URL) is det[private]

True if URL looks like a URL we can download from.

pack_post_install(+Pack, +PackDir, +Options) is det[private]

Process post installation work. Steps:

Create foreign resources [TBD]
Register directory as autoload library
Attach the package

pack_rebuild(+Pack) is det

Rebuilt possible foreign components of Pack.

pack_rebuild is det

Rebuild foreign components of all packages.

post_install_foreign(+Pack, +PackDir, +Options) is det[private]

Install foreign parts of the package.

configure_foreign(+PackDir, +Options) is det[private]

Run configure if it exists. If configure.ac or configure.in exists, first run autoheader and autoconf

cmake_configure_foreign(+PackDir, +Options) is det[private]

Create a build directory in PackDir and run `cmake ..`

make_foreign(+PackDir, +Options) is det[private]

Generate the foreign executable.

save_build_environment(+PackDir)[private]

Create a shell-script build.env that contains the build environment.

environment(-Name, -Value) is nondet[multifile]

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 def_environment/2. In addition to changing the environment, this may be used to pass additional values to the environment, as in:

prolog_pack:environment('USER', User) :-
    getenv('USER', User).

Arguments:

`Name`	- is an atom denoting a valid variable name
`Value`	- is either an atom or number representing the value of the variable.

def_environment(-Name, -Value) is nondet[private]

True if Name=Value must appear in the environment for building foreign extensions.

default_c_compiler(-CC) is semidet[private]

Try to find a suitable C compiler for compiling packages with foreign code.

To be done: - Needs proper defaults for Windows. Find MinGW? Find MSVC?

post_install_autoload(+PackDir, +Options)[private]

Create an autoload index if the package demands such.

pack_upgrade(+Pack) is semidet

Try to upgrade the package Pack.

To be done: - Update dependencies when updating a pack from git?

pack_remove(+Name) is det

Remove the indicated package.

pack_property(?Pack, ?Property) is nondet

True when Property is a property of an installed Pack. This interface is intended for programs that wish to interact with the package manager. Defined properties are:

directory(Directory): Directory into which the package is installed
version(Version): Installed version
title(Title): Full title of the package
author(Author): Registered author
download(URL): Official download URL
readme(File): Package README file (if present)
todo(File): Package TODO file (if present)

git_url(+URL, -Pack) is semidet[private]

True if URL describes a git url for Pack

safe_pack_name(+Name:atom) is semidet[private]

Verifies that Name is a valid pack name. This avoids trickery with pack file names to make shell commands behave unexpectly.

pack_version_file(-Pack, -Version, +File) is semidet[private]

True if File is the name of a file or URL of a file that contains Pack at Version. File must have an extension and the basename must be of the form <pack>-<n>{.<m>}*. E.g., mypack-1.5.

github_release_url(+URL, -Pack, -Version) is semidet[private]

True when URL is the URL of a GitHub release. Such releases are accessible as

https:/github.com/<owner>/<pack>/archive/[vV]?<version>.zip'

atom_version(?Atom, ?Version)[private]

Translate between atomic version representation and term representation. The term representation is a list of version components as integers and can be compared using @>

pack_inquiry(+URL, +DownloadFile, +Info, +Options) is semidet[private]

Query the status of a package with the central repository. To do this, we POST a Prolog document containing the URL, info and the SHA1 hash to http://www.swi-prolog.org/pack/eval. The server replies using a list of Prolog terms, described below. The only member that is always included is downloads (with default value 0).

alt_hash(Count, URLs, Hash): A file with the same base-name, but a different hash was found at URLs and downloaded Count times.
downloads(Count): Number of times a file with this hash was downloaded.
rating(VoteCount, Rating): User rating (1..5), provided based on VoteCount votes.
dependency(Token, Pack, Version, URLs, SubDeps): Required tokens can be provided by the given provides.

query_pack_server(+Query, -Result, +Options)[private]

Send a Prolog query to the package server and process its results.

inquiry_result(+Reply, +File, +Options) is semidet[private]

Analyse the results of the inquiry and decide whether to continue or not.

select_dependency_resolution(+Deps, -Eval, +Options)[private]

Select a resolution.

To be done: - Exploit backtracking over resolve_dependencies/2.

install_dependency(+Options, +TokenResolution)[private]

Install dependencies for the given resolution.

To be done: - : Query URI to use

available_download_versions(+URL, -Versions) is det[private]

Deal with wildcard URLs, returning a list of Version-URL pairs, sorted by version.

To be done: - Deal with protocols other than HTTP

github_url(+URL, -User, -Repo) is semidet[private]

True when URL refers to a github repository.

github_version(+User, +Repo, -Version, -VersionURI) is nondet[private]

True when Version is a release version and VersionURI is the download location for the zip file.

update_dependency_db[private]

Reload dependency declarations between packages.

validate_dependencies is det[private]

Validate all dependencies, reporting on failures

pack_provides(?Package, ?Token) is multi[private]

True if Pack provides Token. A package always provides itself.

pack_depends_on(?Pack, ?Dependency) is nondet[private]

True if Pack requires Dependency, direct or indirect.

resolve_dependencies(+Dependencies, -Resolution) is multi[private]

Resolve dependencies as reported by the remote package server.

Arguments:

`Dependencies`	- is a list of `dependency(Token, Pack, Version, URLs, SubDeps)`
`Resolution`	- is a list of items Token-`resolved(Pack)` Token-`resolve(Pack, Version, URLs, SubResolve)` Token-unresolved

To be done

- Watch out for conflicts

- If there are different packs that resolve a token, make an intelligent choice instead of using the first

run_process(+Executable, +Argv, +Options) is det[private]

Run Executable. Defined options:

directory(+Dir): Execute in the given directory
output(-Out): Unify Out with a list of codes representing stdout of the command. Otherwise the output is handed to print_message/2 with level informational.
error(-Error): As output(Out), but messages are printed at level error.
env(+Environment): Environment passed to the new process.

menu(Question, +Alternatives, +Default, -Selection, +Options)[private]

confirm(+Question, +Default, +Options) is semidet[private]

Ask for confirmation.

Arguments:

Default - is one of yes, no or none.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

pack_list(Arg1)