--- layout: default title: usr/share/doc/pkman/html/index.html --- --- layout: default title: usr/share/doc/pkman/html/index.html ---

pkman

pkman is a package manager utility written in C programming language, and uses (xz compressed) cpio format for packaging. pkman is inspired by the Arch Linux's pacman.

pkman keeps the system up to date by synchronizing the package database from master (or mirror) servers, and upgrading the packages while taking care of dependency packages.

Usage

The following is just a few examples that pkman can do. See the pkman --help for the complete feature set.

Installing packages

To install packages including their dependencies, issue the following command:
# pkman -S package_name_1 package_name_2 ...

To install a package from a specific repository:
# pkman -S repo_name/package_name

Installing package groups

Some packages belong to a group of packages (a package can belong to any number of groups). To install package groups, issue the following command:
# pkman -S group_name_1 group_name_2 ...

To list the packages belong to a group:
$ pkman -Sg group_name_1
Multiple package names can be specified. Without any arguments, list all groups.

Removing packages

To remove a previously installed package leaving all its dependencies installed:
# pkman -R package_name

Upgrading packages

Important! To upgrade a single package try to avoid pkman -Sy package_name, use pkman -Syu package_name instead.

pkman can perform a complete system upgrade, by refreshing the databases, select the necessary package files to download and installing them. This procedure may introduce new dependenies. Therefore, this can take a while.
# pkman -Syu

Package databases can be refreshed by:
# pkman -Sy

To query out-of-date packages:
$ pkman -Qu

Querying package databases

pkman can search in the databases, searching in package names and descriptions as well (EREs (Extended Regular Expressions) are used in case insensitive mode):
$ pkman -Ss ERE_1 ERE_2...

The EREs may list a lot of unwanted results. The search can be limited to package names only. This will exclude to search in package descriptions.
$ pkman -Ss '^pk'

Without any EREs, pkman will list all available packages with their description.
$ pkman -Ss

The search in the installed packages only:
$ pkman -Qs ERE_1 ERE_2...

To display the information page of packages:
$ pkman -Si package_name

For locally installed packages:
$ pkman -Qi package_name

Passing two -i will display more information, such as install reason, backup files and their status:
$ pkman -Qii package_name

To list the files installed by the package:
$ pkman -Ql package_name

To list all installed packages with their version number:
$ pkman -Q

To list installed packages belong to a group:
$ pkman -Qg group_name_1

To list groups with packages that locally installed:
$ pkman -Qg

To query the database to know which package owns specific files:
$ pkman -Qo /path/to/file

To verify whether a package is installed correctly:
$ pkman -Qk package_name
Two ks will perform more checks, three ks will validate hash values (this takes some time). Without any argument, it will check all the installed packages.

To list explicitly installed packages:
$ pkman -Qe

To list packages installed as dependencies:
$ pkman -Qd

Additional commands

To install a "local" package (locally built or downloaded from a different repository):
# pkman -U /path/to/package/packagename-version-arch.pkg.cpio.xz

Database structure

The database files are normally located at /var/lib/pkman/sync. Each repository has a single xz compressed cpio in the following format: repo.db.

Each package has one file (a single package descriptor) in the database cpio. The descriptor contains all the necessary information to identify, populate and verify the package.

Example descriptor file name in the core.db cpio: pkman-0.1-41

To list of the keys stored in the package descriptor, see the /usr/include/libpkman/pkcommon.h header, and look for defines starting with PKCOMMON_KEY_.

Package cache

The pkman place the downloaded package files into /var/lib/pkman/cache.

From time to time it is recommended to clear the package cache, since the pkman will not remove any package file from the cache by itself.
To remove package files that are no longer needed:
# pkman -Sc
To remove all files from the cache:
# pkman -Scc
WARNING! Issue these operation only when previous package versions are not required, for example for a later downgrade. pkman -Sc will keep package files that are currently installed on the system. pkman -Scc, however, will remove all files from the cache (including non-package files).

Configuration

The settings file is located at /etc/pkman/pkman.ini. This file contains the basic settings (i.e. architecture and directories), the known servers and the repositories to work with. Users can alter this file at will, but keep in mind, misconfiguration can cause damage to the system.

User repositories

