<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY poldek "<application>poldek</application>">
<!ENTITY poldekcmd "<command>poldek</command>">
<!ENTITY ipoldek "<application>ipoldek</application>">
<!ENTITY ipoldekcmd "<command>ipoldek</command>">
<!ENTITY rpm "<application>rpm</application>">
<!ENTITY prompt "<prompt>$</prompt>">
<!ENTITY poldek-prompt "<prompt>$</prompt> <command>poldek</command>">
<!ENTITY ipoldek-prompt "<prompt>$</prompt> <command>ipoldek</command>">
<!ENTITY apt-get "<application>apt-get</application>">
<!ENTITY apt-rpm "<application>apt-get</application>">
<!ENTITY yum "<application>yum</application>">

<!ENTITY file_poldek-pri-sample-conf SYSTEM "../conf/poldek-pri-sample.conf">

<!ENTITY ref-repository_index_creation SYSTEM "manual/ref0700-repository_index_creation.xml">
<!ENTITY ref-repository_selection SYSTEM "manual/ref0900-repository_selection.xml">
<!ENTITY ref-repository_related_actions SYSTEM "manual/ref0901-repository_related_actions.xml">
<!ENTITY ref-package_related_options SYSTEM "manual/ref1100-package_related_options.xml">
<!ENTITY ref-package_installation SYSTEM "manual/ref1290-package_installation.xml">
<!ENTITY ref-distribution_installation-upgrade SYSTEM "manual/ref1291-distribution_installation-upgrade.xml">
<!ENTITY ref-installation_switches SYSTEM "manual/ref1300-installation_switches.xml">
<!ENTITY ref-package_deinstallation SYSTEM "manual/ref1490-package_deinstallation.xml">
<!ENTITY ref-verification_options-switches SYSTEM "manual/ref1700-verification_options-switches.xml">
<!ENTITY ref-splitting_options SYSTEM "manual/ref1900-splitting_options.xml">
<!ENTITY ref-miscellaneous_options SYSTEM "manual/ref2100-miscellaneous_options.xml">
<!ENTITY manual-index SYSTEM "m_index.xml">
<!ENTITY section-configuration SYSTEM "m_config.xml">
<!ENTITY section-cookbook SYSTEM "manual/cookbook.xml">
<!ENTITY supported-repositories SYSTEM "manual/supported-repositories.xml">
<!ENTITY yum_link "<ulink url='http://linux.duke.edu/projects/yum/'>yum</ulink>">
<!ENTITY apt_link "<ulink url='http://moin.conectiva.com.br/AptRpm'>&apt-rpm;</ulink>">
<!ENTITY xmlmetadata_link "<ulink url='http://linux.duke.edu/projects/metadata/'>XML Package Metadata</ulink>">
]>

<article lang="en">
<articleinfo>
<title>poldek manual</title>

<?xmlif if output='texi'?>
<!-- satisfy docbook2X -->
 <title role="texinfo-node">poldek</title>
 <titleabbrev role="texinfo-node">poldek</titleabbrev>
 <abstract role="texinfo-node">
  <para>
    full-featured frontend to RPM.
  </para>
 </abstract>

 <subjectset scheme="texinfo-directory">
   <subject><subjectterm>Miscellaneous</subjectterm></subject>
 </subjectset>
<?xmlif elif output='html|xhtml'?>
 <abstract role="texinfo-node">
  <para>
   This document provides a guide for &poldek; meta-package manager POLDEK_VERSION.
  </para>
 </abstract>
<?xmlif fi?>

<authorgroup>
<author>
<firstname></firstname>
<surname></surname>
</author>
</authorgroup>

<date>$Date$</date>
<releaseinfo>$Id$</releaseinfo>

<keywordset>
<keyword>package management</keyword>
<keyword>RPM</keyword>
<keyword>APT</keyword>
<keyword>apt-get</keyword>
<keyword>apt-rpm</keyword>
<keyword>yum</keyword>
<keyword>poldek</keyword>
<keyword>PLD</keyword>
<keyword>smart package manager</keyword>
</keywordset>
</articleinfo>

<sect1 id="overview"> <title id="overview.title">Overview</title>
<para>
&poldek; is a full-featured frontend to RPM package manager. Its core features
are similar to every modern package updater like &apt-get;. The features include
package installation, upgrading and removal with automatic dependency handling,
querying/ search the package database and more.
</para>

<para>
<variablelist id="overview.features"><title>Features</title>
<varlistentry><term>Easy to use</term>
  <listitem>
    <para> 
    &poldek; is easy to learn for users familiar with &rpm; because the
    basic command line options and switches are similar in use.
    
    Apart from rpm-like command line switches, &poldek; provides higher level command 
    set ("install", "upgrade", "ls", etc) quite intuitive for those who knows &apt-get;. 
    A very handy shell-like interface with auto-completion and history is also provided.
    </para>
  </listitem>
</varlistentry>

<varlistentry><term>Relatively fast and scalable</term>
  <listitem>
    <para>
    &poldek; has been designed with efficiency and scalability in mind. 
    The native package repository index format is optimized for storage size 
    and loading speed. Dependency processing (dependencies, conflicts, package
    ordering) is significantly faster and needs less memory than rpmlib-based 
    tools. &poldek; can handle 20K packages without noticable 
    speed degradation on typical machine.
    </para>
  </listitem>
</varlistentry>

<varlistentry><term>Incremental repository updates</term>
  <listitem>
    <para>
    &poldek;'s native repositories are able to update incrementally.
    During the update only the incremental files are transferred 
    instead of the complete index. Such files are certainly much smaller,
    what drastically reduces amout of data need to be retrieved
    when remote repository was changed a bit. 
    </para>
  </listitem>
</varlistentry>

