Version 1.00
Executive Summary
PackageKit is a D-Bus abstraction layer that allows the session user to manage packages in a secure way using a cross-distro, cross-architecture API. PackageKit is built using a lightweight backend architecture. PackageKit is product and vendor neutral and is currently being developed by a small team of developers.
Table of Contents
Table of Contents
PackageKit is a small open source system that abstracts out common package management tasks such as:
Checking for updates and installing them in the background.
Automatically installing new or add-on software.
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:
This logs all transactions to /var/log/PackageKit
so old
daemon debugging output can be observed.
This is the time that the daemon waits when idle before shutting down. A smaller number will result in slower response times when running many transactions in a small amount of time. A longer timeout will lock the underlying packaging backend for longer, although the daemon will start and stop less often.
Table of Contents
The following sections explain key concepts used internally in PackageKit.
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:
csup;20060318-5;x86_64;local
: for locally available package file.
csup;20060318-5;x86_64;fedora-devel
: for package that is not installed
and can be downladed from the Fedora development repostory.
csup;20060318-5;x86_64;installed
: for locally installed package
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:
Option | Description |
---|---|
installed or ~installed | If the package is installed on the system |
devel or ~devel | Development packages typically end -devel, -dgb and -static. |
gui or ~gui | GUI programs typically depend on gtk, libkde or libxfce. |
free or ~free | Free software. The package contains only software and other content that is available under a free license. See http://fedoraproject.org/wiki/Licensing for a list of licenses that are considered free. If a license cannot be determined from the package metadata, or the status of the license is not known, the package will be marked as 'non-free'. |
visible or ~visible | Repositories may want to specify if a package should be visible in an application chooser. |
supported or ~supported | If the package is supported or is a third party addon. |
basename or ~basename |
The basename filter will only return results according to the
package basename.
This is useful if you are searching for pm-utils and you only
want to show the main pm-utils package, not any of the
-devel or -debuginfo or
-common suffixes in the UI.
The basename is normally the original name of the source package.
|
newest or ~newest |
The newest filter will only return the newest package available.
This is useful if you are searching for gimp
and only gimp-2.4.5-1.fc9.i386 would be returned,
not gimp-2.4.5-1.fc9.i386 ,
gimp-2.4.4-1.fc9.i386 and
gimp-2.4.3-1.fc9.i386 .
|
arch or ~arch | The arch filter will only return the packages that match the exact architecture of the system, for instance only showing x86_64 packages on a AMD Turion 64. This would mean that x86_64 packages could be filtered from non-native 32-bit packages. This allows the used to choose non-native packages if a multi-lib policy is allowed. |
source or ~source | The source filter will only return source packages. These are typically useful when rebuilding other packages. |
So valid options would be:
Option | Description |
---|---|
none | All packages installed or available with no filtering |
devel;~installed | All non-installed development packages |
installed;~devel | All installed non-development packages |
gui;~installed;~devel | All non-installed, non-devel gui programs |
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:
Error | Description |
---|---|
out-of-memory | There is an out of memory condition |
no-network | There is no network connection that can be used |
not-supported | Not supported by the backend. NOTE: You shouldn't be setting non-NULL in the compiled backend symbol table if you find yourself using this. |
internal-error | There was an unspecified internal error. NOTE: Please try and be more specific. If you are using this then we should probably add a new type. |
no-cache | The operation is trying to read from the cache, but the cache is not present or invalid |
gpg-failure | There was a GPG failure in the transaction |
package-id-invalid | The package ID is not valid for this transaction |
package-not-installed | The package that is trying to be removed or updated is not installed |
package-not-found | The package that is trying to be removed or updated is not installed |
package-already-installed | The package that is trying to be installed or updated is already installed |
package-download-failed | A package failed to download correctly |
invalid-package-file | The file that is supposed to contain a package to install is corrupt, or is not a valid package file |
package-install-blocked | The backend's configuration or policy prevents the install or updating of a package |
dep-resolution-failed | Dependency resolution failed |
filter-invalid | The filter was invalid. NOTE: syntax checking is done in the backend loader, so you should only use this if the filter is not supported by the backend. |
group-not-found | The specified software group was not found. |
create-thread-failed | Failed to create a thread |
transaction-error | There was a generic transaction error, but please give more details in the description |
transaction-cancelled | The transaction was cancelled as the result of a call to Cancel() |
repo-not-found | The repository name could not be found |
repo-configuration-error | One of the enabled repositories has invalid configuration |
repo-not-available | There was a (possibly transient) problem connecting to a repository |
cannot-remove-system-package | Could not remove a protected system package that is needed for stable operation of the system |
process-quit | The process was asked to quit, probably because it was cancelled |
process-kill | The process was forcibly killed, probably because ignored the quit request. This is probably due to it being cancelled |
failed-config-parsing | Configuration files could not be read or parsed. |
cannot-cancel | The Cancel() method was called, but it is too late to cancel the current transaction. |
cannot-get-lock | The backend could not acquire a lock on the underlying package management system. |
no-packages-to-update | UpdateSystem() was called, but there are no packages to update. |
cannot-write-repo-config | RepoEnable() or RepoSetData() was called, but the repository configuration file could not be written to. |
local-install-failed | A local file could not be installed. The file might not be readable, or it might not contain a valid package. |
bad-gpg-signature | The package is signed with a GPG signature, but that signature is not valid in some way. |
package-corrupt | The downloaded package is corrupt. |
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.
Group | Description |
---|---|
accessibility | Accessibility |
accessories | Accessories |
education | Education |
games | Games |
graphics | Graphics |
internet | Internet |
office | Office |
other | Other |
programming | Programming |
multimedia | Multimedia |
system | System |
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:
Send the process SIGQUIT
.
Wait 500ms
If the process has not already quit, send the process
SIGKILL
to terminate it.
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:
update libxml2 as a dependency
install java as dependency
install openoffice-bin
install openoffice-clipart
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:
Queued in the active queue (PK_STATUS_ENUM_WAIT
)
Transaction started, and is being prepared (PK_STATUS_ENUM_SETUP
)
The transaction is running (PK_STATUS_ENUM_RUNNING
)
(optional) Data is downloading (PK_STATUS_ENUM_DOWNLOADING
)
(optional) Data is installing (PK_STATUS_ENUM_INSTALLING
)
The transaction is finished (PK_STATUS_ENUM_FINISHED
)
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.
Table of Contents
Methods used by the backends are as follows:
The arguments are:
Option | Description |
---|---|
filter |
A correct filter, e.g. none or
installed;~devel
|
This method typically emits
Progress
,
Error
and
Package
.
Package
enumerated types should be
available
or installed
.
The arguments are:
Option | Description |
---|---|
filter |
A correct filter, e.g. none or
installed;~devel
|
search_term | A single word search term with no wildcard chars. |
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:
Option | Description |
---|---|
filter |
A correct filter, e.g. none or
installed;~devel
|
group_type | An enumerated group_type, or unknown |
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:
Option | Description |
---|---|
filter |
A correct filter, e.g. none or
installed;~devel
|
search_term | A single word search term with no wildcard chars. |
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:
Option | Description |
---|---|
filter |
A correct filter, e.g. none or
installed;~devel
|
search_term | A single word search term with no wildcard chars. |
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:
Option | Description |
---|---|
package_ids | An array of package IDs. |
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:
Option | Description |
---|---|
full_paths | An array of full path and filenames to packages. |
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:
Option | Description |
---|---|
sig_type | A key type, e.g. gpg |
key_id | A key ID, e.g. BB7576AC |
package_id | A PackageID for the package that the user is trying to install |
This method typically emits
Error
and
The arguments are:
Option | Description |
---|---|
package_ids | An array of package IDs. |
allow_deps |
Either true or false .
If true allow other packages to be removed with the package,
but false should cause the script to abort if other packages
are dependant on the package.
|
auto_remove |
Either true or false .
This option is only really interesting on embedded devices with a limited amount of
flash storage.
It suggests to the packagekit backend that dependencies installed at the same time as
the package should also be removed if they are not required by anything else.
For instance, if you install OpenOffice, it might download libneon as a dependency.
When auto_remove is set to true, and you remove OpenOffice then
libneon will also get removed automatically.
|
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:
Option | Description |
---|---|
filter |
A correct filter, e.g. none or
installed;
|
package_id | A single, valid, package ID. |
recursive |
Either true or false . If yes then the requirements should be
returned for all packages returned.
This means if gnome-power-manager depends on NetworkManager
and NetworkManager depends on HAL, then GetDepends on
gnome-power-manager should return both HAL and NetworkManager.
|
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:
Option | Description |
---|---|
filter |
A correct filter, e.g. none or
installed;
|
type |
A PkProvideType, e.g. PK_PROVIDES_ENUM_CODEC .
|
data | The data to send to the backend to get the packages. Note: This is backend specific. |
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:
Option | Description |
---|---|
filter |
A correct filter, e.g. none or
installed;~devel
|
package | A single package name, e.g. art-clipart . |
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:
Option | Description |
---|---|
package_id | A single, valid, package ID. |
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:
Option | Description |
---|---|
filter |
A correct filter, e.g. none or
installed;
|
package_id | A single, valid, package ID. |
recursive |
Either true or false . If yes then the requirements should be
returned for all packages returned.
This means if gnome-power-manager depends on NetworkManager
and NetworkManager depends on HAL, then GetRequires on
HAL should return both gnome-power-manager and NetworkManager.
|
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:
Option | Description |
---|---|
package_id | A single, valid, package ID. |
This method typically emits
Progress
,
Status
and
Error
and
Details
.
GetFiles should return the file list of that
package_id
.
The arguments are:
Option | Description |
---|---|
package_id | A single, valid, package ID. |
This method typically emits
Progress
,
Status
and
Error
and
Files
.
The installer should always update extra packages automatically.
The arguments are:
Option | Description |
---|---|
package_ids | An array of package IDs. |
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:
Option | Description |
---|---|
filter |
A correct filter, e.g. none or
basename
|
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:
Option | Description |
---|---|
filter |
A correct filter, e.g. none or
~devel
|
This method should emit
RepoDetail
.
This enables the repository specified.
The arguments are:
Option | Description |
---|---|
repo_id |
A repository identifier, e.g.
fedora-development-debuginfo
|
enabled |
true if enabled,
false if disabled.
|
Table of Contents
Signals used by the backends are as follows:
This is optional. Backends should send the percentage fields to 101 if the amount complete cannot be calculated.
Option | Description |
---|---|
percentage | The percentage complete of the entire transaction |
subpercentage | The subpercentage complete of the sub-transaction |
elapsed | The amount of time in seconds this transaction has been in the running state |
remaining | The amount of time in seconds this transaction will take to complete. Zero is sent for unknown. |
Errors should only be send on fatal abortion.
Option | Description |
---|---|
enum | Enumerated type, e.g. no-network . |
description |
Long description or error, e.g.
failed to connect to mytry.xml
|
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.
Option | Description |
---|---|
status |
One of "download ",
"install ",
"update ",
"remove ".
|
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.
Option | Description |
---|---|
type |
One of "system ",
"application ",
"session ".
|
detail | Optional details about the restart |
This allows the backend to queue up a message to be shown after the transaction has completed.
Option | Description |
---|---|
type |
One of "warning ",
"notice ",
"daemon ".
|
detail | Required details about the message, non localised |
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.
Option | Description |
---|---|
info | A valid info string enumerated type |
package_id | A valid package ID string with as much data as known |
summary | The one line package summary, e.g. "Clipart for OpenOffice" |
The info
enumerated type
Situation | Value | Description |
---|---|---|
Searching | installed | If installed |
available | If available to install | |
Getting Updates | low | If update is of low severity |
normal | If update is of normal severity | |
important | If update is very important | |
security | If the update is security sensitive | |
Installing/Updating/Removing | downloading | If we are downloading this package |
updating | If we are updating this package | |
installing | If we are installing this package | |
removing | If we are removing this package | |
Otherwise | unknown | If we cannot use any other option |
Option | Description |
---|---|
package_id | The package ID |
license | The license, e.g. "GPLv2+" or "proprietary". If you need to add a EULA then do it like this: "proprietary;By installing this software\nyou may kill a kitten." |
group | The enumerated package group description |
detail | The multi-line package description. NOTE: Tabs may have to be stripped from the description to avoid being split. |
url | The upstream project homepage |
size | The size of the package in bytes. This should be the size of the entire package file, not the size of the files installed on the system. |
Option | Description |
---|---|
package_id | The package ID |
updates |
A list of package_id's that are to be updated, seporated by ^ .
This odd delimited was chosen as \t is already being used in the
spawned backends, and ^ is a banned character in a package_id.
This will change in 0.3.x where updates will be a proper string
array field.
|
obsoletes |
A list of package_id's that are to be obsoleted, seporated by ^
This will change in 0.3.x where obsoletes will be a proper string
array field.
|
vendor_url |
A URL with more details on the update, e.g. a page with more
information on the update.
The format of this command should be
http://www.foo.org/page.html?4567;Update to SELinux
|
bugzilla_url | A bugzilla URL with more details on the update. If no URL is available then this field should be left empty. |
cve_url | A CVE URL with more details on the security advisory |
restart_enum | A valid restart type, e.g. "system" |
update_text | The update text describing the update in a non-localised way. Newlines should be converted to ";" before printed. |
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.
Option | Description |
---|---|
package_id | A package ID for the package that is trying to be installed |
repository_name | The name of the repository associated with the provided key |
key_url | The URL provided with the key. |
key_userid | The user id associated with the key |
key_id | A unique identifier for the key |
key_fingerprint | The hashed fingerprint of the key |
key_timestamp | The date the key was created |
type | The type of signature used. 'GPG', for example. |
Some backends support EULAs, which have to be agreed to before the install can proceed.
Option | Description |
---|---|
eula_id |
The eula_id which identifies the EULA - this is provided
so that if a specific EULA has previously agreed to a EULA from Acme Corp it is
not asked again.
An example eula_id 's is vmware5_single_user .
|
package_id | A package ID for the package that is trying to be installed |
vendor_name | The vendor that is providing the EULA. |
license_agreement | The full text EULA. |
If you have a C or C++ binding for your package system then
you can use a compiled backend, which is more efficient than
using helpers as described below.
You can include the headers in the backend (with extra
libraries) and then just write the simple code to interface
with the methods of PackageKit.
A C example can be found in backends/box
and a
C++ example in backends/apt
.
You will have to use threading if your backend does not support async operation as requests have to return immediately. This is very important. Do any significant processing in a thread, and certainly don't return package results without creating a thread. By keeping the backends async we can make sure that there is no blocking which means the command line and UI do not freeze.
Table of Contents
If you do not have a C or C++ language binding, PackageKit executes helper scripts written in pretty much any language. It then watches the standard out and standard error and parses the output into compiled backend commands. This means a python library can be interfaced easily with a C backend.
Even when using helpers, a compiled backend stub is still used for two reasons:
It is still needed for the dlopen internally in PackageKit.
You can add cleverness in the C backend that you might not want to do in the scripted backend, for example using a hashtable in C rather than checking all the names in awk.
Backends are typically open-programmable, which means we can define a
standard for what goes on stdin and stdout to try and maximise
the common code between the backends.
The following section will explain the convention used on
backends/conary
and backends/yum
.
If you are unable to write scripts that conform to these specifications then just launch a PkSpawn object in the compiled helper with stdout callbacks and then try to do screenscraping in the backend. This screenscraping is least popular for obvious reasons.
Backends scripts are run with arguments and data is sent to standard out and standard error asyncronously so that PackageKit can proxy this to DBUS. A method has command line arguments seporated with tabs, and data is also seporated with tabs.
It is important to flush the standard output after each output, else
Linux will helpfully buffer the output into more efficient size chunks.
If you do not flush, then there will be a long IPC delay.
Flushing can be achived in C using fflush
or in python
using sys.stdout.flush()
.
The following methods are mapped from the helper to comand line programs in the spawn helper.
Method | File |
---|---|
Search Name | search-name.* |
Search Group | search-group.* |
Search Details | search-details.* |
Search File | search-file.* |
Install Package | install.* |
Install File | install-file.* |
Remove Package | remove.* |
Get Depends | get-depends.* |
Resolve | resolve.* |
Get Requires | get-requires.* |
Get Update Detail | get-update-detail.* |
Get Details | get-details.* |
Get Files | get-files.* |
Update Package | update.* |
Update System | update-system.* |
Get Updates | get-updates.* |
Refresh Cache | refresh-cache.* |
Get Repo List | get-repo-list.* |
Repo Enable | repo-enable.* |
Repo Set Data | repo-set-data.* |
The following commands echoed to standard error will automatically make the backend-launcher do the correct action in the compiled helper.
Method | Data |
---|---|
Percentage | percentage[tab]value |
Subpercentage | subpercentage[tab]value |
NoPercentageUpdates | no-percentage-updates |
Error | error[tab]enum[tab]description |
Status | status[tab]state |
RequireRestart | requirerestart[tab]type[tab]details |
AllowUpdate | allow-cancel[tab]enabled |
Package | package_id[tab]status[tab]summary |
Details | details[tab]package_id[tab]group[tab]detail[tab]url[tab]size_in_bytes |
Files | files[tab]package_id[tab]file_list |
UpdateDetail | package_id[tab]updates[tab]obsoletes[tab]vendor_url[tab]bugzilla_url[tab]cve_url[tab]restart[tab]update_text |
ChangeTransactionData | change-transaction-data[tab]data |
RepoSignatureRequired | repository_name[tab]key_url[tab]key_userid[tab]key_id[tab]key_fingerprint[tab]key_timestamp[tab]type |
RepoDetail | repo-detail[tab]repo_id[tab]description[tab]enabled |
Backend helpers communicating over standard out and standard error are easy to write, but can have some performance problems. For instance, if your packages system has to do a lot of work when it starts up and shuts down, performance in the UI may suffer. In these cases, you can use a persistant backend daemon that communicates to the C backend over DBUS.
Your daemon will be started by DBUS, and should be responsible
for it's own thread management.
It should receive an Init()
method call when the C
backend starts, and an Exit()
method call before it
exits.
You should also consider adding a timeout value to your daemon so that
it will exit after a set time with no activity from the C backend.
That way the daemon will still exit even if the C backend crashes for
some reason.
Again, like the helper backends described above, a compiled
backend stub is needed. An example of a DBUS backend written
in python can be found in backends/yum2
,
along with a compiled stub written in C.
The following sections explain frequently asked questions from people creating thier own backend. This list is not exhaustive, but please ask before adding to it.
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:
For python: self.status(STATUS_QUERY)
For compiled C/C++: pk_backend_set_status (backend, PK_STATUS_ENUM_QUERY);
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.