[packagekit] packagekit: Branch 'master' - 7 commits
Richard Hughes
hughsient at kemper.freedesktop.org
Wed Oct 17 10:14:27 PDT 2007
Makefile.am | 1
TODO | 5
backends/yum/helpers/yumBackend.py | 14
configure.ac | 2
docs/Makefile.am | 14
docs/backends.xml | 210 ---
docs/introduction.xml | 1672 -----------------------------
docs/pk-backends.xml | 210 +++
docs/pk-introduction.xml | 1672 +++++++++++++++++++++++++++++
docs/pk-reference.xml | 36
docs/reference.xml | 36
html/Makefile.am | 21
html/img/Makefile.am | 20
html/img/dialog-information.png |binary
html/img/large-accessories-text-editor.png |binary
html/img/large-dialog-information.png |binary
html/img/large-emblem-photos.png |binary
html/img/large-help-browser.png |binary
html/img/large-preferences-system.png |binary
html/img/large-system-users.png |binary
html/img/packagekit.png |binary
html/index.html | 48
html/pk-download.html | 70 +
html/pk-help.html | 67 +
html/pk-intro.html | 113 +
html/pk-screenshots.html | 25
html/pk-using.html | 66 +
html/style.css | 65 +
python/packagekit/backend.py | 22
29 files changed, 2464 insertions(+), 1925 deletions(-)
New commits:
commit 6ce74d0f42e0bf6688346fd14f8e1420824c7188
Author: Richard Hughes <richard at hughsie.com>
Date: Wed Oct 17 18:12:27 2007 +0100
include the images in the tarball
diff --git a/html/img/Makefile.am b/html/img/Makefile.am
index b54531e..148ee6b 100644
--- a/html/img/Makefile.am
+++ b/html/img/Makefile.am
@@ -1,8 +1,14 @@
NULL =
IMAGE_FILES = \
- large-accessories-text-editor.png \
dialog-information.png \
+ large-accessories-text-editor.png \
+ large-dialog-information.png \
+ large-emblem-photos.png \
+ large-help-browser.png \
+ large-preferences-system.png \
+ large-system-users.png \
+ packagekit.png \
$(NULL)
EXTRA_DIST = \
commit fe3cf9c5cb493b0e5bfde8e6fc264ffe6e5cca09
Merge: f132323... ccc397f...
Author: Richard Hughes <richard at hughsie.com>
Date: Wed Oct 17 18:07:59 2007 +0100
Merge branch 'master' of git+ssh://hughsie@git.packagekit.org/srv/git/PackageKit
commit f1323233b0731db5162ed0dfd09d94091681010d
Author: Richard Hughes <richard at hughsie.com>
Date: Wed Oct 17 18:06:35 2007 +0100
add the large icons for the website
diff --git a/TODO b/TODO
index bb731c8..71a2a0d 100644
--- a/TODO
+++ b/TODO
@@ -28,3 +28,8 @@ To do rollbacks sanely in PK we need a few things:
*** Use resolve for pkcon operations ***
'pkcon install zsh' should work as well as 'pkcon install "zsh;1.0;i386;repo"'
+*** HTML Help files ***
+Spellcheck and grammar check!
+Add not about the development server and anon-cvs
+Populate screenshots section
+
diff --git a/html/img/large-accessories-text-editor.png b/html/img/large-accessories-text-editor.png
new file mode 100644
index 0000000..78d55f9
Binary files /dev/null and b/html/img/large-accessories-text-editor.png differ
diff --git a/html/img/large-dialog-information.png b/html/img/large-dialog-information.png
new file mode 100644
index 0000000..0a5e281
Binary files /dev/null and b/html/img/large-dialog-information.png differ
diff --git a/html/img/large-emblem-photos.png b/html/img/large-emblem-photos.png
new file mode 100644
index 0000000..222a2b9
Binary files /dev/null and b/html/img/large-emblem-photos.png differ
diff --git a/html/img/large-help-browser.png b/html/img/large-help-browser.png
new file mode 100644
index 0000000..11cbe55
Binary files /dev/null and b/html/img/large-help-browser.png differ
diff --git a/html/img/large-preferences-system.png b/html/img/large-preferences-system.png
new file mode 100644
index 0000000..9d66730
Binary files /dev/null and b/html/img/large-preferences-system.png differ
diff --git a/html/img/large-system-users.png b/html/img/large-system-users.png
new file mode 100644
index 0000000..a44367c
Binary files /dev/null and b/html/img/large-system-users.png differ
diff --git a/html/img/packagekit.png b/html/img/packagekit.png
new file mode 100644
index 0000000..c22a27d
Binary files /dev/null and b/html/img/packagekit.png differ
diff --git a/html/index.html b/html/index.html
index cd33aee..e36320c 100644
--- a/html/index.html
+++ b/html/index.html
@@ -8,7 +8,7 @@
<table align="center" class="title">
<tr>
<td><img src="img/packagekit.png"/></td>
- <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td width="95%" valign="middle"><p class="title">PackageKit Main Page</p></td>
<td><img src="img/packagekit.png"/></td>
</tr>
</table>
@@ -19,9 +19,9 @@
<table align="center" cellpadding="3px" border="0">
<tr>
- <td align="middle"><a href="pk-intro.html"><img src="img/large-accessories-text-editor.png" width="192"/></a></td>
- <td align="middle"><a href="pk-using.html"><img src="img/large-preferences-system.png" width="192"/></a></td>
- <td align="middle"><a href="pk-download.html"><img src="img/large-dialog-information.png" width="192"/></a></td>
+ <td align="middle"><a href="pk-intro.html"><img src="img/large-accessories-text-editor.png" width="128"/></a></td>
+ <td align="middle"><a href="pk-using.html"><img src="img/large-preferences-system.png" width="128"/></a></td>
+ <td align="middle"><a href="pk-download.html"><img src="img/large-dialog-information.png" width="128"/></a></td>
</tr>
<tr>
<td><a href="pk-intro.html"><p class="indextitle">What is<br>PackageKit?</p></a></td>
@@ -29,9 +29,9 @@
<td><a href="pk-download.html"><p class="indextitle">Where can I<br>download it?</p></a></td>
</tr>
<tr>
- <td align="middle"><a href="pk-help.html"><img src="img/large-help-browser.png" width="192"/></a></td>
- <td align="middle"><a href="pk-screenshots.html"><img src="img/large-bookmark-new.png" width="192"/></a></td>
- <td align="middle"><a href="wiki/FAQ"><img src="img/large-dialog-information.png" width="192"/></a></td>
+ <td align="middle"><a href="pk-help.html"><img src="img/large-system-users.png" width="128"/></a></td>
+ <td align="middle"><a href="pk-screenshots.html"><img src="img/large-emblem-photos.png" width="128"/></a></td>
+ <td align="middle"><a href="wiki/FAQ"><img src="img/large-help-browser.png" width="128"/></a></td>
</tr>
<tr>
<td><a href="pk-help.html"><p class="indextitle">How can I help?</p></a></td>
diff --git a/html/pk-download.html b/html/pk-download.html
index bad3044..d784b9b 100644
--- a/html/pk-download.html
+++ b/html/pk-download.html
@@ -8,7 +8,7 @@
<table align="center" class="title">
<tr>
<td><img src="img/packagekit.png"/></td>
- <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td width="95%" valign="middle"><p class="title">PackageKit</p></td>
<td><img src="img/packagekit.png"/></td>
</tr>
</table>
diff --git a/html/pk-help.html b/html/pk-help.html
index 4ea622e..5337d46 100644
--- a/html/pk-help.html
+++ b/html/pk-help.html
@@ -8,7 +8,7 @@
<table align="center" class="title">
<tr>
<td><img src="img/packagekit.png"/></td>
- <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td width="95%" valign="middle"><p class="title">How can I help?</p></td>
<td><img src="img/packagekit.png"/></td>
</tr>
</table>
diff --git a/html/pk-intro.html b/html/pk-intro.html
index e1b23ae..48687a5 100644
--- a/html/pk-intro.html
+++ b/html/pk-intro.html
@@ -8,7 +8,7 @@
<table align="center" class="title">
<tr>
<td><img src="img/packagekit.png"/></td>
- <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td width="95%" valign="middle"><p class="title">What is PackageKit?</p></td>
<td><img src="img/packagekit.png"/></td>
</tr>
</table>
diff --git a/html/pk-screenshots.html b/html/pk-screenshots.html
index 0a10ad9..bbaa210 100644
--- a/html/pk-screenshots.html
+++ b/html/pk-screenshots.html
@@ -8,7 +8,7 @@
<table align="center" class="title">
<tr>
<td><img src="img/packagekit.png"/></td>
- <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td width="95%" valign="middle"><p class="title">Screenshots of latest stuff</p></td>
<td><img src="img/packagekit.png"/></td>
</tr>
</table>
diff --git a/html/pk-using.html b/html/pk-using.html
index 529c1ce..7197c66 100644
--- a/html/pk-using.html
+++ b/html/pk-using.html
@@ -8,14 +8,14 @@
<table align="center" class="title">
<tr>
<td><img src="img/packagekit.png"/></td>
- <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td width="95%" valign="middle"><p class="title">How do I use PackageKit?</p></td>
<td><img src="img/packagekit.png"/></td>
</tr>
</table>
<p>Back to the <a href="index.html">main page</a></p>
-<h1>How do I use PackageKit</h1>
+<h1>How do I use PackageKit?</h1>
<h2>Using the command line</h2>
<p>
diff --git a/html/style.css b/html/style.css
index a30b70a..1b8815b 100644
--- a/html/style.css
+++ b/html/style.css
@@ -50,7 +50,7 @@ pre {
a:hover {
color: #147;
- text-decoration: underline;
+ text-decoration: none;
}
a {
commit ccc397fd4d2e93a4c890e6bfd5e3de378d517ec3
Author: Tim Lauridsen <timlau at fedoraproject.org>
Date: Wed Oct 17 19:02:13 2007 +0200
Added repo support stubs to yum backend
diff --git a/backends/yum/helpers/yumBackend.py b/backends/yum/helpers/yumBackend.py
index dda133a..150ee38 100644
--- a/backends/yum/helpers/yumBackend.py
+++ b/backends/yum/helpers/yumBackend.py
@@ -681,6 +681,20 @@ class PackageKitYumBackend(PackageKitBaseBackend):
else:
self._show_package(pkg,INFO_NORMAL)
+ def repo_enable(self, repoid, enable):
+ '''
+ Implement the {backend}-repo-enable functionality
+ Needed to be implemented in a sub class
+ '''
+ self.error(ERROR_NOT_SUPPORTED,"This function is not implemented in this backend")
+
+ def get_repo_list(self):
+ '''
+ Implement the {backend}-get-repo-list functionality
+ Needed to be implemented in a sub class
+ '''
+ self.error(ERROR_NOT_SUPPORTED,"This function is not implemented in this backend")
+
def _setup_yum(self):
self.yumbase.doConfigSetup(errorlevel=0,debuglevel=0) # Setup Yum Config
commit d87464a1bfc6e4cf5166b9484358b8471a298b57
Author: Tim Lauridsen <timlau at fedoraproject.org>
Date: Wed Oct 17 19:00:13 2007 +0200
Added repo support to backend python base
diff --git a/python/packagekit/backend.py b/python/packagekit/backend.py
index 0bbccbe..88871f7 100644
--- a/python/packagekit/backend.py
+++ b/python/packagekit/backend.py
@@ -118,6 +118,14 @@ class PackageKitBaseBackend:
'''
print >> sys.stderr,"status\t%s" % (state)
+ def repo_detail(self,repoid,state):
+ '''
+ send 'repo-detail' signal
+ @param repoid: The repo id tag
+ @param state: false is repo is disabled else true.
+ '''
+ print >> sys.stderr,"repo-detail\t%s\t%s" % (repoid,state)
+
def data(self,data):
'''
send 'data' signal:
@@ -298,3 +306,17 @@ class PackageKitBaseBackend:
Needed to be implemented in a sub class
'''
self.error(ERROR_NOT_SUPPORTED,"This function is not implemented in this backend")
+
+ def repo_enable(self, repoid, enable):
+ '''
+ Implement the {backend}-repo-enable functionality
+ Needed to be implemented in a sub class
+ '''
+ self.error(ERROR_NOT_SUPPORTED,"This function is not implemented in this backend")
+
+ def get_repo_list(self):
+ '''
+ Implement the {backend}-get-repo-list functionality
+ Needed to be implemented in a sub class
+ '''
+ self.error(ERROR_NOT_SUPPORTED,"This function is not implemented in this backend")
commit 36cfe7420ba3d1466f8e830f48d44fa1719573d7
Author: Richard Hughes <richard at hughsie.com>
Date: Wed Oct 17 17:46:06 2007 +0100
add the start of the website - more to come...
diff --git a/Makefile.am b/Makefile.am
index 705c05e..72d9cc3 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,5 +1,6 @@
SUBDIRS = \
docs \
+ html \
policy \
etc \
man \
diff --git a/configure.ac b/configure.ac
index 8360141..ff47b84 100644
--- a/configure.ac
+++ b/configure.ac
@@ -370,6 +370,8 @@ Makefile
etc/Makefile
man/Makefile
docs/Makefile
+html/Makefile
+html/img/Makefile
backends/Makefile
backends/alpm/Makefile
backends/apt/Makefile
diff --git a/html/Makefile.am b/html/Makefile.am
new file mode 100644
index 0000000..47f7312
--- /dev/null
+++ b/html/Makefile.am
@@ -0,0 +1,21 @@
+NULL =
+
+SUBDIRS = img
+
+HTML_FILES = \
+ index.html \
+ pk-help.html \
+ pk-screenshots.html \
+ pk-download.html \
+ pk-intro.html \
+ pk-using.html \
+ $(NULL)
+
+EXTRA_DIST = \
+ style.css \
+ $(HTML_FILES) \
+ $(NULL)
+
+clean-local:
+ rm -f *~
+
diff --git a/html/img/Makefile.am b/html/img/Makefile.am
new file mode 100644
index 0000000..b54531e
--- /dev/null
+++ b/html/img/Makefile.am
@@ -0,0 +1,14 @@
+NULL =
+
+IMAGE_FILES = \
+ large-accessories-text-editor.png \
+ dialog-information.png \
+ $(NULL)
+
+EXTRA_DIST = \
+ $(IMAGE_FILES) \
+ $(NULL)
+
+clean-local:
+ rm -f *~
+
diff --git a/html/img/dialog-information.png b/html/img/dialog-information.png
new file mode 100644
index 0000000..18af8ec
Binary files /dev/null and b/html/img/dialog-information.png differ
diff --git a/html/index.html b/html/index.html
new file mode 100644
index 0000000..cd33aee
--- /dev/null
+++ b/html/index.html
@@ -0,0 +1,48 @@
+<html>
+<head>
+<title>PackageKit</title>
+<link rel="stylesheet" href="style.css" type="text/css" media="screen"/>
+</head>
+<body>
+
+<table align="center" class="title">
+<tr>
+ <td><img src="img/packagekit.png"/></td>
+ <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td><img src="img/packagekit.png"/></td>
+</tr>
+</table>
+
+<br>
+<br>
+
+<table align="center" cellpadding="3px" border="0">
+
+<tr>
+ <td align="middle"><a href="pk-intro.html"><img src="img/large-accessories-text-editor.png" width="192"/></a></td>
+ <td align="middle"><a href="pk-using.html"><img src="img/large-preferences-system.png" width="192"/></a></td>
+ <td align="middle"><a href="pk-download.html"><img src="img/large-dialog-information.png" width="192"/></a></td>
+</tr>
+<tr>
+ <td><a href="pk-intro.html"><p class="indextitle">What is<br>PackageKit?</p></a></td>
+ <td><a href="pk-using.html"><p class="indextitle">How do I use<br>PackageKit?</p></a></td>
+ <td><a href="pk-download.html"><p class="indextitle">Where can I<br>download it?</p></a></td>
+</tr>
+<tr>
+ <td align="middle"><a href="pk-help.html"><img src="img/large-help-browser.png" width="192"/></a></td>
+ <td align="middle"><a href="pk-screenshots.html"><img src="img/large-bookmark-new.png" width="192"/></a></td>
+ <td align="middle"><a href="wiki/FAQ"><img src="img/large-dialog-information.png" width="192"/></a></td>
+</tr>
+<tr>
+ <td><a href="pk-help.html"><p class="indextitle">How can I help?</p></a></td>
+ <td><a href="pk-screenshots.html"><p class="indextitle">Screenshots of<br>latest stuff</p></a></td>
+ <td><a href="wiki/FAQ"><p class="indextitle">Frequently<br>asked questions</p></a></td>
+</tr>
+</table>
+
+<p align="right">
+<a href="mailto:richard at hughsie.com">Richard Hughes</a> 2007
+</p>
+
+</body>
+</html>
diff --git a/html/pk-download.html b/html/pk-download.html
new file mode 100644
index 0000000..bad3044
--- /dev/null
+++ b/html/pk-download.html
@@ -0,0 +1,70 @@
+<html>
+<head>
+<title>PackageKit</title>
+<link rel="stylesheet" href="style.css" type="text/css" media="screen"/>
+</head>
+<body>
+
+<table align="center" class="title">
+<tr>
+ <td><img src="img/packagekit.png"/></td>
+ <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td><img src="img/packagekit.png"/></td>
+</tr>
+</table>
+
+<p>Back to the <a href="index.html">main page</a></p>
+
+<h1>Where do I download it?</h1>
+
+<p>
+Your distribution may already have compiled packages that are much
+easier to install.
+Conary:
+Yes, just do sudo conary update-all
+Fedora 8:
+Yes, just install this repo and do yum install PackageKit
+gnome-packagekit
+Others:
+Probably not, although you can compile from source. See the download <a
+href="">page</a> for more details.
+</p>
+
+<p>
+PackageKit itself is an abstract daemon, the only bits that are distro
+specific are the backends.
+To make PackageKit work on your unknown distribution you have to write a
+"backend" which is basically a shim layer from the distro tool to
+packagekitd.
+A backend can have one or more threads and also spawn other processes.
+See the developer information <a href="moo">here</a> for loads more
+information.
+</p>
+
+<p>
+Backends do not have to be complete; often they just contain basic
+functionality to install and remove but not provide dependency or file
+lists for example.
+For instance:
+</p>
+<ul>
+<li>yum (95% complete)</li>
+<li>conary (70% complete)</li>
+<li>apt (40% complete)</li>
+<li>box (10% complete)</li>
+<li>pacman/alpm (10% complete)</li>
+</ul>
+
+<p>
+We need people to create a backend, and then package (pardon the pun)
+PackageKit and gnome-packagekit for distributions.
+I think it's important that installing and updating software should be
+as easy as possible.
+</p>
+
+Use Wiki:/Downloads
+
+<p>Back to the <a href="index.html">main page</a></p>
+
+</body>
+</html>
diff --git a/html/pk-help.html b/html/pk-help.html
new file mode 100644
index 0000000..4ea622e
--- /dev/null
+++ b/html/pk-help.html
@@ -0,0 +1,67 @@
+<html>
+<head>
+<title>PackageKit</title>
+<link rel="stylesheet" href="style.css" type="text/css" media="screen"/>
+</head>
+<body>
+
+<table align="center" class="title">
+<tr>
+ <td><img src="img/packagekit.png"/></td>
+ <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td><img src="img/packagekit.png"/></td>
+</tr>
+</table>
+
+<p>Back to the <a href="index.html">main page</a></p>
+
+<h1>How can I help?</h1>
+
+<p>
+Anyone interested in PackageKit development is invited to join the
+channel <code>#PackageKit</code> on <code>freenode</code>.
+We are a friendly bunch, and can answer questions on backends, GUI's or
+anything else PackageKit related.
+</p>
+
+<p>
+There is also a subscription-only <a
+href="http://lists.freedesktop.org/mailman/listinfo/packagekit">mailing
+list</a> where we discuss PackageKit development, patches and future
+development.
+All commits are sent to this list as well, so we can audit any commits
+for bugs or security flaws.
+</p>
+
+<p>
+You can file bugs, or track the status at <a href="http://bugs.freedesktop.org">
+bugs.freedesktop.org</a>
+</p>
+
+<p>
+If you want to write a backend, you can see the <a
+href="pk-reference.html">developer information</a>, or you can checkout
+the source and see the docbook files in doc. Use the <a
+href="wiki/FAQ">FAQ</a> and mailing list for questions, and try to use
+existing backends as a template for what you are trying to do.
+</p>
+
+<table>
+<tr>
+ <td><img src="img/dialog-information.png" alt="[NOTE]"></td>
+ <td>
+ <p>
+ If PackageKit cannot do what you need then please ask on the mailing list.
+ It might already be on the TODO, or we might have to slightly tweak the API
+ to make it possible.
+ For instance, instead of using PolicyKit you might want to use RBAC
+ which we can quite easy add configure <code>#ifdef</code>'s for.
+ </p>
+ </td>
+</tr>
+</table>
+
+<p>Back to the <a href="index.html">main page</a></p>
+
+</body>
+</html>
diff --git a/html/pk-intro.html b/html/pk-intro.html
new file mode 100644
index 0000000..e1b23ae
--- /dev/null
+++ b/html/pk-intro.html
@@ -0,0 +1,113 @@
+<html>
+<head>
+<title>PackageKit</title>
+<link rel="stylesheet" href="style.css" type="text/css" media="screen"/>
+</head>
+<body>
+
+<table align="center" class="title">
+<tr>
+ <td><img src="img/packagekit.png"/></td>
+ <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td><img src="img/packagekit.png"/></td>
+</tr>
+</table>
+
+<p>Back to the <a href="index.html">main page</a></p>
+
+<h1>What is PackageKit?</h1>
+<p>
+PackageKit is a system designed to make installing and updating software
+on your computer easier.
+The primary design goal is to unify all the software graphical tools
+used in different distributions, and use some of the latest technology
+like PolicyKit to make the process suck less.
+</p>
+
+<p>
+The actual nuts-and-bolts distro tool (yum, apt, conary etc-) is used in
+PackageKit using compiled and scripted helpers.
+PackageKit isn't meant to replace these tools, instead providing a
+common set abstraction that can be used by standard GUI and text mode
+package managers.
+</p>
+
+<p>
+PackageKit itself is a system activated daemon called
+<code>packagekitd</code>.
+Being system activated means that it's only being run when the user is
+using a text mode or graphical tool, and quits when it's no longer being
+used.
+This means we don't delay the boot sequence or session startup and don't
+consume memory when not being used.
+</p>
+
+<p>
+<code>gnome-packagekit</code> is the name of the collection of graphical
+tools for PackageKit to be used in the GNOME desktop.
+There are also QT applications being designed, although these are not
+fully functional yet.
+</p>
+
+<table>
+<tr>
+ <td><img src="img/dialog-information.png" alt="[NOTE]"></td>
+ <td>
+ <p>
+ By default, PackageKit uses PolicyKit for user authentication.
+ This means as an admin you can specify with fine-grained control what
+your users can and cannot do.
+ For instance, an admin could specify that unprivileged users can
+update the system and do searching, but are not allowed to install or
+remove packages.
+ For home users it's typical to ask the user for their own, or the
+administrator "root" password.
+ With PolicyKit, all these options are possible.
+ </p>
+ </td>
+</tr>
+</table>
+
+<p>
+Use cases for PackageKit exist for the following scenarios:
+</p>
+
+<ul>
+ <li>Boot time security updates</li>
+ <li>Installing files automatically, e.g. openoffice-clipart</li>
+ <li>Installing new features, e.g. smart-card readers</li>
+ <li>Allowing unprivileged users to install software in a corporate
+build</li>
+ <li>Opening unknown file formats</li>
+ <li>Removing dependencies for files</li>
+</ul>
+<p>
+More details can be found on the wiki.
+</p>
+
+<p>
+PackageKit and gnome-packagekit is GPL2+ licensed.
+</p>
+
+<p>
+What PackageKit is not:
+</p>
+<ul>
+ <li>A huge daemon with lots of dependencies.</li>
+ <li>100% API stable. The API may change a little until we ship
+1.0.0</li>
+ <li>Targeted to a particular architecture or platform.</li>
+ <li>Produced by any one vendor. There are many contributors helping to
+get this done.</li>
+</ul>
+
+<p>
+Formally, 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.
+</p>
+
+<p>Back to the <a href="index.html">main page</a></p>
+
+</body>
+</html>
diff --git a/html/pk-screenshots.html b/html/pk-screenshots.html
new file mode 100644
index 0000000..0a10ad9
--- /dev/null
+++ b/html/pk-screenshots.html
@@ -0,0 +1,25 @@
+<html>
+<head>
+<title>PackageKit</title>
+<link rel="stylesheet" href="style.css" type="text/css" media="screen"/>
+</head>
+<body>
+
+<table align="center" class="title">
+<tr>
+ <td><img src="img/packagekit.png"/></td>
+ <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td><img src="img/packagekit.png"/></td>
+</tr>
+</table>
+
+<p>Back to the <a href="index.html">main page</a></p>
+
+<h1>Screenshots of latest stuff</h1>
+
+Get from NEWS on the release and post screenshots
+
+<p>Back to the <a href="index.html">main page</a></p>
+
+</body>
+</html>
diff --git a/html/pk-using.html b/html/pk-using.html
new file mode 100644
index 0000000..529c1ce
--- /dev/null
+++ b/html/pk-using.html
@@ -0,0 +1,66 @@
+<html>
+<head>
+<title>PackageKit</title>
+<link rel="stylesheet" href="style.css" type="text/css" media="screen"/>
+</head>
+<body>
+
+<table align="center" class="title">
+<tr>
+ <td><img src="img/packagekit.png"/></td>
+ <td width="90%" valign="middle"><p class="title">PackageKit</p></td>
+ <td><img src="img/packagekit.png"/></td>
+</tr>
+</table>
+
+<p>Back to the <a href="index.html">main page</a></p>
+
+<h1>How do I use PackageKit</h1>
+
+<h2>Using the command line</h2>
+<p>
+The <code>pkcon</code> text-mode program allows you to interact with
+PackageKit on the command. e.g. <code>pkcon get updates</code> or
+<code>pkcon search description power</code>.
+The <code>pkmon</code> program allows you to monitor what PackageKit is
+doing on the command line and is mainly used for debugging.
+</p>
+
+<h2>Using graphical tools:</h2>
+<p>
+<code>gnome-packagekit</code> provides a rich set of GTK tools for
+automatically updating your computer and installing software. See the <a
+href=>screenshots page</a> for more details.
+</p>
+
+<h2>Using libpackagekit:</h2>
+<p>
+The libpackagekit gobject library wraps the DBUS interface in a nice
+glib-style API.
+This makes designing programs that use libpackagekit can concentrate on
+core functionality rather that the DBUS and PackageKit internals.
+PkClient in libpackagekit can be used as easily as:
+</p>
+<pre>
+PkClient *client;
+client = pk_client_new ();
+pk_client_install_package (client, "openoffice-clipart");
+g_object_unref (client);
+</pre>
+
+<h2>Using the raw DBUS API:</h2>
+<p>
+Using the DBUS methods and signals directly means that no glib or
+gobject dependency is needed, although this means you will have to
+manage the transaction_id multiplexing in any client program.
+This is not difficult, although does require more code than just using
+libpackagekit.
+The latest interface is available in the source tree or <a
+href="http://gitweb.freedesktop.org/?p=packagekit.git;a=blob;f=src/pk-in
+terface.xml">online</a>.
+</p>
+
+<p>Back to the <a href="index.html">main page</a></p>
+
+</body>
+</html>
diff --git a/html/style.css b/html/style.css
new file mode 100644
index 0000000..a30b70a
--- /dev/null
+++ b/html/style.css
@@ -0,0 +1,65 @@
+body {
+ color: #000000;
+ font-family: 'Lucida Grande', Verdana, Arial, Sans-Serif;
+ }
+
+h1, h2, h3 {
+ color: #000000;
+ font-family: 'Trebuchet MS', 'Lucida Grande', Verdana, Arial, Sans-Serif;
+ font-weight: bold;
+ }
+
+p.title {
+ color: #000000;
+ text-align: center;
+ font-weight: bolder;
+ font-size: 20px;
+ }
+
+th {
+ color: #000000;
+ text-align: left;
+ }
+
+p.indextitle {
+ color: #000000;
+ text-align: center;
+ font-weight: bolder;
+ font-size: 20px;
+ }
+
+table.title {
+ color: #000000;
+ background-color: #f5f5ff;
+ }
+
+img {
+ border: 0;
+ }
+
+code {
+ color: #000000;
+ font: 1.1em 'Courier New', Courier, Fixed;
+ }
+
+pre {
+ color: #000000;
+ background: #eeeeee;
+ padding: 3;
+}
+
+a:hover {
+ color: #147;
+ text-decoration: underline;
+ }
+
+a {
+ color: #147;
+ text-decoration: none;
+ }
+
+td.title {
+ color: #000000;
+ font-weight: bold;
+ }
+
commit e8433131af785f754f17854889de0c55b857cc2a
Author: Richard Hughes <richard at hughsie.com>
Date: Wed Oct 17 17:05:31 2007 +0100
rename reference.html to pk-reference.html for the upcoming website work
diff --git a/docs/Makefile.am b/docs/Makefile.am
index cc6e59b..a0ac370 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -3,12 +3,12 @@ IMAGE_FILES = \
pk-structure.svg
SPEC_XML_FILES = \
- reference.xml \
- introduction.xml \
- backends.xml
+ pk-reference.xml \
+ pk-introduction.xml \
+ pk-backends.xml
SPEC_HTML_FILES = \
- reference.html
+ pk-reference.html
clean-local:
rm -f *~
@@ -23,10 +23,10 @@ EXTRA_DIST = \
if DOCBOOK_DOCS_ENABLED
htmldocdir = $(docdir)
-htmldoc_DATA = reference.html
+htmldoc_DATA = pk-reference.html
-reference.html : introduction.xml
- $(XMLTO) html-nochunks -m config.xsl reference.xml
+pk-reference.html : pk-introduction.xml
+ $(XMLTO) html-nochunks -m config.xsl pk-reference.xml
EXTRA_DIST += $(SPEC_HTML_FILES)
diff --git a/docs/backends.xml b/docs/backends.xml
deleted file mode 100644
index da849c6..0000000
--- a/docs/backends.xml
+++ /dev/null
@@ -1,210 +0,0 @@
-<?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>Install File</entry>
- <entry><literal>install-file.*</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>Resolve</entry>
- <entry><literal>resolve.*</literal></entry>
- </row>
- <row>
- <entry>Get Requires</entry>
- <entry><literal>get-requires.*</literal></entry>
- </row>
- <row>
- <entry>Get Update Detail</entry>
- <entry><literal>get-update-detail.*</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>
- <row>
- <entry>Get Repo List</entry>
- <entry><literal>get-repo-list.*</literal></entry>
- </row>
- <row>
- <entry>Repo Enable</entry>
- <entry><literal>repo-enable.*</literal></entry>
- </row>
- <row>
- <entry>Repo Set Data</entry>
- <entry><literal>repo-set-data.*</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_id[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[tab]size_in_bytes[tab]file_list</literal></entry>
- <entry><literal>stdout</literal></entry>
- </row>
- <row>
- <entry>UpdateDetail</entry>
- <entry><literal>package_id[tab]updates[tab]obsoletes[tab]url[tab]restart[tab]update_text</literal></entry>
- <entry><literal>stdout</literal></entry>
- </row>
- <row>
- <entry>ChangeTransactionData</entry>
- <entry><literal>change-transaction-data[tab]data</literal></entry>
- <entry><literal>stdout</literal></entry>
- </row>
- <row>
- <entry>RepoSignatureRequired</entry>
- <entry><literal>repository_name[tab]key_url[tab]key_userid[tab]key_id[tab]key_fingerprint[tab]key_timestamp[tab]type</literal></entry>
- <entry><literal>stdout</literal></entry>
- </row>
- <row>
- <entry>RepoDetail</entry>
- <entry><literal>repo-detail[tab]repo_id[tab]description[tab]enabled</literal></entry>
- <entry><literal>stdout</literal></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect1>
-
-
-</chapter>
diff --git a/docs/introduction.xml b/docs/introduction.xml
deleted file mode 100644
index 4676fd2..0000000
--- a/docs/introduction.xml
+++ /dev/null
@@ -1,1672 +0,0 @@
-<?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>
- </listitem>
- <listitem>
- <para>
- Automatically installing new or add-on software.
- </para>
- </listitem>
- <listitem>
- <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 description.
- 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 separate 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>
-
- <sect2 id="introduction-ideas-transactionid">
- <title>Transaction ID</title>
- <para>
- A <literal>transaction_id</literal> is a unique identifier that
- identifies the present or past transaction.
- A transaction is made up of one or more sub-transactions.
- A transaction has one <literal>role</literal> for the entire lifetime,
- but the transaction can different values of <literal>status</literal>
- as the transaction is processed.
- </para>
- <para>
- For example, if the user "Installed OpenOffice" and the backend has to:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- update libxml as a dependancy
- </para>
- </listitem>
- <listitem>
- <para>
- install java as dependancy
- </para>
- </listitem>
- <listitem>
- <para>
- install openoffice-bin
- </para>
- </listitem>
- <listitem>
- <para>
- install openoffice-clipart
- </para>
- </listitem>
- </itemizedlist>
- <para>
- This is one single transaction with the role <literal>install</literal>,
- with 4 different sub-transactions.
- This allows the user to rollback transactions with selected backends,
- rather than select sub-transactions which may need complex complict
- resolution.
- </para>
- <para>
- The <literal>transaction_id</literal> must be of the format
- <literal>job;identifier;data</literal> where the daemon controls
- all parameters.
- <literal>job</literal> is a monotonically updating number and is
- retained over reboots.
- <literal>identifier</literal> is random data used by the daemon to
- ensure jobs started in parallel cannot race, and also to make a
- malicious client program harder to write.
- <literal>data</literal> can be used for refcounting in the backend or
- for any other purpose.
- It is designed to make the life of a backend writer a little bit easier.
- An example <literal>transaction_id</literal> would be
- <literal>45;dafeca;checkpoint32</literal>
- </para>
- </sect2>
- <sect2 id="config-main">
- <title>Daemon Config Options</title>
- <para>
- The config file <literal>/etc/PackageKit.conf</literal> allows to the
- administrator to change system daemon options.
- In normal use this file does not have to be changed, but it may be
- useful to people debugging the daemon or developing backends.
- </para>
- <para>
- The options are:
- </para>
- <sect3 id="config-main-logging">
- <title>TransactionLogging</title>
- <para>
- This logs all transactions to a database so old transactions can be viewed.
- </para>
- </sect3>
- <sect3 id="config-main-timeout">
- <title>ShutdownTimeout</title>
- <para>
- This is the time that the daemon waits when idle before shutting down.
- A smaller number will result in slower response times when running
- many transactions in a small amount of time.
- A longer timeout will lock the underlying packaging backend for longer,
- although the daemon will start and stop less often.
- </para>
- </sect3>
- <sect3 id="config-main-default">
- <title>DefaultBackend</title>
- <para>
- The default backend that the daemon should use.
- The default is set at compile time to the
- <literal>--default-backend=</literal> configure setting.
- </para>
- </sect3>
- </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>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>available</literal> or <literal>installed</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>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>available</literal> or <literal>installed</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>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>available</literal> or <literal>installed</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>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>available</literal> or <literal>installed</literal>.
- </para>
- </sect2>
-
- <sect2 id="api-install-package">
- <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>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>downloading</literal>,
- <literal>updating</literal>,
- <literal>installing</literal> or
- <literal>removing</literal>.
- </para>
- </sect2>
-
- <sect2 id="api-install-file">
- <title>Install File</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>full_path</literal></entry>
- <entry>A full path and filename to a single package.</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>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>downloading</literal>,
- <literal>updating</literal>,
- <literal>installing</literal> or
- <literal>removing</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>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>downloading</literal>,
- <literal>updating</literal>,
- <literal>installing</literal> or
- <literal>removing</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>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>available</literal> or <literal>installed</literal>.
- </para>
- </sect2>
-
- <sect2 id="api-resolve">
- <title>Resolve</title>
- <para>
- Resolve turns a single package name into a package_id suitable for the
- other methods.
- </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</literal></entry>
- <entry>A single package name, e.g. <literal>art-clipart</literal>.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>
- This method typically emits
- <literal>Error</literal> and
- <literal>Package</literal>.
- </para>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>available</literal> or <literal>installed</literal>.
- </para>
- </sect2>
-
- <sect2 id="api-get-update-detail">
- <title>Get Update Detail</title>
- <para>
- GetUpdateDetail should return details about the update.
- </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>UpdateDetail</literal> and
- <literal>Error</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>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>available</literal> or <literal>installed</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>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>downloading</literal>,
- <literal>updating</literal>,
- <literal>installing</literal> or
- <literal>removing</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>
- <para>
- <literal>Package</literal> enumerated types should be
- <literal>low</literal>,
- <literal>normal</literal>,
- <literal>important</literal> or
- <literal>security</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>
-
- <sect2 id="api-get-repo-list">
- <title>Get Repo List</title>
- <para>
- Return the list of repositories used in the system.
- </para>
- <para>
- There are no arguments.
- </para>
- <para>
- This method typically emits
- <literal>RepoDetail</literal>.
- </para>
- </sect2>
-
- <sect2 id="api-repo-enable">
- <title>Repo Enable</title>
- <para>
- This enables the repository specified.
- </para>
- <para>
- The arguments are:
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>repo_id</literal></entry>
- <entry>
- A repository identifier, e.g.
- <literal>fedora-development-debuginfo</literal>
- </entry>
- </row>
- <row>
- <entry><literal>enabled</literal></entry>
- <entry>
- <literal>true</literal> if enabled,
- <literal>false</literal> if disabled.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
-
- <sect2 id="api-repo-set-data">
- <title>Repo Set Data</title>
- <para>
- This sets a parameter for the repository specified.
- </para>
- <para>
- The arguments are:
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>repo_id</literal></entry>
- <entry>
- A repository identifier, e.g.
- <literal>fedora-development-debuginfo</literal>
- </entry>
- </row>
- <row>
- <entry><literal>parameter</literal></entry>
- <entry>
- The backend specific value, e.g.
- <literal>set-download-url</literal>.
- </entry>
- </row>
- <row>
- <entry><literal>value</literal></entry>
- <entry>
- The backend specific value, e.g.
- <literal>http://foo.bar.org/baz</literal>.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </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>
- <para>
- When returning results from a search always return
- <literal>installed</literal> before <literal>available</literal> for
- the same package name.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>info</literal></entry>
- <entry>A valid <literal>info</literal> string enumunerated type</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>
-
- <para>
- The <literal>info</literal> enumunerated type
- </para>
-
- <informaltable>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Situation</entry>
- <entry>Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Searching</entry>
- <entry><literal>installed</literal></entry>
- <entry>If installed</entry>
- </row>
- <row>
- <entry></entry>
- <entry><literal>available</literal></entry>
- <entry>If available to install</entry>
- </row>
- <row>
- <entry>Getting Updates</entry>
- <entry><literal>low</literal></entry>
- <entry>If update is of low severity</entry>
- </row>
- <row>
- <entry></entry>
- <entry><literal>normal</literal></entry>
- <entry>If update is of normal severity</entry>
- </row>
- <row>
- <entry></entry>
- <entry><literal>important</literal></entry>
- <entry>If update is very important</entry>
- </row>
- <row>
- <entry></entry>
- <entry><literal>security</literal></entry>
- <entry>If the update is security sensitive</entry>
- </row>
- <row>
- <entry>Installing/Updating/Removing</entry>
- <entry><literal>downloading</literal></entry>
- <entry>If we are downloading this package</entry>
- </row>
- <row>
- <entry></entry>
- <entry><literal>updating</literal></entry>
- <entry>If we are updating this package</entry>
- </row>
- <row>
- <entry></entry>
- <entry><literal>installing</literal></entry>
- <entry>If we are installing this package</entry>
- </row>
- <row>
- <entry></entry>
- <entry><literal>removing</literal></entry>
- <entry>If we are removing this package</entry>
- </row>
- <row>
- <entry>Otherwise</entry>
- <entry><literal>unknown</literal></entry>
- <entry>If we cannot use any other option</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>licence</literal></entry>
- <entry>
- The licence, e.g. "GPL2" or "proprietary".
- If you need to add a EULA then do it like this:
- "proprietary;By installing this software\nyou may kill a kitten."
- </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>
- <row>
- <entry><literal>size</literal></entry>
- <entry>
- The size of the package in bytes. This should be the
- size of the entire package file, not the size of the
- files installed on the system.
- </entry>
- </row>
- <row>
- <entry><literal>file_list</literal></entry>
- <entry>
- A list of all files and directories created by the package
- at install time.
- The list is separated by the <literal>;</literal> character.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
-
- <sect2 id="backends-spawn-update-detail">
- <title>UpdateDetail</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>updates</literal></entry>
- <entry>A list of package_id's that are to be updated</entry>
- </row>
- <row>
- <entry><literal>obsoletes</literal></entry>
- <entry>A list of package_id's that are to be obsoletes</entry>
- </row>
- <row>
- <entry><literal>url</literal></entry>
- <entry>A URL with more details on the update, e.g. a security advisory</entry>
- </row>
- <row>
- <entry><literal>restart_enum</literal></entry>
- <entry>A valid restart type, e.g. "system"</entry>
- </row>
- <row>
- <entry><literal>update_text</literal></entry>
- <entry>
- The update text describing the update in a non-localised way.
- Newlines should be converted to ";"
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
-
- <sect2 id="backends-spawn-repo-signature-required">
- <title>RepoSignatureRequired</title>
- <para>
- Some backends support repositories which use a cryptographic
- signature, such as GPG. If a package cannot be installed
- because it is signed with a key that has not been verified,
- this signal is generated so the user can choose to accept or
- decline the key.
- </para>
- <para>
- This signal includes information that can be used to verify
- that the key should be trusted, such as a URL for the company
- or person who owns the key, the key's ID, the userid of
- the key creator, and the date the key was generated.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>repository_name</literal></entry>
- <entry>The name of the repository associated with the provided key</entry>
- </row>
- <row>
- <entry><literal>key_url</literal></entry>
- <entry>The URL provided with the key.</entry>
- </row>
- <row>
- <entry><literal>key_userid</literal></entry>
- <entry>The user id associated with the key</entry>
- </row>
- <row>
- <entry><literal>key_id</literal></entry>
- <entry>A unique identifier for the key</entry>
- </row>
- <row>
- <entry><literal>key_fingerprint</literal></entry>
- <entry>The hashed fingerprint of the key</entry>
- </row>
- <row>
- <entry><literal>key_timestamp</literal></entry>
- <entry>The date the key was created</entry>
- </row>
- <row>
- <entry><literal>type</literal></entry>
- <entry>The type of signature used. 'GPG', for example.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- </sect1>
-
-</chapter>
diff --git a/docs/pk-backends.xml b/docs/pk-backends.xml
new file mode 100644
index 0000000..da849c6
--- /dev/null
+++ b/docs/pk-backends.xml
@@ -0,0 +1,210 @@
+<?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>Install File</entry>
+ <entry><literal>install-file.*</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>Resolve</entry>
+ <entry><literal>resolve.*</literal></entry>
+ </row>
+ <row>
+ <entry>Get Requires</entry>
+ <entry><literal>get-requires.*</literal></entry>
+ </row>
+ <row>
+ <entry>Get Update Detail</entry>
+ <entry><literal>get-update-detail.*</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>
+ <row>
+ <entry>Get Repo List</entry>
+ <entry><literal>get-repo-list.*</literal></entry>
+ </row>
+ <row>
+ <entry>Repo Enable</entry>
+ <entry><literal>repo-enable.*</literal></entry>
+ </row>
+ <row>
+ <entry>Repo Set Data</entry>
+ <entry><literal>repo-set-data.*</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_id[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[tab]size_in_bytes[tab]file_list</literal></entry>
+ <entry><literal>stdout</literal></entry>
+ </row>
+ <row>
+ <entry>UpdateDetail</entry>
+ <entry><literal>package_id[tab]updates[tab]obsoletes[tab]url[tab]restart[tab]update_text</literal></entry>
+ <entry><literal>stdout</literal></entry>
+ </row>
+ <row>
+ <entry>ChangeTransactionData</entry>
+ <entry><literal>change-transaction-data[tab]data</literal></entry>
+ <entry><literal>stdout</literal></entry>
+ </row>
+ <row>
+ <entry>RepoSignatureRequired</entry>
+ <entry><literal>repository_name[tab]key_url[tab]key_userid[tab]key_id[tab]key_fingerprint[tab]key_timestamp[tab]type</literal></entry>
+ <entry><literal>stdout</literal></entry>
+ </row>
+ <row>
+ <entry>RepoDetail</entry>
+ <entry><literal>repo-detail[tab]repo_id[tab]description[tab]enabled</literal></entry>
+ <entry><literal>stdout</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect1>
+
+
+</chapter>
diff --git a/docs/pk-introduction.xml b/docs/pk-introduction.xml
new file mode 100644
index 0000000..4676fd2
--- /dev/null
+++ b/docs/pk-introduction.xml
@@ -0,0 +1,1672 @@
+<?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>
+ </listitem>
+ <listitem>
+ <para>
+ Automatically installing new or add-on software.
+ </para>
+ </listitem>
+ <listitem>
+ <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 description.
+ 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 separate 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>
+
+ <sect2 id="introduction-ideas-transactionid">
+ <title>Transaction ID</title>
+ <para>
+ A <literal>transaction_id</literal> is a unique identifier that
+ identifies the present or past transaction.
+ A transaction is made up of one or more sub-transactions.
+ A transaction has one <literal>role</literal> for the entire lifetime,
+ but the transaction can different values of <literal>status</literal>
+ as the transaction is processed.
+ </para>
+ <para>
+ For example, if the user "Installed OpenOffice" and the backend has to:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ update libxml as a dependancy
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ install java as dependancy
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ install openoffice-bin
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ install openoffice-clipart
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ This is one single transaction with the role <literal>install</literal>,
+ with 4 different sub-transactions.
+ This allows the user to rollback transactions with selected backends,
+ rather than select sub-transactions which may need complex complict
+ resolution.
+ </para>
+ <para>
+ The <literal>transaction_id</literal> must be of the format
+ <literal>job;identifier;data</literal> where the daemon controls
+ all parameters.
+ <literal>job</literal> is a monotonically updating number and is
+ retained over reboots.
+ <literal>identifier</literal> is random data used by the daemon to
+ ensure jobs started in parallel cannot race, and also to make a
+ malicious client program harder to write.
+ <literal>data</literal> can be used for refcounting in the backend or
+ for any other purpose.
+ It is designed to make the life of a backend writer a little bit easier.
+ An example <literal>transaction_id</literal> would be
+ <literal>45;dafeca;checkpoint32</literal>
+ </para>
+ </sect2>
+ <sect2 id="config-main">
+ <title>Daemon Config Options</title>
+ <para>
+ The config file <literal>/etc/PackageKit.conf</literal> allows to the
+ administrator to change system daemon options.
+ In normal use this file does not have to be changed, but it may be
+ useful to people debugging the daemon or developing backends.
+ </para>
+ <para>
+ The options are:
+ </para>
+ <sect3 id="config-main-logging">
+ <title>TransactionLogging</title>
+ <para>
+ This logs all transactions to a database so old transactions can be viewed.
+ </para>
+ </sect3>
+ <sect3 id="config-main-timeout">
+ <title>ShutdownTimeout</title>
+ <para>
+ This is the time that the daemon waits when idle before shutting down.
+ A smaller number will result in slower response times when running
+ many transactions in a small amount of time.
+ A longer timeout will lock the underlying packaging backend for longer,
+ although the daemon will start and stop less often.
+ </para>
+ </sect3>
+ <sect3 id="config-main-default">
+ <title>DefaultBackend</title>
+ <para>
+ The default backend that the daemon should use.
+ The default is set at compile time to the
+ <literal>--default-backend=</literal> configure setting.
+ </para>
+ </sect3>
+ </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>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>available</literal> or <literal>installed</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>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>available</literal> or <literal>installed</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>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>available</literal> or <literal>installed</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>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>available</literal> or <literal>installed</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-install-package">
+ <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>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>downloading</literal>,
+ <literal>updating</literal>,
+ <literal>installing</literal> or
+ <literal>removing</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-install-file">
+ <title>Install File</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>full_path</literal></entry>
+ <entry>A full path and filename to a single package.</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>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>downloading</literal>,
+ <literal>updating</literal>,
+ <literal>installing</literal> or
+ <literal>removing</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>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>downloading</literal>,
+ <literal>updating</literal>,
+ <literal>installing</literal> or
+ <literal>removing</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>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>available</literal> or <literal>installed</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-resolve">
+ <title>Resolve</title>
+ <para>
+ Resolve turns a single package name into a package_id suitable for the
+ other methods.
+ </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</literal></entry>
+ <entry>A single package name, e.g. <literal>art-clipart</literal>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ This method typically emits
+ <literal>Error</literal> and
+ <literal>Package</literal>.
+ </para>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>available</literal> or <literal>installed</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-get-update-detail">
+ <title>Get Update Detail</title>
+ <para>
+ GetUpdateDetail should return details about the update.
+ </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>UpdateDetail</literal> and
+ <literal>Error</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>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>available</literal> or <literal>installed</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>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>downloading</literal>,
+ <literal>updating</literal>,
+ <literal>installing</literal> or
+ <literal>removing</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>
+ <para>
+ <literal>Package</literal> enumerated types should be
+ <literal>low</literal>,
+ <literal>normal</literal>,
+ <literal>important</literal> or
+ <literal>security</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>
+
+ <sect2 id="api-get-repo-list">
+ <title>Get Repo List</title>
+ <para>
+ Return the list of repositories used in the system.
+ </para>
+ <para>
+ There are no arguments.
+ </para>
+ <para>
+ This method typically emits
+ <literal>RepoDetail</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="api-repo-enable">
+ <title>Repo Enable</title>
+ <para>
+ This enables the repository specified.
+ </para>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>repo_id</literal></entry>
+ <entry>
+ A repository identifier, e.g.
+ <literal>fedora-development-debuginfo</literal>
+ </entry>
+ </row>
+ <row>
+ <entry><literal>enabled</literal></entry>
+ <entry>
+ <literal>true</literal> if enabled,
+ <literal>false</literal> if disabled.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="api-repo-set-data">
+ <title>Repo Set Data</title>
+ <para>
+ This sets a parameter for the repository specified.
+ </para>
+ <para>
+ The arguments are:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>repo_id</literal></entry>
+ <entry>
+ A repository identifier, e.g.
+ <literal>fedora-development-debuginfo</literal>
+ </entry>
+ </row>
+ <row>
+ <entry><literal>parameter</literal></entry>
+ <entry>
+ The backend specific value, e.g.
+ <literal>set-download-url</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>value</literal></entry>
+ <entry>
+ The backend specific value, e.g.
+ <literal>http://foo.bar.org/baz</literal>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </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>
+ <para>
+ When returning results from a search always return
+ <literal>installed</literal> before <literal>available</literal> for
+ the same package name.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>info</literal></entry>
+ <entry>A valid <literal>info</literal> string enumunerated type</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>
+
+ <para>
+ The <literal>info</literal> enumunerated type
+ </para>
+
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Situation</entry>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Searching</entry>
+ <entry><literal>installed</literal></entry>
+ <entry>If installed</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><literal>available</literal></entry>
+ <entry>If available to install</entry>
+ </row>
+ <row>
+ <entry>Getting Updates</entry>
+ <entry><literal>low</literal></entry>
+ <entry>If update is of low severity</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><literal>normal</literal></entry>
+ <entry>If update is of normal severity</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><literal>important</literal></entry>
+ <entry>If update is very important</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><literal>security</literal></entry>
+ <entry>If the update is security sensitive</entry>
+ </row>
+ <row>
+ <entry>Installing/Updating/Removing</entry>
+ <entry><literal>downloading</literal></entry>
+ <entry>If we are downloading this package</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><literal>updating</literal></entry>
+ <entry>If we are updating this package</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><literal>installing</literal></entry>
+ <entry>If we are installing this package</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><literal>removing</literal></entry>
+ <entry>If we are removing this package</entry>
+ </row>
+ <row>
+ <entry>Otherwise</entry>
+ <entry><literal>unknown</literal></entry>
+ <entry>If we cannot use any other option</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>licence</literal></entry>
+ <entry>
+ The licence, e.g. "GPL2" or "proprietary".
+ If you need to add a EULA then do it like this:
+ "proprietary;By installing this software\nyou may kill a kitten."
+ </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>
+ <row>
+ <entry><literal>size</literal></entry>
+ <entry>
+ The size of the package in bytes. This should be the
+ size of the entire package file, not the size of the
+ files installed on the system.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>file_list</literal></entry>
+ <entry>
+ A list of all files and directories created by the package
+ at install time.
+ The list is separated by the <literal>;</literal> character.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="backends-spawn-update-detail">
+ <title>UpdateDetail</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>updates</literal></entry>
+ <entry>A list of package_id's that are to be updated</entry>
+ </row>
+ <row>
+ <entry><literal>obsoletes</literal></entry>
+ <entry>A list of package_id's that are to be obsoletes</entry>
+ </row>
+ <row>
+ <entry><literal>url</literal></entry>
+ <entry>A URL with more details on the update, e.g. a security advisory</entry>
+ </row>
+ <row>
+ <entry><literal>restart_enum</literal></entry>
+ <entry>A valid restart type, e.g. "system"</entry>
+ </row>
+ <row>
+ <entry><literal>update_text</literal></entry>
+ <entry>
+ The update text describing the update in a non-localised way.
+ Newlines should be converted to ";"
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="backends-spawn-repo-signature-required">
+ <title>RepoSignatureRequired</title>
+ <para>
+ Some backends support repositories which use a cryptographic
+ signature, such as GPG. If a package cannot be installed
+ because it is signed with a key that has not been verified,
+ this signal is generated so the user can choose to accept or
+ decline the key.
+ </para>
+ <para>
+ This signal includes information that can be used to verify
+ that the key should be trusted, such as a URL for the company
+ or person who owns the key, the key's ID, the userid of
+ the key creator, and the date the key was generated.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>repository_name</literal></entry>
+ <entry>The name of the repository associated with the provided key</entry>
+ </row>
+ <row>
+ <entry><literal>key_url</literal></entry>
+ <entry>The URL provided with the key.</entry>
+ </row>
+ <row>
+ <entry><literal>key_userid</literal></entry>
+ <entry>The user id associated with the key</entry>
+ </row>
+ <row>
+ <entry><literal>key_id</literal></entry>
+ <entry>A unique identifier for the key</entry>
+ </row>
+ <row>
+ <entry><literal>key_fingerprint</literal></entry>
+ <entry>The hashed fingerprint of the key</entry>
+ </row>
+ <row>
+ <entry><literal>key_timestamp</literal></entry>
+ <entry>The date the key was created</entry>
+ </row>
+ <row>
+ <entry><literal>type</literal></entry>
+ <entry>The type of signature used. 'GPG', for example.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+ </sect1>
+
+</chapter>
diff --git a/docs/pk-reference.xml b/docs/pk-reference.xml
new file mode 100644
index 0000000..bb5fddd
--- /dev/null
+++ b/docs/pk-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="pk-introduction.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pk-backends.xml" />
+
+</book>
+
diff --git a/docs/reference.xml b/docs/reference.xml
deleted file mode 100644
index b6a38cd..0000000
--- a/docs/reference.xml
+++ /dev/null
@@ -1,36 +0,0 @@
-<?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