<varlistentry><term>Support for multiple repository types</term>
  <listitem>
    <para> 
    &poldek; supports various types of package repositories including
    &apt_link;, &yum_link; and &xmlmetadata_link;. 
    See the <link linkend="repositories.types">list</link> of
    supported repository types for details. Support for other types may be easily added.
    </para>
  </listitem>
</varlistentry>

<varlistentry><term>Flexible installation of a big package sets</term>
  <listitem>
    <para>
    Before their installation packages are divided into small groups,
    usually 2-10 items (depending on their reciprocal dependencies).
    Each group is installed separately, what ensures that unsucessful installation
    of one of the groups does not influence other ones. 
    Another benefit of this separate installation is that it requires
    less memory and disk space than the usual one.
   </para>
  </listitem>
</varlistentry>

<varlistentry><term>Flexible downloading</term>
  <listitem>
    <para>
    Out of the box FTP, HTTP, HTTPS, RSYNC and SMB are supported. This list
    may be easily extended to other protocols by external scripts. 
    </para><para>
    FTP and HTTP are handled by built-in client designed to retrieve
    files over slow or unstable network connections -- if a download
    fails due to a network problem, it will keep trying until the
    whole file will be downloaded.  Download resuming, timestamp
    checking, proxy support are implemented as well.

    </para>
  </listitem>
</varlistentry>


<varlistentry><term>Repository management</term>
  <listitem>
    <para>
     &poldek; provides functionality which helps to manage distribution repositories. 
     Features include:
     <itemizedlist>
     <listitem><para> Detail reports about dependency loops, unmet dependencies,
     package conflicts, file sharing/conflicts, orphaned directories and missing dependencies.
     </para></listitem>
     
     <listitem><para> Division package set to chunks to be placed on removable media
     with ordering according dependency tree and with priority handling.</para></listitem>
     <listitem><para> Moving packages from one repository to another with full 
     dependency checking. </para></listitem>
     </itemizedlist>
    </para>
  </listitem>
</varlistentry>


</variablelist>

</para>
</sect1>

<sect1 id="quickstart"> <title>Quick start</title>
<para> 
Suppose you want to: a) use remote repository of Fedora Core 4, 
b) prepare your local package directory <filename>$HOME/rpm/RPMS</filename> to be available 
to poldek. 
</para>

<sect2 id="quickstart.configure"> <title>Step #1 - Configure repositories</title>
<para>
Source configuration may be placed in your local 
<filename id="file.poldekrc">$HOME/.poldekrc</filename> or global <filename id="file.source-conf">/etc/poldek/source.conf</filename>. Whatever you choose, put there 
something like:
<screen>
[source]
_fcurl = http://download.fedora.redhat.com # macro, just for short
name   = fc4                               # name 
type   = metadata                          # use xml metadata indexes
url    = %{_fcurl}/pub/fedora/linux/core/4/i386/os/

[source]
name = home
path = $HOME/rpm/RPMS
</screen>
</para>
</sect2>

<sect2 id="quickstart.create"> <title>Step #2 - Create repository index</title>
  <para>
  Fedora Core 4 index is ready, we must create one for <filename>$HOME/rpm/RPMS</filename>:

  <screen>
&prompt; <command>poldek -n <replaceable>home</replaceable> --makeidx</command>
  </screen>

  As result several files with package data will be created under 
  <filename>$HOME/rpm/RPMS</filename>.
  <screen> 
&prompt; <command>poldek -n <replaceable>home</replaceable> --makeidx</command>
Creating pndir index of /home/me/rpm/RPMS (type=dir)...
Loading [dir]home...
200..400..600..800..1000..1200..1400..1600..1652
Writing /home/me/rpm/RPMS/packages.ndir.gz...
  </screen>

  Remember to call this command after every change of 
  <filename>$HOME/rpm/RPMS</filename>'s content.
  </para>
</sect2>

<sect2 id="quickstart.use"> <title>Step #3 - Use the program</title>
<para>
&poldek; provides two commands: &poldekcmd; with rpm-like command line interface
and &ipoldekcmd; with interactive mode command interface. Invoking syntax is:
<screen>
&poldek-prompt; [OPTION...] [PACKAGE...]
&ipoldek-prompt; [OPTION...] [COMMAND] [COMMAND_OPTION...] [PACKAGE...]
</screen>

For example to install or upgrade Apache HTTP server:
<screen>
&poldek-prompt; -uv apache 
&ipoldek-prompt; install apache
</screen>     
 <!-- See also <url name="sample interactive mode session" url="screenshoots.html">. -->

Selection of particular repositories may be done by <option>-n</option> option:
<screen>
&ipoldek-prompt; -n fc4 ls foo\*
&poldek-prompt; -n home -uv foo-3.1-2
&ipoldek-prompt; -n home -s http://foo.bar/RPMS/ install foo-3.1\*
</screen>

Most used &poldek; command options are compliant with &rpm;: 
<option>--install</option> (<option>-i</option>), 
<option>--upgrade</option> (<option>-u</option>,<option>-U</option>),
<option>--erase</option> (<option>-e</option>), etc. Their &ipoldek; equivalents
are: <option>install -IN</option> (--install), <option>install</option> (--upgrade) 
and <option>uninstall</option> (--erase). Notice that &ipoldek; <option>install</option>
command it more general -- equivalent of <option>--install</option> is 
<option>install -IN</option>.
</para>
<para>

Extensive help is available for all commands, for &poldekcmd; by using the <option>--help</option> switch, for &ipoldekcmd; by using the <option>help</option> command and 
<option>--help</option> switch for individual commands:
<screen>
&poldek-prompt; --help
&ipoldek-prompt; help
&ipoldek-prompt; install --help
</screen>

&ipoldekcmd; provides comfortable shell-like mode which puts you into 
a readline interface. To enter it, execute &ipoldekcmd; without any command:
<screen id="screen.shell-start">
&ipoldek-prompt; -n ac
Loading [pdir]ac...
10998 packages read
Loading [rpmdbcache]/var/lib/rpm...
1751 packages loaded

