path: root/ufed.8.in

.TH "UFED" "8" "15 Feb 2013" "UFED 0.90" "UFED"
.SH "NAME"
ufed \- Gentoo Linux USE flags editor
.SH "SYNOPSIS"
.B ufed 
.SH "DESCRIPTION"
UFED is a simple program designed to help you configure the
systems USE flags (see below) to your liking. To enable or
disable a flag highlight it and hit space.

ufed edits the USE flag settings in your make.conf file only. It can not be
used to edit your package.use file.

If you have two make.conf files, @GENTOO_PORTAGE_EPREFIX@/etc/make.conf and
@GENTOO_PORTAGE_EPREFIX@/etc/portage/make.conf, ufed reads the first, overrides
its settings with the second, and writes changes to the second.

.B What are USE flags?

The USE settings system is a flexible way to enable or disable various features
at package build-time on a global level and for individual packages. This
allows an administrator to control how packages are built in regards to the
optional features which can be compiled into those packages.

For instance, packages with optional GNOME support can have this support
disabled at compile time by disabling the "gnome" USE flag. Enabling the
"gnome" USE flag would enable GNOME support in these packages.

The effect of USE flags on packages is dependent on whether both the
software itself and the package ebuild supports the USE flag as an optional
feature. If the software does not have support for an optional feature then the
corresponding USE flag will obviously have no effect.

Also many package dependencies are not considered optional by the software and
thus USE flags will have no effect on those mandatory dependencies.

A list of USE keywords used by a particular package can be found by checking
the IUSE line in any ebuild file or by using "equery" from gentoolkit.

See http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=2
for more information on USE flags.

Please also note that if UFED describes a flag (Unknown) it generally means
that it is either a spelling error in one of the 3 configuration files or
it is not an officially sanctioned USE flag. Sanctioned USE flags can be found 
in @GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/use.desc and
in @GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/use.local.desc.

.B What are "global" and "local" USE flags?

Global USE flags are called such because they represent functionality that is
found in a wider variety of packages. For example, the global flag "cjk" is
about adding / not adding support for Eastern-Asian languages, which affects
a multitude of various packages. Global flags are described in
@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/use.desc.

Local USE flags are unique package-wise, because the functionality they stand
for is only found in that particular package and no other. See
@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/use.local.desc for a full, 
per-package listing of all local USE flags.

It still happens that a flag which is defined as global is also defined as
local for one or more packages. That is because the general definition of the
global flag takes on specialized semantics in some particular package. It also
occurs that multiple packages define a local flag of the same name - the
meaning of the flag differs, however, for each package.

.B What are "Masked" and "Forced" flags?

ufed allows to view the descriptions of flags that are either masked or forced.

If a USE flag does not apply to your system, or is highly experimental, it can
be masked, making it impossible to select.
.br
If a USE flag is mandatory for your system or for a specific package, it can be
forced, making it impossible to turn it off.

Flags that are masked or forced globally have their names displayed in
parentheses, and are prefixed with a '-' if they are masked. If one of these
flags is set in your make.conf, you can remove it with ufed.
.br
If a flag is only masked or forced for specific packages, a lower case 'm'
or 'f' in the defaults column (see "Display layout" below) indicates this.

.B Navigation and control

Use the Up and Down arrow keys, the Page Up and Page Down keys, the Home and
End keys, or start typing the name of a flag to select it.
Use the space bar to toggle the setting.

You can apply various filters on the flags to display. A status line on the
bottom right will show you which filters are in effect.

F5: Switch between local, global or all flag descriptions.
.br
F6: Switch between flags for which packages are installed that accept this
flag, no packages are installed or all flag descriptions.
.br
F7: Switch between masked and forced flags, flags that are neither masked nor
forced and all flag descriptions.

The default is to display all flags that are neither masked nor forced.

If ncurses is installed with the "gpm" use flag enabled, you can use your
mouse to navigate and to toggle the settings, too.

After changing flags, press the Return or Enter key to make this permanent,
or press Escape to revert your changes.

