Abstract¶

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

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.

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

Disadvantages and advantages¶

You might not want to use Cupt, because:

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

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

Infrastructure¶

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

The following infrastructure items are Cupt-specific:

Getting started¶

To start working with Cupt just install it using any present package manager (for example, apt-get install cupt or aptitude install cupt) and run cupt update afterwards.

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

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

Use cupt help to get a list of subcommands and their short descriptions.

The debian system as Cupt sees it¶

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

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

Any installed package may be marked as automatically installed, 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 manually installed.

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

Errors and warnings¶

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

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

All error messages are prepended with E:. Most of errors block the executing of the program, but not all.

Errors and warnings are written to the standard error.

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

Exploring the system¶

what packages are installed?¶

cupt pkgnames --installed-only

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

dpkg -l | grep "^ii"

for more detailed information.

getting information about an installed package¶

dpkg -s package_name

or

cupt show --installed-only package_name

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

details of available package versions¶

To show a default package version:

cupt show package_name

Example: cupt show dpkg

To show all available package versions:

cupt show --all-versions package_name

If you want to see a Debian changelog for a package, use the subcommand changelog.

Example: cupt changelog exim4

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

Example: cupt copyright exim4

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

searching for a package¶

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

cupt search keyword1 keyword2 ... keywordN

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

cupt search audio qt player: found qmmp.

cupt search music qt player: found also amarok.

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

cupt search --names-only "gtk.*perl"

Updating repository metadata¶

To update repository medadata, use

cupt update

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

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

E: there were errors while downloading release and index data

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

Modifying the system¶

package actions terminology¶

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

install

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

remove

when a package will be removed

upgrade

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

downgrade

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

purge

when a package and its configuration files will be removed

action preview prompt¶

An example of action preview prompt:

$ 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 libntlm0 msmtp 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/?]

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.

The following answers to a user prompt are available:

y

accept a solution, i.e. proceed with it

n

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

q

don't do anything, quit immediately

?

output a short help about available answers

a

explained here

installing packages¶

To install a package:

cupt install package_name

Example: cupt install exim4

To install several packages:

cupt install package_name_1 package_name_2 ... package_name_N

Example: cupt install exim4 kvirc kdm

upgrading packages¶

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

removing packages¶

To remove a package:

cupt remove package_name

Example:

cupt remove gdb

To remove several packages:

cupt remove package_name_1 package_name_2 ... package_name_N

Example:

cupt remove gdb kvirc exim4

upgrading the whole system¶

To upgrade as many packages as possible:

cupt full-upgrade

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

cupt full-upgrade --no-remove

Or, shorter:

cupt safe-upgrade

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

cupt dist-upgrade

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

purging packages¶

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

cupt remove --purge package_name

Or:

cupt purge package_name

To purge several packages:

cupt purge package_name_1 package_name_2 ... package_name_N

Example:

cupt purge gdb

Package archives cleaning¶

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

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 autoclean:

cupt autoclean

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

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

cupt clean

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

Working with multiple package versions¶

changing repositories¶

Cupt uses the same repository list format as APT. See sources.list(5).

release information¶

Each version of a certain package has one or more sources where it comes from.

Each source consists of download information and a subrepository information, or release information.

The following properties belong to release information:

basic URI

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

Example: http://ftp.fi.debian.org/debian

archive

a repository archive name, for example testing or stable

codename

a release code name, for example wheezy or sid

component

a subrepository component name, for example main or non-free

vendor

a vendor name, for example: Debian

label

a vendor-provided label, for example: Debian-Security

version

a release version, for example: 6.0

description

a repository description line

Any of properties above may be empty.

To see available releases:

cupt policy

Example:

 $ 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

The format of lines above:

basic_URI archive/component: o=vendor,a=archive,l=label,c=component,v=version,n=codename

Note that "installed" release have the archive installed and the codename now.

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

cupt show --with-release-info package_name

Example:

cupt show --with-release-info dpkg

version pinning system¶

Each package version has a pin, an integer number.

Amongst all versions of the same binary package, the one who has maximal pin is policy, or preferred version. It's also candidate in APT terminology and in Cupt before 2.3.

Cupt assigns pins to package versions according to the APT documentation (apt_preferences(5)). Plus, it adds:

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.

what package versions are available?¶

cupt policy package_name

Example:

 $ 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)

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.

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.

Each repository line is:

basic_URI archive/component (signedness)

The repository marked as signed if it has a valid and verified cryptographic signature, and unsigned otherwise.

version string id suffixes¶

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

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 ^installed suffix, for example 1.2.4^installed.

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

selecting binary package versions¶

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:

policy version

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

Example:

cupt show dpkg

specific version

to select an exact version of the package, use the suffix =version.

Example:

cupt show dpkg=1.15.8.10

by archive or codename

to select a version in release with known archive or codename, use the suffix /archive or /codename.

Examples:

cupt show dpkg/unstable

cupt show dpkg/sid

The syntax described above is known as binary package version expression. In the cupt(1) manual page all subcommands which accept this syntax are clearly marked as such.

Combining multiple version arguments¶

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

cupt show dpkg cupt libpqxx3=3.0.2-1