Welcome to the poldek shell mode. Type "help" for help with commands.

<prompt>poldek:/all-avail></prompt>
</screen>
Once you are on &poldek;'s command line, type 'help' and the rest should be, more 
or less, self-explanatory.
</para>
<screen id="screen.shell-help">
<prompt>poldek:/all-avail></prompt>help

ls        [OPTION...] [PACKAGE...]             List packages
search    [OPTION...] PATTERN [PACKAGE...]     Search packages
get       [OPTION...] PACKAGE...               Download packages
desc      [OPTION...] PACKAGE...               Display packages info
install   [OPTION...] PACKAGE...               Install packages
uninstall [OPTION...] PACKAGE...               Uninstall packages
cd        [PATH]                               Change current package directory
pwd                                            Print name of current directory
help                                           Display this help
alias                                          Print defined command aliases
reload                                         Reload installed packages
quit                                           Exit poldek

Type COMMAND -? for details.
<prompt>poldek:/all-avail></prompt>
</screen>
</sect2>     
</sect1>

<sect1 id="repositories"> <title>Package repositories</title>
<para>
Like other packages management tools &poldek; uses package repositories
(<emphasis>sources</emphasis>) to obtain meta-information about available 
packages.

Repository consist of database (<emphasis>package index</emphasis>) of
package meta-data (dependencies, files, description, etc) and, of course packages 
itself. Various types of repositories are supported including &apt-rpm; and 
&yum; ones. 
</para>

<!-- WTF?
&supported-repositories; - 'IDREF attribute linkend references an unknown ID "repositories.types"'

<xi:include href="manual/supported-repositories.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - 'variablelist: validity error : No declaration for attribute base of element variablelist'

So, lets old good m4:
-->
include(manual/supported-repositories.xml)

<para>
Native &poldek; repositories 'pndir' and 'pdir' have <quote>incremental updates</quote> 
feature consist in creation of package index delta files with differences between
already created and previous package index. Deltas are used later to perform update 
of local indexes what noticeably reduces amout of data downloaded. In the other words, 
when repository was changed by adding a few packages, only information about those few 
packages will be retrieved on update 
(see <link linkend="repositories.using.update">Update</link> subsection).
</para>

<sect2 id="repositories.configuration"> <title>Repositories configuration</title>
<para>
Although repositories can be specified directly at command line,
they are usually configured. Every repository has its own configuration 
section <quote>[source]</quote>, for example:

<screen>
[source]
type   = pndir                                      # package index type 
name   = distro                                     # name of the source
path   = http://my-favourite-distro.org/1.0/RPMS/   # path 
signed = yes                                        # verify package signatures

[source]
type   = pndir                                 
name   = distro-updates                        
path   = http://my-favourite-distro.org/1.0/updates/
signed = yes                                 

[source]
type = dir
name = home
path = ${HOME}/rpm/RPMS
auto = no                                            # load on demand only
</screen>
 
<option>type</option> is not obligatory - if not set, then type is 
taken from <option>default index type</option> configuration option value. 
For all possible source configuration and extensible option description
see <link linkend="configuration">Configuration</link> and 
and <filename>*source.conf</filename> files supplied with &poldek;.
</para>

<para>
&poldek; is can read &apt-rpm;'s 
<filename id="file.sources-list">/etc/apt/sources.list</filename> directly.
It is controlled by <option>load apt sources list</option>, to load apt's
sources do:
<screen>load apt sources list = yes</screen> 
</para>


</sect2>

<sect2 id="repositories.using"> <title>Using repositories</title>

<sect3 id="repositories.using.select"> <title>Selection</title>
<para> 
&poldek; loads all configured repositories at startup  
Executed without repository selection options &poldek; 
loads all configured repositories at startup, except they which have 
<option>auto</option> turned off. 

To use particular repositories use <option>--sn</option> 
(<option>-n</option>) option, for example, to use only <emphasis>home</emphasis> 
source, do:
<screen>
&poldek-prompt; -n home
</screen>

Repository name can be also a glob, to use all sources with <quote>distro</quote>
prefix, do:
<screen>
&poldek-prompt; -n distro\*
</screen>
</para>

<para>
Non configured repositories can be specified directly at command line
by <option>--source</option> (<option>-s</option>) option. 
The syntax is: 

<screen>
&poldek-prompt; [--st=TYPE] --source=SOURCEPATH [--prefix=PATH]
</screen>

where <emphasis>TYPE</emphasis> is one of index supported types, and SOURCEPATH is
the path or URL of repository. If package index and packages 
are located in different paths/URLs then <option>--prefix</option> can
be used to point packages location. Examples:

<screen>
&poldek-prompt; -s ~/rpm/RPMS
&poldek-prompt; --st pdir -s ftp://foo.bar.org/RPMS/
&poldek-prompt; -s ftp://foo.bar.org/RPMS.index/ --prefix ftp://foo.bar.org/RPMS/
&poldek-prompt; -s /tmp/packages.ndir.gz --prefix /media/cdrom
</screen>
</para>
</sect3>

<sect3 id="repositories.using.update"> <title>Updating</title>
<para> 
 To resynchronize the package index from its repository use 
 <option>--update</option> (<option>--up</option>) or 
 <option>--update-whole</option> (<option>--upa</option>):

<screen>
&poldek-prompt; [-s PATH] [-n NAME] --update
&poldek-prompt; [-s PATH] [-n NAME] --update-whole
</screen>

</para>
<para>
With <option>--update</option> program looks for an index delta files which
can be used to update local package index. If they are unavailable, then whole 
index is downloaded.

With <option>--update-whole</option> program updates whole package index if it is 
outdated. It is a good idea to run do updates regularly to keep indexes up to date.

</para>
<para>
Update requested for local repositories causes verification integrity of indexes.
</para>

