PackageKit Documentation

PackageKit is a small open source system that abstracts out common package management tasks such as:

PackageKit has a modular design with an asynchronous API for client programs, a flexible queuing module, and run-time selectable backends.

A backend is just a compiled .so object that is loaded at run-time and provides an interface to the underlying package commands. A backend converts an asynchronous request into either a new thread in the same process, executes external "glue" files that can be written in any language, or uses DBUS to signal a daemon process to handle the request.

Backends do not have to support all of the commands supported by PackageKit. Each backend advertises the commands and options it supports, and the frontend will only show UI elements for those commands. Please see the html/pk-faq.html file for the current status of the existing backends. Backed maintainers, please keep this file updated.

The config file /etc/PackageKit/PackageKit.conf allows to the administrator to change system daemon options. In normal use this file does not have to be changed, but it may be useful to people debugging the daemon or developing backends.

The options are:

One important idea is the package_id. This is the name;version;arch;data in a single string and is meant to represent a single package. This is important when multiple versions of a package are installed and only the correct one is removed.

The package_id is parsed and checked carefully in the helper code. The package arch and data is optional, but 3 ;'s must be present. For instance, gnome-keyring-manager;2.18.0;; is valid but gnome-keyring-manager;2.18.0 is not. The data field can be used for the repository name or any other purpose. It is designed to make the life of a backend writer a little bit easier.

The data field for an installed package must be installed as this is used to identify which packages are installable or installed in the client tools.

The data field for an non-installed local package must be local as this signifies a repository name is not available and that package resides locally on the client system.

For example:

The backend must ensure that the package_id only matches on one single package. A single package_id must be enough to uniquely identify a single object in any repository used on the system.

Search filtering on the name is done in the backend for efficiency reasons. This can be added into the compiled backend if this is not possible in any new backend design.

Filter options are:

So valid options would be:

If you have to handle an error, try to use internal-error as little as possible. Just ask on the mailing list, and we can add some more error enums to cover the type of error in an abstract way as possible.

Every error should have an enumerated type (e.g. out-of-memory) and also an error description. The error description is not translated and not converted into the users locale. The error description should be descriptive, as it's for power users and people trying to debug the problem. For instance, "Out of memory" is not helpful as an error description that is reported in a bugzilla, but "Could not create database index" is. For the description use ; to separate the lines if required.

The following error enumerated types are available for use in all backends:

Groups are enumerated for localisation. Backends should try to put packages in different groups if possible, else just don't advertise SearchGroup and the options should not be shown in the UI.

The following group enumerated types are available, but please check libpackagekit/pk-enum.h for the latest list.

If you have a multipart transaction that can be aborted in one phase but not another then the AllowCancel signal can be sent. This allows for example the yum download to be cancelled, but not the install transaction. By cancelling a job all subtransactions are killed.

By default actions cannot be cancelled unless enabled in the backend. Use AllowCancel(true) to enable cancellation and AllowCancel(false) to disable it. This can be done for any job type.

For compiled backends that are threaded, the cancel() method can be used to terminate the thread.

For spawned backends, there are two staggered signals send to allow locks to be released or for the backend to clean up after itself:

PackageKit does not ask the user questions when the transaction is running. It also supports a fire-and-forget method invocation, which means that transactions will have one calling method, and have many signals going back to the caller.

Each transaction is a new path on the org.freedesktop.PackageKit service, and to create a path you have to call GetTid on the base interface which creates the new DBUS path, and returns the new path for you to connect to. In the libpackagekit binding, PkControl handles the base interface, whilst PkClient handles all the transaction interface stuff. The org.freedesktop.PackageKit.Transaction interface can be used on the newly created path, but only used once. New methods require a new transaction path (i.e. another call to GetTid) which is synchronous and thus very fast.

A typical successful transaction can be seen below.

A typical simple transaction failure case can be seen below. The user is not given the change to requeue the transaction as it is a fatal error.

In this non-trivial example, a local file install is being attempted. First the InstallFile is called with the trusted flag set. This will fail if the package does not have a valid GPG key, and ordinarily the transaction would fail. What the client can do, e.g. using gnome-packagekit, is to re-request the InstallFile with non-trusted. This will use a different PolicyKit authentication, and allow the file to succeed.

