useflag.1 - 5461 bytes

useflag.1 (text/plain), 5.33 KB, created by Michael Thompson on 2002-06-29 23:07:24 UTC

.TH useflag "1" "May 2002" "gentoolkit"
.SH NAME
useflag \- manage and update Gentoo Linux USE flags
.SH SYNOPSIS
.B useflag
\fIaction\fR [\fIflag\fR] [\fI...\fR]
.SH DESCRIPTION
The \fBuseflag\fR utility allows the user to manage Gentoo Linux USE flags through a simple command-line interface.  It allows quick and easy, single-command manipulation of the USE variable defined in \fI/etc/make.conf\fR.  It also simplifies the process of handling changes to the master list of USE flags defined in \fI/usr/portage/profile/use.desc\fR.
.br

It is important to note that a USE variable must exist in \fImake.conf\fR for this utility to work.  Be sure that the USE variable is uncommented.  It is OK for the USE variable to be empty.  Please be sure to back up \fImake.conf\fR before using this utility for the first time.
.PP
.SH ACTIONS
.TP
\fBshow, -s\fR
Displays the raw contents of the USE variable as defined in \fImake.conf\fR.  The output contains only the flags themselves.
.TP
\fBdesc, -i [flag] ...\fR
Displays a description of one or more USE flags specified on the command line.  The flags should be seperated by spaces and should not contain leading dashes.  Specifying a flag that does not exist returns a non-fatal error.
.TP
\fBadd, -a [[\-]flag] ...\fR
Adds one or more specified flags to the USE variable defined in \fImake.conf\fR.  The flags are appended to the USE variable exactly as they appear on the command line.  If a specified flag already exists in the USE variable, it is removed before the new set of flags is appended.  The utility removes existing flags regardless of whether they are in an enabled or disabled state, allowing the user to enable or disable a flag with a single command.  The user may add flags that are not defined in the \fIuse.desc\fR master list.
.TP
\fBdel, -d [flag] ...\fR
Deletes one or more specified flags from the USE variable defined in \fImake.conf\fR.  The enabled/disabled state of a flag in the USE variable as well as any dashes prepended to flags on the command line is ignored.  Attempting to delete a flag that is not in the USE variable returns a non-fatal error.  When a flag is deleted from the USE variable using this utility, it is automatically unlocked.
.TP
\fBlock, -l [flag] ...\fR
Locks one or more specified flags that exist in the USE variable defined in \fImake.conf\fR.  Locked flags are not considered to be deprecated by the update function of this utility.  This allows the user to avoid being queried by the utility about deprecated, undocumented, or custom flags that the user wishes to preserve when performing an update.  A flag must exist in the USE variable in order to be locked.  The enabled/disabled state of a flag in the USE variable as well as any dashes prepended to flags on the command line is ignored.
.TP
\fBunlock, -k [flag] ...\fR
Unlocks one or more specified USE flags.  This allows the update function to consider a flag deprecated if it no longer exists in the master list defined in \fIuse.desc\fR.  Any dashes prepended to flags on the command line are ignored.  Attempting to unlock flags that are not locked returns a non-fatal error.
.TP
\fBshowlock, -w\fR
Displays the raw list of locked flags, seperated by spaces.
.TP
\fBupdate, -u\fR
Interactively updates the USE variable defined in \fImake.conf\fR to reflect changes to the master list of USE flags defined in \fI use.desc\fR.
.br

First, the user is presented with the current raw contents of the USE variable.  The user is also shown the list of locked flags if any exist.
.br

Next, the USE variable is searched for flags that do not appear in the master list.  If any are found and they are not locked, then they are considered to be deprecated and are displayed to the user along with a list of options for handling them.  The user may choose to remove all of the flags, remove none of the flags, lock all of the flags, or handle each flag individually.
.br

Last, the master list is searched for any new flags that have become available since the last time the update function was run, and these are displayed to the user.  If this is the first time, then all flags not currently defined in the USE variable will be displayed.  The user will then be presented with a list of options for handling these flags.  The user may choose to add all of the new flags to the USE variable as enabled, add all of the new flags as disabled, use Portage defaults for all of the flags, or handle each flag individually.
.SH FILES
.TP
\fI/etc/make.conf\fR
Contains the USE variable that Portage uses to control build-time functionality.
.TP
\fI/usr/portage/profile/use.desc\fR
Contains a master list of all documented USE flags along with their descriptions.
.TP
\fI/var/cache/use_desc/use.cache\fR
Contains a cached list of flags from \fIuse.desc\fR.  This prevents the user from being repeatedly queried about flags that exist in \fIuse.desc\fR but not in the USE variable.  DO NOT EDIT THIS FILE MANUALLY.
.TP
\fI/var/cache/use_desc/lock.cache\fR
Contains a list of USE flags that have been locked.  DO NOT EDIT THIS FILE MANUALLY.
.SH AUTHOR
Michael Thompson <[e-mail]>, 2002
.SH SEE ALSO
ebuild(1), ebuild(5), emerge(1), make.conf(5).
.TP
See \fI/usr/share/doc/gentoolkit-<version>/\fR for documentation on other gentoolkit utilities.
.SH TIPS
.TP
Deleting \fI/var/cache/use_desc/use.cache\fR will allow the utility to query about all flags not currently defined in the USE variable.