<para> 
Examples:
<screen>
&poldek-prompt; --st pdir -s ftp://foo.bar.org/RPMS/ --up 
&poldek-prompt; -s ftp://foo.bar.org/RPMS.index/ --prefix ftp://foo.bar.org/RPMS/ --upa
&poldek-prompt; -n home --up
</screen>
</para>
</sect3>

<sect3 id="repositories.using.list"> <title>Listing available repositories</title>
<para> To list all configured repositories use 
<option>--sl</option> (<option>-l</option>):
<screen>
&poldek-prompt; -l
distro          http://my-favourite-distro.org/1.0/RPMS/    (sign,type=pndir)
distro-updates  http://my-favourite-distro.org/1.0/updates/ (sign,type=pndir)
home            /home/me/rpm/RPMS/  (noauto,type=dir)
</screen>
</para>
</sect3>

<sect3 id="repositories.using.listype"> <title>Listing available repository types</title>
<para> To list all available repository types, use <option>--stl</option>:
<screen>
&poldek-prompt; --stl
dir    r--  Dynamic index built by scanning directory for packages
             (aliases: rpmdir)
hdrl   r-u  File with raw RPM package headers; used by apt-rpm
             (aliases: apt)
pdir   rwu  Native poldek's index format prior to 0.20 version
             (aliases: pidx)
pndir  rwu  Native poldek's index format
rpmdb  r--  RPM package database
yum    r-u  Yum index format
Legend: r - readable, w - writeable, u - updateable
</screen>
</para>
</sect3>
</sect2>

<sect2 id="repositories.creating"> <title>Creating</title>
<para> 
Creation of &poldek;'s repositories is quite simple, the syntax is:

<screen>
&poldek-prompt; -s PATH --mkidx[=PATH] [--mt=TYPE[,TYPE]...] [--nodesc] [--nocompress] [--nodiff]
&poldek-prompt; -n NAME --mkidx[=PATH] [--mt=TYPE[,TYPE]...] [--nodesc] [--nocompress] [--nodiff]
</screen>
</para>
<para>
what creates package index of repository specified by <option>-n</option> or <option>-s</option> and saves it under directory specified by <option>--mkidx</option>
(a package directory by default). Type of created index is the same
as specified by <option>default index type</option> configuration option. 
To make index of the other type or make many indexes of different types at once, use 
<option>--mt</option> option.
</para>

<para>
For 'pndir' and 'pdir' indexes delta files are created if previous repository index 
is different from currently created one. Outdated deltas are automatically removed.
To skip deltas creation use <option>--nodiff</option> option.
</para>

<para>
Other related options are: <option>--nodesc</option> with that package descriptions are not saved to repository index and <option>--nocompress</option> means that uncompressed index will be created.
</para>

<para>
Examples:
<screen>
&poldek-prompt; -s ~/rpm/RPMS --mkidx --nodiff
&poldek-prompt; -s /cdrom/RPMS --mkidx=/tmp
&poldek-prompt; -n home --mkidx 
&poldek-prompt; -n pld --mkidx --mt=pdir,pndir
</screen>
</para>
</sect2>

<sect2 id="repositories.cache"> <title>Cache</title>
<para>
By default only package index files are cached. To cache packages too, i.e. keep 
them even after successful installation, set <option>keep downloads</option> 
configuration option. Default cache directory is 
<filename id="file.home-poldek-cache">$HOME/.poldek-cache</filename>, 
it can be set to different location by <option>cachedir</option>
configuration option. Cached files can be removed by three options:
<itemizedlist>
<listitem> <para><option>--clean</option> remove source index files</para> </listitem>
<listitem> <para><option>--clean-pkg</option> remove cached packages. </para></listitem>
<listitem> <para><option>--clean-whole</option> remove all files from cache directory </para> </listitem>
</itemizedlist>

In conjunction with <option>-n</option> or <option>-s</option> cleannig 
may be limited to files belongs to specified repositories only. Examples:
<screen>
&poldek-prompt; -s http://foo.bar/RPMS --clean
&poldek-prompt; -n foo --clean-whole
&poldek-prompt; --clean-pkg
</screen>
</para>
</sect2>

<!-- 
<para>
See also repository related command line options <link linkend="ref.cmdl.repository_index_creation">reference</link>.
</para>
-->
</sect1>

<sect1 id="pkgmanaging"> <title>Managing packages</title>
<para>
&poldek; operates in two basic modes - the first one is more generic 
and compliant with &rpm; (&poldek; command) and the second, 
called <emphasis>interactive</emphasis> mode with simplified and 
intuitive command set. </para>

<para>
Interactive mode commands is available from both command line (&ipoldek; command) 
and shell like interface with auto-completion and history. To enter shell interface
execute &ipoldek; without any "command" options like "install", "erase", etc. 
See also an <link linkend="screen.shell-start">example</link>.
</para>

<sect2 id="pkgmanaging.spec"> <title>Specifying packages</title>
<para>
Packages can be specified in five ways:
<itemizedlist>
  <listitem>
     <para>as package Name[-[Epoch:]Version-Release] mask, e.g.
     <screen>
&poldek-prompt; ... apache
&poldek-prompt; ... apache-1.3.31-2
&poldek-prompt; ... apache-2:1.3.31-2
&poldek-prompt; ... 'apache-1.3*'
&poldek-prompt; ... 'apache-mod_*pam*'
     </screen>
     </para>
  </listitem>
  <listitem> 
     <para>as packages files, e.g:
     <screen>
&poldek-prompt; ... apache-1.3.31-1.i386.rpm
     </screen>
     </para>    
  </listitem> 
  <listitem> 
     <para> as Name#Version[-Release] string, e.g.:
     <screen>
&poldek-prompt; ... apache#1.3.31
&poldek-prompt; ... apache#1.3.31-1
     </screen>
     </para> 
  </listitem>
  <listitem> 
     <para> by package capability (Provides):
     <screen>
