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.
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.
========= Find Packages =========
FILENAME {backend}-search-name.*
ARGUMENTS $options $search_term
options: One of "installed", "available", "all".
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",
"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-clipart;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 {backend}-search-details.*
ARGUMENTS $options $search_term
options: One of "installed", "available", "all".
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",
"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-clipart;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.
========= Refresh Cache =========
FILENAME {backend}-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 {backend}-install.*
ARGUMENTS $package
package: Single word package with no wildcard chars.
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 data<tab>$current_data
$current_data: The current worked on package
notes: This is optional, but allows the UI to show what
package is being installed on for that sub-transaction.
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: Always "1"
$package_id: The package ID name, e.g. openoffice-clipart;2.6.22;ppc64;fedora
A package_id always has to have three sections.
$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.
NOTES The installer should always install extra packages automatically
as the use could call GetDeps prior to the intstall if a
confirmation is required in the UI.
========= Remove Packages =========
FILENAME {backend}-remove.*
ARGUMENTS $allowdeps $package
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: Single word package with no wildcard chars.
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 data<tab>$current_data
$current_data: The current worked on package
notes: This is optional, but allows the UI to show what
package is being installed on for that sub-transaction.
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: Always "1"
$package_id: The package ID name, e.g. openoffice-clipart;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 Dependancies =========
FILENAME {backend}-get-deps.*
ARGUMENTS $package
package: Single word package with no wildcard chars.
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",
"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-clipart;2.6.22;ppc64;fedora
$summary: The one line package summary.
========= Update System =========
FILENAME {backend}-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: Always "1"
$package_id: The package ID name, e.g. openoffice-clipart;2.6.22;ppc64;fedora
$summary: The one line package summary.
NOTE: As packages are updated then emit them to the screen.
This allows a summary to be presented after the transaction.
========= Get Description =========
FILENAME {backend}-get-description.*
ARGUMENTS $package
package: Single word package with no wildcard chars.
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 description<tab>$package_id<tab>$group<tab>$detail<tab>$url
$package_id: The package ID name, e.g. openoffice-clipart;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",
"sound-video", "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 {backend}-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-clipart;2.6.22;ppc64;fedora
$summary: The one line package summary.