So why do we bother calling trusted in the first place? Well, the trusted PolicyKit role can be saved in the gnome-keyring, or could be set to the users password as the GPG key is already trusted by the user. The non-trusted action would likely ask for the administrator password, and not allowed to be saved. This gives the user the benifit of installing trusted local files without a password (common case) but requiring something stronger for untrusted or unsigned files.

If the package is signed, and a valid GPG signature is available, then we need to ask the user to import the key, and re-run the transaction. This is done as three transactions, as other transactions may be queued and have a higher priority, and to make sure that the transaction object is not reused.

If the package is signed, and a valid GPG signature is available, then we need to ask the user to import the key, and re-run the transaction. This is done as three transactions, as other transactions may be queued and have a higher priority, and to make sure that the transaction object is not reused.

A transaction_id is a unique identifier that identifies the present or past transaction. A transaction is made up of one or more sub-transactions. A transaction has one role for the entire lifetime, but the transaction can different values of status as the transaction is processed.

For example, if the user "Installed OpenOffice" and the backend has to:

This is one single transaction with the role install, with 4 different sub-transactions. This allows the user to rollback transactions with selected backends, rather than select sub-transactions which may need complex conflict resolution.

The transaction_id must be of the format /job_identifier_data where the daemon controls all parameters. job is a monotonically updating number and is retained over reboots. identifier is random data used by the daemon to ensure jobs started in parallel cannot race, and also to make a malicious client program harder to write. data can be used for ref-counting in the backend or for any other purpose. It is designed to make the life of a backend writer a little bit easier. An example transaction_id would be /45_dafeca_checkpoint32

A transaction will have different status values as it it queued, prepared and executed. The ::StatusChanged signal from PkClient allow you to design user interfaces that tell the user what is happening with the transaction.

A typical transaction will have the following states:

If the transaction is waiting for other jobs to finish (in the active queue) then the status will be stuck at PK_STATUS_ENUM_WAIT and the UI should show a message to this effect.

If the transaction is waiting for a package lock (when a legacy tool like pirut is loaded and has the yum lock) then the transaction will be stuck at PK_STATUS_ENUM_SETUP.

As a backend writer, you do not have to set PK_STATUS_ENUM_RUNNING manually, as this will be set for you if you set any other value such as PK_STATUS_ENUM_DOWNLOADING or PK_STATUS_ENUM_INFO. However, you will need to avoid setting any status values until a package lock is available and the transaction has started.

The arguments are:

This method typically emits Progress, Error and Package.

Package enumerated types should be available or installed.

The arguments are:

Do not refresh the package cache. This should be fast.

Try to emit installed before available packages first, as it allows the client program to perform the GUI filtering and matching whilst the daemon is running the transaction.

If the backend includes installed and available versions of the same package when searching then the available version will have to be filtered in the backend.

The search query in the backend should not be case sensitive, and should not be sensitive to _ or -.

The search methods should return all results in all repositories. This may mean that multiple versions of package are returned. If this is not what is wanted by the client program, then the newest filter should be used.

This method typically emits Progress, Error and Package.

Package enumerated types should be available or installed.

The arguments are:

Do not refresh the package cache. This should be fast.

This method typically emits Progress, Error and Package.

Package enumerated types should be available or installed.

The arguments are:

Do not refresh the package cache. This should be fast. This is very similar to search-name. This should search as much data as possible, including, if possible repo names, package summaries, descriptions and URLs.

This method typically emits Progress, Error and Package.

Package enumerated types should be available or installed.

The arguments are:

This should search for files. This should allow an application to find out what package owns a file on the system.

This method typically emits Progress, Error and Package.

Package enumerated types should be available or installed.

The installer should always install extra packages automatically as the use could call GetDepends prior to the install if a confirmation is required in the UI.

The arguments are:

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be downloading, updating, installing or removing.

The installer should always install extra packages automatically as the use could call GetDepends prior to the install if a confirmation is required in the UI.

The arguments are:

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be downloading, updating, installing or removing.

Sometimes we need to install new security keys to allow an install to continue.

The arguments are:

This method typically emits Error and

The arguments are:

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be downloading, updating, installing or removing.

GetDepends should return packages that this package depends on.

The arguments are:

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be available or installed.

WhatProvides should return packages that provide the supplied attributes. This method is useful for finding out what package(s) provide a modalias or GStreamer codec string.