&poldek-prompt; ... --caplookup webserver
&poldek-prompt; ... --caplookup smtpdaemon
     </screen>
     <option>--caplookup</option> is available in command line mode only.
     </para> 
  </listitem>
  <listitem>
   <para> as list read from file, e.g.:
     <screen>
&poldek-prompt; ... --pset ~/.package-sets/tiny-system
&poldek-prompt; ... --pset http://foo.bar.com/package-sets/tiny-system.txt
     </screen>

     Syntax of file passed as <option>--pset</option> argument is very simple.
     Each package is specified in separated line in following syntax:
     <screen>
     NAME [EVR] | @VIRTUAL [DEFAULT_NAME [DEFAULT_EVR]]
     </screen>
     '@' specifies virtual package. Hashed lines are treated as comments.

     Example:
     <screen>
FHS 2.1 
basesystem
pdksh
@bootloader lilo 2.1
@smtpdaemon exim
     </screen>
     <option>--pset</option> is available in command line mode only.
     </para> 
  </listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="pkgmanaging.install"> <title>Installing packages</title>
<para>
To install packages in &rpm; sense, i.e. do not upgrade even if older version is already installed:
<screen>
&poldek-prompt;  [OPTION..] --install                 (command line mode)
&ipoldek-prompt; [OPTION..] install -IN               (interactive mode)
</screen>

It is useful when installation of multiple instance of package is needed (kernel for example).
Example:
<screen>
&poldek-prompt; -iv kernel-2.6.11 
Processing dependencies...
There are 1 package to install:
I kernel-2.6.11-2
Need to get 13.4MB of archives (13.4MB to download).
After unpacking 15.2MB will be used.
Retrieving ac::kernel-2.6.11-2.i686.rpm...
.............................. 100.0% [13.4MB (2M/s)]
Executing sudo /bin/rpm --install -vh --root / --noorder...
Preparing...                ########################################### [100%]
   1:kernel                 ########################################### [100%]
</screen>
</para>

<para>
To install or upgrade package if older version is already installed:
<screen>
&poldek-prompt;  [OPTION..] --upgrade                 (command line mode)
&ipoldek-prompt; [OPTION..] install                   (interactive mode)
</screen>
This is most used installation type. Example:
<screen>
&prompt; &ipoldek; install vim
Loading [pdir]ac...
10998 packages read
Processing dependencies...
vim-6.2.479-1 obsoleted by vim-6.3.067-1
vim-6.3.067-1 marks vim-rt-6.3.067-1 (cap vim-rt = 4:6.3.067-1)
  vim-rt-6.2.479-1 obsoleted by vim-rt-6.3.067-1
    greedy upgrade gvim-gtk-6.2.479-1 to 6.3.067-1 (unresolved vim-rt = 4:6.2.479-1)
      gvim-gtk-6.2.479-1 obsoleted by gvim-gtk-6.3.067-1
    greedy upgrade vim-ispell-6.2.479-1 to 6.3.067-1 (unresolved vim-rt = 4:6.2.479-1)
      vim-ispell-6.2.479-1 obsoleted by vim-ispell-6.3.067-1
There are 4 packages to install (3 marked by dependencies), 4 to uninstall:
I vim-6.3.067-1
D gvim-gtk-6.3.067-1, vim-ispell-6.3.067-1, vim-rt-6.3.067-1
R gvim-gtk-6.2.479-1, vim-rt-6.2.479-1, vim-6.2.479-1, vim-ispell-6.2.479-1
Need to get 4.5MB of archives (4.5MB to download).
After unpacking 14.0MB will be used.

Retrieving ac::vim-ispell-6.3.067-1.i686.rpm...
.............................. 100.0% [526.3K (56.4K/s)]                      
Retrieving ac::vim-6.3.067-1.i686.rpm...
.............................. 100.0% [518.0K (62.5K/s)]                      
Retrieving ac::gvim-gtk-6.3.067-1.i686.rpm...
.............................. 100.0% [679.2K (69.1K/s)]                      
Retrieving ac::vim-rt-6.3.067-1.i686.rpm...
.............................. 100.0% [2.9M (56.4K/s)]                       

Executing sudo /bin/rpm --upgrade -vh --root / --noorder...
Preparing...                ########################################### [100%]
   1:vim-rt                 ########################################### [ 25%]
   2:gvim-gtk               ########################################### [ 50%]
   3:vim                    ########################################### [ 75%]
   4:vim-ispell             ########################################### [100%]
</screen>
</para>

<para>
To upgrade packages, i.e. install only if older version is already installed:
<screen>
&poldek-prompt;  [OPTION..] --upgrade --fresh         (command line mode)
&ipoldek-prompt; [OPTION..] upgrade                   (interactive mode)
</screen>
</para>
<para>
Example:
<screen>
&poldek-prompt; -uvF 'apache*'
</screen>
</para>
<para>

To upgrade all packages need upgrade <option>--upgrade-dist</option> can be used,
or, in interactive mode '*' may be specified as package mask.
Examples:
<screen>
&poldek-prompt; -v --upgrade-dist

&ipoldek-prompt; -v upgrade '*'    
&ipoldek-prompt; -v install -F '*' (the same, "upgrade" is just an alias for "install -F")
</screen>
</para>
</sect2>

<sect2 id="pkgmanaging.distinstall"> <title>Installation system from a scratch</title>
<para>
&poldek; can be used as system installer, to install system from scratch use 
<option>--install-dist</option> option. The syntax is:
<screen>
&poldek-prompt; --install-dist=DIR [PACKAGE...]
</screen>
All unmet dependencies will be satisfied by marking additionall packages. 
Packages are installed one by one what reduces memory consumption and CPU 
utilization of CPU and permits to install the system on older machines.
</para>
<para>
As example, command which installs system under <filename>/mnt/dest</filename> might looks like:
<screen>
&poldek-prompt; -s ftp://foo.bar/RPMS --install-dist=/mnt/dest --pset ftp://foo-bar/package-sets/myset.txt
</screen>
</para>

