diff options
Diffstat (limited to 'man/dselect.pod')
| -rw-r--r-- | man/dselect.pod | 675 |
1 files changed, 675 insertions, 0 deletions
diff --git a/man/dselect.pod b/man/dselect.pod new file mode 100644 index 0000000..507a741 --- /dev/null +++ b/man/dselect.pod @@ -0,0 +1,675 @@ +# dselect manual page - dselect(1) +# +# Copyright © 1995 Juho Vuori <javuori@cc.helsinki.fi> +# Copyright © 2000 Josip Rodin +# Copyright © 2001 Joost Kooij +# Copyright © 2001 Wichert Akkerman <wakkerma@debian.org> +# Copyright © 2010-2015 Guillem Jover <guillem@debian.org> +# +# This is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <https://www.gnu.org/licenses/>. + +=encoding utf8 + +=head1 NAME + +dselect - Debian package management frontend + +=head1 SYNOPSIS + +B<dselect> +[I<option>...] [I<command>...] + +=head1 DESCRIPTION + +B<dselect> +is one of the primary user interfaces for managing packages on a Debian +system. At the B<dselect> main menu, the system administrator can: + +=over + +=item * + +Update the list of available package versions, + +=item * + +View the status of installed and available packages, + +=item * + +Alter package selections and manage dependencies, + +=item * + +Install new packages or upgrade to newer versions. + +=back + +B<dselect> +operates as a front-end to B<dpkg>(1), the low-level Debian package +handling tool. It features a full-screen package selections manager +with package depends and conflicts resolver. When run with administrator +privileges, packages can be installed, upgraded and removed. Various +access methods can be configured to retrieve available package version +information and installable packages from package repositories. +Depending on the used access method, these repositories can be public +archive servers on the internet, local archive servers or CD-ROMs. +The recommended access method is I<apt>, which is provided by the +package B<apt>(8). + +Normally B<dselect> is invoked without parameters. An interactive +menu is presented, offering the user a list of commands. If a command +is given as argument, then that command is started immediately. Several +command line parameters are still available to modify the running behaviour +of B<dselect> or show additional information about the program. + +=head1 OPTIONS + +All options can be specified both on the command line and in the B<dselect> +configuration file I<%PKGCONFDIR%/dselect.cfg> or the files on the +configuration directory I<%PKGCONFDIR%/dselect.cfg.d/>. Each line in the +configuration file is either an option (exactly the same as the +command line option but without leading hyphens) or a comment (if it starts +with a ‘B<#>’). + +=over + +=item B<--admindir> I<directory> + +Changes the directory where the dpkg ‘I<status>’, +‘I<available>’ and similar files are located. +Defaults to I<%ADMINDIR%> if B<DPKG_ADMINDIR> has not been set. + +=item B<--instdir> I<directory> + +Set the installation directory, which refers to the directory where +packages get installed (since dpkg 1.21.2). +Defaults to «I</>» if B<DPKG_ROOT> has not been set. + +=item B<--root> I<directory> + +Set the root directory to I<directory>, which sets the installation +directory to «I<directory>» and the administrative +directory to «I<directory>%ADMINDIR%» (since dpkg 1.21.0). + +=item B<-D>I<file>, B<--debug> I<file> + +Turn on debugging. Debugging information is sent to I<file>. + +=item B<--expert> + +Turns on expert mode, i.e. doesn't display possibly annoying help +messages. + +=item B<--color> I<screenpart>:[I<foreground>],[I<background>][:I<attr>[I<+attr>]...] + +=item B<--colour> I<screenpart>:[I<foreground>],[I<background>][:I<attr>[I<+attr>]...] + +Configures screen colors. This works only if your display supports colors. +This option may be used multiple times (and is best used in +I<dselect.cfg>). Each use changes the color (and optionally, other +attributes) of one part of the screen. +The parts of the screen (from top to bottom) are: + +=over + +=item B<title> + +The screen title. + +=item B<listhead> + +The header line above the list of packages. + +=item B<list> + +The scrolling list of packages (and also some help text). + +=item B<listsel> + +The selected item in the list. + +=item B<pkgstate> + +In the list of packages, the text indicating the current state of each +package. + +=item B<pkgstatesel> + +In the list of packages, the text indicating the current state of the +currently selected package. + +=item B<infohead> + +The header line that displays the state of the currently selected package. + +=item B<infodesc> + +The package's short description. + +=item B<info> + +Used to display package info such as the package's description. + +=item B<infofoot> + +The last line of the screen when selecting packages. + +=item B<query> + +Used to display query lines + +=item B<helpscreen> + +Color of help screens. + +=back + +After the part of the screen comes a colon and the color specification. You +can specify either the foreground color, the background color, or both, +overriding the compiled-in colors. Use standard curses color names. + +Optionally, after the color specification is another colon, and an +attribute specification. This is a list of one or more attributes, +separated by plus (‘+’) characters. +Available attributes include (not all of these will work on all terminals): +B<normal>, B<standout>, B<underline>, B<reverse>, B<blink>, +B<bright>, B<dim>, B<bold> + +=item B<-?>, B<--help> + +Print a brief help text and exit successfully. + +=item B<--version> + +Print version information and exit successfully. + +=back + +=head1 COMMANDS + +When +B<dselect> +is started it can perform the following commands, either directly if it +was specified on the command line or by prompting the user with a menu +of available commands if running interactively: + +=head2 access + +Choose and configure an access method to access package repositories. + +By default, B<dselect> provides several methods such +as I<multi_cd>, I<mounted> or I<ftp>, but other +packages may provide additional methods, for example the I<apt> access method +provided by the B<apt>(8) package. + +The use of the I<apt> access method is strongly recommended. + +=head2 update + +Refresh the available packages database. + +Retrieves a list of available package versions from the package +repository, configured for the current access method, and update +the dpkg database. The package lists are commonly provided by the +repository as files named I<Packages> or I<Packages.gz>. +These files can be generated by repository maintainers, using the +program B<dpkg-scanpackages>(1). + +Details of the update command depend on the access method's implementation. +Normally the process is straightforward and requires no user interaction. + +=head2 select + +View or manage package selections and dependencies. + +This is the main function of B<dselect>. In the select screen, the +user can review a list of all available and installed packages. When run +with administrator privileges, it is also possible to interactively +change packages selection state. B<dselect> tracks the implications +of these changes to other depending or conflicting packages. + +When a conflict or failed depends is detected, a dependency resolution +subscreen is prompted to the user. In this screen, a list of conflicting +or depending packages is shown, and for each package listed, the reason +for its listing is shown. The user may apply the suggestions proposed +by B<dselect>, override them, or back out all the changes, including +the ones that created the unresolved depends or conflicts. + +The use of the interactive package selections management screen is +explained in more detail below. + +=head2 install + +Installs selected packages. + +The configured access method will fetch installable or upgradable packages +from the relevant repositories and install these using B<dpkg>. +Depending on the implementation of the access method, all packages can +be prefetched before installation, or fetched when needed. +Some access methods may also remove packages that were marked for removal. + +If an error occurred during install, it is usually advisable to run +install again. In most cases, the problems will disappear or be solved. +If problems persist or the installation performed was incorrect, please +investigate into the causes and circumstances, and file a bug in the +Debian bug tracking system. Instructions on how to do this can be found +at L<https://bugs.debian.org/> or by reading the documentation +for B<bug>(1) or B<reportbug>(1), if these are installed. + +Details of the install command depend on the access method's implementation. +The user's attention and input may be required during installation, +configuration or removal of packages. This depends on the maintainer +scripts in the package. Some packages make use of the B<debconf>(1) +library, allowing for more flexible or even automated installation +setups. + +=head2 config + +Configures any previously installed, but not fully configured packages. + +=head2 remove + +Removes or purges installed packages, that are marked for removal. + +=head2 quit + +Quit B<dselect>. + +Exits the program with zero (successful) error code. + +=head1 PACKAGE SELECTIONS MANAGEMENT + +=head2 Introduction + +B<dselect> +directly exposes +the administrator to some of the complexities involved with managing +large sets of packages with many interdependencies. For a user who is +unfamiliar with the concepts and the ways of the Debian package management +system, it can be quite overwhelming. Although B<dselect> is aimed +at easing package management and administration, it is only instrumental +in doing so and cannot be assumed to be a sufficient substitute for +administrator skill and understanding. The user is required to +be familiar with the concepts underlying the Debian packaging system. +In case of doubt, consult the B<dpkg>(1) manpage and the distribution +policy. + +Unless B<dselect> is run in expert +or immediate mode, a help screen is first displayed when choosing this +command from the menu. The user is I<strongly> advised to study all of +the information presented in the online help screens, when one pops up. +The online help screens can at any time be invoked with the ‘B<?>’ key. + +=head2 Screen layout + +The select screen is by default split in a top and a bottom half. +The top half shows a list of packages. A cursor bar can select an +individual package, or a group of packages, if applicable, by selecting +the group header. The bottom half of the screen shows some details +about the package currently selected in the top half of the screen. +The type of detail that is displayed can be varied. + +Pressing the ‘B<I>’ key toggles a full-screen display of the packages +list, an enlarged view of the package details, or the equally split screen. + +=head2 Package details view + +The package details view by default shows the extended package description +for the package that is currently selected in the packages status list. +The type of detail can be toggled by pressing the ‘B<i>’ key. +This alternates between: + +=over + +=item * + +the extended description + +=item * + +the control information for the installed version + +=item * + +the control information for the available version + +=back + +In a dependency resolution screen, there is also the possibility of +viewing the specific unresolved depends or conflicts related to the +package and causing it to be listed. + +=head2 Packages status list + +The main select screen displays a list of all packages known to the Debian +package management system. This includes packages installed on the system +and packages known from the available packages database. + +For every package, the list shows the package's status, priority, section, +installed and available architecture, installed and available versions, +the package name and its short description, all in one line. +By pressing the ‘B<A>’ key, the display of the installed and +available architecture can be toggled between on an off. +By pressing the ‘B<V>’ key, the display of the installed and +available version can be toggled between on an off. +By pressing the ‘B<v>’ key, the package status display is toggled +between verbose and shorthand. +Shorthand display is the default. + +The shorthand status indication consists +of four parts: an error flag, which should normally be clear, the +current status, the last selection state and the current selection state. +The first two relate to the actual state of the package, the second pair +are about the selections set by the user. + +These are the meanings of the shorthand package status indicator codes: + +=over + +Error flag: + +=over + +=item I<empty> no error + +=item B<R> serious error, needs reinstallation; + +=back + +Installed state: + +=over + +=item I<empty> not installed; + +=item B<*> fully installed and configured; + +=item B<-> not installed but some config files may remain; + +=item B<U> unpacked but not yet configured; + +=item B<C> half-configured (an error happened); + +=item B<I> half-installed (an error happened). + +=back + +Current and requested selections: + +=over + +=item B<*> marked for installation or upgrade; + +=item B<-> marked for removal, configuration files remain; + +=item B<=> on hold: package will not be processed at all; + +=item B<_> marked for purge, also remove configuration; + +=item B<n> package is new and has yet to be marked. + +=back + +=back + +=head2 Cursor and screen movement + +The package selection list and the dependency conflict +resolution screens can be navigated using motion +commands mapped to the following keys: + +=over + +=over + +=item B<p, Up, k> move cursor bar up + +=item B<n, Down, j> move cursor bar down + +=item B<P, Pgup, Backspace> scroll list 1 page up + +=item B<N, Pgdn, Space> scroll list 1 page down + +=item B<^p> scroll list 1 line up + +=item B<^n> scroll list 1 line down + +=item B<t, Home> jump to top of list + +=item B<e, End> jump to end of list + +=item B<u> scroll info 1 page up + +=item B<d> scroll info 1 page down + +=item B<^u> scroll info 1 line up + +=item B<^d> scroll info 1 line down + +=item B<B, Left-arrow> pan display 1/3 screen left + +=item B<F, Right-arrow> pan display 1/3 screen right + +=item B<^b> pan display 1 character left + +=item B<^f> pan display 1 character right + +=back + +=back + +=head2 Searching and sorting + +The list of packages can be searched by package name. This +is done by pressing ‘B</>’, and typing a simple search +string. The string is interpreted as a +B<regex>(7) +regular expression. +If you add ‘B</d>’ to the search expression, dselect will also +search in descriptions. +If you add ‘B</i>’ the search will be case insensitive. +You may combine these two suffixes like this: ‘B</id>’. +Repeated searching is accomplished by repeatedly pressing the +‘B<n>’ or ‘B<\>’ keys, until the wanted package is found. +If the search reaches the bottom of the list, it wraps to the top +and continues searching from there. + +The list sort order can be varied by pressing +the ‘B<o>’ and ‘B<O>’ keys repeatedly. +The following nine sort orderings can be selected: + +=over + +=over + +=item B<alphabet> + +=item B<priority+section> + +=item B<section+priority> + +=item B<available> + +=item B<available+priority> + +=item B<available+section> + +=item B<status> + +=item B<status+priority> + +=item B<status+section> + +=back + +=back + +Where not listed above explicitly, alphabetic order is used as +the final subordering sort key. + +=head2 Altering selections + +The requested selection state of individual packages may be +altered with the following commands: + +=over + +=over + +=item B<+, Insert> install or upgrade + +=item B<=, H> hold in present state and version + +=item B<:, G> unhold: upgrade or leave uninstalled + +=item B<-, Delete> remove, but leave configuration + +=item B<_> remove & purge configuration + +=back + +=back + +When the change request results in one or more unsatisfied depends +or conflicts, B<dselect> prompts the user with a dependency resolution +screen. This will be further explained below. + +It is also possible to apply these commands to groups of package +selections, by pointing the cursor bar onto a group header. The +exact grouping of packages is dependent on the current list ordering +settings. + +Proper care should be taken when altering large groups of selections, +because this can instantaneously create large numbers of unresolved +depends or conflicts, all of which will be listed in one dependency +resolution screen, making them very hard to handle. In practice, +only hold and unhold operations are useful when applied to groups. + +=head2 Resolving depends and conflicts + +When the change request results in one or more unsatisfied depends +or conflicts, B<dselect> prompts the user with a dependency resolution +screen. First however, an informative help screen is displayed. + +The top half of this screen lists all the packages that will have +unresolved depends or conflicts, as a result of the requested change, +and all the packages whose installation can resolve any of these +depends or whose removal can resolve any of the conflicts. +The bottom half defaults to show the depends or conflicts that +cause the currently selected package to be listed. + +When the sublist of packages is displayed initially, B<dselect> +may have already set the requested selection status of some of the +listed packages, in order to resolve the depends or conflicts that +caused the dependency resolution screen to be displayed. Usually, +it is best to follow up the suggestions made by B<dselect>. + +The listed packages' selection state may be reverted to the original +settings, as they were before the unresolved depends or conflicts +were created, by pressing the ‘B<R>’ key. +By pressing the ‘B<D>’ key, the automatic suggestions are reset, +but the change that caused the dependency resolution screen to be prompted +is kept as requested. +Finally, by pressing ‘B<U>’, the selections are again set to the +automatic suggestion values. + +=head2 Establishing the requested selections + +By pressing B<enter>, the currently displayed set of selections +is accepted. If B<dselect> detects no unresolved depends as a result +of the requested selections, the new selections will be set. +However, if there are any unresolved depends, B<dselect> will again +prompt the user with a dependency resolution screen. + +To alter a set of selections that creates unresolved depends or +conflicts and forcing B<dselect> to accept it, press the ‘B<Q>’ +key. This sets the selections as specified by the user, +unconditionally. Generally, don't do this unless you've read +the fine print. + +The opposite effect, to back out any selections change requests and +go back to the previous list of selections, is attained by pressing +the ‘B<X>’ or B<escape> keys. By repeatedly pressing these +keys, any possibly detrimental changes to the requested package +selections can be backed out completely to the last established +settings. + +If you mistakenly establish some settings and wish to revert all the +selections to what is currently installed on the system, press the +‘B<C>’ key. +This is somewhat similar to using the unhold command on all packages, +but provides a more obvious panic button in cases where the user +pressed B<enter> by accident. + +=head1 EXIT STATUS + +=over + +=item B<0> + +The requested command was successfully performed. + +=item B<2> + +Fatal or unrecoverable error due to invalid command-line usage, or +interactions with the system, such as accesses to the database, +memory allocations, etc. + +=back + +=head1 ENVIRONMENT + +=over + +=item B<DPKG_ROOT> + +If set and the B<--instdir> or B<--root> options have not been specified, +it will be used as the filesystem root directory (since dpkg 1.21.0). + +=item B<DPKG_ADMINDIR> + +If set and the B<--admindir> or B<--root> option have not been specified, +it will be used as the B<dpkg> database directory (since dpkg 1.21.0). + +=item B<HOME> + +If set, B<dselect> will use it as the directory from which to read the +user specific configuration file. + +=back + +=head1 BUGS + +The +B<dselect> +package selection interface is confusing to some new users. +Reportedly, it even makes seasoned kernel developers cry. + +The documentation is lacking. + +There is no help option in the main menu. + +The visible list of available packages cannot be reduced. + +The built in access methods can no longer stand up to current quality +standards. Use the access method provided by B<apt>(8), it is not only not +broken, it is also much more flexible than the built in access methods. + +=head1 SEE ALSO + +B<dpkg>(1), +B<apt>(8), +B<sources.list>(5), +B<deb>(5). |