471 lines
17 KiB
Plaintext
471 lines
17 KiB
Plaintext
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.
|
|
|