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.

To make changes to a package:

• Clone the git repo, then go into the repo and run: ?- pack_install(.). This builds the pack locally and creates a symlink to make it available. It will also write a file buildenv.sh that you can source to get the environment for running a normal make (this is done only if there is a configure step; i.e., if there is a configure.in or configure file).
• `(source ./buildenv.sh` && make)` to rebuild
• ?- pack_rebuild(package_name). This runs `make distclean and make` with the right environment.
• The build process also supports cmake.

Once you have made the changes, you should edit the pack.pl file to change the version item. After updating the git repo, issue a pack_install(package_name, [upgrade(true), test(true), rebuild(make)]) to cause the repository to refresh. You can simulate the full installation process by removing all the build files in the package (including any in submodules), running pack_install/1, and then running pack_install using a file:// URL.

See also

- Installed packages can be inspected using ?- doc_browser.

- library(build/tools)

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]

 current_pack(?Pack, ?Dir) is nondet[private]

True if Pack is a currently installed pack.

 pack_list_installed is det

List currently installed packages. This calls

?- pack_list('', [server(false)]).

See also

- pack_list/2.

 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_list(+Query) is det

 pack_list(+Query, +Options) is det

 pack_search(+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

Options processed:

installed(true)

Only list packages that are locally installed. Contacts the server to compare our local version to the latest available version.

outdated(true)

Only list packages that need to be updated. This option implies installed(true).

server((Server|false))

If false, do not contact the server. This implies installed(true). Otherwise, use the given pack server.

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

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

See also

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

 join_status(+PacksIn, -PacksOut) is det[private]

Combine local and remote information to assess the status of each package. PacksOut is a list of pack(Name, Status, Version, URL). If the versions do not match, Version is VersionInstalled-VersionRemote and similar for thee URL.

 local_search(+Query, -Packs:list(atom)) is det[private]

Search locally installed packs.

 pack_install(+Spec:atom) is det

Install a package. Spec is one of

• A package name. This queries the package repository at http://www.swi-prolog.org
• 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
• '.', in which case a relative symlink is created to the current directory (all other options for Spec make a copy of the files).

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.

 in_explicit_pack_dir(+Pack, +Options) is semidet[private]

True when Pack is installed in the explicit target directory.

 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.

global(+Boolean)

If true, install in the XDG common application data path, making the pack accessible to everyone. If 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.

insecure(+Boolean)

When true (default false), do not perform any checks on SSL certificates when downloading using https.

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.

rebuild(Condition)

Rebuild the foreign components. Condition is one of if_absent (default, do nothing if the directory with foreign resources exists), make (run make) or true (run `make distclean` followed by the default configure and build steps).

test(Boolean)

If true (default), run the pack tests.

git(+Boolean)

If true (default false unless URL ends with =.git=), assume the URL is a GIT repository.

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.

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_install_local(:Spec, +Dir, +Options) is det

Install a number of packages in a local directory. This predicate supports installing packages local to an application rather than globally.

 pack_install_local_(+Latest, +Installed, +Options, +PackAndOptions) is det[private]

 local_packs(+Dir, -Packs) is det[private]

True when Packs is a list of package search term results for packs installed in 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

• If the directory exist and is empty, done.
• Else if the directory exists, remove the directory and recreate it. Note that if the directory is a symlink this just deletes the link.
• Else create the directory.

 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.

 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
• Register directory as autoload library
• Attach the package

 pack_rebuild(+Pack) is det

Rebuild 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.

 foreign_present(+PackDir) is semidet[private]

True if we find one or more modules in the pack lib directory for the current architecture. Does not check that these can be loaded, nor whether all required modules are present.

 is_foreign_pack(+PackDir, -Type) is nondet[private]

True when PackDir contains files that indicate the need for a specific class of build tools indicated by Type.

 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'

 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

 pack_attach(+Dir, +Options) is det

Attach a single package in Dir. The Dir is expected to contain the file pack.pl and a prolog directory. Options processed:

duplicate(+Action)

What to do if the same package is already installed in a different directory. Action is one of

warning

Warn and ignore the package

keep

Silently ignore the package

replace

Unregister the existing and insert the new package

search(+Where)

Determines the order of searching package library directories. Default is last, alternative is first.

See also

- attach_packs/2 to attach multiple packs from a directory.

 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.

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.

 pack_list(+Query) is det

 pack_list(+Query, +Options) is det

 pack_search(+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

Options processed:

installed(true)

Only list packages that are locally installed. Contacts the server to compare our local version to the latest available version.

outdated(true)

Only list packages that need to be updated. This option implies installed(true).

server((Server|false))

If false, do not contact the server. This implies installed(true). Otherwise, use the given pack server.

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

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

See also

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

 pack_list(+Query) is det

 pack_list(+Query, +Options) is det

 pack_search(+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

Options processed:

installed(true)

Only list packages that are locally installed. Contacts the server to compare our local version to the latest available version.

outdated(true)

Only list packages that need to be updated. This option implies installed(true).

server((Server|false))

If false, do not contact the server. This implies installed(true). Otherwise, use the given pack server.

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

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

See also

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