External Backends

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.

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.*

STDIN:		$options $search_term
		options:	One of "installed", "available", "all".
		search_term:	Single word search term with no wildcard chars.

STDERR		percentage:$value
		value:		Percentage complete of the entire transaction
		notes:		This is optional. Backends should send the signal
				NoPercentageUpdates if these are not expected.

STDOUT		$status<tab>$package_name<tab>$summary
		$status:	"yes" if installed, "no" if not
		$package_name:	The package name, e.g. openoffice-clipart
		$summary:	The one line package summary, e.g. "Clipart for OpenOffice"

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

========= Refresh Cache =========

FILENAME:	{backend}-refresh-cache.*

STDIN:		<none>

STDERR		percentage:$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:$value
		$value:		Percentage complete of the sub-transaction.
		notes:		This is optional.

STDOUT		<none>

========= Install Packages ========= 

FILENAME:	{backend}-install.*

STDIN:		$package
		package:	Single word package with no wildcard chars.

STDERR		percentage:$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:$value
		$value:		Percentage complete of the sub-transaction
		notes:		This is optional.

STDERR		status:$state
		$state:		One of "download", "install", "update", "remove"
		notes:		This is optional.

STDERR		data:$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.

STDOUT		$status<tab>$package_name<tab>$summary
		$status:	Always "yes"
		$package_name:	The package name, e.g. openoffice-clipart
		$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.

========= Remove Packages ========= 

FILENAME:	{backend}-install.*

STDIN:		$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:$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:$value
		$value:		Percentage complete of the sub-transaction
		notes:		This is optional.

STDERR		data:$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.

STDOUT		$status<tab>$package_name<tab>$summary
		$status:	Always "yes"
		$package_name:	The package name, e.g. openoffice-clipart
		$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.*

STDIN:		$package
		package:	Single word package with no wildcard chars.

STDERR		percentage:$value
		value:		Percentage complete of the entire transaction
		notes:		This is optional. Backends should send the signal
				NoPercentageUpdates if these are not expected.

STDOUT		$status<tab>$package_name<tab>$summary
		$status:	Always "yes"
		$package_name:	The package name, e.g. openoffice-clipart
		$summary:	The one line package summary.

========= Update System ========= 

FILENAME:	{backend}-update-system.*

STDIN:		<none>

STDERR		percentage:$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:$value
		$value:		Percentage complete of the sub-transaction
		notes:		This is optional.

STDOUT		$status<tab>$package_name<tab>$summary
		$status:	Always "yes"
		$package_name:	The package name, e.g. openoffice-clipart
		$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.*

STDIN:		$package
		package:	Single word package with no wildcard chars.

STDOUT		$package_name<tab>$version<tab>$detail<tab>$url
		$package_name:	The package name, e.g. openoffice-clipart
		$version:	The full distro package version
		$detail:	The multi line package description.
		$url:		The upstream project homepage