[packagekit] packagekit: Branch 'master'
Richard Hughes
hughsient at kemper.freedesktop.org
Sat Sep 8 06:33:50 PDT 2007
Makefile.am | 1
backends/README | 470 --------------------
configure.ac | 1
docs/.gitignore | 2
docs/Makefile.am | 33 +
docs/backends.xml | 166 +++++++
docs/introduction.xml | 1129 ++++++++++++++++++++++++++++++++++++++++++++++++++
docs/reference.xml | 36 +
8 files changed, 1367 insertions(+), 471 deletions(-)
New commits:
diff-tree ed33f3adc7e164a5e8f4ae90627d8f5c1b250d04 (from 86121cfc725c5055402fc819325eca8e014f629d)
Author: Richard Hughes <richard at hughsie.com>
Date: Sat Sep 8 14:33:16 2007 +0100
covert the crazy text files into xml docbook
diff --git a/Makefile.am b/Makefile.am
index 3ac4952..d22300e 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,4 +1,5 @@
SUBDIRS = \
+ docs \
policy \
etc \
man \
diff --git a/backends/README b/backends/README
deleted file mode 100644
index 80ecf8f..0000000
--- a/backends/README
+++ /dev/null
@@ -1,470 +0,0 @@
-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.
-
diff --git a/configure.ac b/configure.ac
index 68c0b0b..ba571e7 100644
--- a/configure.ac
+++ b/configure.ac
@@ -341,6 +341,7 @@ packagekit.pc
Makefile
etc/Makefile
man/Makefile
+docs/Makefile
backends/Makefile
backends/apt/Makefile
backends/box/Makefile
diff --git a/docs/.gitignore b/docs/.gitignore
index 05f8d34..891430b 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,4 +1,4 @@
Makefile.in
Makefile
-index.html
+*.html
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..cc6e59b
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1,33 @@
+IMAGE_FILES = \
+ pk-structure.png \
+ pk-structure.svg
+
+SPEC_XML_FILES = \
+ reference.xml \
+ introduction.xml \
+ backends.xml
+
+SPEC_HTML_FILES = \
+ reference.html
+
+clean-local:
+ rm -f *~
+ rm -f *.html
+
+EXTRA_DIST = \
+ config.xsl \
+ docbook.css \
+ $(SPEC_XML_FILES) \
+ $(IMAGE_FILES)
+
+if DOCBOOK_DOCS_ENABLED
+
+htmldocdir = $(docdir)
+htmldoc_DATA = reference.html
+
+reference.html : introduction.xml
+ $(XMLTO) html-nochunks -m config.xsl reference.xml
+
+EXTRA_DIST += $(SPEC_HTML_FILES)
+
+endif #DOCBOOK_DOCS_ENABLED
diff --git a/docs/backends.xml b/docs/backends.xml
new file mode 100644
index 0000000..78fa968
--- /dev/null
+++ b/docs/backends.xml
@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+
+<chapter id="backends">
+ <title>Backends</title>
+
+ <sect1 id="backends-spawn-introduction">
+ <title>Spawn Introduction</title>
+ <para>
+ Backends are typically open-programmable, which means we can define a
+ standard for what goes on stdin, stdout and stderr to try and maximise
+ the common code between the backends.
+ The following section will explain the convention used on
+ <literal>backends/conary</literal> and <literal>backends/yum</literal>.
+ </para>
+ <para>
+ If you are unable to write scripts that conform to these specifications
+ then just launch a PkSpawn object in the compiled helper with stdout and
+ stderr callbacks and then try to do screenscraping in the backend.
+ This screenscraping is least popular for obvious reasons.
+ </para>
+ <para>
+ 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.
+ </para>
+ </sect1>
+
+ <sect1 id="backends-spawn-methods">
+ <title>Methods</title>
+ <para>
+ The following methods are mapped from the helper to comand line programs
+ in the compile helper.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>File</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Search Name</entry>
+ <entry><literal>search-name.*</literal></entry>
+ </row>
+ <row>
+ <entry>Search Group</entry>
+ <entry><literal>search-group.*</literal></entry>
+ </row>
+ <row>
+ <entry>Search Details</entry>
+ <entry><literal>search-details.*</literal></entry>
+ </row>
+ <row>
+ <entry>Search File</entry>
+ <entry><literal>search-file.*</literal></entry>
+ </row>
+ <row>
+ <entry>Install Package</entry>
+ <entry><literal>install.*</literal></entry>
+ </row>
+ <row>
+ <entry>Remove Package</entry>
+ <entry><literal>remove.*</literal></entry>
+ </row>
+ <row>
+ <entry>Get Depends</entry>
+ <entry><literal>get-depends.*</literal></entry>
+ </row>
+ <row>
+ <entry>Get Requires</entry>
+ <entry><literal>get-requires.*</literal></entry>
+ </row>
+ <row>
+ <entry>Get Description</entry>
+ <entry><literal>get-description.*</literal></entry>
+ </row>
+ <row>
+ <entry>Update Package</entry>
+ <entry><literal>update.*</literal></entry>
+ </row>
+ <row>
+ <entry>Update System</entry>
+ <entry><literal>update-system.*</literal></entry>
+ </row>
+ <row>
+ <entry>Get Updates</entry>
+ <entry><literal>get-updates.*</literal></entry>
+ </row>
+ <row>
+ <entry>Refresh Cache</entry>
+ <entry><literal>refresh-cache.*</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ </sect1>
+
+ <sect1 id="backends-spawn-common">
+ <title>Common function outputs</title>
+ <para>
+ The following commands echoed to standard error will
+ automatically make the backend-launcher do the correct action in the
+ compiled helper.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Data</entry>
+ <entry>File</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Percentage</entry>
+ <entry><literal>percentage[tab]value</literal></entry>
+ <entry><literal>stderr</literal></entry>
+ </row>
+ <row>
+ <entry>Subpercentage</entry>
+ <entry><literal>subpercentage[tab]value</literal></entry>
+ <entry><literal>stderr</literal></entry>
+ </row>
+ <row>
+ <entry>NoPercentageUpdates</entry>
+ <entry><literal>no-percentage-updates</literal></entry>
+ <entry><literal>stderr</literal></entry>
+ </row>
+ <row>
+ <entry>Error</entry>
+ <entry><literal>error[tab]enum[tab]description</literal></entry>
+ <entry><literal>stderr</literal></entry>
+ </row>
+ <row>
+ <entry>Status</entry>
+ <entry><literal>status[tab]state</literal></entry>
+ <entry><literal>stderr</literal></entry>
+ </row>
+ <row>
+ <entry>RequireRestart</entry>
+ <entry><literal>requirerestart[tab]type[tab]details</literal></entry>
+ <entry><literal>stderr</literal></entry>
+ </row>
+ <row>
+ <entry>Package</entry>
+ <entry><literal>package[tab]status[tab]package_id[tab]summary</literal></entry>
+ <entry><literal>stdout</literal></entry>
+ </row>
+ <row>
+ <entry>Description</entry>
+ <entry><literal>description[tab]package_id[tab]group[tab]detail[tab]url</literal></entry>
+ <entry><literal>stdout</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect1>
+
+
+</chapter>
diff --git a/docs/introduction.xml b/docs/introduction.xml
new file mode 100644
index 0000000..70144de
--- /dev/null
+++ b/docs/introduction.xml
@@ -0,0 +1,1129 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+
+<chapter id="introduction">
+ <title>PackageKit Introduction</title>
+
+ <sect1 id="introduction-description">
+ <title>Overall Description</title>
+
+ <para>
+ PackageKit is a small open source systems abstracts out common package
+ management tasks such as:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Checking for updates and installing in the background.
+ </para>
+ <para>
+ Automatically installing new or add-on software.
+ </para>
+ <para>
+ Monitoring the state of the system.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ PackageKit is a modular design with an asyncronous API for client programs,
+ a flexible queing module, and run-time selectable backends.
+ </para>
+
+ <mediaobject id="pk-structure">
+ <imageobject>
+ <imagedata format="PNG" fileref="pk-structure.png" align="center"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ PackageKit is GPL licensed.
+ </para>
+
+ <para>
+ PackageKit comprises:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <literal>packagekitd</literal> system daemon which runs using
+ system activation as the root user and queues and performs the package
+ actions. It quits after a small period of inactivity.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>pkcon</literal> text client access program.
+ This allows you to interact with PackageKit on the command line
+ either in an async or sync mode. e.g.
+ <literal>pkcon async check updates</literal> or
+ <literal>pkcon sync search description power</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>pkmon</literal> text client monitor program.
+ This allows you to monitor what PackageKit is doing on the command
+ line.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ What PackageKit is not:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A huge daemon with lots of dependencies.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ API or ABI stable. Expect the ABI and API to change on a regular
+ basis until we ship 1.0.0.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Targeted to a particular architecture or platform.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Produced by any one vendor.
+ There are many contributors helping to get this done.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="introduction-backends">
+ <title>Backends</title>
+ <para>
+ The following sections explain what a backend is, and how it is implimented.
+ </para>
+ <sect2 id="introduction-backends-overview">
+ <title>Overview</title>
+ <para>
+ A backend is just a compiled <literal>.so</literal> object that is
+ loaded at runtime and provides an interface to the underlying package
+ commands.
+ A backend converts an async request into either a new thread which
+ in the same process, or using external "glue" files that can be written
+ in any language.
+ </para>
+ <para>
+ Please see the <literal>helpers/BACKENDS</literal> file for the current
+ status of the existing backends.
+ Backend maintainers, please keep this file updated.
+ </para>
+ </sect2>
+
+ <sect2 id="introduction-backends-compiled-backends">
+ <title>Compiled backeds</title>
+ <para>
+ If you have got 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 set methods of
+ PackageKit.
+ A C example can be found in <literal>backends/box</literal> and a
+ C++ example in <literal>backends/apt</literal>.
+ </para>
+ <para>
+ You will have to use threading if your backend does not support async
+ operation as requests have to return immediatly.
+ 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.
+ </para>
+ </sect2>
+
+ <sect2 id="introduction-backends-helpers">
+ <title>Backends with helpers</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ Even when using helpers, a compiled backed is still used for two reasons:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ It is still needed for the dlopen internally in PackageKit.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+ <sect1 id="introduction-ideas">
+ <title>Important Ideas</title>
+ <para>
+ The following sections explain key concepts used internally in PackageKit.
+ </para>
+ <sect2 id="introduction-ideas-packageid">
+ <title>Package ID</title>
+ <para>
+ One important idea is the <literal>package_id</literal>.
+ This is the <literal>name;version;arch;data</literal> 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.
+ </para>
+ <para>
+ The <literal>package_id</literal> is parsed and checked carefully in
+ the helper code.
+ The package arch and data is optional, but 3 <literal>;</literal>'s must
+ be present.
+ For instance, <literal>gnome-keyring-manager;2.18.0;;</literal> is
+ valid but <literal>gnome-keyring-manager;2.18.0</literal> 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.
+ </para>
+ <para>
+ The backend must ensure that it 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.
+ </para>
+ </sect2>
+
+ <sect2 id="introduction-ideas-filters">
+ <title>Filters</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ Filter options are:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>installed</literal> or <literal>~installed</literal></entry>
+ <entry>If the package is installed on the system</entry>
+ </row>
+ <row>
+ <entry><literal>devel</literal> or <literal>~devel</literal></entry>
+ <entry>Development packages typically end -devel, -dgb and -static.</entry>
+ </row>
+ <row>
+ <entry><literal>gui</literal> or <literal>~gui</literal></entry>
+ <entry>GUI programs typically depend on gtk, libkde or libxfce.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ So valid options would be:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>none</literal></entry>
+ <entry>All packages installed or available with no filtering</entry>
+ </row>
+ <row>
+ <entry><literal>devel;~installed</literal></entry>
+ <entry>All non-installed development packages</entry>
+ </row>
+ <row>
+ <entry><literal>installed;~devel</literal></entry>
+ <entry>All installed non-development packages</entry>
+ </row>
+ <row>
+ <entry><literal>gui;~installed;~devel</literal></entry>
+ <entry>All non-installed, non-devel gui programs.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ </sect2>
+
+ <sect2 id="introduction-errors">
+ <title>Error Enums</title>
+ <para>
+ If you have to handle an error, try to use <literal>internal-error</literal>
+ 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.
+ </para>
+ <para>
+ Every error should have an enumerated type
+ (e.g. <literal>out-of-memory</literal>) and also an error dscription.
+ 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,
+ but "Could not create database index" is.
+ For the description use <literal>;</literal> to seporate the lines if
+ required.
+ </para>
+ <para>
+ The following error enumerated types are available for use in all
+ backends:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Error</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>out-of-memory</literal></entry>
+ <entry>There is an out of memory condition</entry>
+ </row>
+ <row>
+ <entry><literal>no-network</literal></entry>
+ <entry>There is no network connection</entry>
+ </row>
+ <row>
+ <entry><literal>not-supported</literal></entry>
+ <entry>
+ 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.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>internal-error</literal></entry>
+ <entry>
+ 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.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>gpg-failure</literal></entry>
+ <entry>There was a GPG failure in the transaction</entry>
+ </row>
+ <row>
+ <entry><literal>package-id-invalid</literal></entry>
+ <entry>The package ID is not valid for this transaction</entry>
+ </row>
+ <row>
+ <entry><literal>package-not-installed</literal></entry>
+ <entry>
+ The package that is trying to be removed or updated is not
+ installed
+ </entry>
+ </row>
+ <row>
+ <entry><literal>package-already-installed</literal></entry>
+ <entry>
+ The package that is trying to be installed or updated is already
+ installed
+ </entry>
+ </row>
+ <row>
+ <entry><literal>package-download-failed</literal></entry>
+ <entry>A package failed to download correctly</entry>
+ </row>
+ <row>
+ <entry><literal>dep-resolution-failed</literal></entry>
+ <entry>Dependancy resolution failed</entry>
+ </row>
+ <row>
+ <entry><literal>filter-invalid</literal></entry>
+ <entry>
+ 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.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>create-thread-failed</literal></entry>
+ <entry>Failed to create a thread</entry>
+ </row>
+ <row>
+ <entry><literal>transaction-error</literal></entry>
+ <entry>There was a generic transaction error</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="introduction-group-type">
+ <title>Group type</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ The following group enumerated types are available:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Group</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>accessibility</literal></entry>
+ <entry>Accessibility</entry>
+ </row>
+ <row>
+ <entry><literal>accessories</literal></entry>
+ <entry>Accessories</entry>
+ </row>
+ <row>
+ <entry><literal>education</literal></entry>
+ <entry>Education</entry>
+ </row>
+ <row>
+ <entry><literal>games</literal></entry>
+ <entry>Games</entry>
+ </row>
+ <row>
+ <entry><literal>graphics</literal></entry>
+ <entry>Graphics</entry>
+ </row>
+ <row>
+ <entry><literal>internet</literal></entry>
+ <entry>Internet</entry>
+ </row>
+ <row>
+ <entry><literal>office</literal></entry>
+ <entry>Office</entry>
+ </row>
+ <row>
+ <entry><literal>other</literal></entry>
+ <entry>Other</entry>
+ </row>
+ <row>
+ <entry><literal>programming</literal></entry>
+ <entry>Programming</entry>
+ </row>
+ <row>
+ <entry><literal>multimedia</literal></entry>
+ <entry>Multimedia</entry>
+ </row>
+ <row>
+ <entry><literal>system</literal></entry>
+ <entry>System</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="introduction-cancellation">
+ <title>Cancellation</title>
+ <para>
+ 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 <literal>AllowInterrupt(true)</literal> to enable cancellation
+ and <literal>AllowInterrupt(false)</literal> to disable it.
+ This can be done for any job type.
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="api-method-reference">
+ <title>API Method Reference</title>
+ <para>
+ Methods used by the backends are as follows:
+ </para>
+ <sect2 id="api-search-name">
+ <title>Search Name</title>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>search_term</literal></entry>
+ <entry>A single word search term with no wildcard chars.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ Do not refresh the package cache. This should be fast.
+ </para>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-search-group">
+ <title>Search Group</title>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>group_type</literal></entry>
+ <entry>An enumerated group_type, or <literal>unknown</literal>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ Do not refresh the package cache. This should be fast.
+ </para>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-search-details">
+ <title>Search Details</title>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>search_term</literal></entry>
+ <entry>A single word search term with no wildcard chars.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ Do not refresh the package cache. This should be fast.
+ 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.
+ </para>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-search-file">
+ <title>Search File</title>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>search_term</literal></entry>
+ <entry>A single word search term with no wildcard chars.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ This should search for files.
+ This should allow an application to find out what package owns
+ a file on the system.
+ </para>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-install">
+ <title>Install Package</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>package_id</literal></entry>
+ <entry>A single, valid, package ID.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ This should search for files.
+ This should allow an application to find out what package owns
+ a file on the system.
+ </para>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>Subpercentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Status</literal> and
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-remove">
+ <title>Remove Package</title>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>allow_deps</literal></entry>
+ <entry>
+ 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.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>package_id</literal></entry>
+ <entry>A single, valid, package ID.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>Subpercentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Status</literal> and
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-get-depends">
+ <title>Get Depends</title>
+ <para>
+ GetDepends should return packages that this package depends on.
+ </para>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>package_id</literal></entry>
+ <entry>A single, valid, package ID.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>Subpercentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Status</literal> and
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-get-requires">
+ <title>Get Requires</title>
+ <para>
+ GetRequires should return packages that depend on this package.
+ This is useful to know, as if <literal>package_id</literal> is being
+ removed, we can warn the user what else would be removed.
+ </para>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>package_id</literal></entry>
+ <entry>A single, valid, package ID.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>Subpercentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Status</literal> and
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-get-description">
+ <title>Get Description</title>
+ <para>
+ GetDescription should return the description of that
+ <literal>package_id</literal>.
+ </para>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>package_id</literal></entry>
+ <entry>A single, valid, package ID.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>Subpercentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Status</literal> and
+ <literal>Error</literal> and
+ <literal>Description</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-update">
+ <title>Update Package</title>
+ <para>
+ The installer should always update extra packages automatically.
+ </para>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>package_id</literal></entry>
+ <entry>A single, valid, package ID.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ This should search for files.
+ This should allow an application to find out what package owns
+ a file on the system.
+ </para>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>Subpercentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Status</literal> and
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-update-system">
+ <title>Update System</title>
+ <para>
+ There are no arguments.
+ </para>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>Subpercentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Error</literal> and
+ <literal>RequireRestart</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-get-updates">
+ <title>Get Updates</title>
+ <para>
+ There are no arguments.
+ </para>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-refresh-cache">
+ <title>Refresh Cache</title>
+ <para>
+ There are no arguments.
+ </para>
+ <para>
+ This should search for files.
+ This should allow an application to find out what package owns
+ a file on the system.
+ </para>
+ <para>
+ This method typically emits
+ <literal>Percentage</literal>,
+ <literal>Subpercentage</literal>,
+ <literal>NoPercentageUpdates</literal>,
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="api-signal-reference">
+ <title>API Signal Reference</title>
+ <para>
+ Signals used by the backends are as follows:
+ </para>
+ <sect2 id="api-percentage">
+ <title>Percentage</title>
+ <para>
+ This is optional.
+ Backends should send the DBUS signal NoPercentageUpdates or use
+ no-percentage-updates if the remaining position cannot be calculated.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>value</literal></entry>
+ <entry>The percentage complete of the entire transaction</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="api-subpercentage">
+ <title>Subpercentage</title>
+ <para>
+ This is optional.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>value</literal></entry>
+ <entry>Percentage complete of the sub-transaction.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="api-no-percentage-updates">
+ <title>NoPercentageUpdates</title>
+ <para>
+ This is optional and signifies that the helper is no longer able to
+ send percentage updates.
+ </para>
+ </sect2>
+
+ <sect2 id="api-error">
+ <title>Error</title>
+ <para>
+ Errors should only be send on fatal abortion.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>enum</literal></entry>
+ <entry>Enumerated type, e.g. <literal>no-network</literal>.</entry>
+ </row>
+ <row>
+ <entry><literal>description</literal></entry>
+ <entry>Long description or error, e.g. "<literal>failed to connect to mytry.xml</literal>"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="api-status">
+ <title>Status</title>
+ <para>
+ This is optional, but highly recommended.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>status</literal></entry>
+ <entry>
+ One of "<literal>download</literal>",
+ "<literal>install</literal>",
+ "<literal>update</literal>",
+ "<literal>remove</literal>".
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="api-requirerestart">
+ <title>RequireRestart</title>
+ <para>
+ This is optional, but highly recommended.
+ </para>
+ <para>
+ This can be sent as many times as needed by the backend script.
+ PackageKit will always choose the 'worst' method in the UI notification.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>type</literal></entry>
+ <entry>
+ One of "<literal>system</literal>",
+ "<literal>application</literal>",
+ "<literal>session</literal>".
+ </entry>
+ </row>
+ <row>
+ <entry><literal>detail</literal></entry>
+ <entry>Optional details about the restart</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="backends-spawn-package">
+ <title>Package</title>
+ <para>
+ If updating, as packages are updated then emit them to the screen.
+ This allows a summary to be presented after the transaction.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>status</literal></entry>
+ <entry>
+ <para>
+ When searching: "1" if installed, "0" if not
+ </para>
+ <para>
+ When getting updates: "0" for normal priority updates,
+ "1" for security updates, "2" for important updates,
+ "3" for low priority updates.
+ </para>
+ <para>
+ When processing packages: "0" if downloading,
+ "1" if updating or installing.
+ </para>
+ <para>
+ Else, set as "1"
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><literal>package_id</literal></entry>
+ <entry>A valid package ID string with as much data as known</entry>
+ </row>
+ <row>
+ <entry><literal>summary</literal></entry>
+ <entry>The one line package summary, e.g. "Clipart for OpenOffice"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="backends-spawn-description">
+ <title>Description</title>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>package_id</literal></entry>
+ <entry>The package ID</entry>
+ </row>
+ <row>
+ <entry><literal>group</literal></entry>
+ <entry>The enumerated package group description</entry>
+ </row>
+ <row>
+ <entry><literal>detail</literal></entry>
+ <entry>
+ The multi line package description.
+ NOTE: Tabs may have to be stripped from the description to
+ avoid being split.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>url</literal></entry>
+ <entry>The upstream project homepage</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+ </sect1>
+
+</chapter>
diff --git a/docs/reference.xml b/docs/reference.xml
new file mode 100644
index 0000000..b6a38cd
--- /dev/null
+++ b/docs/reference.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<book id="index">
+ <bookinfo>
+ <title>PackageKit Documentation</title>
+ <releaseinfo>Version 1.00</releaseinfo>
+ <abstract>
+ <title>Executive Summary</title>
+ <para>
+ 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.
+ </para>
+ </abstract>
+ <date>September 8th, 2007</date>
+ <authorgroup>
+ <author>
+ <firstname>Richard</firstname>
+ <surname>Hughes</surname>
+ <affiliation>
+ <address>
+ <email>richard at hughsie.com</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+ </bookinfo>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="introduction.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="backends.xml" />
+
+</book>
+
More information about the PackageKit
mailing list