External Backends
Introduction:
Right, so you've not got a C or C++ binding for your package system.
You are in the right place.
PackageKit executes scripts written in pretty much any language
(perl,java,python) and watches on the standard out and standard error.
This means we need a standard for what goes on stdin, stdout and stderr to
try and maximise the common code between the backends.
Please see the helpers/BACKENDS file for the current status of the existing
backends. Backend maintainers, please keep this file updated.
Package Id:
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
one is removed.
In the backend the package_id must be parsed and checked carefully to make sure
it only matches on package.
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.
Other options:
If you are unable to write scripts that conform to these specifications then
just launch a PkSpawn object with stdout and stderr callbacks and then try to
do screenscraping in the backend. This option is least popular.
The following are guidelines. Feel free to break the rules if you have to,
you have a compiled backend to use if you need it.
Filters:
Search filtering on the name is done in the backend for efficiency reasons.
Feel free to add this into the compiled backend if this is not possible in the
scripted backend.
Filter options are:
"installed" or "~installed" if the package is installed on the system
"devel" or "~devel" devel packages typically end -devel, -dgb and -static.
"gui" or "~gui" gui programs typically depend on gtk, libkde or libxfce.
So valid options would be:
"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
Error enums:
If you have to handle an error, try to use "internal-error" as little as
possible. Just ask, and I'll add some more error enums to cover the type of
error in an abstract way as possible.
For the non-translated error description use ";" to seporate the lines.
Cancellation:
If you have a multipart transaction that can be aborted in one phase but not
another then the AllowInterrupt 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 compiled backend.
Use "allow-interrupt<tab>true" to enable cancellation and
"allow-interrupt<tab>false" to disable it. This can be done for any job type.
========= Search Name =========
FILENAME search-name.*
ARGUMENTS $options $search_term
$filter The filter applied to the search operation,
e.g. "gui;~installed;~devel" or "none"
search_term: Single word search term with no wildcard chars.
STDERR percentage<tab>$value
value: Percentage complete of the entire transaction
notes: This is optional. Backends should send the DBUS
signal NoPercentageUpdates or use no-percentage-updates
if the remaining position cannot be calculated.
STDERR no-percentage-updates
notes: This is optional and signifies that the helper
is no longer able to send percentage updates.
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network", "filter-invalid"
"not-supported" or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT package<tab>$status<tab>$package_id<tab>$summary
$status: "1" if installed, "0" if not
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$summary: The one line package summary, e.g. "Clipart for OpenOffice"
NOTES Do not refresh the package cache. This should be fast.
========= Search Group =========
FILENAME search-group.*
ARGUMENTS $filter $group
$filter The filter applied to the search operation,
e.g. "gui;~installed;~devel" or "none"
$group: The enumerated package group description
This should be one of:
"accessibility", "accessories", "education", "games",
"graphics", "internet", "office", "other", "programming",
"multimedia", "system"
STDERR percentage<tab>$value
value: Percentage complete of the entire transaction
notes: This is optional. Backends should send the DBUS
signal NoPercentageUpdates or use no-percentage-updates
if the remaining position cannot be calculated.
STDERR no-percentage-updates
notes: This is optional and signifies that the helper
is no longer able to send percentage updates.
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network", "filter-invalid"
"not-supported" or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT package<tab>$status<tab>$package_id<tab>$summary
$status: "1" if installed, "0" if not
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$summary: The one line package summary, e.g. "Clipart for OpenOffice"
NOTES Do not refresh the package cache. This should be fast.
========= Search Details =========
FILENAME search-details.*
ARGUMENTS $options $search
$filter The filter applied to the search operation,
e.g. "gui;~installed;~devel" or "none"
$search: Single word search term with no wildcard chars.
STDERR percentage<tab>$value
value: Percentage complete of the entire transaction
notes: This is optional. Backends should send the DBUS
signal NoPercentageUpdates or use no-percentage-updates
if the remaining position cannot be calculated.
STDERR no-percentage-updates
notes: This is optional and signifies that the helper
is no longer able to send percentage updates.
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network", "filter-invalid"
"not-supported" or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT package<tab>$status<tab>$package_id<tab>$summary
$status: "1" if installed, "0" if not
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$summary: The one line package summary, e.g. "Clipart for OpenOffice"
NOTES This is very similar to find-package.
This should search as much data as possible, including, if possible
repo names, package summaries, descriptions and urls.
========= Search File =========
FILENAME search-file.*
ARGUMENTS $options $search
$filter The filter applied to the search operation,
e.g. "gui;~installed;~devel" or "none"
$search: Single word filename with no wildcard chars.
STDERR percentage<tab>$value
value: Percentage complete of the entire transaction
notes: This is optional. Backends should send the DBUS
signal NoPercentageUpdates or use no-percentage-updates
if the remaining position cannot be calculated.
STDERR no-percentage-updates
notes: This is optional and signifies that the helper
is no longer able to send percentage updates.
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network", "filter-invalid"
"not-supported" or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT package<tab>$status<tab>$package_id<tab>$summary
$status: "1" if installed, "0" if not
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$summary: The one line package summary, e.g. "Clipart for OpenOffice"
NOTES This should allow an application to find out what package owns
a file on the system.
========= Refresh Cache =========
FILENAME refresh-cache.*
ARGUMENTS <none>
STDERR percentage<tab>$value
value: Percentage complete of the entire transaction
notes: This is optional. Backends should send the signal
NoPercentageUpdates if these are not expected.
STDERR subpercentage<tab>$value
$value: Percentage complete of the sub-transaction.
notes: This is optional.
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network",
"not-supported" or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT <none>
========= Install Packages =========
FILENAME install.*
ARGUMENTS $package_id
package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
STDERR percentage<tab>$value
value: Percentage complete of the entire transaction
notes: This is optional. Backends should send the signal
NoPercentageUpdates if these are not expected.
STDERR subpercentage<tab>$value
$value: Percentage complete of the sub-transaction
notes: This is optional.
STDERR status<tab>$state
$state: One of "download", "install", "update", "remove"
notes: This is optional.
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network", "package-id-invalid",
"not-supported", "package-already-installed"
or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT package<tab>$status<tab>$package_id<tab>$summary
$status: "0" if downloading, "1" if installing or updating
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$summary: The one line package summary, e.g. "Clipart for OpenOffice"
NOTE: As packages are downloaded or installed then emit them to the screen.
This allows a summary to be presented after and during the transaction.
NOTES The installer should always install extra packages automatically
as the use could call GetDepends prior to the intstall if a
confirmation is required in the UI.
========= Update Packages =========
FILENAME update.*
ARGUMENTS $package_id
package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
STDERR percentage<tab>$value
value: Percentage complete of the entire transaction
notes: This is optional. Backends should send the signal
NoPercentageUpdates if these are not expected.
STDERR subpercentage<tab>$value
$value: Percentage complete of the sub-transaction
notes: This is optional.
STDERR status<tab>$state
$state: One of "download", "install", "update", "remove"
notes: This is optional.
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network", "package-id-invalid",
"not-supported", "package-not-installed"
or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT package<tab>$status<tab>$package_id<tab>$summary
$status: "0" if downloading, "1" if updating
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$summary: The one line package summary, e.g. "Clipart for OpenOffice"
NOTE: As packages are downloaded or updated then emit them to the screen.
This allows a summary to be presented after and during the transaction.
NOTES The installer should always update extra packages automatically
if required.
========= Remove Packages =========
FILENAME remove.*
ARGUMENTS $allowdeps $package_id
allowdeps: Either "yes" or "no". If yes allow other packages
to be removed with the package, but "no" should
cause the script to abort if other packages are
dependant on the package.
package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
STDERR percentage<tab>$value
value: Percentage complete of the entire transaction
notes: This is optional. Backends should send the signal
NoPercentageUpdates if these are not expected.
STDERR subpercentage<tab>$value
$value: Percentage complete of the sub-transaction
notes: This is optional.
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network",
"not-supported", "package-not-installed", "package-id-invalid"
or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT package<tab>$status<tab>$package_id<tab>$summary
$status: Always "1"
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$summary: The one line package summary, e.g. "Clipart for OpenOffice"
NOTE: as packages are installed then emit them to the screen.
This allows a summary to be presented after the transaction.
========= Get Depends =========
FILENAME get-depends.*
ARGUMENTS $package_id
package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
STDERR percentage<tab>$value
value: Percentage complete of the entire transaction
notes: This is optional. Backends should send the signal
NoPercentageUpdates if these are not expected.
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network", "package-id-invalid",
"not-supported" or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT package<tab>$status<tab>$package_id<tab>$summary
$status: Always "1"
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$summary: The one line package summary.
NOTE GetDepends should return packages that this package depends on.
========= Get Requires =========
FILENAME get-requires.*
ARGUMENTS $package_id
package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
STDERR percentage<tab>$value
value: Percentage complete of the entire transaction
notes: This is optional. Backends should send the signal
NoPercentageUpdates if these are not expected.
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network", "package-id-invalid",
"not-supported" or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT package<tab>$status<tab>$package_id<tab>$summary
$status: Always "1"
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$summary: The one line package summary.
NOTE 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.
========= Update System =========
FILENAME update-system.*
ARGUMENTS <none>
STDERR percentage<tab>$value
value: Percentage complete of the entire transaction
notes: This is optional. Backends should send the signal
NoPercentageUpdates if these are not expected.
STDERR subpercentage<tab>$value
$value: Percentage complete of the sub-transaction
notes: This is optional.
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network",
"not-supported" or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDERR requirerestart<tab>$type<tab>$details
type: Enumerated type, e.g. "system", "application", "session"
details: Optional details about the restart
notes: This can be sent as many times as needed by the
backend script. PackageKit will always choose
the 'worst' method in the UI notification.
STDOUT package<tab>$status<tab>$package_id<tab>$summary
$status: "0" if downloading, "1" if updating or installing
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$summary: The one line package summary. (optional)
NOTE: As packages are updated then emit them to the screen.
This allows a summary to be presented after the transaction.
========= Get Description =========
FILENAME get-description.*
ARGUMENTS $package_id
package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network", "package-id-invalid",
"not-supported" or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT description<tab>$package_id<tab>$group<tab>$detail<tab>$url
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$group: The enumerated package group description
This should be one of:
"accessibility", "accessories", "education", "games",
"graphics", "internet", "office", "other", "programming",
"multimedia", "system"
$detail: The multi line package description
NOTE: Tabs may have to be stripped from the
description to avoid being split for the url.
$url: The upstream project homepage
========= Get Updates =========
FILENAME get-updates.*
ARGUMENTS <none>
STDERR error<tab>$enum<tab>description
enum: Enumerated type, e.g. "no-network",
"not-supported" or "internal-error"
description: Long description or error
notes: Errors should only be send on fatal abortion.
STDOUT package<tab>$status<tab>$package_id<tab>$summary
$status: "0" for normal priority updates
"1" for security updates
"2" for important updates
"3" for low priority updates
$package_id: The package ID name, e.g. openoffice;2.6.22;ppc64;fedora
$summary: The one line package summary.
