genup.8

.TH GENUP 8 "Version 1.0.14: June 2017"
.SH NAME
genup \- update Portage tree, all installed packages, and kernel
.SH SYNOPSIS
.B genup
[\fIoptions\fR]
.SH DESCRIPTION
.B genup
is a utility intended to simplify the process of keeping your Gentoo system
up to date. 
When invoked, it automatically performs the following steps, in order:
.br
.RS
.IP \(bu 2
updates Portage tree & overlays; syncs \fBeix\fR(1)
(if desired)
.br
(using (if needed) \fBemaint sync --auto\fR, and \fBeix-sync\fR)
.IP \(bu 2
removes any prior \fBemerge\fR(1) resume history;
.br
(using \fBemaint --fix cleanresume\fR)
.IP \(bu 2
ensures Portage itself is up-to-date
.br
(using \fBemerge --oneshot --update portage\fR)
.IP \(bu 2
updates all packages in the @world set
.br
(using \fBemerge --deep --with-bdeps=y --changed-use --update @world\fR)
.IP \(bu 2
builds any external modules (such as those for VirtualBox)
.br
(using \fBemerge @module-rebuild --exclude '*-bin'\fR)
.IP \(bu 2
rebuilds any packages depending on stale libraries
.br
(using \fBemerge @preserved-rebuild\fR)
.IP \(bu 2
updates any old \fBperl\fR(1) modules (if desired)
.br
(using \fBperl-cleaner --all\fR)
.IP \(bu 2
updates any old \fBpython\fR(1) modules (if desired)
.br
(using \fBpython-updater\fR)
.IP \(bu 2
resolves clashing config file changes (in interactive mode)
.br
(using \fBdispatch-conf\fR)
.IP \(bu 2
upgrades the kernel if possible (to staging, in \fI/boot\fR)
.br
(using \fBbuildkernel --stage-only\fR)
.IP \(bu 2
removes unreferenced packages
.br
(using \fBemerge --depclean\fR)
.IP \(bu 2
fixes missing shared library dependencies
.br
(using \fBrevdep-rebuild\fR)
.IP \(bu 2
rebuilds any packages depending on stale libraries (again)
.br
(using \fBemerge @preserved-rebuild\fR)
.IP \(bu 2
removes any unused source tarballs (if desired)
.br
(using \fBeclean --deep distfiles\fR)
.IP \(bu 2
deploys new kernel from staging (if desired and available)
.br
(using \fBbuildkernel --copy-from-staging\fR)
.IP \(bu 2
updates environment settings (as a precautionary measure)
.br
(using \fBenv-update\fR)
.IP \(bu 2
runs any custom updaters in \fI/etc/genup/updaters.d\fR
.PP
.RE
The \fBgenup\fR utility can be invoked in non-interative (default) or 
interactive mode (see the \fB--ask\fR option, below).
Non-interactive mode is suitable for use in a scripted invocation, for example
as part of a nightly \fBcron\fR(8) job (see \fBAUTOMATING GENUP\fR, below).
.SH OPTIONS
.TP
.BR \-a ", " \-\-ask
By default, \fBgenup\fR will:
a) attempt to perform the update automatically;
b) attempt to rebuild the kernel (if a new version becomes available);
c) fail immediately on any error; 
d) invoke underlying tools (such as \fBbuildkernel\fR(8)) in non-interactive
mode; and
e) not invoke \fBdispatch-conf\fR(1) to resolve clashing configuration file
updates (unless the \fB--dispatch-conf\fR option has been specified)

However, if you supply the \fB--ask\fR option, then \fBgenup\fR will instead:
a) prompt for confirmation during important steps of the update;
b) ask whether or not you wish to rebuild the kernel
(if a new version becomes available)
c) fail immediately on any error, \fBexcept\fR when that error occurs during the
@world update \fBemerge\fR(1) (in which case, prompt whether or not to retry,
allowing the problem \(em for example, a missing use flag \(em to be fixed in
a separate terminal);
d) invoke most underlying tools (such as \fBbuildkernel\fR(8)) in interactive mode; and
e) invoke \fBdispatch-conf\fR(1) to resolve clashing configuration file updates.

In both interactive and non-interactive modes, \fBgenup\fR can be instructed
to skip the kernel rebuild check, using the \fB--no-kernel-upgrade\fR option
(see below).
.TP
.BR \-A ", " \-\-alert
If possible, sounds the terminal bell when interaction is needed.
Selecting this option automatically selects \fB--ask\fR.
.TP
.BR \-b ", " \-\-buildkernel\-args\=ADDITIONAL_ARGS
Passes the specified arguments to the main
.BR buildkernel (8)
invocation (the one used to create a new kernel in the \fI/boot\fR staging
area). These arguments are \fInot\fR passed to the second invocation, where used
(which copies the built kernel to from the staging area to the system
partition).
.TP
.BR \-c ", " \-\-dispatch\-conf
Always forces \fBdispatch-conf\fR(1) to be run, where necessary, even if
not in interactive mode.
.TP
.BR \-C ", " \-\-no\-custom\-updaters
Do not attempt to run any custom updaters found in
\fI/etc/genup/updaters.d\fR.
.TP
.BR \-d ", " \-\-deploy\-from\-staging
When a new kernel is available (and, if in interactive mode, you so request)
\fBgenup\fR will build that new kernel to the staging area in \fI/boot\fR 
(using \fBbuildkernel\fR(8) with the \fB--stage-only\fR option).
This ensures that the build can proceed without needing your boot USB key
(if used) to be inserted, so it can be completed in an unattended context.
When the \fB--deploy-from-staging\fR option is specified, \fBgenkernel\fR will
also attempt to deploy the new kernel (if any) at the end of the process
to your EFI system partition (NB, in
interactive mode, you will be asked whether you wish to do this anyway).

If you create a new kernel as the result of a \fBgenup\fR run, but do \fInot\fR
choose to deploy it at the time, you can always do so later by issuing:
\fBbuildkernel --ask --copy-from-staging\fR.
.TP
.BR \-e ", " \-\-emerge\-args\=ADDITIONAL_ARGS
Passes the specified arguments to the main
.BR emerge (1)
invocation. One possible use here is to specify:
.br
\fB--emerge-args="--autounmask-write"\fR

This instructs \fBemerge\fR(1) to automatically make any necessary changes to 
Portage configuration files to ensure that the process can proceed (adding
additional use flags, allowing libraries, and so on), provided the Portage
\fB--autounmask\fR option is enabled (which by default it is).
This can be useful when
running \fBgenup\fR in an unattended situation (assuming of course you are
comfortable with such changes being made automatically on your behalf; you
will of course still get a chance to review any changes made via
the \fBdispatch-conf\fR(1) mechanism).
Note also that if you do use this approach, you should also specify
the \fB--ignore-required-changes\fR option.
.TP
.BR \-h ", " \-\-help
Displays a short help screen, and exits.
.TP
.BR \-i ", " \-\-ignore\-required\-changes
By default, wqhen running in non-interactive mode, \fBgenup\fR checks to see if
the \fBemerge @world\fR step would fail due to required user changes
(to \fI/etc/portage/package.use\fR etc.), and stops with an error if so.
This option suppresses that check.

Note that specifying this option (in non-interactive mode) can result in cases
where your \fBgenup\fR run completes successfully, but the \fB@world\fR set
has \fBnot\fR, in fact, been brought fully up to date.

It has no effect in interactive mode.
.TP
.BR \-k ", " \-\-keep\-old\-distfiles
By default, \fBgenup\fR will remove any source tarballs that have previously
been downloaded by Portage, but which do not relate to the installed version of
any package.
This option inhibits such cleaning.
.TP
.BR \-n ", " \-\-no\-kernel\-upgrade
Do not perform (in non-interactive mode) or offer to perform (in interactive
mode) a kernel recompile, even should a newer version be available.
This option is implied if the \fBbuildkernel\fR USE flag is unset.

Note, this does \fBnot\fR itself prevent the update of \fBgentoo-sources\fR (or similar
package), during the @world \fBemerge\fR(1) step.
.TP
.BR \-p ", " \-\-no\-perl\-cleaner
Do not attempt to run \fBperl-cleaner\fR(1) during the process.
.TP
.BR \-P ", " \-\-no\-python\-updater
Do not attempt to run \fBpython-updater\fR(1) during the process.
.TP
.BR \-r ", " \-\-adjustment\=N
Specifies the \fBnice\fR(1) adjustment value N (-20<=N<=19) under which
to run \fBemerge\fR(1) and \fBbuildkernel\fR(8) operations.

If this option is unspecified, the default niceness adjustment value is 19,
which causes builds to run at the lowest possible
priority; this is useful to prevent \fBgenup\fR clogging up your
system. Be careful about using negative values!
.TP
.BR \-S ", " \-\-no\-eix\-sync
Do not attempt to run \fBeix-sync\fR(1) at the start of the process.
.TP
.BR \-v ", " \-\-verbose
Provides more verbose output from invoked tools, where possible.
.TP
.BR \-V ", " \-\-version
Displays the version number of \fBgenup\fR, and exits.

.TP
.BR \-x ", " \-\-eix\-sync\-args\=ADDITIONAL_ARGS
Passes the specified arguments to the main
.BR eix-sync (1)
invocation. One possible use here is to specify:
.br
\fB--eix-sync-args="-q"\fR

This instructs \fBeix-sync\fR(1) to suppress its otherwise verbose output
(which was the default behaviour of \fBgenup\fR prior to version 1.0.14).
.SH EXIT STATUS
The exit status is 0 if the update completed successfully, and 1 otherwise.
.SH PARALLEL MAKE
Quite frequently, large \fBemerge\fR(1) runs fail because one
or more of the invoked ebuilds have problems running with parallel
\fBmake\fR(1) (as set via MAKEOPTS="-jN", where N>1).

Because of this, \fBgenup\fR will attempt to
automatically resume any \fBemerge\fR(1) operation with parallel make
inhibited, should the original operation fail. A warning is issued if this
happens.

In a similar fashion, if you are using distributed compilation
with the \fBdistcc\fR and \fBdistcc-pump\fR features, these will be
automatically inhibited if operations are retried.
.SH AUTOMATING GENUP
Should you wish to run \fBgenup\fR automatically, you need to ensure it has
an appropriate environment.
For example, you could put the following script in
\fI/etc/cron.daily/genup\fR, to execute an update nightly (be sure to make
the file executable):
.nf
.RS

#!/bin/bash
export PATH="/usr/local/sbin:/usr/local/bin:"\\
"/usr/sbin:/usr/bin:/sbin:/bin:/opt/bin"
genup >/var/log/latest-genup-run.log 2>&1
.fi
.SH EFFECT OF USE FLAGS
If the \fBbuildkernel\fR USE flag is \fIun\fRset when \fBgenup\fR is emerged
(it is set by default), then in effect the \fB--no-kernel-upgrade\fR option
is always forced on, and as such
\fBgenup\fR will never attempt to call
\fBbuildkernel\fR(8).
This makes it suitable for use in an embedded context (where there may
be no EFI system partition etc.).
.SH EXTENDING GENUP
At the end of the main process, \fBgenup\fR will attempt to run any executable
files found in the \fI/etc/genup/updaters.d\fR directory
(symlinks to executable files are also OK). You can use this facility to add
your own custom update steps should you need to do so.

Should any such custom updater exit with a non-zero
exit status, \fBgenup\fR will also exit (immediately) with a failure code.

Note that you can suppress the running of custom updaters, by passing the
\fB--no-custom-updaters\fR option to \fBgenup\fR.
.SH USE WITH WEBRSYNC-GPG
If you have the webrsync-gpg FEATURE enabled in \fI/etc/portage/make.conf\fR,
\fBgenup\fR will select the -w option when calling \fBeix-sync\fR.
Since, in this
mode, \fBeix-sync\fR does not automatically sync (non-layman) overlays,
\fBgenup\fR will
call \fBemaint sync --auto\fR to do this for you, before \fBeix-sync\fR.

As such, you must make sure you have set "auto-sync = no" in
\fI/etc/portage/repos.conf/gentoo.conf\fR when using the webrsync-gpg FEATURE,
to prevent \fBemaint sync --auto\fR from also updating the main gentoo repo
using rsync (which will almost certainly not be what you want).

NB: most users will \fBnot\fR have the webrsync-gpg FEATURE set, and so should ignore
this note.
.SH COPYRIGHT
.nf
Copyright \(co 2014-2017 sakaki
License GPLv3+ (GNU GPL version 3 or later)
<http://gnu.org/licenses/gpl.html>

This is free software, you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.fi
.SH AUTHORS
sakaki \(em send bug reports or comments to <sakaki@deciban.com>
.SH "SEE ALSO"
.BR dispatch-conf (1),
.BR eclean (1),
.BR emerge (1),
.BR eix (1),
.BR eix-sync (1),
.BR emaint (1),
.BR nice (1),
.BR make (1),
.BR perl-cleaner (1),
.BR python-updater (1),
.BR buildkernel (8),
.BR revdep-rebuild (1),
.BR cron (8),
.BR portage (5).