To add a user repository, modify the /etc/pkman/pkman.ini by creating a new entry under the repository root:
repository.myrepo.name = "myrepo"
To add custom servers, append this:
repository.myrepo.server.mysrv = "http://example.net/threos/$repo/$arch"
Note: mysrv is the key of the server, it is for internal use only, however it must be unique.

Servers listed in repository entries will be applied before global servers.

For details, see pkman --config-help.

Hooks

pkman can run hooks before and after transaction. The conditions when to arm a hooks is defined in the hook.

A hook consists of:

• short, unique name
• human readable description (optional)
• command to run
• the operation when to trigger the hook:
  • install
  • upgrade
  • remove
• when to run the hook:
  • PreTransaction
  • PostTransaction
• type to match the hook targets:
  • file
  • package
• list of extended regular expressions (EREs) to match against; the hook will be triggered if one of the EREs matched
• a flag to abort the transaction if the hook exits non-zero (PreTransaction only, optional)
• list of packages which must be installed to execute the hook

The hooks are located at /usr/share/libpkman/hooks. To read more about the hooks, see the /usr/include/libpkman/pkcommon.h header file.

An example hooks is available in the sync-hook in the core repository.

Install scripts

Packages may have install script that pkman can run after the package has been installed, and before the package is removed. The install script must start with a shebang, otherwise the pkman refuses to execute it, and returns with a failure. The shebang is processed as usual (it will be cut at the first space).

Before the install script is executed, the current working directory will be changed to the root directory specified in the pkman. See the -r or --root command-line option, the PKMAN_ROOT environment variable, or the rootdir variable in the config file. The pkman -v will print the actual root path to be used.

The extra parameters the install scripts get:

• reason: the reason of the script invokation (either install or remove)
• pkgver: the package version to be installed/removed

NOTE: Currently, the exit code of the install script is ignored.

Troubleshooting

failed to commit transaction: One or more file conflicts found

The pkman will issue an error message if it detects file conflicts, and by design it will not overwrite files:

pkman: failed to commit transaction: One or more file conflicts found
package: /path/to/file exists in filesystem

To safely resolve this, first check which package owns the conflicted file:
$ pkman -Qo /path/to/file

1. If no package owns the file, rename it, perform the original command, and may remove after successful operation.
2. If a package owns the file, file a bug report.

failed to initialize pkman context: Local database error

The pkman may issue an error message if the local database is corrupted:

pkman: dirname: entry is not a valid package descriptor
pkman: failed to initialize pkman context: Local database error

Tips to fix it:

1. Remove any empty directory in /var/lib/pkman/local.
2. A database entry (which is a directory) contains two important files:
   • desc: the package descriptor extended with local attributes
   • files: the file catalogue with path, size, mode and the SHA2-256 hash of the file content (if it is a regular file)
   Make sure that all database entry have these files. (Note: these files may exist, but their content still can be corrupted.) If not, move the corrupted directory outside the local directory, reinstall that package, and remove the residue (that was manually moved outside from the local).

package integrity check failed

The pkman will issue an error message if the integrity of a package cannot be verified:

pkman: package integrity check failed on PKGNAME-VERSION

Where PKGNAME is an actual package name, and VERSION is its version.

Tips to fix it:

1. If the package was downloaded from a sync database, then run the pkman again, and let the pkman download the package file again. If the problem is persist, check your internet connection, then if the problem is still persists, file a bug report.
2. If the package is not downloaded from a sync database, then try to obtain the package file again from you obtained originally. Check whether the file is an XZ-compressed CPIO file.

pkman: failed to commit transaction: Not enough space to commit the transaction

This means, the system does not have enough free space to install the selected packages. Try to free up some space (by removing old package files, see above), or install less packages, or remove unnecessary packages in general.

You can get more detailed information about the necessary space by specifying --print-chkspace or --detail-chkspace command-line options.

If the error message that preceeds is similar to this:

pkman: disk space check failed:  requires 1 blocks of 0 by installing 0 blocks

Then, it is probably an internal error. See the tail of the log file (placed in /var/log/pkman.log by default). If you cannot resolve the issue by seeing the produced error messages, consult the maintainers.

Author: Aron Barath, 2017-2018