<!--
<para>
See also install command line options <link linkend="ref.cmdl.package_installation">reference</link>.
</para>
-->
</sect2>

<sect2 id="pkgmanaging.removal"> <title>Removing packages</title>
<para>
&poldek; removes packages with its reverse-dependent ones by default. Packages are 
removed in the right order following <emphasis>Requires(un)</emphasis> 
&rpm; requirements.
</para>
<para>
To remove installed packages:
<screen>
&poldek-prompt;  [OPTION..] --erase                      (command line mode)
&ipoldek-prompt; [OPTION..] uninstall [ERASE_OPTION...]  (interactive mode)
</screen>
</para>
<para>
Examples:
<screen>
&poldek-prompt; -e apache 
&poldek-prompt; -e kernel-2.6.11.5-3
&poldek-prompt; -e kernel-3:2.6.11.5-3
&ipoldek-prompt; uninstall kernel-2.6.11.5-3
</screen>
</para>


<!--
<para>
See also package removal command line options <link linkend="ref.cmdl.package_deinstallation">reference</link>.
</para>
-->
</sect2>

<sect2 id="pkgmanaging.desc"> <title>Obtaining information about packages</title>
<para>
Package details, both about installed and available ones can be easily accessed
through interactive mode commands: <command>ls</command>, <command>search</command>
and <command>desc</command>. 
</para>

<sect3> <title>ls - package listing</title>
<para>
<command>ls</command> like system ls, list packages in different ways.
Type <literal>"ls --help"</literal> to see all available options.
Output example:
<screen><prompt>poldek:/installed></prompt> ls -O *gimp*
gimp-2.0.0-1
    The GNU Image Manipulation Program
gimp-print-lib-4.2.6-1
    gimp-print library
</screen>
</para>
</sect3>

<sect3> <title>search - search packages</title>
<para>
Package repositories may be easily searched by many criteria like package
description, summary, group, requirements, etc. Type <literal>"search --help"</literal> 
to see all available options.
Syntax of command is:
<screen>
search [OPTION...] PATTERN [PACKAGE...]
</screen>
Where <emphasis>PATTERN</emphasis> is a glob or, with <option>--perlre</option>, 
Perl regular expression.  

For instance to find the packages that contains <filename>/usr/sbin/ab</filename> file:
<screen>
&ipoldek-prompt; search -l /usr/sbin/ab
2 package(s) found:
apache-2.0.53-4
apache1-tools-1.3.33-4
</screen>

Try to find something for audio files manipulation:
<screen>
&ipoldek-prompt; search --perlre /audio.+editor/
3 package(s) found:
ecawave-0.6.1-3
piave-0.2.4-2
rezound-0.11.1-0.beta.2
</screen>
</para>
</sect3>

<sect3><title>desc - show package details</title>
<para>
Command gives access to all package information: package description and summary,
group, vendor, build time,requirements, capabilities and conflicts, full file list, etc.
Type <literal>"desc --help"</literal> to see all available options. Example:
<screen>
<prompt>poldek:/all-avail></prompt> desc apache
Package:        apache-2.0.53-4
Summary:        The most widely used Web server on the Internet
Group:          Networking/Daemons
Vendor:         PLD
License:        Apache Group License
Arch/OS:        i686/linux
URL:            http://httpd.apache.org/
Built:          2005/03/14 22:02 at i686.ac.pld-linux.org
Size:           2.4 MB (2516798 B)
Package size:   1.0 MB (1097448 B)
Path:           http://ftp.pld-linux.org/dists/ac/PLD/i686/PLD/RPMS
File:           apache-2.0.53-4.i686.rpm
Description:
Apache is a powerful, full-featured, efficient and freely-available
Web server. Apache is also the most popular Web server on the Internet.
</screen>
</para>
</sect3>
</sect2>
</sect1>

<sect1 id="security"> <title id="security.title">Security issues</title>
<para>
Although there is not known security problems, it is strongly recommended 
to use &poldek; as an ordinary user and use the root privileges for package 
installation and removal only. It is possible in two ways with help of 
<command>sudo</command> command.
</para>

<sect2 id="security.sudo"> <title>Using sudo</title>
<para>
<option>use sudo</option> configuration opinion causes 
execution of &rpm; binary through sudo for read-write operations. 
The rest works without super user privileges. 

</para><para>
Of course it is necessary to configure <application>sudo</application>
to allow the user to run <command>rpm</command> binary. 
</para>

<para>
<option>use sudo</option> is set to "auto" by default, means that 
<command>rpm</command> is executed through <command>sudo</command>
when poldek is run by an ordinary user.
</para>
</sect2>

<sect2 id="security.runas"> <title>Automatic switching to an ordinary user</title>
<para>
There is more automated way of using sudo. Configured by <option>runas</option> 
option &poldek; will automatically switch to an ordinary user if detects being 
executed by root. To setup this scenario, set <option>runas</option> option:
<screen>
runas = poldek
</screen>
and configure <quote>poldek</quote> user account. There is 
<filename id="file.poldekuser-setup">poldekuser-setup.sh</filename> script 
which automates user account configuration supplied with poldek.
</para>
</sect2>

</sect1>

<sect1 id="maintain"> <title id="maintain.title">Repository management</title>
<para>
&poldek; can be useful for distribution developers and maintainers by make 
detailed reports about package set consistency, automating move packages 
from one repository to another and helping to generate CD/DVD ISO images.
</para>

<sect2 id="maintain.verify"> <title>Verification of package set quality</title>
<para>
&poldek; can do reports about package set consistency: dependency loops, 
unmet dependencies, conflicts between packages, orphaned directories
and missing (not the same as unmet) dependencies. Reports are accessible through 
<option>--verify</option>(<option>-V</option>) switch with report type as argument.