cupt install youtube-dl clive/stable

cupt remove libabc-dev libefg-dev libxyz-dev

cupt policy perl perl-base

You can use wildcards * and ? to select multiple package names. Examples:

Conditional installation¶

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

Examples:

Overriding package management actions¶

Action override options¶

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

Examples:

Package name suffixes¶

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

+

"install this"

-

"remove this"

You can use the + modifier in subcommands: remove, purge. Examples:

cupt remove youtube-dl clive+: remove youtube-dl, install clive

cupt purge exim4 msmtp-mta+ mutt/experimental+: remove exim4 along with its configuration files, install msmtp-mta and mutt (from experimental)

You can use the - modifier in the install and *-upgrade-like subcommands. Examples:

cupt install gnuchess/unstable gnome-chess pychess-: install gnuchess (from unstable), gnome-chess, remove pychess

cupt full-upgrade cvs-:

a) cvs is installed -> do an upgrade with removing cvs

b) cvs is not installed -> do an upgrade, keeping cvs uninstalled

Using package archive deltas¶

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

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

Listing dependency information¶

To list the dependencies of one or more package versions, use the subcommand depends:

cupt depends libc6/testing arora/unstable

If you don't want to see Recommends there, use --important:

cupt depends --important libc6/testing

If, on the contrary, you want to see even Suggests, use --with-suggests:

cupt depends --with-suggests libc6/testing

You can also list selected relations recursively, using --recurse:

cupt depends --recurse dpkg

If you want to see a reverse dependencies of some version, use the subcommand rdepends:

cupt rdepends xz-utils

All the command switches described here are also applicable to rdepends as well.

Action preview prompt (extended)¶

summary¶

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

To remove it, use --no-summary command-line option. To remove it permanently, set the configuration option cupt::console::actions-preview::show-summary to no.

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

detailed solution preview¶

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

You can also combine them.

reason chain¶

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 rc. Example:

 $ 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/?]

specifying more package expression arguments¶

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 a. Example:

 $ 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 librasqal2


 


 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


 


 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/?]

The effect above is the same as if you specified

cupt install gnash libgnome-keyring0-

in the command line from the start.

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

colors¶

Some parts of the actions preview will be colored if you enable colors by setting the option cupt::console::use-colors to auto or yes (see cupt.conf(5)).

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

Starting from Cupt 2.10, colors are enabled on terminals by default (auto setting).

Adjusting configuration variables¶

intro¶

There are two types of configuration variables - regular (or scalar) and list 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.

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 cupt.conf(5).

To see the current configuration, use config-dump subcommand. Examples:

 $ cupt config-dump | grep recommends


 apt::install-recommends "yes";


 cupt::resolver::keep-recommends "yes";


 cupt::resolver::tune-score::failed-recommends "600";

 $ 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"; };

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

configuration sources¶

Cupt reads configuration in the following order:

setting options using the command line¶

To modify a regular option in the command line, use

-o option_name=new_value

Example:

cupt install kmail -o cupt::console::assume-yes=yes

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

-o option_name::=added_string

Example:

cupt -s update -o "apt::update::pre-invoke::=ls /var"

You can use -o multiple times.

Automatically installed packages¶

view¶

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

cupt show --installed-only package_name

Example:

cupt show --installed-only dpkg

To list manually installed packages:

cupt showauto --invert

To list automatically installed packages:

cupt showauto

change¶

To mark some package(s) as automatically installed, use the markauto subcommand, for example:

cupt markauto libqtcore4 udev

To mark some package(s) as manually installed, use the unmarkauto subcommand, for example:

cupt unmarkauto tar traceroute

removal¶

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 auto-removal.

If you don't want auto-removal to be performed, use --no-auto-remove switch or set the option cupt::resolver::auto-remove to no.

Soft dependencies¶

All forward interdependencies between packages can be divided into two groups -- hard and soft 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.

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

You can use the following options to change the behavior:

apt::install-recommends

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

cupt::resolver::keep-recommends

set this to no to make resolver ignore all 'Recommends'

apt::install-suggests

set this yes to make resolver try to satisfy new 'Suggests'

cupt::resolver::keep-suggests

set this to yes to make resolver try to keep already satisfied 'Suggests'

Note 1: having the option apt::install-X set to yes without cupt::resolver::keep-X set to yes as well is useless, Cupt's native resolver will warn about it.

Note 2: even when the appropriate apt::install-X option is set, Cupt ignores not changed soft dependencies. Say, if there is an installed package gettext of version 1.2 which Recommends: cvs, a relation cvs is not satisfied in the system, and gettext is upgraded to a version 1.3 which also have the same Recommends: cvs, Cupt won't try to satisfy this dependency.

Understanding package installation process¶

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:

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

Example:

 1: # cupt install cmake

This is a command line.

 2: Building the package cache...


 3: Initializing package resolver and worker...


 4: Scheduling requested actions...


 5: Resolving possible unmet dependencies...

These are (optional) information messages from Cupt.

 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

This is an action preview prompt.

 17: Performing requested actions:

This is the 'preparation' phase.

 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.