The arguments are:

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be available or installed.

Resolve turns a single package name into a package_id suitable for the other methods.

The arguments are:

This method typically emits Error and Package.

Package enumerated types should be available or installed.

GetUpdateDetail should return details about the update.

The arguments are:

This method typically emits UpdateDetail and Error

GetRequires should return packages that depend on this package. This is useful to know, as if package_id is being removed, we can warn the user what else would be removed.

The arguments are:

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be available or installed.

GetDetails should return all the details about a specific package_id.

The arguments are:

This method typically emits Progress, Status and Error and Details.

GetFiles should return the file list of that package_id.

The arguments are:

This method typically emits Progress, Status and Error and Files.

The installer should always update extra packages automatically.

The arguments are:

This should search for files. This should allow an application to find out what package owns a file on the system.

This method typically emits Progress, Status and Error and Package.

The installer should update all the updateable packages on the system, including automatically installing any new packages that are needed for dependancies.

There are no arguments.

This method typically emits Progress, Error and RequireRestart and Package.

Package enumerated types should be downloading, updating, installing or removing.

This function should return a list of packages that are installed and are upgradable. It should only return the newest update for each installed package.

The arguments are:

This method typically emits Progress, Error and Package.

Package enumerated types should be blocked, low, normal, important or security.

The status blocked signifies the package cannot be updated, probably due to other dependencies not being met. This type allows the GUI tools to show to the user that an update exists, but cannot be installed. The reason for it not being installed should be put into the update description when doing GetUpdateDetail.

A filter such as basename or gui is also useful if you want to do filtering on the method to only show the main packages rather than the complete list. The complete list is available but specifying none as the filter. Using no filter which may be useful in advanced tools or when using libpackagekit and searching for an update of a specific name. Other filter types may be present, but can be safely ignored of the backend does not support them.

There are no arguments.

This should fetch updated meta-data for all enabled repositories. This operation should be only scheduled when the computer is idle as the network connection will be very active, and will the computer will have have non-trivial levels of hard disk and processor activity. For these reasons, it should not be done automatically when on battery power.

This method typically emits Progress, Error and Package.

Return the list of repositories used in the system.

The arguments are:

This method should emit RepoDetail.

This enables the repository specified.

The arguments are:

This sets a parameter for the repository specified.

The arguments are:

This is optional. Backends should send the percentage fields to 101 if the amount complete cannot be calculated.

Errors should only be send on fatal abortion.

This is optional, but highly recommended. It gives the GUI tools a chance to show a different icon to show what stage the transaction is in, for instance, a downloading icon can be shown whilst in the download state.

This is optional, but highly recommended.

This can be sent as many times as needed by the backend script. PackageKit will always choose the 'worst' method in the UI notification.

This allows the backend to queue up a message to be shown after the transaction has completed.

If updating, as packages are updated then emit them to the screen. This allows a summary to be presented after the transaction.

When returning results from a search always return installed before available for the same package name.

The info enumerated type

Some backends support repositories which use a cryptographic signature, such as GPG. If a package cannot be installed because it is signed with a key that has not been verified, this signal is generated so the user can choose to accept or decline the key.

This signal includes information that can be used to verify that the key should be trusted, such as a URL for the company or person who owns the key, the key's ID, the userid of the key creator, and the date the key was generated.

Some backends support EULAs, which have to be agreed to before the install can proceed.

The following methods are mapped from the helper to comand line programs in the spawn helper.

The following commands echoed to standard error will automatically make the backend-launcher do the correct action in the compiled helper.

If your backend does not set status signals you will get the following dialog:

For every transaction, you need to tell the datemon what the backend is doing. You need to add to your backend:

You can send as many status calls as you need as the transaction progresses. The more calls you send, the more the UI will reflect what is being done, for instance, showing a downloading icon when PK_STATUS_ENUM_DOWNLOAD is used.

If your backend does not send Finished() after ErrorCode() then the following dialog will be shown.

The daemon recovers automatically, so this warning is not fatal, but the automatic recovery is not cost free. Every time the daemon cleans up a transaction like this, an additional 500ms is added to the transaction duration (to allow slow backends to clean up after themselves) and so the next transaction is delayed from starting.

You need to ensure that Finished() follows ErrorCode() to remove this warning.