<variablelist><title>Avaialble reports:</title>

<varlistentry><term>Dependency loops and unmet dependencies</term>
  <listitem><para>
   This report allows to verify if package set contain any unsatisfied dependencies
   and requirements (<emphasis>PreReq</emphasis>s) loops (loop makes impossible to 
   install packages in the right order). This report is called <emphasis>deps</emphasis> 
   and it is the default one, so it is accessible through <option>--verify</option> 
   without an argument. Output example:
    <screen>
&poldek-prompt; -n home --verify
Verifying dependency loops...
error: PreReq loop: pam &lt;- coreutils &lt;- pam &lt;- SysVinit
error: PreReq loop: xinitrc &lt;- XFree86 &lt;- xinitrc
2 prerequirement loops detected 

Verifying dependencies...
error: docbook-utils-0.6.13-7: req perl(Getopt::Long) &gt;= 2.01 version mismatch
eog-2.8.2-1: req libexif.so.10 not found
error: ruby-gnome2-0.11.0-2: req ruby-rbogl not found
3 unsatisfied dependencies found
    </screen>
   </para>
   </listitem>
</varlistentry>

<varlistentry><term>Package conflicts</term>
  <listitem><para>
    Report prints all package pairs being in conflict or being obsoleted one another.
    It lets to verify if all conflicts are needed, what are redundant, and so on. Report is 
    called <emphasis>conflicts</emphasis>. Output example (Obsoletes 
    are printed with asterisk '*'):
    <screen>
&poldek-prompt; -n foo --verify=conflicts
Verifying conflicts...
bind-9.2.5-2 -> *maradns-1.1.30-1, *dnsmasq-2.19-1, *pdnsd-1.1.8b1-0.par8.2
maradns-1.1.30-1 -> *bind-9.2.5-2 
login-2.12-15 -> *heimdal-login-0.6.3-2
pdnsd-1.1.8b1-0.par8.2 -> *maradns-1.1.30-1, *maradns-zoneserver-1.1.30-1 
shadow-4.0.4.1-3 -> pwdutils-2.6.90-3
    </screen>
  </para>
 </listitem>
</varlistentry>

<varlistentry><term>File conflicts</term>
  <listitem><para>
    Report prints all package pairs being in conflict on file level and pairs 
    which share the same file. It lets to verify if all file conflicts are wanted.
    Report is called <emphasis>file-conflicts</emphasis>:
    <screen>
&poldek-prompt; -n foo --verify=file-conflicts
Path: /usr/lib/perl5/vendor_perl/5.8.0/i686-pld-linux-thread-multi/Image
  shr   perl-base-5.8.6-3(D m40755 s4096)  -  ImageMagick-perl-6.1.8.9-1(D m40755 s4096)

Path: /var/log/archiv/mail
  cnfl  syslog-ng-1.6.6-2(D m40755 s4096) &lt;-&gt; zmailer-2.99.56-4(D m40750 s48)

Path: /usr/bin/digest
  cnfl  perl-XMLDigest-0.1-1(F m100755 s1418) &lt;-&gt; nss-tools-3.1-1(F m100755 s32964)
    </screen>
    '&lt;' and '&gt;' mean missing explicit conflict between packages.
   </para>
  </listitem>
</varlistentry>

<varlistentry><term>Orphaned directories</term>
  <listitem><para>
    Report prints all directories without an owner, i.e. directories not explicit
    included in packages (a %files section of RPM spec file). In proper package
    distribution set such directories should not happened. Orphans are created 
    with root's umask and they later cannot be verified by rpm.
    </para><para>
    Report is called <emphasis>file-orphans</emphasis>:
    <screen>
&poldek-prompt; -n foo --verify=file-orphans
error: /etc/X11/dm: orphaned directory from gdm-2.4.4.5-1, gnome-session-2.4.0-1
error: /var/games/phantasia: orphaned directory from bsd-games-2.16-2
    </screen>
   </para>
  </listitem>
</varlistentry>


<varlistentry><term>Missing dependencies</term>
  <listitem><para>
    Report helps to avoid rather subtle packaging bugs when one package has
    files in directories owned by other package which is not requied by the 
    first one.
    </para><para>
    Report is called <emphasis>file-missing-deps</emphasis>:
    <screen>
&poldek-prompt; -n foo --verify=file-missing-deps
GConf-1.0.9-11: /etc/gconf: not in required packages (missing Requires: gnome-utils?)
cups-1.1.19-13: /etc/logrotate.d: not in required packages (missing Requires: logrotate?)
    </screen>
   </para>
  </listitem>
</varlistentry>
</variablelist>
</para>

<para>
Some or all of above reports may be requested at once, <option>--verify</option>
can be fed by comma separated report list, for example:

<screen>
&poldek-prompt; -n foo --verify=deps,file-orphans,file-missing-deps
</screen>
</para>

<para>
Package subset can verified too. If it is not desirable to verify whole
repository, just give to poldek package list you want to verify:
<screen>
&poldek-prompt; -n foo --verify=deps --pset=packages-minicd.txt
&poldek-prompt; -n foo --verify=deps glibc poldek
</screen>
</para>
</sect2>

<sect2 id="maintain.split"> <title>Preparation of distribution disks</title>

<para>
&poldek; can partition package set for the purpose of placing it on removable media 
like DVD or CD. Package set is divided in the way that minimize needs of disk changes,
i.e if distribution packages fits on 3 CDs, then only 2 changes of CD disk are necessary
during installation system from a scratch. The invoking syntax is:
<screen>
&poldek-prompt; --split=SIZE[:FIRST_FREE_SPACE] [--priconf=FILE] [--split-out=PREFIX]
</screen>
Where <emphasis>SIZE</emphasis> is a size of the chunk in megabytes. Optional 
<emphasis>FIRST_FREE_SPACE</emphasis> makes the first chunk FIRST_FREE_SPACE MB smaller,
useful to save space for installer for example.
</para>