This is the 'downloading' phase.

 23: Reading changelogs... Done

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

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

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

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.

Source packages¶

overview¶

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

exploring¶

To view a source package information:

cupt showsrc package_name

Example:

cupt showsrc cupt

You can specify more than one package, for example:

cupt showsrc sed mawk

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

cupt policysrc sed mawk

To download source package(s), use the source subcommand, for example:

cupt source clive youtube-dl

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

satisfying build dependencies¶

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 build-dep to do it, for example:

cupt build-dep clive

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.

So, the process of building binary packages out of source one may be, taking clive package as an example:

 cupt source clive


 cupt build-dep clive


 cd clive-2.2.13 && debuild && cd ../


 [...]


 cupt install

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

selecting source package versions¶

You can select source package versions in two ways:

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

cupt build-dep clive/unstable

cupt source man-db=2.5.9-4

Package manager shell¶

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.

Example:

 $ 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

What this mode may be useful for:

Limiting used repositories¶

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

The common syntax is:

limiting_option=value,value,...,value

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

Examples:

Use the option --exclude-archives or --exclude-codenames 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.

Examples:

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

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.

Logging¶

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.

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

There are 4 levels of logging:

0

absolutely no logging at all

1

very minimal logging

2

the significant information is logged

3

very detailed logging

Logging levels are set for each subsystem independently. By default, the logging level for package changes is set to 2, other logging levels are set to 1. To change the logging level for some subsystem, use the option cupt::worker::log::levels::subsystem. See cupt.conf(5) for details.

Finally, if you want to disable the logging entirely, set the option cupt::worker::log to no.

Functional selectors¶

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

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 search --fse.

The full syntax and function reference can be found in cupt_functionalselectors(7).

Examples of functional selector expressions (FSE):

System snapshots¶

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.

Caveats:

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

To create a snapshot, use

cupt snapshot save snapshot_name

Example:

cupt snapshot save 20110405

To revert the system to a saved snapshot, use

cupt snapshot load snapshot_name

Example:

cupt snapshot load 20110405

You can also list the available snapshots (cupt snapshot list), rename (cupt snapshot rename), remove (cupt snapshot remove).

Satisfying particular dependency relation expressions¶

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 satisfy:

cupt satisfy dependency_expression_1 ... dependency_expression_N

Examples:

cupt satisfy "xserver-xorg (>> 1.6)" "xserver-common (<< 1.6.1~)"

cupt satisfy "nautilus (>= 2.16.0), libnautilus-extension1 (>= 2.16.0), wget (>= 1.10.0)"

cupt satisfy "youtube-dl | clive"

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

cupt satisfy mail-reader-

Be careful:

cupt satisfy vim emacs-: install vim or anything which provides it, remove emacs and anything which provides it

cupt satisfy "vim, emacs-": remove emacs, vim and anything which provides them

Request type options¶

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

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

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

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

Request importance options¶

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.

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 --importance= command line option.

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 --importance=try (or its shortcut --try). For example:

 $ 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'

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

 $ 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'

To specify precise numeric importance(s), use --importance=number. For example:

 $ 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'

 $ 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'

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

cupt install --try pinentry-* --wish *debootstrap --must --select=flexible icedove *xulrunner*

The penalty values of --importance=try and --importance=wish are controlled by configuration options cupt::resolver::score::unsatisfied-try and cupt::resolver::score::unsatisfied-wish, respectively.

Changes in systems with a low disk space¶

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.

To enable the changeset-based mode 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.

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

cupt full-upgrade -o cupt::worker::archives-space-limit=200000000

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:

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

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

Synchronization by source versions¶

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

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

But the following are usually not:

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

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

Note: this option doesn't touch installed packages.

Example:

cupt safe-upgrade -o cupt::resolver::synchronize-by-source-versions=hard

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

Example:

Suppose we have libfoo1 and foo binary packages which came from the same source package. We have libfoo1 1.2-1 and foo 1.2-1 installed.

Situation 1: libfoo1 has new 1.3-1 version and foo has new 1.3-1 version.

Situation 2: libfoo1 has new 1.3-1 version and foo has new 1.3-2 version.

We do:

cupt install foo

What would be done by resolver if we have:

Resolver tuning¶

score¶

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

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

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 cupt::resolver::score::X (see the full list of them in cupt.conf(5)).

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.

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.

Examples:

$ 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

maximum solution count¶

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

W: some solutions were dropped, you may want to increase the value of the 'cupt::resolver::max-solution-count' option

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 cupt::resolver::max-solution-count 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.

Getting debug information¶

There are several types of debug information available, the debug output is turned on by setting some debug::type option to yes. All debug output lines is prepended with D: and are sent to standard error.

resolver

The native resolver will output its resolution tree and scores.

The debug option is debug::resolver.

worker

A debug information regarding scheduling dpkg actions will be printed.

The debug option is debug::worker.

downloader

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

The debug option is debug::downloader.

gpg signatures

The gpg signature checker will output its debug information.

The debug option is debug::gpgv.

logger

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

The debug option is debug::logger.

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

cupt install exim4 -o debug::resolver=yes 2>resolver.debug.log

A debug information will be put to a file resolver.debug.log.