.TH "Cupt tutorial" 7 "20161227" "Eugene V. Lyubimkin"


.P


.SH NAME

.P
cupt_tutorial \- tutorial for cupt package manager

.SH PREFACE

.SS Abstract

.P
Cupt is a high\-level package manager for Debian and Debian\-derived OSes, with
\fIdpkg(1)\fR as a back\-end.

.P
The aim of this manual is to describe the all features Cupt package manager has
to manage the system, from the most basics to very advanced tuning. Please
submit your proposals/patches when you see some use case is not covered.

.P
This manual was written for the second major version of Cupt (2.x branch).

.SS Disadvantages and advantages

.P
You might not want to use Cupt, because:

.RS
.IP \(bu 3
Cupt is "unofficial" package manager. Currently, nothing in Debian ecosystem
uses Cupt. It also means you won't get a support for it on most of Debian
resources (you can however file bugs or join IRC channel, see \fIcupt(1)/Reporting\fR).

.IP \(bu 3
Cupt is not very well tested by users yet. Its userbase is relatively small.
However, you are invited to test it and increase the number of users.

.IP \(bu 3
Some features which are present in other high\-level package managers are missing.

Among them: multiarch, GUI and TUI interfaces, cdrom:// URI download method, repositories
without a Release file, integration with \fIcron(8)\fR. And there are probably
many more.
.RE

.P
You might want to use Cupt to have these, to my best knowledge, unique features:

.RS
.IP \(bu 3
integration with debdelta (binary package deltas)

.IP \(bu 3
synchronization by source versions

.IP \(bu 3
strict, full\-case, configurable problem resolver

.IP \(bu 3
full tree errors for unresolvable dependency problems

.IP \(bu 3
package manager shell

.IP \(bu 3
satisfy subcommand

.IP \(bu 3
changeset\-based system modifications for systems with low free disk space

.IP \(bu 3
option name checker (for the 'cupt::*' option family)

.IP \(bu 3
dpkg action sequences with heuristics to make an average number of packages in interim states low
.RE

.P
Also, one of Cupt's targets is to have zero non\-wishlist bugs. You might want
to try it if you encountered a bug in other package manager(s).

.SS Infrastructure

.P
Out of existing APT infrastructure, Cupt uses (and shares):

.RS
.IP \(bu 3
remote repositories and \fIsources.list(5)\fR

.IP \(bu 3
".deb" archives' cache

.IP \(bu 3
configuration (\fIapt.conf(5)\fR)

.IP \(bu 3
preferences (\fIapt_preferences(5)\fR)

.IP \(bu 3
database of automatically installed packages
.RE

.P
The following infrastructure items are Cupt\-specific:

.RS
.IP \(bu 3
local cache of repository metadata (since version 2.1.0)

.IP \(bu 3
Cupt\-specific configuration (\fIcupt.conf(5)\fR)

.IP \(bu 3
system snapshots
.RE

.SS Getting started

.P
To start working with Cupt just install it using any present package manager
(for example, \fBapt\-get install cupt\fR or \fBaptitude install cupt\fR) and run
\fBcupt update\fR afterwards.

.P
It should be safe to co\-use Cupt and any APT\-based package managers.

.P
When using commands that modify a system, you have to either execute \fBcupt\fR with
root privileges or supply \fB\-\-simulate\fR (or \fB\-s\fR) option.

.P
Use \fBcupt help\fR to get a list of subcommands and their short descriptions.

.SH BASICS

.SS The debian system as Cupt sees it

.P
Cupt package manager sees the Debian system as a set of installed packages and
repositories of available packages.

.P
Each binary package has zero, one or more versions, of which zero or one versions
may be installed.

.P
Any installed package may be marked as \fBautomatically installed\fR, it means that
user didn't ask for this package to be installed, but it is needed to satisfy
some dependency. Packages which are not automatically installed are
\fBmanually installed\fR.

.P
Available versions (including installed one) of the binary package have unique
version strings. Since Cupt 2.6, Cupt\-specific version string suffixes (for example,
\fB^installed\fR or \fB^dhs0\fR) may be applied. More details on this here.

.SS Errors and warnings

.P
Cupt uses three types of output to user: information, warnings and errors.

.P
All warning messages are prepended with \fBW:\fR. They mean non\-critical errors,
which may be, depending on the situation, real errors or things to ignore.

.P
All error messages are prepended with \fBE:\fR. Most of errors block the executing
of the program, but not all.

.P
Errors and warnings are written to the standard error.

.P
All other messages are the information for the user. They are written to
standard output.

.SS Exploring the system

.SS what packages are installed?

.P
\fBcupt pkgnames \-\-installed\-only\fR

.P
gives you the list, one package name per line. You can also use

.P
\fBdpkg \-l | grep "^ii"\fR

.P
for more detailed information.

.SS getting information about an installed package

.P
\fBdpkg \-s\fR \fIpackage_name\fR

.P
or

.P
\fBcupt show \-\-installed\-only\fR \fIpackage_name\fR

.P
A second command is preferable, for example, when you want to know is this
package automatically installed or not.

.SS details of available package versions

.P
To show a default package version:

.P
\fBcupt show\fR \fIpackage_name\fR

.P
Example: \fBcupt show dpkg\fR

.P
To show all available package versions:

.P
\fBcupt show \-\-all\-versions\fR \fIpackage_name\fR

.P
If you want to see a Debian changelog for a package, use the subcommand \fBchangelog\fR.

.P
Example: \fBcupt changelog exim4\fR

.P
If you want to see a Debian copyright file a for a package, use the subcommand \fBcopyright\fR.

.P
Example: \fBcupt copyright exim4\fR

.P
Note: Cupt can show changelogs and copyrights either for installed packages, or
for packages available in official repositories in Debian or Ubuntu.

.SS searching for a package

.P
To search for a package, specify one or more regular expressions as arguments:

.P
\fBcupt search\fR \fIkeyword1\fR \fIkeyword2\fR ... \fIkeywordN\fR

.P
Example: you want to find a Qt\-based audio player:

.P
\fBcupt search audio qt player\fR: found qmmp.

.P
\fBcupt search music qt player\fR: found also amarok.

.P
Another example: you want to find GTK+\-related Perl modules:

.P
\fBcupt search \-\-names\-only "gtk.*perl"\fR

.SS Updating repository metadata

.P
To update repository medadata, use

.P
\fBcupt update\fR

.P
It's recommended to update metadata every time before you install or upgrade
packages.

.P
Note: Cupt downloads quite a many files to update repository metadata. Some
files may be downloaded in 2\-3 different ways (like indexes) or are not so
important (like translations for package descriptions). You may see some
warnings, but if you don't see an error message like

.P
\fBE: there were errors while downloading release and index data\fR

.P
, the process overall went fine. You can also check program exit code.

.SS Modifying the system

.SS package actions terminology

.P
When some package is changing its state, Cupt calls the action:

.TP
install

when a package which wasn't installed is now going to be installed

.TP
remove

when a package will be removed

.TP
upgrade

when a new (bigger) version of the already installed package is to be installed

.TP
downgrade

when an old (more less) version of the already installed package is to be installed

.TP
purge

when a package and its configuration files will be removed

.SS action preview prompt

.P
An example of action preview prompt:

.nf
$ cupt install kdm akregator exim4

The following packages will be installed:

exim4 exim4-base exim4-config exim4-daemon-light 

The following packages will be upgraded:

kde-window-manager kdebase-workspace-bin kdebase-workspace-data
kdebase-workspace-kgreet-plugins kdm ksysguard ksysguardd libkdecorations4
libkephal4abi1 libkscreensaver5 libksgrd4 libksignalplotter4
libkwineffects1abi1 libkworkspace4 libplasma-geolocation-interface4
libplasmaclock4abi1 libplasmagenericshell4 libprocesscore4abi1 libprocessui4a
libsolidcontrol4abi1 libsolidcontrolifaces4abi1 libtaskmanager4abi1
libweather-ion6 plasma-dataengines-workspace plasma-desktop
plasma-widgets-workspace 

The following packages will be removed:

libgsasl7(a) libntlm0(a) msmtp(a) msmtp-mta 

Action summary:
  1 manually installed and 3 automatically installed packages will be installed
  1 manually installed and 25 automatically installed packages will be upgraded
  1 manually installed and 3 automatically installed packages will be removed

Need to get 25.7MiB/83.4MiB of archives. After unpacking 3512KiB will be used.
Do you want to continue? [y/N/q/a/?]
.fi


.P
In the output above you can see: lists of packages to change the state,
the summary of planned changes, the total download amount of packages (83.4MiB),
the download amount considering the cache of already downloaded archives
(25.7MiB), an estimate of difference in disk usage after the actions
(+3512KiB), a user prompt what to do.

.P
For removed and purged packages, a suffix \fB(a)\fR is appended to a package name
if a package was automatically installed.

.P
The following answers to a user prompt are available:

.TP
y

accept a solution, i.e. proceed with it

.TP
n

decline a solution, i.e. ask to find another solution

.TP
q

don't do anything, quit immediately

.TP
?

output a short help about available answers

.TP
a

explained here

.SS installing packages

.P
To install a package:

.P
\fBcupt install\fR \fIpackage_name\fR

.P
Example: \fBcupt install exim4\fR

.P
To install several packages:

.P
\fBcupt install\fR \fIpackage_name_1\fR \fIpackage_name_2\fR ... \fIpackage_name_N\fR

.P
Example: \fBcupt install exim4 kvirc kdm\fR

.SS upgrading packages

.P
To upgrade one or more installed packages, use the same commands as for installing packages.

.SS removing packages

.P
To remove a package:

.P
\fBcupt remove\fR \fIpackage_name\fR

.P
Example:

.P
\fBcupt remove gdb\fR

.P
To remove several packages:

.P
\fBcupt remove\fR \fIpackage_name_1\fR \fIpackage_name_2\fR ... \fIpackage_name_N\fR

.P
Example:

.P
\fBcupt remove gdb kvirc exim4\fR

.SS upgrading the whole system

.P
To upgrade as many packages as possible:

.P
\fBcupt full\-upgrade\fR

.P
In the mode above, Cupt will even consider removing manually installed
packages. If you want to restrict removing manually installed packages, do

.P
\fBcupt full\-upgrade \-\-no\-remove\fR

.P
Or, shorter:

.P
\fBcupt safe\-upgrade\fR

.P
There is the third upgrade mode, which is to be used for upgrades to the next
major distribution releases:

.P
\fBcupt dist\-upgrade\fR

.P
This subcommand upgrades Cupt itself and dpkg at first, and then calls new version of itself to upgrade the rest.

.SS purging packages

.P
To purge a package, i.e. remove a package along with its configuration files
and maybe some dynamically generated or runtime files:

.P
\fBcupt remove \-\-purge\fR \fIpackage_name\fR

.P
Or:

.P
\fBcupt purge\fR \fIpackage_name\fR

.P
To purge several packages:

.P
\fBcupt purge\fR \fIpackage_name_1\fR \fIpackage_name_2\fR ... \fIpackage_name_N\fR

.P
Example:

.P
\fBcupt purge gdb\fR

.SS Package archives cleaning

.P
Whenever Cupt needs to install, upgrade or downgrade packages it downloads
binary package archives (\fB\&.deb\fR files) to an archive cache. These archives
are not removed after the first usage so they can be reused later.

.P
If you do upgrades often, it's a good idea to periodically delete old package
archives to save the disk space. It's done by the subcommand \fBautoclean\fR:

.P
\fBcupt autoclean\fR

.P
The command above will delete all package archives which do not belong to
currently available repositories.

.P
If you want to remove all archives from the cache, do

.P
\fBcupt clean\fR

.P
Both subcommands above will also remove the partially downloaded archive files
which may stay around after the terminated download operations.

.SH INTERMEDIATE LEVEL

.SS Working with multiple package versions

.SS changing repositories

.P
Cupt uses the same repository list format as APT. See \fIsources.list(5)\fR.

.SS release information

.P
Each version of a certain package has one or more \fBsource\fRs where it comes from.

.P
Each source consists of download information and a subrepository information,
or \fBrelease information\fR.

.P
The following properties belong to release information:

.TP
basic URI

a common prefix of URIs for all files which come for this (sub)repository (also
referred as \fBorigin\fR in APT documentation)

Example: \fBhttp://ftp.fi.debian.org/debian\fR

.TP
archive

a repository archive name, for example \fBtesting\fR or \fBstable\fR

.TP
codename

a release code name, for example \fBwheezy\fR or \fBsid\fR

.TP
component

a subrepository component name, for example \fBmain\fR or \fBnon\-free\fR

.TP
vendor

a vendor name, for example: \fBDebian\fR

.TP
label

a vendor\-provided label, for example: \fBDebian\-Security\fR

.TP
version

a release version, for example: \fB6.0\fR

.TP
description

a repository description line

.P
Any of properties above may be empty.

.P
To see available releases:

.P
\fBcupt policy\fR

.P
Example:

.nf
 $ cupt policy
 Package files:
   /var/lib/dpkg/status installed/: o=dpkg,a=installed,l=,c=,v=,n=now
   http://ftp.fi.debian.org/debian stable/main: o=Debian,a=stable,l=Debian,c=main,v=6.0,n=squeeze
   http://security.debian.org stable/main: o=Debian,a=stable,l=Debian-Security,c=main,v=6.0,n=squeeze
   http://ftp.fi.debian.org/debian squeeze-updates/main: o=Debian,a=squeeze-updates,l=Debian,c=main,v=,n=squeeze-updates
   http://ftp.fi.debian.org/debian testing/main: o=Debian,a=testing,l=Debian,c=main,v=,n=wheezy
   http://ftp.fi.debian.org/debian testing/contrib: o=Debian,a=testing,l=Debian,c=contrib,v=,n=wheezy
   http://ftp.fi.debian.org/debian testing/non-free: o=Debian,a=testing,l=Debian,c=non-free,v=,n=wheezy
   http://ftp.fi.debian.org/debian unstable/main: o=Debian,a=unstable,l=Debian,c=main,v=,n=sid
   http://ftp.fi.debian.org/debian unstable/contrib: o=Debian,a=unstable,l=Debian,c=contrib,v=,n=sid
   http://ftp.fi.debian.org/debian unstable/non-free: o=Debian,a=unstable,l=Debian,c=non-free,v=,n=sid
   http://ftp.fi.debian.org/debian experimental/main: o=Debian,a=experimental,l=Debian,c=main,v=,n=experimental
.fi


.P
The format of lines above:

.P
\fIbasic_URI\fR \fIarchive\fR\fB/\fR\fIcomponent\fR\fB: o=\fR\fIvendor\fR\fB,a=\fR\fIarchive\fR\fB,l=\fR\fIlabel\fR\fB,c=\fR\fIcomponent\fR\fB,v=\fR\fIversion\fR\fB,n=\fR\fIcodename\fR

.P
Note that "installed" release have the archive \fBinstalled\fR and the codename \fBnow\fR.

.P
To see the release descriptions of releases a version belongs to:

.P
\fBcupt show \-\-with\-release\-info\fR \fIpackage_name\fR

.P
Example:

.P
\fBcupt show \-\-with\-release\-info dpkg\fR

.SS version pinning system

.P
Each package version has a \fBpin\fR, an integer number.

.P
Amongst all versions of the same binary package, the one who has maximal pin is
\fBpolicy\fR, or \fBpreferred\fR version.  It's also \fBcandidate\fR in APT
terminology and in Cupt before 2.3.

.P
Cupt assigns pins to package versions according to the APT documentation
(\fIapt_preferences(5)\fR). Plus, it adds:

.RS
.IP \(bu 3
1 to pin of every version which has a signed source

.IP \(bu 3
downgrade penalty (the option \fBcupt::cache::pin::addendums::downgrade\fR)

.IP \(bu 3
hold penalty for packages that are 'on hold' (the option \fBcupt::cache::pin::addendums::hold\fR)

.IP \(bu 3
\fBnot automatic\fR penalty for versions which come solely from sources marked as not automatic, for example, from Debian
\fBexperimental\fR distribution (the option \fBcupt::cache::pin::addendums::not\-automatic\fR)
.RE

.P
Note that sometimes the way APT assigns pins to versions is not the way
described in its documentation, so Cupt's pins (modulo Cupt\-specific additions
described above) are not necessarily identical to what APT produces.

.SS what package versions are available?

.P
\fBcupt policy\fR \fIpackage_name\fR

.P
Example:

.nf
 $ cupt policy dpkg
 dpkg:
   Installed: 1.15.5.6
   Preferred: 1.15.8.10
   Version table:
      1.15.8.10 991
         http://ftp.fi.debian.org/debian testing/main (signed)
         http://ftp.fi.debian.org/debian unstable/main (unsigned)
         http://ftp.se.debian.org/debian testing/main (signed)
         http://ftp.se.debian.org/debian unstable/main (signed)
  *** 1.15.5.6 100
         /var/lib/dpkg/status installed/ (unsigned)
      1.14.31 -1499
         http://security.debian.org oldstable/main (signed)
.fi


.P
In the output above we can see: installed version ('1.15.5.6'), preferred version
('1.15.8.10') and a version table. In total, 3 versions of dpkg are available.

.P
For each version in version table we can see (on example of '1.15.8.10'): a version pin ('991'),
a list of repositories where this version is available.

.P
Each repository line is:

.P
\fIbasic_URI\fR \fIarchive\fR\fB/\fR\fIcomponent\fR (\fIsignedness\fR)

.P
The repository marked as \fBsigned\fR if it has a valid and
verified cryptographic signature, and \fBunsigned\fR otherwise.

.SS version string id suffixes

.P
Starting with version 2.6, Cupt's behavior regarding merging versions having
the same version string changed.

.P
Firstly, Cupt now never merges installed versions with versions from
repositories, since dpkg provides no way to know if the installed version is
the same as the version from repository. All version strings of installed
versions now have \fB^installed\fR suffix, for example \fB1.2.4^installed\fR.

.P
Secondly, if same versions from different repositories have different hash
sums, instead of discarding everything but first version Cupt now append
suffixes like \fB^dhs0\fR or \fB^dhs315\fR to version strings of non\-first
versions, for example \fB1.2.4^dhs0\fR.

.SS selecting binary package versions

.P
When there are more than one version for a package, Cupt provides following ways to
select a version of the binary package in the arguments of the various subcommands:

.TP
policy version

to select a policy version, just specify a package name alone.

Example:

\fBcupt show dpkg\fR

.TP
specific version

to select an exact version of the package, use the suffix \fB=\fR\fIversion\fR.

Example:

\fBcupt show dpkg=1.15.8.10\fR

.TP
by archive or codename

to select a version in release with known archive or codename, use the suffix
\fB/\fR\fIarchive\fR or \fB/\fR\fIcodename\fR.

Examples:

\fBcupt show dpkg/unstable\fR

\fBcupt show dpkg/sid\fR

.P
The syntax described above is known as \fBbinary package version expression\fR.
In the \fIcupt(1)\fR manual page all subcommands which accept this syntax are clearly
marked as such.

.SS Combining multiple version arguments

.P
Many subcommands accept several arguments of the same meaning. Examples:

.P
\fBcupt show dpkg cupt libpqxx3=3.0.2\-1\fR

.P
\fBcupt install youtube\-dl clive/stable\fR

.P
\fBcupt remove libabc\-dev libefg\-dev libxyz\-dev\fR

.P
\fBcupt policy perl perl\-base\fR

.P
You can use wildcards \fB*\fR and \fB?\fR to select multiple package names. Examples:

.RS
.IP \(bu 3
\fBcupt show perl\-b*\fR

Shows policy versions of packages which names start with \fBperl\-b\fR, for example
\fBperl\-base\fR and \fBperl\-byacc\fR.

.IP \(bu 3
\fBcupt show perl\-*/experimental\fR

Shows experimental version of packages which names start with \fBperl\-\fR and
which have experimental versions. In other words, packages without a version in
\fBexperimental\fR distribution won't be selected.

.IP \(bu 3
\fBcupt show *=2.0.0\-1 | grep Package\fR

List packages which have a version \fB2.0.0\-1\fR. Using wildcards with versions is
maybe useless, but possible.

.IP \(bu 3
\fBcupt full\-upgrade xserver\-xorg\-*/installed\fR

Perform a full upgrade but keep all installed packages with names starting with
\fBxserver\-xorg\-\fR at their current versions.

.IP \(bu 3
\fBcupt show ?aff*\fR

Show policy versions of packages with names which have 'a', 'f' and 'f' on 2nd,
3rd and 4th positions (starting with 1st), respectively.
.RE

.SS Conditional installation

.P
Starting with Cupt 2.4, there is a special subcommand \fBiii\fR ("install if
installed") for installing new versions of already installed packages while not
touching uninstalled packages. It behaves like \fBinstall\fR, but ignores
arguments corresponding to not installed packages.

.P
Examples:

.RS
.IP 1. 3
You want to upgrade a certain package (say, \fBgit\fR) on multiple
machines, where some of these machines have that package installed and some
not. If you have a mechanism to send one command to all machines (say, ssh
multiplexer), you can send the command

\fBcupt update && cupt iii git\fR

The second part of the command will do nothing on the machines where \fBgit\fR is
not installed and will install the preferred version of the package \fBgit\fR
where this package was installed.

.IP 2. 3
You have an X server and some X video drivers installed, and you want to
upgrade all installed drivers. For that you can do

\fBcupt iii xserver\-xorg\-video*\fR
.RE

.SS Overriding package management actions

.SS Action override options

.P
You can use special positional options \fB\-\-install\fR, \fB\-\-remove\fR,
\fB\-\-purge\fR, \fB\-\-iii\fR, \fB\-\-satisfy\fR, \fB\-\-unsatisfy\fR, \fB\-\-markauto\fR,
\fB\-\-unmarkauto\fR, \fB\-\-asauto=yes\fR, \fB\-\-asauto=no\fR, \fB\-\-asauto=default\fR to
override the specified action until the end of the arguments or the next action
override option.

.P
Examples:

.RS
.IP \(bu 3
\fBcupt remove msmtp\-mta \-\-install exim4\-daemon\-light esmtp\fR

Install packages \fBexim4\-daemon\-light\fR and \fBesmtp\fR, remove the package
\fBmsmtp\-mta\fR.

.IP \(bu 3
\fBcupt install exim4\-daemon\-light \-\-remove msmtp\-mta esmtp\fR

Install the package \fBexim4\-daemon\-light\fR, remove packages \fBmsmtp\-mta\fR and \fBesmtp\fR.

.IP \(bu 3
\fBcupt purge libkate1 \-\-remove libass4 \-\-purge libdirac\-decoder0\fR

Remove the package \fBlibass4\fR, purge packages \fBlibkate1\fR and \fBlibdirac\-decoder0\fR.

.IP \(bu 3
\fBcupt install lightspark \-\-remove gnash \-\-satisfy "iceweasel (>= 5)"\fR

Install the package \fBlightspark\fR, remove the packae \fBgnash\fR, and make sure that
\fBiceweasel\fR (at least of version \fB5\fR) is installed.

.IP \(bu 3
\fBcupt install sieve\-connect \-\-unsatisfy "iceweasel (<< 3.5.20)"\fR

Install the package \fBsieve\-connect\fR, upgrade or remove the package \fBiceweasel\fR
if it is installed and has the version lower than \fB3.5.20\fR.

.IP \(bu 3
\fBcupt install libv4l\-0 cupt \-\-iii libreadline7 vlc*\fR

Install packages \fBlibv4l\-0\fR and \fBcupt\fR, install the preferred version of
\fBlibreadline7\fR if it's installed already, install the preferred versions of
packages which names start with \fBvlc\fR and which are installed already .

.IP \(bu 3
\fBcupt remove youtube\-dl \-\-install clive \-\-satisfy "iceweasel (>= 4)" \-\-purge cvs subversion \-\-install git \-\-unsatisfy "xinput (<< 1.5)"\fR

Install packages \fBclive\fR and \fBgit\fR, remove the package
\fByoutube\-dl\fR, purge packages \fBcvs\fR and \fBsubversion\fR, make sure that the package
\fBiceweasel\fR of version 4 or higher is installed, make sure that the package
\fBxinput\fR either is not installed or has the version \fB1.5\fR or higher.

.IP \(bu 3
\fBcupt install vlc \-\-markauto xine\fR

Install the package \fBvlc\fR and mark the package \fBxine\fR automatically installed.

.IP \(bu 3
\fBcupt remove bindfs \-\-unmarkauto fuse\fR

You have a package \fBbindfs\fR installed and now don't need it anymore.
\fBcupt remove bindfs\fR shows that the package \fBfuse\fR will be removed as it was a
dependency of \fBbindfs\fR; you however decide you want to keep it in the system
and run the command above.

.IP \(bu 3
\fBcupt install mumble libgeoip1 geoip\-dbg\fR

(in this and following examples we suppose that currently \fBmumble\fR is
manually installed, \fBlibgeoip1\fR is automatically installed, \fBgeoip\-dbg\fR is
not installed)

\fBgeoip\-dbg\fR will be manually installed.

.IP \(bu 3
\fBcupt install \-\-asauto=yes mumble libgeoip1 geoip\-dbg\fR

\fBmumble\fR will be marked as automatically installed, \fBgeoip\-dbg\fR will be automatically installed

.IP \(bu 3
\fBcupt install \-\-asauto=no mumble libgeoip1 geoip\-dbg\fR

\fBlibgeoip1\fR will be marked as manually installed, \fBgeoip\-dbg\fR will be manually installed

.IP \(bu 3
\fBcupt install \-\-asauto=yes mumble \-\-asauto=default libgeoip1 geoip\-dbg\fR

\fBmumble\fR will be marked as automatically installed, \fBgeoip\-dbg\fR will be manually installed

.IP \(bu 3
\fBcupt satisfy \-\-asauto=no "iptables (>= 1.4)"\fR

(assuming \fBiptables\fR package not installed) if possible, install enough
recent (\fB1.4\fR or later) version of \fBiptables\fR; \fBiptables\fR itself will be
marked as manually installed, its possible dependencies as automatically
installed
.RE

.SS Package name suffixes

.P
Alternatively, you can supply some suffixes to package names, that suffixes override the current action for the suffixed package(s) only:

.TP
+

"install this"

.TP
\-

"remove this"

.P
You can use the \fB+\fR modifier in subcommands: \fBremove\fR, \fBpurge\fR. Examples:

.P
\fBcupt remove youtube\-dl clive+\fR: remove \fByoutube\-dl\fR, install \fBclive\fR

.P
\fBcupt purge exim4 msmtp\-mta+ mutt/experimental+\fR: remove \fBexim4\fR along with
its configuration files, install \fBmsmtp\-mta\fR and \fBmutt\fR (from experimental)

.P
You can use the \fB\-\fR modifier in the \fBinstall\fR and \fB*\-upgrade\fR\-like subcommands. Examples:

.P
\fBcupt install gnuchess/unstable gnome\-chess pychess\-\fR: install \fBgnuchess\fR
(from \fBunstable\fR), \fBgnome\-chess\fR, remove \fBpychess\fR

.P
\fBcupt full\-upgrade cvs\-\fR:

.P
a) \fBcvs\fR is installed \-> do an upgrade with removing \fBcvs\fR

.P
b) \fBcvs\fR is not installed \-> do an upgrade, keeping \fBcvs\fR uninstalled

.SS Using package archive deltas

.P
Cupt has an integration (through a special download method) with
\fIdebdelta(1)\fR. To make Cupt try to download archive deltas before downloading
full archives, just install the package \fBdebdelta\fR and that's it. No manual
invocation of debdelta utilities is needed.

.P
See more about debdelta project here: http://debdelta.debian.net/.

.SS Listing dependency information

.P
To list the dependencies of one or more package versions, use the subcommand \fBdepends\fR:

.P
\fBcupt depends libc6/testing arora/unstable\fR

.P
If you don't want to see Recommends there, use \fB\-\-important\fR:

.P
\fBcupt depends \-\-important libc6/testing\fR

.P
If, on the contrary, you want to see even Suggests, use \fB\-\-with\-suggests\fR:

.P
\fBcupt depends \-\-with\-suggests libc6/testing\fR

.P
You can also list selected relations recursively, using \fB\-\-recurse\fR:

.P
\fBcupt depends \-\-recurse dpkg\fR

.P
If you want to see a \fBreverse\fR dependencies of some version, use the subcommand \fBrdepends\fR:

.P
\fBcupt rdepends xz\-utils\fR

.P
All the command switches described here are also applicable to \fBrdepends\fR as well.

.SS Action preview prompt (extended)

.SS summary

.P
Starting with Cupt 2.3 an action summary is shown by default.

.P
To remove it, use \fB\-\-no\-summary\fR command\-line option. To remove it
permanently, set the configuration option
\fBcupt::console::actions\-preview::show\-summary\fR to \fBno\fR.

.P
Alternatively, you may want to hide details and view only a summary, this can
be achieved by specifying \fB\-\-summary\-only\fR command\-line option. This option
can be useful in a conjunction with \fB\-\-simulate\fR command\-line option to have
a quick preview.

.SS detailed solution preview

.P
You can request more information to show in the action preview prompt:

.RS
.IP \(bu 3
package versions

Use \fB\-\-show\-versions\fR (\fB\-V\fR) option. Example:

.nf
 $ cupt install gcc-4.6 -V
 
 The following packages will be installed:
 
 cpp-4.6 [4.6.0~rc1-1]
 gcc-4.6 [4.6.0~rc1-1]
 gcc-4.6-base [4.6.0~rc1-1]
 libppl-c4 [0.11.2-3]
 libppl9 [0.11.2-3]
 libpwl5 [0.11.2-3]
 libquadmath0 [4.6.0~rc1-1]
 
 The following packages will be upgraded:
 
 binutils [2.20.1-15 -> 2.21.0.20110302-2]
 libcloog-ppl0 [0.15.9-2 -> 0.15.9-3]
 libgcc1 [1:4.5.2-1 -> 1:4.6.0~rc1-1]
 libgomp1 [4.5.2-1 -> 4.6.0~rc1-1]
.fi



.IP \(bu 3
by\-package disk usage changes

Use \fB\-\-show\-size\-changes\fR (\fB\-Z\fR) option. Example:

.nf
 $ cupt install gcc-4.6 -Z

 The following packages will be installed:
 
 cpp-4.6 <+10.6MiB>
 gcc-4.6 <+15.0MiB>
 gcc-4.6-base <+192KiB>
 libppl-c4 <+4264KiB>  
 libppl9 <+1176KiB>    
 libpwl5 <+100KiB>     
 libquadmath0 <+496KiB>
 
 The following packages will be upgraded:
 
 binutils <+1300KiB>
 libcloog-ppl0
 libgcc1 <+8192B>
 libgomp1 <+16.0KiB>
.fi



.IP \(bu 3
release archives

Use \fB\-\-show\-archives\fR (\fB\-A\fR) option. Example:

.nf
 $ cupt install gcc-4.7 -A
 
 The following packages will be installed:
 
 cpp-4.7 [(experimental)]
 gcc-4.7 [(experimental)]
 gcc-4.7-base [(experimental)]
 libitm1 [(experimental)]
 
 The following packages will be upgraded:
 
 libgcc1 [(installed,testing) -> (experimental)]
 libgomp1 [(installed,testing) -> (experimental)]
 libquadmath0 [(installed,testing) -> (experimental)]
.fi



.IP \(bu 3
release codenames

Use \fB\-\-show\-codenames\fR (\fB\-N\fR) option. Example:

.nf
 $ cupt install libstreams0 -N
 
 The following packages will be upgraded:
 
 libstreamanalyzer0 [(now,squeeze) -> (wheezy,sid)]
 libstreams0 [(now,squeeze) -> (wheezy,sid)]
.fi



.IP \(bu 3
release components

Use \fB\-\-show\-components\fR (\fB\-C\fR) option. It's mostly useful in conjunction
with \fB\-\-show\-codenames\fR or \fB\-\-show\-archives\fR. Example:

.nf
 $ cupt install libstreams0 -CN
 
 The following packages will be upgraded:
 
 libstreamanalyzer0 [(now,squeeze/main) -> (wheezy/main,sid/main)]
 libstreams0 [(now,squeeze/main) -> (wheezy/main,sid/main)]
.fi



.IP \(bu 3
release vendors

Use \fB\-\-show\-vendors\fR (\fB\-O\fR) option. Useful if you have repositories of more
than one vendor and usually in conjunction with \fB\-V\fR, \fB\-A\fR or \fB\-N\fR. Example:

.nf
 $ cupt install libstreams0 -VNO
 
 The following packages will be upgraded:
 
 libstreamanalyzer0 [0.7.2-1+b1(dpkg:now,Debian:squeeze) -> 0.7.7-1(Debian:wheezy,Debian:sid)]
 libstreams0 [0.7.2-1+b1(dpkg:now,Debian:squeeze) -> 0.7.7-1(Debian:wheezy,Debian:sid)]
.fi



.IP \(bu 3
change reasons

To show, why resolver did the change(s), use \fB\-\-show\-reasons\fR (\fB\-D\fR) option.
Example:

.nf
 $ cupt install gcc-4.6 -D
 
 The following packages will be installed:
 
 cpp-4.6
   reason: gcc-4.6 4.6.0~rc1-1 depends on 'cpp-4.6 (= 4.6.0~rc1-1)'
 
 gcc-4.6
   reason: user request
 
 gcc-4.6-base
   reason: cpp-4.6 4.6.0~rc1-1 depends on 'gcc-4.6-base (= 4.6.0~rc1-1)'
 
 libppl-c4
   reason: gcc-4.6 4.6.0~rc1-1 depends on 'libppl-c4'
 
 libppl9
   reason: gcc-4.6 4.6.0~rc1-1 depends on 'libppl9'
 
 libpwl5
   reason: libppl-c4 0.11.2-3 depends on 'libpwl5'
 
 libquadmath0
   reason: gcc-4.6 4.6.0~rc1-1 depends on 'libquadmath0 (>= 4.6.0~rc1-1)'
 
 
 The following packages will be upgraded:
 
 binutils
   reason: gcc-4.6 4.6.0~rc1-1 depends on 'binutils (>= 2.21~)'
 
 libcloog-ppl0
   reason: gcc-4.6 4.6.0~rc1-1 depends on 'libcloog-ppl0 (>= 0.15.9-3~)'
 
 libgcc1
   reason: gcc-4.6 4.6.0~rc1-1 depends on 'libgcc1 (>= 1:4.6.0~rc1-1)'
 
 libgomp1
   reason: gcc-4.6 4.6.0~rc1-1 depends on 'libgomp1 (>= 4.6.0~rc1-1)'
.fi



.IP \(bu 3
show not preferred versions

To show packages which will have a not preferred version (which usually means
not (enough) upgraded), use \fB\-\-show\-not\-preferred\fR option.

This is enabled for upgrades by default.

For non\-upgrade example, the next command may be used to determine the
installed packages which have a better candidate (again, usually that means
they can be upgraded):

.nf
 $ cupt install --no-auto-remove --show-not-preferred -V
 
 The following packages will have a not preferred version:
 
 comerr-dev [2.1-1.41.12-4], preferred: 2.1-1.41.12-4stable1
 e2fslibs [1.41.12-4], preferred: 1.41.12-4stable1
 e2fsprogs [1.41.12-4], preferred: 1.41.12-4stable1
 libcomerr2 [1.41.12-4], preferred: 1.41.12-4stable1
 libkadm5clnt-mit7 [1.8.3+dfsg-4], preferred: 1.8.3+dfsg-4squeeze2
 libkadm5srv-mit7 [1.8.3+dfsg-4], preferred: 1.8.3+dfsg-4squeeze2
 libkdb5-4 [1.8.3+dfsg-4], preferred: 1.8.3+dfsg-4squeeze2
 libss2 [1.41.12-4], preferred: 1.41.12-4stable1
 linux-image-2.6.32-5-amd64 [2.6.32-34squeeze1], preferred: 2.6.32-38
 openssh-client [1:5.5p1-6], preferred: 1:5.5p1-6+squeeze1
 tzdata [2011g-1], preferred: 2011k-0squeeze1
 
.fi


.RE

.P
You can also combine them.

.SS reason chain

.P
Instead of displaying the reasons for all changed packages, starting with Cupt 2.6
you can request the reason chain for the specific package. To do this, use the choice \fBrc\fR. Example:

.nf
 $ cupt -s install exim4-daemon-light
 
 The following packages will be installed:
 
 bsd-mailx exim4-base exim4-config exim4-daemon-light liblockfile-bin liblockfile1 
 
 The following packages will be removed:
 
 msmtp-mta 
 
 The following packages are no longer needed and thus will be auto-removed:
 
 libgsasl7 libntlm0 msmtp 
 
 Action summary:
   1 manually installed and 5 automatically installed packages will be installed
   1 manually installed packages will be removed
   3 automatically installed packages are no longer needed and thus will be auto-removed
 
 Need to get 2241KiB/2241KiB of archives. After unpacking 3006KiB will be used.
 Do you want to continue? [y/N/q/a/rc/?] rc
 Enter a binary package name to show reason chain for (empty to cancel): bsd-mailx
 
 bsd-mailx: exim4-base 4.80-6 recommends 'mailx'
   exim4-base: exim4-daemon-light 4.80-6 depends on 'exim4-base (>= 4.80)'
     exim4-daemon-light: user request
 
 Do you want to continue? [y/N/q/a/rc/?] rc
 Enter a binary package name to show reason chain for (empty to cancel): msmtp-mta
 
 msmtp-mta: exim4-daemon-light 4.80-6 conflicts with 'mail-transport-agent'
   exim4-daemon-light: user request
 
 Do you want to continue? [y/N/q/a/rc/?]
.fi


.SS specifying more package expression arguments

.P
In a solution preview (action preview prompt) you have an ability to specify
more package expressions and a restart a resolving process. To do this, use the
choice \fBa\fR. Example:

.nf
 $ cupt install gnash
 
 The following packages will be installed:
 
 dmsetup dosfstools freepats fuse-utils gconf2-common gnash gnash-common
 gstreamer0.10-ffmpeg gstreamer0.10-fluendo-mp3 gstreamer0.10-plugins-bad
 gstreamer0.10-plugins-base gvfs hdparm libass4 libatasmart4
 libboost-thread1.42.0 libcdaudio1 libcelt0-0 libexempi3 libexif12 libfftw3-3
 libflite1 libfuse2 libgconf2-4 libgdu0 libgme0 libgnome-keyring0 libgsf-1-114
 libgsf-1-common libgtkglext1 libgudev-1.0-0 libidl0 libiptcdata0 libkate1
 liblvm2app2.2 libmimic0 libmms0 libmodplug1 libmusicbrainz4c2a libntfs-3g75
 libntfs10 libofa0 libopenspc0 liborbit2 liborc-0.4-0 libparted0debian1
 libpolkit-backend-1-0 libraptor2-0 librasqal3 librsvg2-2 libsgutils2-2
 libslv2-9 libsoundtouch0 libvisual-0.4-0 libvisual-0.4-plugins libwildmidi1
 libyajl1 libzbar0 mtools ntfs-3g ntfsprogs policykit-1 policykit-1-gnome udisks
 
 The following packages will be upgraded:
 
 libblkid1 libdbus-glib-1-2 libdevmapper1.02.1 libglib2.0-0
 libgstreamer-plugins-base0.10-0 libgstreamer0.10-0 libpcre3 libpolkit-agent-1-0
 libpolkit-gobject-1-0 librdf0 libschroedinger-1.0-0 libudev0
 
 The following packages will be removed:
 
 libeggdbus-1-0(a) librasqal2(a)
 
 Need to get 62.3MiB/62.3MiB of archives. After unpacking 105MiB will be used.
 Do you want to continue? [y/N/q/a/?] a
 Enter a package expression (empty to finish): libgnome-keyring0-
 Enter a package expression (empty to finish):
 
 The following packages will be installed:
 
 freepats gnash gnash-common gstreamer0.10-ffmpeg gstreamer0.10-fluendo-mp3
 gstreamer0.10-plugins-bad gstreamer0.10-plugins-base libass4
 libboost-thread1.42.0 libcdaudio1 libcelt0-0 libexempi3 libexif12 libfftw3-3
 libflite1 libgme0 libgsf-1-114 libgsf-1-common libgtkglext1 libgudev-1.0-0
 libiptcdata0 libkate1 libmimic0 libmms0 libmodplug1 libmusicbrainz4c2a libofa0
 libopenspc0 liborc-0.4-0 libraptor2-0 librasqal3 librsvg2-2 libslv2-9
 libsoundtouch0 libvisual-0.4-0 libvisual-0.4-plugins libwildmidi1 libyajl1
 libzbar0
 
 The following packages will be upgraded:
 
 libglib2.0-0 libgstreamer-plugins-base0.10-0 libgstreamer0.10-0 libpcre3
 librdf0 libschroedinger-1.0-0 libudev0
 
 The following packages will be removed:
 
 librasqal2(a)
 
 Leave the following dependencies unresolved:
 
 gstreamer0.10-plugins-base 0.10.30-1 recommends 'gvfs'
 
 Need to get 56.2MiB/56.2MiB of archives. After unpacking 85.6MiB will be used.
 Do you want to continue? [y/N/q/a/?]
.fi


.P
The effect above is the same as if you specified

.P
\fBcupt install gnash libgnome\-keyring0\-\fR

.P
in the command line from the start.

.P
Starting from Cupt 2.6 you can specify multiple expressions on the same line.

.SS colors

.P
Some parts of the actions preview will be colored if you enable colors by
setting the option \fBcupt::console::use\-colors\fR to \fBauto\fR or \fByes\fR (see
\fIcupt.conf(5)\fR).

.P
In the colored output different colors specify different actions types.
Manually installed package names and potentially unsafe actions have bold
colors.

.SS Adjusting configuration variables

.SS intro

.P
There are two types of configuration variables \- \fBregular\fR (or \fBscalar\fR) and
\fBlist\fR ones.  Scalar options have a single scalar value, and list option's
value is a list of strings. Modifying a scalar option means substituting its
previous value completely in favor of new specified one, modifying a list
option means adding one more string to the existing list.

.P
Cupt has many configuration variables, some of them may be specified/overridden
using command\-line switches, some needs to be modified explicitly. See the full
variable list and descriptions at \fIcupt.conf(5)\fR.

.P
To see the current configuration, use \fBconfig\-dump\fR subcommand. Examples:

.nf
 $ cupt config-dump | grep recommends
 apt::install-recommends "yes";
 cupt::resolver::keep-recommends "yes";
 cupt::resolver::tune-score::failed-recommends "600";
.fi


.nf
 $ cupt config-dump | grep "methods "
 cupt::downloader::protocols::copy::methods { "file"; };
 cupt::downloader::protocols::debdelta::methods { "debdelta"; };
 cupt::downloader::protocols::file::methods { "file"; };
 cupt::downloader::protocols::ftp::methods { "curl"; };
 cupt::downloader::protocols::ftp::methods { "wget"; };
 cupt::downloader::protocols::http::methods { "curl"; };
 cupt::downloader::protocols::http::methods { "wget"; };
 cupt::downloader::protocols::https::methods { "curl"; };
 cupt::downloader::protocols::https::methods { "wget"; };
.fi


.P
You can distinguish list options there by figure brackets around the values.

.SS configuration sources

.P
Cupt reads configuration in the following order:

.RS
.IP 1. 3
from Cupt preconfiguration file (see \fIcupt.conf(5)/cupt::directory::configuration::pre\fR)

.IP 2. 3
from APT configuration files (conforming to the APT documentation (\fIapt.conf(5)\fR))

.IP 3. 3
from Cupt\-specific configuration files (see \fIcupt.conf(5)/cupt::directory::configuration\fR)

.IP 4. 3
from the command line (\fB\-\-option\fR (or \fB\-o\fR) switches and dedicated switches corresponding to specific options)
.RE

.SS setting options using the command line

.P
To modify a regular option in the command line, use

.P
\fB\-o\fR \fIoption_name\fR\fB=\fR\fInew_value\fR

.P
Example:

.P
\fBcupt install kmail \-o cupt::console::assume\-yes=yes\fR

.P
To modify a list option (i.e. add a new string) in the command line, use

.P
\fB\-o\fR \fIoption_name\fR\fB::=\fR\fIadded_string\fR

.P
Example:

.P
\fBcupt \-s update \-o "apt::update::pre\-invoke::=ls /var"\fR

.P
You can use \fB\-o\fR multiple times.

.SS Automatically installed packages

.SS view

.P
If you want to know, is a certain package automatically installed or not, do

.P
\fBcupt show \-\-installed\-only\fR \fIpackage_name\fR

.P
Example:

.P
\fBcupt show \-\-installed\-only dpkg\fR

.P
To list manually installed packages:

.P
\fBcupt showauto \-\-invert\fR

.P
To list automatically installed packages:

.P
\fBcupt showauto\fR

.SS change

.P
To mark some package(s) as automatically installed, use the \fBmarkauto\fR subcommand, for example:

.P
\fBcupt markauto libqtcore4 udev\fR

.P
To mark some package(s) as manually installed, use the \fBunmarkauto\fR subcommand, for example:

.P
\fBcupt unmarkauto tar traceroute\fR

.SS removal

.P
When doing installs/upgrades/etc. all newly installed packages not requested by
user are marked as automatically installed. For every package management
actions Cupt's resolver can determine if some automatically installed packages
are not needed anymore. Automatically installed packages, which are no more a
part of any valuable dependency chain of manually installed packages, are
deleted by default. The names of this process is \fBauto\-removal\fR.

.P
If you don't want auto\-removal to be performed, use \fB\-\-no\-auto\-remove\fR switch
or set the option \fBcupt::resolver::auto\-remove\fR to \fBno\fR.

.SS Soft dependencies

.P
All forward interdependencies between packages can be divided into two groups
\-\- \fBhard\fR and \fBsoft\fR ones. While hard dependencies must be satisfied in order
to make a system (or proposed solution) valid, soft ones may stay unsatisfied.
Hard dependencies are 'Pre\-Depends', 'Depends'. Soft dependencies are
\&'Recommends', 'Suggests' and 'Enhances'. Cupt completely ignores 'Enhances',
but can act on 'Recommends' or 'Suggests'. All the remainder of this section is
dedicated to the last two.

.P
By default, Cupt ignores 'Suggests', but tries to, with an average priority,
satisfy new dependencies in 'Recommends' and keep already satisfied
\&'Recommends'.

.P
You can use the following options to change the behavior:

.TP
apt::install\-recommends

set this to \fBno\fR to not satisfy new 'Recommends'. See also the command\-line
switch \fB\-\-no\-install\-recommends\fR.

.TP
cupt::resolver::keep\-recommends

set this to \fBno\fR to make resolver ignore all 'Recommends'

.TP
apt::install\-suggests

set this \fByes\fR to make resolver try to satisfy new 'Suggests'

.TP
cupt::resolver::keep\-suggests

set this to \fByes\fR to make resolver try to keep already satisfied 'Suggests'

.P
Note 1: having the option \fBapt::install\-\fR\fIX\fR set to \fByes\fR without
\fBcupt::resolver::keep\-\fR\fIX\fR set to \fByes\fR as well is useless, Cupt's native
resolver will warn about it.

.P
Note 2: even when the appropriate \fBapt::install\-\fR\fIX\fR option is set, Cupt
ignores not changed soft dependencies.  Say, if there is an installed package
\fBgettext\fR of version \fB1.2\fR which \fBRecommends: cvs\fR, a relation \fBcvs\fR is not
satisfied in the system, and \fBgettext\fR is upgraded to a version \fB1.3\fR which also
have the same \fBRecommends: cvs\fR, Cupt won't try to satisfy this dependency.

.SS Understanding package installation process

.P
After you agree with a proposed solution (by entering a positive answer in an
action preview prompt) Cupt starts a package
installation process, which is done in several phases:

.RS
.IP 1. 3
preparation

In this phase Cupt computes the order in which \fIdpkg(1)\fR will called and the
options to pass. This phase may take a while for large changes.

.IP 2. 3
downloading

In this phase Cupt downloads needed binary packages (\fB*.deb\fR). May be empty
if no packages are needed or all needed packages are already in the cache.

.IP 3. 3
pre\-hooks

In this phase Cupt calls registered pre\-hooks (options \fBdpkg::pre\-invoke\fR and
\fBdpkg::pre\-install\-pkgs\fR) if any. Examples of them are \fIapt\-listchanges(1)\fR,
\fIapt\-listbugs(1)\fR and \fIdpkg\-preconfigure(1)\fR.  These hooks may ask questions
and cancel the whole package installation process.

.IP 4. 3
action themselves

In this phase Cupt calls dpkg as many times as needed to perform requested
actions.

.IP 5. 3
post\-hooks

In this phase Cupt calls registered post\-hooks (the option
\fBdpkg::post\-invoke\fR) if any.
.RE

.P
Note: Cupt itself does not ask anything from the user during the package
installation process. All questions usually come from programs which Cupt
calls.

.P
Example:

.nf
 1: # cupt install cmake
.fi


.P
This is a command line.

.nf
 2: Building the package cache...
 3: Initializing package resolver and worker...
 4: Scheduling requested actions...
 5: Resolving possible unmet dependencies...
.fi


.P
These are (optional) information messages from Cupt.

.nf
 6:
 7: The following 4 packages will be INSTALLED:
 8:
 9: libarchive1 libcurl3 libssh2-1 libxmlrpc-core-c3
 10:
 11: The following 2 packages will be UPGRADED:
 12:
 13: cmake cmake-data
 14:
 15: Need to get 5637KiB/6007KiB of archives. After unpacking 1963KiB will be freed.
 16: Do you want to continue? [y/N/q/a/?] y
.fi


.P
This is an action preview prompt.

.nf
 17: Performing requested actions:
.fi


.P
This is the 'preparation' phase.

.nf
 18: Get:1 http://ftp.fi.debian.org/debian wheezy/main,sid/main,wheezy/main,sid/main cmake-data 2.8.4+dfsg.1-2 [1224KiB]
 19: Get:2 http://ftp.fi.debian.org/debian wheezy/main,sid/main,wheezy/main,sid/main cmake 2.8.4+dfsg.1-2 [4102KiB]
 20: Get:3 http://ftp.fi.debian.org/debian wheezy/main,sid/main,wheezy/main,sid/main libarchive1 2.8.4-1 [149KiB]
 21: Get:4 http://ftp.fi.debian.org/debian wheezy/main,sid/main,wheezy/main,sid/main libxmlrpc-core-c3 1.16.33-2 [162KiB]
 22: Fetched 5637KiB in 1s.
.fi


.P
This is the 'downloading' phase.

.nf
 23: Reading changelogs... Done
.fi


.P
This is the 'pre\-hooks' phase (namely, apt\-listchanges in this case).

.nf
 24: Selecting previously deselected package libarchive1.
 25: (Reading database ... 94022 files and directories currently installed.)
 26: Unpacking libarchive1 (from .../libarchive1_2.8.4-1_i386.deb) ...
 27: Setting up libarchive1 (2.8.4-1) ...
 28: Processing triggers for man-db ...
 29: Selecting previously deselected package libssh2-1.
 30: (Reading database ... 94034 files and directories currently installed.)
 31: Unpacking libssh2-1 (from .../libssh2-1_1.2.6-1_i386.deb) ...
 32: Setting up libssh2-1 (1.2.6-1) ...
 33: Selecting previously deselected package libcurl3.
 34: (Reading database ... 94041 files and directories currently installed.)
 35: Unpacking libcurl3 (from .../libcurl3_7.21.3-1_i386.deb) ...
 36: Setting up libcurl3 (7.21.3-1) ...
 37: Selecting previously deselected package libxmlrpc-core-c3.
 38: (Reading database ... 94058 files and directories currently installed.)
 39: Unpacking libxmlrpc-core-c3 (from .../libxmlrpc-core-c3_1.16.33-2_i386.deb) ...
 40: Setting up libxmlrpc-core-c3 (1.16.33-2) ...
 41: (Reading database ... 94080 files and directories currently installed.)
 42: Removing cmake ...
 43: Processing triggers for man-db ...
 44: (Reading database ... 94071 files and directories currently installed.)
 45: Preparing to replace cmake-data 2.8.1-2 (using .../cmake-data_2.8.4+dfsg.1-2_all.deb) ...
 46: Unpacking replacement cmake-data ...
 47: Setting up cmake-data (2.8.4+dfsg.1-2) ...
 48: emacsen-common: Handling install of emacsen flavor emacs
 49: Processing triggers for man-db ...
 50: Selecting previously deselected package cmake.
 51: (Reading database ... 94087 files and directories currently installed.)
 52: Unpacking cmake (from .../cmake_2.8.4+dfsg.1-2_i386.deb) ...
 53: Setting up cmake (2.8.4+dfsg.1-2) ...
 54: Processing triggers for man-db ...
.fi


.P
This is the 'action themselves' phase, dpkg's output and messages from packages' maintainer scripts.

.P
In the case the process fails at phase 'action themselves' (either due to bug
in Cupt, dpkg, or packages), you'll see some error messages from dpkg and then
error messages from Cupt.

.SS Source packages

.SS overview

.P
Source packages are the files from which binary packages are built. They have two major differences:

.RS
.IP \(bu 3
Source packages cannot be "installed" to the system like binary packages.

.IP \(bu 3
Unlike binary packages, source package consists of 3 or more files, not a single one:

.RS
.IP \(bu 3
tarball(s)

one or more compressed \fItar(1)\fR archives containing an upstream code

.IP \(bu 3
diff

a file containing Debian changes, may be missing in the \fBnative\fR (Debian\-specific) packages

.IP \(bu 3
dsc

a text file with some headers
.RE
.RE

.SS exploring

.P
To view a source package information:

.P
\fBcupt showsrc\fR \fIpackage_name\fR

.P
Example:

.P
\fBcupt showsrc cupt\fR

.P
You can specify more than one package, for example:

.P
\fBcupt showsrc sed mawk\fR

.P
To view available source versions, pin info and releases versions come from,
use \fBpolicysrc\fR subcommand. Its output is the same as for policy
subcommand. Example:

.P
\fBcupt policysrc sed mawk\fR

.P
To download source package(s), use the \fBsource\fR subcommand, for example:

.P
\fBcupt source clive youtube\-dl\fR

.P
By default \fBsource\fR subcommand also unpack the package so it's ready for the
exploring and building. To prevent this, use the \fB\-\-download\-only\fR switch.
Also, you can download only one part of source package, use switches
\fB\-\-tar\-only\fR, \fB\-\-diff\-only\fR and \fB\-\-dsc\-only\fR for that.

.SS satisfying build dependencies

.P
If you want to build binary packages out of a source one, you will have to
satisfy source package's build dependencies before. Use the subcommand
\fBbuild\-dep\fR to do it, for example:

.P
\fBcupt build\-dep clive\fR

.P
All new packages, installed by this subcommand, will be marked as
automatically installed, and will be a
subject for auto\-removal (#auto\-removal) at next package management action.

.P
So, the process of building binary packages out of source one may be, taking
\fBclive\fR package as an example:

.nf
 cupt source clive
 cupt build-dep clive
 cd clive-2.2.13 && debuild && cd ../
 [...]
 cupt install
.fi


.P
The last line will remove all unneeded anymore packages (given auto\-removal is
turned on), including those installed by \fBbuild\-dep\fR.

.SS selecting source package versions

.P
You can select source package versions in two ways:

.RS
.IP 1. 3
Provide a \fBsource package version expression\fR. It has the same syntax as
binary package version expression, but
instead of specifying a binary package name you specify a source package name.

Example:

\fBcupt showsrc game\-music\-emu=0.5.5\-2 gcc\-defaults/experimental\fR

.IP 2. 3
Provide a binary package version expression, which will be converted to a
source package version expression when possible.

Example:

.nf
 $ cupt show g++/experimental | head -n5
 Package: g++
 Version: 4:4.6.0-2exp1
 Status: not installed
 Source: gcc-defaults
 Source version: 1.101exp1
 $ cupt showsrc g++/experimental | head -n3
 Package: gcc-defaults
 Binary: cpp, g++, g++-multilib, gobjc, gobjc-multilib, gobjc++,
 gobjc++-multilib, gfortran, gfortran-multilib, gccgo, gccgo-multilib,
 libgcj-common, gcj, gij, libgcj-bc, gcj-jdk, gcj-jre-headless, gcj-jre, gcc,
 gcc-multilib, gdc, gcc-spu, g++-spu, gfortran-spu
 Version: 1.101exp1
.fi



Here, \fBg++\fR is a binary package name and \fBgcc\-defaults\fR is a source package
name. In the second command, as there is no source package \fBg++\fR, a binary
package was looked up, a version \fB4:4.6.0\-2exp1\fR of it was found, and then a
source version was selected as if you specified

\fBcupt showsrc gcc\-defaults=1.101exp1\fR

in the first place.
.RE

.P
You can supply both syntaxes to all subcommands which work with source
package versions, examples:

.P
\fBcupt build\-dep clive/unstable\fR

.P
\fBcupt source man\-db=2.5.9\-4\fR

.SS Package manager shell

.P
Cupt has a shell\-like environment, in which you can supply any subcommand as if
you typed it in to the command line, but without preceding cupt command name.

.P
Example:

.nf
 $ cupt shell
 This is interactive shell of cupt package manager.
 cupt>policy libsoprano4
 libsoprano4:
   Installed: 2.2.2+dfsg.1-1
   Preferred: 2.3.0+dfsg.1-2
   Version table:
      2.3.0+dfsg.1-2 501
        http://debian.org.ua/debian unstable/main (signed)
  *** 2.2.2+dfsg.1-1 100
        /var/lib/dpkg/status installed/ (unsigned)
      2.3.0+dfsg.1-1 2
        http://debian.org.ua/debian experimental/main (signed)
 cupt>depends libsoprano4/experimental
 libsoprano4 2.3.0+dfsg.1-1:
   Depends: libc6 (>= 2.2.5)
   Depends: libclucene0ldbl (>= 0.9.20-1)
   Depends: libgcc1 (>= 1:4.1.1)
   Depends: libqt4-dbus (>= 4:4.5.2)
   Depends: libqt4-network (>= 4:4.5.2)
   Depends: libqt4-xml (>= 4:4.5.2)
   Depends: libqtcore4 (>= 4:4.5.2)
   Depends: libstdc++6 (>= 4.1.1)
   Depends: soprano-daemon (= 2.3.0+dfsg.1-1)
 cupt>rdepends soprano-daemon
 soprano-daemon 2.3.0+dfsg.1-2:
   Reverse-Depends: libsoprano4 2.3.0+dfsg.1-2: soprano-daemon (= 2.3.0+dfsg.1-2)
 cupt>show soprano-daemon
 Package: soprano-daemon
 Version: 2.3.0+dfsg.1-2
 Status: not installed
 Source: soprano
 Priority: optional
 Section: utils
 Size: 153KiB
 Uncompressed size: 536KiB
 Maintainer: Debian Qt/KDE Maintainers <debian-qt-kde@lists.debian.org>
 Architecture: amd64
 Depends: libc6 (>= 2.2.5), libgcc1 (>= 1:4.1.1), libqt4-dbus (>= 4:4.5.2), libqt4-network (>= 4:4.5.2),
 libqtcore4 (>= 4:4.5.2), libraptor1 (>= 1.4.18), librdf0 (>= 1.0.9), libsoprano4 (>= 2.3.0), libstdc++6 (>= 4.1.1)
 Conflicts: libsoprano-dev (<< 2.3.0+dfsg.1-1), libsoprano4 (<< 2.3.0+dfsg.1-1)
 Replaces: libsoprano-dev (<< 2.3.0+dfsg.1-1), libsoprano4 (<< 2.3.0+dfsg.1-1)
 URI: http://debian.org.ua/debian/pool/main/s/soprano/soprano-daemon_2.3.0+dfsg.1-2_amd64.deb
 MD5: af29b39a741d9a52de91c8e5562e0609
 SHA1: 1dfebe27b79f10911358949e56f89c64b43265eb
 SHA256: d5b290a60de56f6a7e0af44f5265c6668bb4689204556b9022a5233a808349fc
 Description: daemon for the Soprano RDF framework
  Soprano is a pluggable RDF storage, parsing, and serialization framework based
  on Qt 4. Soprano is targeted at desktop applications that need to store RDF
  data. Its API has been optimized for simplicity and ease of use, while its
  modular structure allows it to use various different RDF storage
  implementations as its backend.
  .
  This package contains the Soprano daemon, D-Bus service, parser
  plugins, and a storage plugin for the Redland RDF Application Framework.
 Homepage: http://soprano.sourceforge.net

 cupt>--simulate install libsoprano4

 The following 1 packages will be INSTALLED:

 soprano-daemon 

 The following 1 packages will be UPGRADED:

 libsoprano4 

 Need to get 700KiB/700KiB of archives. After unpacking 196KiB will be used.
 Do you want to continue? [y/N/q] q

 cupt>exit
.fi


.P
What this mode may be useful for:

.RS
.IP \(bu 3
fast queries

When entering shell mode, the configuration is read and cache is built. Until
some management subcommand is executed, query subcommands don't have to re\-read
the configuration and cache on each invocation, and most of them execute
instantly in shell mode.

.IP \(bu 3
common configuration changes

As the \fBshell\fR subcommand, as all others, recognizes \fIcupt(1)/Common options\fR,
you can use that to set some configuration options for all the shell session.

Example:

\fBcupt shell \-\-simulate \-o apt::install\-recommends=no\fR

Installing new recommends will be switched off for all the session inside the
shell, and no real actions will be performed for subcommands that change the
system. Note that you can override them (by supplying \fB\-o cupt::worker::simulate=no\fR
and \fB\-o apt::install\-recommends=yes\fR, respectively, for this example).
.RE

.SS Limiting used repositories

.P
As of Cupt version 2.3, you can limit the used package repositories for each
package manager invocation without editing the \fIsources.list(5)\fR. The
limiting can be done by repository archive names or codenames.

.P
The common syntax is:

.P
\fIlimiting_option\fR\fB=\fR\fIvalue\fR\fB,\fR\fIvalue\fR\fB,\fR...\fB,\fR\fIvalue\fR

.P
Use the option \fB\-\-include\-archives\fR or \fB\-\-include\-codenames\fR to use only
specified repositories. In other words, no matter how many repositories are
present in the \fIsources.list(5)\fR, only packages from specified repositories
will be considered.

.P
Examples:

.RS
.IP \(bu 3
\fBcupt rdepends \-\-include\-archives=testing,unstable libffi5\fR

List reverse\-dependencies of \fBlibffi5\fR package in \fBtesting\fR and
\fBunstable\fR.

.IP \(bu 3
\fBcupt safe\-upgrade \-\-include\-archives=stable,stable\-updates\fR

Upgrade the system, considering only packages from archives \fBstable\fR and
\fBstable\-updates\fR.

.IP \(bu 3
\fBcupt install xserver\-xorg \-\-include\-codenames=wheezy\fR

Install the package \fBxserver\-xorg\fR, if its version in the \fBwheezy\fR is different
than installed one or there is no such package installed. If any packages need
to be changed in order to process this query (e.g., installing new dependencies
or removing conflicting packages), only versions from \fBwheezy\fR will be
considered.

.IP \(bu 3
\fBcupt search \-\-names\-only '.*?\-perl' \-\-include\-archives=experimental\fR

Search for Perl module packages in \fBexperimental\fR.
.RE

.P
Use the option \fB\-\-exclude\-archives\fR or \fB\-\-exclude\-codenames\fR to not use
specified repositories.  If a package version has multiple repositories and at
least one of them is not excluded, the version will be visible.

.P
Examples:

.RS
.IP \(bu 3
\fBsearch \-n cupt \-\-exclude\-archives=stable\fR

Search for Cupt\-related packages, but ignore packages from \fBstable\fR.

.IP \(bu 3
\fBcupt full\-upgrade \-\-exclude\-codenames=sid,experimental\fR

Upgrade not using packages which come only from \fBsid\fR or \fBexperimental\fR.
.RE

.P
Limiting repositories can also be done by modifying the
\fBcupt::cache::limit\-releases::*\fR family of configuration variables directly.

.P
Note: unlike the pinning settings which only set version priorities,
limiting repositories is an "absolute" tool. For example, if the version has a
very negative pin, it will be still considered for installation if there is no
better choices, but if all repositories which contain a version are not used,
Cupt will forgot about that version from a very start and forever, without
exceptions.

.SS Logging

.P
As of Cupt version 2.2, most actions that effectively change the state of
the system or Cupt itself (namely, working with packages,
updating repository metadata and
working with system snapshots) are logged by default.

.P
The place (the file path) where to place the logs is determined by the option
\fBcupt::directory::log\fR. By default, logs are written to \fB/var/log/cupt.log\fR.

.P
There are 4 levels of logging:

.TP
0
absolutely no logging at all

.TP
1
very minimal logging

.TP
2
the significant information is logged

.TP
3
very detailed logging

.P
Logging levels are set for each subsystem independently. By default, the
logging level for package changes is set to \fB2\fR, other logging levels are set
to \fB1\fR. To change the logging level for some subsystem, use the option
\fBcupt::worker::log::levels::\fR\fIsubsystem\fR.  See \fIcupt.conf(5)\fR for details.

.P
Finally, if you want to disable the logging entirely, set the option
\fBcupt::worker::log\fR to \fBno\fR.

.SH ADVANCED USAGE

.SS Functional selectors

.P
\fBFunctional selectors\fR is a extended syntax for selecting binary or source
versions by their properties or relations. It's available starting with Cupt 2.6.

.P
It can be used whereever
binary package version expression and
source package version expression can be
used. It addition, it can be used as a parameter to \fBsearch \-\-fse\fR.

.P
The full syntax and function reference can be found in
\fIcupt_functionalselectors(7)\fR.

.P
Examples of functional selector expressions (FSE):

.RS
.IP \(bu 3
\fBessential()\fR

All essential versions (those which have \fBEssential: yes\fR).

In the command line it will be

\fBcupt show 'essential()'\fR

or

\fBcupt search \-\-fse 'essential()'\fR

.IP \(bu 3
\fBe()\fR

The same. \fBe\fR is a shortcut for \fBessential\fR.

.IP \(bu 3
\fBpackage:name(.*req.*)\fR

All versions which package name contains the substring \fBreq\fR.

.IP \(bu 3
\fBPn(.*req.*)\fR

Same. \fBPn\fR is a shortcut for \fBpackage:name\fR.

.IP \(bu 3
\fBand(Pn(b.*), e())\fR

All versions which are essential and which package name starts with a letter
\fBb\fR.

.IP \(bu 3
\fBand(Pn(b.*), e)\fR

Same. In subexpressions \fB()\fR can be omitted for functions with no parameters.

.IP \(bu 3
\fBPn(b.*) & e()\fR

Same. \fBx & y & z\fR is a special shortcut syntax for \fBand(x, y, z)\fR.

.IP \(bu 3
\fBor(e, provides(vim))\fR

Versions which are essential or provide \fBvim\fR virtual package.

.IP \(bu 3
\fBe() | provides(vim)\fR

Same. \fBx | y | z\fR is a special shortcut syntax for \fBor(x, y, z)\fR.

.IP \(bu 3
\fBxor(Pn(vim.*), provides(vim))\fR

Versions, which either have a package name which starts with \fBvim\fR or provide
\fBvim\fR virtual package, but not both.

.IP \(bu 3
\fBnot(Pn(vim\-nox)) & provides(vim)\fR

Versions which provide \fBvim\fR virtual package, excluding the package
\fBvim\-nox\fR.

.IP \(bu 3
\fBinstalled() & priority(extra)\fR

Installed versions of priority \fBextra\fR.

.IP \(bu 3
\fBmaintainer(.*lists.alioth.debian.org.*) & priority(required)\fR

Versions of priority \fBrequired\fR and which maintainer email address is a
mailing list hosted on the Alioth service.

.IP \(bu 3
\fBfield(Python\-Version, .*2\e.3.*)\fR

Versions which have a non\-standard field \fBPython\-Version\fR with a substring
\fB2.3\fR somewhere in the value.

.IP \(bu 3
\fBPn(.*python.*) & section(utils)\fR

Versions from \fButils\fR section having \fBpython\fR somewhere in the package
name.

.IP \(bu 3
\fBpackage:installed() & release:component(non\-free)\fR

All versions of installed packages which come from \fBnon\-free\fR release
component.

.IP \(bu 3
\fBuploaders(.*gmail\e.com>)\fR

All source versions where at least one uploader has a Gmail mail address.

.IP \(bu 3
\fBbinary\-to\-source(provides(vim))\fR

All corresponding source versions of those binary versions which provide \fBvim\fR.

.IP \(bu 3
\fBrecommends(installed() & e)\fR

All packages which are recommended by installed essential packages.

.IP \(bu 3
\fBand( Ys(Pn(xfce4.*))|Ye(Pn(xfce4.*)), not(Pn(xfce4.*)) )\fR

All packages which are Suggests (\fBYs\fR) or Enhances (\fBYe\fR) of any package
which name starts with \fBxfce4\fR, excluding \fBxfce4...\fR packages themselves.

.IP \(bu 3
\fBwith(_x, Pn(xfce4.*), and( Ys(_x)|Ye(_x), not(_x)) )\fR

Same.

.IP \(bu 3
\fBwith(_x, Pn(grep), reverse\-depends(_x) | reverse\-recommends(_x))\fR

All versions which depend on or recommend \fBgrep\fR.

.IP \(bu 3
\fBfmap(Pn(grep), reverse\-depends,reverse\-recommends)\fR

Same.

.IP \(bu 3
\fBbuild\-depends(Pn(grep))\fR

Build\-dependencies of the all available versions of the source package \fBgrep\fR.

.IP \(bu 3
\fBrecursive(_r, Pn(cupt)&i, and( Yd(_r)|Yr(_r), not(Pn(.*downloadmethod.*))) )\fR

All direct and indirect depended on and recommended packages (excluding those
which have \fBdownloadmethod\fR in the package name from the recursive chain) of
the installed version of \fBcupt\fR package.

For complex FSEs like this it, the multiline no\-shortcut equivalent might be preferred:

.nf
#!/bin/sh
cupt search --fse '
	recursive(_r, 
		package:name(cupt) & installed(), 
		and(
			depends(_r) | recommends(_r), 
			not( package:name(.*downloadmethod.*) ) 
		)
	)'
.fi


.RE

.SS System snapshots

.P
System snapshots, created by Cupt, consist of binary archives of installed
packages.  The idea is you create snapshots at some time, and when after some
changes you system is messed up, you can go back to the working set of
packages.

.P
Caveats:

.RS
.IP \(bu 3
The most usual use case for it is downgrade the packages after a bad upgrade,
but package downgrades are usually not supported, so it have not a guarantee
to work.

.IP \(bu 3
As of now, snapshots does not store an information about automatically
installed packages.

.IP \(bu 3
If the system doesn't boot or messed up to the level that Cupt or dpkg are
unable to run properly, you cannot revert the system.
.RE

.P
It's recommended not to use this feature if you have better alternatives
available (for example, LVM snapshots or filesystem\-level snapshots).

.P
To create a snapshot, use

.P
\fBcupt snapshot save\fR \fIsnapshot_name\fR

.P
Example:

.P
\fBcupt snapshot save 20110405\fR

.P
To revert the system to a saved snapshot, use

.P
\fBcupt snapshot load\fR \fIsnapshot_name\fR

.P
Example:

.P
\fBcupt snapshot load 20110405\fR

.P
You can also list the available snapshots (\fBcupt snapshot list\fR), rename
(\fBcupt snapshot rename\fR), remove (\fBcupt snapshot remove\fR).

.SS Satisfying particular dependency relation expressions

.P
There is an ability to change the system not by specifying versions of packages
to install or remove, but by specifying dependencies just as some binary
package have them. The subcommand to perform this is \fBsatisfy\fR:

.P
\fBcupt satisfy\fR \fIdependency_expression_1\fR ... \fIdependency_expression_N\fR

.P
Examples:

.P
\fBcupt satisfy "xserver\-xorg (>> 1.6)" "xserver\-common (<< 1.6.1~)"\fR

.P
\fBcupt satisfy "nautilus (>= 2.16.0), libnautilus\-extension1 (>= 2.16.0), wget (>= 1.10.0)"\fR

.P
\fBcupt satisfy "youtube\-dl | clive"\fR

.P
If you want some dependency expression to be unsatisfied instead, add minus
(\fB\-\fR) to the end of an argument:

.P
\fBcupt satisfy mail\-reader\-\fR

.P
Be careful:

.P
\fBcupt satisfy vim emacs\-\fR: install vim or anything which provides it, remove emacs and anything which provides it

.P
\fBcupt satisfy "vim, emacs\-"\fR: remove emacs, vim and anything which provides them

.SS Request type options

.P
By default, when you type \fBcupt install abcde\fR, the preferred version of
\fBabcde\fR package will be installed. By default, on \fBcupt install abcde/unstable\fR
the best of \fBabcde\fR versions found in \fBunstable\fR distribution will be
installed. Also, by default, \fBcupt remove wget/installed\fR or
\fBcupt remove wget/wheezy\fR will remove all versions of \fBwget\fR package (so none of them may
be installed). This is \fBtraditional\fR selection behavior.

.P
Starting with Cupt 2.6, it's possible to choose (per request) new \fBflexible\fR
selection behavior, though traditional selection behavior is still the default.
Flexible behavior is enabled using \fB\-\-select=flexible\fR (or, shorter,
\fB\-\-sf\fR) command line option. Traditional behavior can be (re)enabled using
\fB\-\-select=traditional\fR (or, shorter, \fB\-\-st\fR) command line option.

.P
Flexible selection behavior is often more intuitive.
\fBcupt \-\-sf install abcde\fR will install any version of \fBabcde\fR package
(with, as usual, resolver choosing versions with higher pins first).
\fBcupt \-\-sf install abcde/unstable\fR will install any version of \fBabcde\fR
found in \fBunstable\fR distribution. \fBcupt \-\-sf remove wget\fR will still remove
the package unconditionally just like traditional behavior, but, say,
\fBcupt \-\-sf remove wget/installed wget/wheezy\fR may either remove \fBwget\fR
package or install some its version not from \fBwheezy\fR distribution.

.P
The command line options above are positional and can be mixed.
\fBcupt \-\-select=flexible iii jhc ncdu/experimental \-\-select=traditional \-\-remove automake*/installed\fR
will install (if were installed) any version of \fBjhc\fR and any version
of \fBncdu\fR found in \fBexperimental\fR distribution, but unconditionally remove
installed packages which names start with \fBautomake\fR.

.SS Request importance options

.P
By default, when you ask Cupt to perform some package management actions, they
will be performed unconditionally. As in, the command will fail if any of
requested actions cannot be performed. Sometimes more flexibility might be
wanted, especially with wildcards
and FSE.

.P
Starting with Cupt 2.6, it's possibly to specify also non\-mandatory, or
optional, requests. For optional requests you also specify their importance,
choosing from a three predefined profiles or supplying precise integer value.
The request importance is controlled by \fB\-\-importance=\fR command line option.

.P
To specify actions which should be tried hard but you accept that some of them
could not be satisfied at reasonable price (e.g. some of them conflicts with
each other or require extremely "bad" changes to the system), use
\fB\-\-importance=try\fR (or its shortcut \fB\-\-try\fR). For example:

.nf
 $ cupt -s install --try 'provides(vim)' --no-summary
 
 The following packages will be installed:
 
 [...] vim-athena vim-nox 
 
 The following packages will be upgraded:
 
 [...] vim vim-common vim-gtk vim-gui-common vim-runtime 
 
 [...]
 
 Leave the following dependencies unresolved:
 
 user request: install provides(vim) | for package 'vim-gnome'
.fi


.P
To specify actions with low importance (as in: "do some of them if possible"),
use \fB\-\-importance=wish\fR (or its shortcut \fB\-\-wish\fR). For example:

.nf
 $ cupt -s --wish remove *gnome*

 [...]
 
 The following packages will be removed:
 
 gnome-keyring gstreamer0.10-plugins-good libpam-gnome-keyring
 libsoup-gnome2.4-1 
 
 The following packages are no longer needed and thus will be auto-removed:
 
 gcr gstreamer0.10-gconf gstreamer0.10-x iptables libcap-ng0 libcap2-bin
 libdrm-nouveau1a libdv4 libgck-1-0 libgcr-3-1 libgcr-3-common libiec61883-0
 libnfnetlink0 libpam-cap libxtables10 
 
 Leave the following dependencies unresolved:
 
 gksu 2.0.2-6^installed recommends 'gnome-keyring'
 user request: remove *gnome* | for package 'libgnome-keyring-common'
 user request: remove *gnome* | for package 'libgnome-keyring0'
 libwebkitgtk-3.0-0 2.0.4-5 recommends 'gstreamer1.0-plugins-good'
 libwebkitgtk-1.0-0 2.0.4-5 recommends 'gstreamer1.0-plugins-good'
.fi


.P
To specify precise numeric importance(s), use \fB\-\-importance=\fR\fInumber\fR. For example:

.nf
 $ cupt -s install --importance=10000 xmail --importance=15000 nullmailer --no-auto-remove
 
 The following packages will be installed:
 
 nullmailer 
 
 The following packages will be removed:
 
 msmtp-mta 
 
 Leave the following dependencies unresolved:
 
 user request: install xmail | for package 'xmail'
.fi


.nf
 $ cupt -s install --importance=20000 xmail --importance=15000 nullmailer --no-auto-remove
 
 The following packages will be installed:
 
 xmail 
 
 The following packages will be removed:
 
 msmtp-mta 
 
 Leave the following dependencies unresolved:
 
 user request: install nullmailer | for package 'nullmailer'
.fi


.P
You can also, as usually, mix those options and use \fB\-\-importance=must\fR (or
its shortcut \fB\-\-must\fR) to restore default behavior, for example:

.P
\fBcupt install \-\-try pinentry\-* \-\-wish *debootstrap \-\-must \-\-select=flexible icedove *xulrunner*\fR

.P
The penalty values of \fB\-\-importance=try\fR and \fB\-\-importance=wish\fR are
controlled by configuration options \fBcupt::resolver::score::unsatisfied\-try\fR
and \fBcupt::resolver::score::unsatisfied\-wish\fR, respectively.

.SS Changes in systems with a low disk space

.P
If you happen to have a system, where the disk space is very limited, doing a
big upgrades or installations can be a problem. For example, you have 1 GiB of
disk space total, installed packages occupy 600 MiB of them, now you want to do
a massive upgrade, and it's needed to download 500 MiB of archives to do that,
and after the upgrade packages will occupy 700 MiB. Here, the simple approach
of download everything needed and then upgrade everything needed wouldn't work
since there is no 1100 MiB of the disk space available. The answer is to do the
upgrade by smaller parts. Now, although it can be done by selecting groups of
packages to upgrade or install by hand, Cupt can try to do it automatically.

.P
To enable the \fBchangeset\-based mode\fR you will be need specify how many space is
available for downloaded files. It's impossible to compute the amount reliably since
changed packages may use some additional space (for example, kernel upgrades)
or you may write or remove something to the filesystem before/while the
upgrading is progressing. A rough guess of 'amount of free space minus 100 MiB' is
a good start.

.P
After you computed the disk space you can give for package archives, specify it
as a value, in bytes, for \fBcupt::worker::archives\-space\-limit\fR option.
Example:

.P
\fBcupt full\-upgrade \-o cupt::worker::archives\-space\-limit=200000000\fR

.P
Once this option is set, an action scheduler will try to divide all the changes
into smaller consecutive changesets so the following conditions are met:

.RS
.IP \(bu 3
Download amounts for package changes in any changeset won't exceed the declared limit.

.IP \(bu 3
After each changeset is done, system is fully working in the sense of packages,
i.e. all dependencies are met and there are no packages in interim states.
.RE

.P
If such changesets are found, Cupt will proceed with actions, otherwise an
error with a minimal suitable number will be printed.

.P
For each changeset, package archives will be downloaded before doing actions
and removed before the next changeset begins.

.SS Synchronization by source versions

.P
Sometimes it is a good idea to keep installed binary packages which were built
out of same source package (let's call them \fBrelated\fR) to have the same source version.

.P
Related packages are \fBsynchronized\fR if they have the same source version, i.e.
binary version may not be the same. For example, the following pairs are usually synchronized:

.RS
.IP \(bu 3
\fBqprint 1.0\-1\fR and \fBqprint\-doc 1.0\-1\fR

.IP \(bu 3
\fBqprint 1.0\-1+b2\fR and \fBqprint\-doc 1.0\-1\fR
.RE

.P
But the following are usually not:

.RS
.IP \(bu 3
\fBqprint 1.0\-1\fR and \fBqprint\-doc 1.0\-2\fR
.RE

.P
Cupt's resolver tries to synchronize the versions of related binary packages if
the option \fBcupt::resolver::synchronize\-by\-source\-versions\fR is set to
non\-default value.

.P
Note: this option works properly only if you have source packages available for
all the packages touched by a resolver.

.P
Note: this option doesn't touch installed packages.

.P
Example:

.P
\fBcupt safe\-upgrade \-o cupt::resolver::synchronize\-by\-source\-versions=hard\fR

.P
The \fBhard\fR value means that all changed packages must be synchronized, e.g.
consider the synchronization an additional hard dependency.  The \fBsoft\fR value
means that all unsynchronized changed packages will have a penalty of
\fBcupt::resolver::score::failed\-synchronization\fR, e.g. consider the
synchronization as additional soft dependency.

.P
Example:

.P
Suppose we have \fBlibfoo1\fR and \fBfoo\fR binary packages which came from the same
source package. We have \fBlibfoo1 1.2\-1\fR and \fBfoo 1.2\-1\fR installed.

.P
Situation 1: \fBlibfoo1\fR has new \fB1.3\-1\fR version and foo has new \fB1.3\-1\fR version.

.P
Situation 2: \fBlibfoo1\fR has new \fB1.3\-1\fR version and foo has new \fB1.3\-2\fR version.

.P
We do:

.P
\fBcupt install foo\fR

.P
What would be done by resolver if we have:

.RS
.IP \(bu 3
no synchronization

Situation 1: install new \fBfoo\fR, leave \fBlibfoo1\fR as of installed version

Situation 2: install new \fBfoo\fR, leave \fBlibfoo1\fR as of installed version

.IP \(bu 3
soft synchronization

Situation 1: install new \fBfoo\fR and \fBlibfoo1\fR

Situation 2: install new \fBfoo\fR, leave \fBlibfoo1\fR as of installed version

.IP \(bu 3
hard synchronization

Situation 1: install new \fBfoo\fR and \fBlibfoo1\fR

Situation 2: give up with an error tree, (assuming \fBfoo\fR depends on
\fBlibfoo1\fR, if it does not, then install new \fBfoo\fR, remove \fBlibfoo1\fR)
.RE

.SS Resolver tuning

.SS score

.P
Cupt's native dependency problem resolver plans system changes, if needed, to
make installed packages set correct after making the changes user demand.

.P
In the most cases, there are several solutions to a problem. To choose
amongst them, resolver assign \fBscores\fR to all of them.

.P
Score is an integer (positive or negative) and is a sum of version weight
difference and an action modifier. Version weight, or "normalized version
priority", is a version pin value minus a default pin for a preferred versions.
Action modifiers are action type\-specific addendums and are controlled by the
option group \fBcupt::resolver::score::\fR\fIX\fR (see the full list of them in
\fIcupt.conf(5)\fR).

.P
For native resolver, the negative scores indicate "negative" changes, and
positive scores indicate "positive" changes. When several alternative solutions
for a problem are available, they are considered in the score descending order.
The ultimate goal of score system to assign positive scores to everything user
wants and negative scores to everything user doesn't want. But since "positive"
and "negative" is something that varies from user to user and from action to
action, there is no (and cannot be) a silver bullet.

.P
So, how can you adjust solution scores? From the definition of the score
(above) you may adjust version pinning and/or set
resolver score variables to different values.

.P
Examples:

.nf
$ echo 'q' | cupt -s -t experimental full-upgrade --summary-only | grep "^  "
W: some solutions were dropped, you may want to increase the value of the 'cupt::resolver::max-solution-count' option
  0 manually installed and 48 automatically installed packages will be installed
  129 manually installed and 474 automatically installed packages will be upgraded
  0 manually installed and 32 automatically installed packages will be removed
  2 manually installed and 17 automatically installed packages will have a not preferred version
$ echo 'q' | cupt -s -t experimental full-upgrade --summary-only -o cupt::resolver::score::unsatisfied-recommends=250 | grep "^  "
W: some solutions were dropped, you may want to increase the value of the 'cupt::resolver::max-solution-count' option
  0 manually installed and 43 automatically installed packages will be installed
  129 manually installed and 473 automatically installed packages will be upgraded
  0 manually installed and 34 automatically installed packages will be removed
  2 manually installed and 14 automatically installed packages will have a not preferred version
  4 dependency problems will stay unresolved
$ echo 'q' | cupt -s -t experimental full-upgrade --summary-only -o cupt::resolver::score::new=-1000 | grep "^  "
W: some solutions were dropped, you may want to increase the value of the 'cupt::resolver::max-solution-count' option
  0 manually installed and 30 automatically installed packages will be installed
  124 manually installed and 429 automatically installed packages will be upgraded
  3 manually installed and 70 automatically installed packages will be removed
  9 manually installed and 14 automatically installed packages will have a not preferred version
  7 dependency problems will stay unresolved
$ echo 'q' | cupt -s -t experimental full-upgrade --summary-only -o cupt::resolver::score::new=-1000 -o cupt::resolver::score::downgrade=0 | grep "^  "
W: some solutions were dropped, you may want to increase the value of the 'cupt::resolver::max-solution-count' option
  0 manually installed and 18 automatically installed packages will be installed
  119 manually installed and 464 automatically installed packages will be upgraded
  1 manually installed and 20 automatically installed packages will be removed
  14 manually installed and 37 automatically installed packages will have a not preferred version
  4 dependency problems will stay unresolved
.fi


.SS maximum solution count

.P
When an amount of available solutions is big, you may see the following message while resolver is operating:

.P
\fBW: some solutions were dropped, you may want to increase the value of the 'cupt::resolver::max\-solution\-count' option\fR

.P
Cupt's native resolver may have only limited amount of different solutions in
the memory, and this amount is determined by the value of the
\fBcupt::resolver::max\-solution\-count\fR option. The default value is enough for
requests of small and medium complexity, but may be not enough for request of
high complexity. So, for systems where there is enough free RAM, consider
increasing the value to values like 4000 or even 16000.

.SS Getting debug information

.P
There are several types of debug information available, the debug output is
turned on by setting some \fBdebug::\fR\fItype\fR option to \fByes\fR. All debug output
lines is prepended with \fBD:\fR and are sent to standard error.

.TP
resolver

The native resolver will output its resolution tree and scores.

The debug option is \fBdebug::resolver\fR.

.TP
worker

A debug information regarding scheduling dpkg actions will be printed.

The debug option is \fBdebug::worker\fR.

.TP
downloader

A debug information regarding downloader's states will be printed.

The debug option is \fBdebug::downloader\fR.

.TP
gpg signatures

The gpg signature checker will output its debug information.

The debug option is \fBdebug::gpgv\fR.

.TP
logger

All log messages (of all levels, regardless of logging settings) will be
printed as debug messages.

The debug option is \fBdebug::logger\fR.

.P
An example: you want to see a very detailed resolver information regarding your query:

.P
\fBcupt install exim4 \-o debug::resolver=yes 2>resolver.debug.log\fR

.P
A debug information will be put to a file \fBresolver.debug.log\fR.

.\" man code generated by txt2tags 2.6 (http://txt2tags.org)
.\" cmdline: txt2tags -t man -o cupt_tutorial.7 /tmp/buildd/cupt-2.9.9/doc/tutorial.t2t