Note: Depending on your system, you may need to wait a second before ufed
detects the Escape key or mouse clicks; in some cases, you can use the
ncurses environment variable ESCDELAY to change this. See the ncurses(3X)
manpage for more info.

.B Display layout

ufed will present you with a list of descriptions for each USE flag. If a
description is too long to fit on your screen, you can use the Left and Right
arrow keys to scroll the descriptions.

ufed attempts to show you where a particular use setting came from, and what
its scope and state is.

The display consists of the following information:

 (s) flag  |DPC|Si| (packages) description

(s)  : Your selection, either [+] to enable, [-] to disable, or empty to keep
the default value. If a flag is enabled or disabled by default, it will be
shown as either (+) or (-). 
.br
flag : The name of the flag. If the flag is globally masked, it will be shown
as (-flag). If the flag is globally forced, it will be shown as (flag).
.br
D    : [D]efault settings from make.defaults or the ebuilds of installed
packages. Masked flags are shown here as 'm', forced flags as 'f'.
.br
P    : [P]rofile package settings from package.use.
.br
C    : [C]onfiguration settings from @GENTOO_PORTAGE_EPREFIX@/etc/make.conf,
@GENTOO_PORTAGE_EPREFIX@/etc/portage/make.conf and
@GENTOO_PORTAGE_EPREFIX@/etc/portage/package.use.
.br
S    : [S]cope of the description, package specific descriptions have an 'L'
for "local".
.br
i    : [i]nstalled, indicates with an 'i' if either the listed packages are
installed on your system, or if at least one package that supports this flag
is installed. The latter applies to the global description of the flag.
.br
(packages): List of packages that support this flag with the following
description.
.br
description : The description of the flag from use.desc or use.local.desc.

If the character in any of the D, P or C column is a + then that USE flag was
set in that file(s), if it is a space then the flag was not mentioned in that
file(s) and if it is a - then that flag was unset in that file(s).

You can change the order of the (packages) and the description with the F9 key.

.SH "REPORTING BUGS"
Please report bugs via http://bugs.gentoo.org/
.SH "SEE ALSO"
.BR emerge (1),
.BR ebuild (5),
.BR make.conf (5)
.SH "FILES"
.TP
\fB@GENTOO_PORTAGE_EPREFIX@/etc/make.conf, @GENTOO_PORTAGE_EPREFIX@/etc/portage/make.conf\fR 
.br
Contains user specified USE flags
.TP
\fB@GENTOO_PORTAGE_EPREFIX@/etc/make.conf.old, @GENTOO_PORTAGE_EPREFIX@/etc/portage/make.conf.old\fR
.br
This is where ufed places a backup of your make.conf file.
.TP
\fB@GENTOO_PORTAGE_EPREFIX@/etc/make.profile/make.defaults\fR
Contains system default USE flags
.TP
\fB@GENTOO_PORTAGE_EPREFIX@/etc/make.profile/package.use\fR
Contains per package default USE flags
.TP
\fB@GENTOO_PORTAGE_EPREFIX@/etc/portage/package.use\fR
Contains user specified USE flags per package
.TP
\fB@GENTOO_PORTAGE_EPREFIX@/etc/make.profile/use.mask\fR
Restricted USE flags
.TP
\fB@GENTOO_PORTAGE_EPREFIX@/etc/make.profile/use.force\fR
Enforced USE flags
.TP
\fB@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/use.desc\fR
Description strings for global USE flags
.TP
\fB@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/use.local.desc\fR
Description strings for local USE flags
.SH "AUTHORS"
ufed was originally written by Maik Schreiber <blizzy@blizzy.de>.
.br
ufed was previously maintained by
.br
 Robin Johnson <robbat2@gentoo.org>,
.br
 Fred Van Andel <fava@gentoo.org>,
.br
 Arun Bhanu <codebear@gentoo.org> and
.br
 Harald van Dijk <truedfx@gentoo.org>.
.br
ufed is currently maintained by
.br
 Sven Eden <yamakuzure@gmx.net>.