<para>
Packages are placed in successive chunks in order of their
installation. To reorder packages moving some to higher or lower chunk,
especially on first/ last one, priorities may be assigned to
them. Package priorities are taken from file given by <option>--priconf</option>. 
Format of this file is quite simple, see sample 
<link linkend="appendix.sample-pri.conf"><filename>poldek-pri-sample.conf</filename></link> supplied with &poldek;.
</para>

<para>
Each chunk is written as <filename>NAME-EVR.ARCH.rpm</filename> list to 
<emphasis>PREFIX.XX</emphasis> file, the default <emphasis>PREFIX</emphasis> 
is <quote>packages.chunk</quote>.
</para>
</sect2>

<sect2 id="maintain.manage"> <title>Managing repository packages</title>
<para>
A typical scenario during distribution development looks like there is repository 
for untested packages from where they periodically, when found to be tested enough, 
are moved to the another repository marked as stable branch. 
</para><para>
&poldek; can help movig packages between repositories through
<quote>to repository</quote> installation, i.e. packages 
are copied from source to destination repository with full dependency
checking. Thus this feature allows to move subtree of
packages from one repository to another without a risk of break
dependencies. The syntax is:

<screen>
&poldek-prompt; ... --dn SOURCE_NAME [--dn SOURCE_NAME] ...
</screen>
Where <emphasis>SOURCE_NAME</emphasis> is a name of destination repository 
to which we want to move packages, for example:
<screen>
&poldek-prompt; -n ac-test --dn ac -uv libselinux
Loading [pdir]ac-test...
1161 packages read
Loading [pdir]ac...
Processing dependencies...
libselinux-1.18-1 obsoleted by libselinux-1.22-1
  greedy upgrade libselinux-devel-1.18-1 to 1.22-1 (unresolved libselinux = 1.18-1)
    libselinux-devel-1.18-1 obsoleted by libselinux-devel-1.22-1
      greedy upgrade libselinux-static-1.18-1 to 1.22-1 (unresolved libselinux-devel = 1.18-1)
        libselinux-static-1.18-1 obsoleted by libselinux-static-1.22-1
  greedy upgrade libselinux-utils-1.18-1 to 1.22-1 (unresolved libselinux = 1.18-1)
    libselinux-utils-1.18-1 obsoleted by libselinux-utils-1.22-1
There are 4 packages to install (3 marked by dependencies), 4 to uninstall:
I libselinux-1.22-1
D libselinux-devel-1.22-1, libselinux-static-1.22-1, libselinux-utils-1.22-1
R libselinux-1.18-1, libselinux-devel-1.18-1, libselinux-static-1.18-1, libselinux-utils-1.18-1
Need to get 153.9KB of archives (153.9KB to download).
rm /home/ftp/pub/ac/libselinux-1.18-1.i686.rpm
rm /home/ftp/pub/ac/libselinux-devel-1.18-1.i686.rpm
rm /home/ftp/pub/ac/libselinux-static-1.18-1.i686.rpm
rm /home/ftp/pub/ac/libselinux-utils-1.18-1.i686.rpm
cp libselinux-utils-1.22-1.i686.rpm /tmp/RPMS/libselinux-utils-1.22-1.i686.rpm
cp libselinux-static-1.22-1.i686.rpm /tmp/RPMS/libselinux-static-1.22-1.i686.rpm
cp libselinux-devel-1.22-1.i686.rpm /tmp/RPMS/libselinux-devel-1.22-1.i686.rpm
cp libselinux-1.22-1.i686.rpm /tmp/RPMS/libselinux-1.22-1.i686.rpm
</screen>

Removing packages from repositories in that safe manner is also possible:
<screen>
&poldek-prompt; --dn ac -e poldek
mark poldek-0.18.8-3
Processing dependencies...
poldek-0.18.8-3 marks libpi-0.1.1-1 (req poldek)
  libpi-0.1.1-1 marks libpi-devel-0.1.1-1 (req libpi = 0.1.1-1)
  libpi-0.1.1-1 marks pacman-0.1-3 (req libpi)
poldek-0.18.8-3 marks poldex-0.17.4-1 (req poldek)
There are 5 packages to remove (4 marked by dependencies):
R poldek-0.18.8-3
D libpi-0.1.1-1, libpi-devel-0.1.1-1, pacman-0.1-3, poldex-0.17.4-1
Proceed? [y/N]
</screen>

Sometimes it is not desirable to let poldek to move packages itself. With
<option>--test</option> and <option>--parsable-tr-summary</option> switches
easy to parse output is produced, what allows to handle move operation by 
external scripts. Example:
<screen>
&poldek-prompt; --dn ac -et poldek --parsable-tr-summary
[cut]
%R poldek-0.18.8-3
%D libpi-0.1.1-1
%D libpi-devel-0.1.1-1
%D pacman-0.1-3
%D poldex-0.17.4-1
</screen>
</para>
</sect2>
</sect1>

<sect1 id="ref"><title>Command line options reference</title>
&ref-repository_index_creation;
&ref-repository_selection;
&ref-repository_related_actions;
&ref-package_related_options;
&ref-package_installation;
&ref-distribution_installation-upgrade;
&ref-installation_switches;
&ref-package_deinstallation;
&ref-verification_options-switches;
&ref-splitting_options;
&ref-miscellaneous_options;
</sect1>

<sect1 id="configuration"><title>Configuration</title>
&section-configuration;
</sect1>

<sect1 id="cookbook"><title>Cookbook</title>
&section-cookbook;
</sect1>

<appendix id="appendix.sample-pri.conf"><title>Package priorities configuration sample</title>
<para>
<screen>
&file_poldek-pri-sample-conf;
</screen>
</para>
</appendix>

<index id="manualindex"><title>Index</title>
&manual-index;
</index>

</article>
