An incorrect change for "show" command was fixed back.

[portsreinstall/current.git] / portsreinstall.8

.\" ==================================================================================
.\" ports reinstall installation guide
.\" Copyright (C) 2010-2012 Mamoru Sakaue, MwGhennndo, All Rights Reserved.
.\" ==================================================================================
.TH PORTSREINSTALL 8 "08 January 2011" "FreeBSD" "FreeBSD System Manager's Manual"
.SH NAME
portsreinstall \- ports upgrading utility for massive forced reinstallation
.SH SYNOPSIS
.B portsreinstall
[
.I
OPTIONS
] [
.I
command
]
.SH NOTATIONS
The "glob" is either of pkgname_glob or portorigin_glob explained in the man page of portsdb(1) and ports_glob(1): for example, zip\-3.0, zip\-*, and archivers .zip. Here the wild card symbol "*" must be quoted or escaped.
In evaluation of globs, ports_glob(1) is used if it is installed for better compatibility, otherwise an alternative internal function is used.
.SH DESCRIPTION
This utility is an alternative to portupgrade(1) and portmaster(8), and designed to be suitable for reinstallation of all packages after major version upgrade of the system or very long absence of ports upgrade.
Usually, execute with no option nor argument, or with \fB\-p\fR or \fB\-P\fR if you have installed portupgrade(1).
.SH ARGUMENTS
One of the following \fIcommands\fR can be given for optional operations or confirmation.
.TP
\fBdo\fR
Full execution (default).
.TP
\fBprepare\fR
Stop before the actual operations to the ports/packages.
.TP
\fBredo\fR
Execute again for failed ports and their dependents.
.TP
\fBclean\fR
Clean up the temporal database.
.TP
\fBok add\fR \fIglob1\fR [\fIglob2\fR ...]
Register manually resolved ports.
Each port globs are separated by commas or spaces.
.TP
\fBok del\fR \fIglob1\fR [\fIglob2\fR ...]
deregister manually resolved ports.
Each port globs are separated by commas or spaces.
.TP
\fBtaboo add\fR \fIglob1\fR [\fIglob2\fR ...]
Register taboo ports.
Each port globs are separated by commas or spaces.
.TP
\fBtaboo del\fR \fIglob1\fR [\fIglob2\fR ...]
Deregister taboo ports.
Each port globs are separated by commas or spaces.
.TP
\fBsave\fR [\fIdir\fR]
Save the current temporal database as a .tar.gz archive.
The file name is created automatically by containing the current date time.
By default save directory is the current directory.
.TP
\fBload\fR \fIpath\fR
Load a temporal database archive.
Note that the currently temporal database is removed.
.TP
\fBshow\fR [\fIarg\fR]
Show the list of ports to be reinstalled.
The following \fIargs\fR are available.
.IP
\fBtodo\fR : ports to be reinstalled (default)

\fBdone\fR : already reinstalled ports

\fBresolved\fR : manually reinstalled ports

\fBfailure\fR : failed ports

\fBtaboo\fR : taboo ports

\fBdeleted\fR : obsolete ports to be or have been deleted

\fBrequirements\fR \fIglob1\fR [\fIglob2\fR ...] : ports required by matching ports

\fBdependents\fR \fIglob1\fR [\fIglob2\fR ...] : ports depending on matching ports
.SH OPTIONS
The following options are available.
They must be given separately with each other.
.TP
\fB\-h\fR
Show short help.
.TP
\fB\-H\fR
Show this long help.
.TP
\fB\-V\fR
Show the current version.
.TP
\fB\-t\fR \fIglob1\fR[\fB,\fIglob2\fR[\fB,\fR...]]
Reinstall only target ports and their dependents.
Target ports which are not installed yet are newly installed.
Target ports which are obsolete are deinstalled.
This option can be given multiply.
This option is recognized in the first \fBdo\fR or \fBredo\fR runs, and transferred to the restarted runs.
Dependency relations are inspected for all installed packages as well.
Combination with options \fB\-T\f','\fB\-r\fR and \fB\-R\fR is available..
.TP
\fB\-r\fR \fIglob\fR
Reinstall only target ports and their dependents.
This option can be given multiply.
The difference from \fB\-t\fR is that only one port glob can be specified.
Thus a package name with commas is available.
Combination with options \fB\-t\fR, \fB\-T\fR and \fB\-R\fR is available.
.TP
\fB\-T\fR \fIglob1\fR[\fB,\fIglob2\fR[\fB,\fR...]]
Reinstall only target ports and their requirements.
Target ports which are not installed yet are newly installed.
Target ports which are obsolete are deinstalled.
This option can be given multiply.
This option is recognized in the first \fBdo\fR or \fBredo\fR runs, and transferred to the restarted runs.
Dependency relations are inspected for all installed packages as well.
Combination with options \fB\-t\fR, \fB\-r\fR and \fB\-R\fR is available.
.TP
\fB\-R\fR \fIglob\fR
Reinstall only target ports and their requirements.
This option can be given multiply.
The difference from \fB\-T\fR is that only one port glob can be specified.
Thus a package name with commas is available.
Combination with options \fB\-t\fR, \fB\-r\fR and \fB\-T\fR is available.
.TP
\fB\-x\fR \fIglob1\fR[\fB,\fIglob2\fR[\fB,\fR...]]
Set the port glob(s) to be taboo.
This option registers a port to be ignored as taboo.
This option can be given multiply.
Mainly for ports that show terrible behaviors resulting in system crash.
This option is recognized in the first \fBdo\fR or \fBredo\fR runs, and transferred to the restarted runs.
Alternatively you can do the same thing by
.B portsreinstall taboo
.I globs
.
If you want to register permanently, set to the configuration file.
Combination with options \fB\-X\fR is available.
.TP
\fB\-X\fR \fIglob\fR
This option can be given multiply.
The difference from \fB\-x\fR is that only one port glob can be specified.
Thus a package name with commas is available.
Combination with options \fB\-x\fR is available.
.TP
\fB\-p\fR
Import settings from pkgtools.conf(5) as the primary (Default; ignored if ports\-mgmt/portupgrade* is not installed).
For duplicated configurations, values in pkgtools.conf(5) are applied first and then those in portsreinstall.conf are.
This option is ignored when you restart a terminated process.
.TP
\fB\-P\fR
Import settings from pkgtools.conf(5) as the secondary (Ignored if ports\-mgmt/portupgrade* is not installed).
For duplicated configurations, values in portsreinstall.conf are applied first and then those in pkgtools.conf(5) are.
This option is ignored when you restart a terminated process.
.TP
\fB\-Q\fR
Ignore pkgtools.conf(5) even if it exists.
This option is ignored when you restart a terminated process.
.TP
\fB\-s\fR
Build of vulnerable ports are avoided by triggering errors.
Note that already installed vulnerable packages are untouched.
If you desire to uninstall them, do it manually.
This specification will be reasonable for the practical situations.
This option is fixed at the first \fBdo\fR run, and transferred to the following runs.
If you want to continue the reinstallation process by resetting this option, execute by \fBredo\fR command with \fB\-N\fR option.
.TP
\fB\-q\fR
Ports whose all requirements and themselves are not new are skipped.
This option is safe and useful when the all of the major version of the system, configuration options of each ports, pkgtools.conf(5), portsreinstall.conf are unchanged.
This option is fixed at the first \fBdo\fR run, and transferred to the following runs.
If you want to continue the reinstallation process by resetting this option, execute by \fBredo\fR command with \fB\-N\fR option.
.TP
\fB\-d\fR
Do not clean up obsolete or unused distfiles.
This option is fixed at the first \fBdo\fR run, and transferred to the following runs.
If you want to continue the reinstallation process by resetting this option, execute by \fBredo\fR command with \fB\-N\fR option.
.TP
\fB\-N\fR
Renew option settings.
This option is effective only with \fBredo\fR command.
Option settings for \fB\-s\fR, \fB\-q\fR and \fB\-d\fR are reset according to the simultaneously given ones.
.TP
\fB\-k\fR
Keep portsreinstall itself untouched.
This option supresses update, deinstallation and reinstallation of the currently installed portsreinstall.
.TP
\fB\-c\fR
Suppress cleaning the temporal database even if its obsolete.
By default, the temporal database is automatically cleaned up if it is older than the ports tree or portsreinstall itself is to be updated.
This option replace this behavior with termination with warnings.
This option should not be used unless the user has special intentions.
.SH DETAILS
This utility realizes smart reinstallation of a large number of ports by allowing you to run when when the machine is free and terminate when busy.
Concretely, you can stop the process by CTRL+C anytime and restart quickly.
This functionality allows you, for example, to start this utility before lunch, terminate after lunch, restart before dinner, terminate after dinner, restart before going to bed, terminate after breakfast, restart before lunch, ..., and finally complete.
.PP
The policy of this utility is to complete the job by the most automatic and finally successful way even if it will take a long time in total.
All missing build\- and run\-time dependencies are newly installed if any.
All reinstallation processes are tried to be proceeded forcibly by ignoring errors or vulnerabilities as possible.
This utility pursues the consistency of the dependency relations in the latest version of the ports tree by on-the-fly entire reconstruction of the relations while portupgrade(1) and portmaster(8) believe the existing relations of the installed packages to reduce the total work time as much as possible.
.PP
In the simplest case, all a user has to do toward complete reinstallation is execute this utility without any arguments (corresponding to \fBdo\fR command).
If the run completes with notations on failures for any ports, after resolving the errors manually, register the resolved ports by executing this utility with \fBok add\fR command and then execute with \fBredo\fR command.
This task is continued until successful completion.
.PP
The algorithms of this utility are customized for massive reinstallation to be invoked after major upgrade of the system where rebuild of all third\-party applications are encouraged before cleaning up obsolete system libraries.
Nevertheless, the all functionalities of this utility is applicable to any situations where complete reinstallation of the all or parts of ports is preferred, e.g., when you have been lazy in upgrade of ports for too long time.
For the usual purposes of upgrading packages installed by ports, you are recommended to use ports\-mgmt/portupgrade or ports\-mgmt/portmaster instead.
.PP
If this utility has been installed by ports/packages and the corresponding port is renewed, update of this utility is carried out first and then the following processes are continued by the new version after cleaning up the temporal database.
.PP
The scheme of this utility is divided into the temporal database construction phase and the reinstallation phase.
Execution by
.B portsreinstall prepare
procedes to the end the first phase, and that without any argument procedes to the end of the second phase.
Each of these two major phases is divided into minor phases.
When a previously terminated process is restarted, completed minor phases are skipped.
.PP
The massive minor phases belong to "collecting dependencies of installed/missing packages", "ordering dependencies" for the first major phase and "reinstallation" "package database update" for the second.
Most of them are divided into more minor phases except for "package database update".
.PP
When option(s) \fB\-t\fR,  \fB\-r\fR, \fB\-T\fR or \fB\-R\fR is/are given in the first run of \fBdo\fR or \fBredo\fR commands, only the targets and their required or dependent ports are reinstalled.
This specification is effective until the completion of the run.
Run by \fBredo\fR command without the options inherits the previous settings.
Meanwhile, run by \fBredo\fR command with the options resets the previous settings, and inspects the dependencies again if new ports are to be installed.
.PP
The user is encouraged to run this utility under script(1) so as to record all logs in order to resolve problems that you may (rather "will", practically) encounter.
The solutions depend on the individual cases.
If the problem will be resolved by reconfiguration of the port option, execute
.B make config
at the corresponding port directory, and then restart this utility.
If the problem will be resolved by manual fetch of tarballs, do it and then restart this utility.
If the problem will be resolved by deleting a concerned package, do it by
.B pkg_delete \-f
.I package
(conventional package),
.B pkg delete \-f
.I package
(new generation package, pkgng) or execute
.B make deinstall
at the corresponding port directory, execute
.B portsreinstall ok add
.I glob
where \fIglob\fR is the ports glob of the concerned port, and then restart this utility.
If the problem will be resolved by manual reinstallation using pkg_add(1) (conventional package), pkg add (pkg\-add(8), pkgng) or so on, do it and execute
.B portsreinstall ok add
.I glob
where \fIglob\fR is the ports glob of the concerned port, and then restart this utility by
.B portsreinstall redo
command.
.PP
The current package system is automatically detected; the new generation package (pkgng) is used if it is installed and 'WITH_PKGNG=yes' is set and "WITHOUT_PKGNG=yes" is not set /etc/make.conf, and otherwise the conventional package is used.
.PP
If you are familiar to the mechanism of Ports Collections system, in order to minimize package conflictions, it may be a good idea to delete packages which you don't think necessary before starting to use this utility.
Don't be afraid to delete necessary dependencies because all required ports are automatically installed.
.PP
If you run into confusion, it may be a good idea to clean up the temporal database by executing
.B portsreinstall clean
and start again from the first.
.SH "ENVIRONMENT VARIABLES"
The following environment variables can be used to change the behavior of \fBportsreinstall\fR.
Usually they should be kept to be the system default or empty.
.TP
.B PORTSDIR
Location of the ports tree.
See also ports(7).
.TP
.B PREFIX
Where to install things in general (/usr/local by default).
.SH FILES/DIRECTORIES
The following files and directories are referred to.
.TP
${PREFIX}/etc/portsreinstall.conf
Configuration file.
.TP
/var/tmp/portsreinstall.db
Temporal database directory.
The whole contents can be saved by \fBportsreinstall save\fR command.
.TP
${PREFIX}/etc/pkgtools.conf
Configuration file of portupgrade(1).
.SH HISTORY
\fBportsreinstall\fR has been developed as below.
.TP
2.0.1 (09 December 2012)
[NEW] New generation package (pkgng) is supported.

[IMPROVED] A countermeasure for a build failure in a restarted build from a terminated build is implemented.

[BUG FIX] Restoration of backup packages after failed installation was not working correctly.

[BUG FIX] The transferring mechanism of option values to restarted run was broken.

[BUG FIX] Error end in case that no packages are installed is fixed.
.TP
2.0.0 (12 August 2012)
[NEW] Options \fB\-X\fR, \fB\-r\fR and \fB\-R\fR are added so as to compensate a fact that \fB\-x\fR, \fB\-t\fR and \fB\-T\fR cannot specify package names with commas.

[NEW] Commands of \fBshow requirements\fR and  \fBshow dependents\fR are added.

[NEW] A functionality of self-update is added so as to be carried out first if the port of portsreinstall is new.

[NEW] Option \fB\-k\fR is added for cases that update of portsreinstall should be avoided.

[IMPROVED] Messages are extended to output configuration parameter values.

[CHANGED] Functionalities of options \fB\-t\fR and \fB\-T\fR are changed so as to prevent deinstallation of irrelevant packages and detect obsolete installed dependencies.

[CHANGED] Use of commas as delimiters in \fBok\fR and \fBtaboo\fR commands is abolished.

[CHANGED] The specification of \fBshow\fR command is changed to exclude irrelevant packages/ports and output messages about the matching targets when options \fB\-r\fR, \fB\-R\fR, \fB\-t\fR and \fB\-T\fR are enabled.

[CHANGED] The default behavior in case that the temporal database is older than the ports tree is changed from warnings to automatic reconstruction; the old behavior is recovered by option \fB\-c\fR.

[BUG FIX] Termination message is corrected (portsreinstall ok => portsreinstall ok add).

[BUG FIX] Values of BEFOREBUILD, BEFOREDEINSTALL and AFTERINSTALL were not correctly imported from pkgtools.conf(5).

[BUG FIX] The file name given by save command was with a wrong time stamp.
.TP
1.1.0 (28 April 2012)
[NEW] Command of show deleted is newly added.

[CHANGED] Origin names in messages and results of show command are changed to be accompanied with package names.

[CHANGED] The default option for treating pkgtools.conf(5) is changed to \fB\-p\fR and \fB\-Q\fR is newly added.

[IMPROVED] Custom make environment variables and arguments are changed to be reflected in the phase of inspection of dependencies.

[IMPROVED] Command of show todo is now available before starting reinstallation.

[BUG FIX] Independence from ports\-mgmt/portupgrade* was incomplete.

[BUG FIX] Error messages for show command when the temporal database does not exist are improved.

[BUG FIX] Ports with names contaning '+' were not correctly treated.

[BUG FIX] Save and load commands were broken.

[BUG FIX] Deletion of MOVED-back packages is now prevented.
.TP
1.0.0 (14 March 2012)
[MISC] Explanations for \fB\-p\fR and \fB\-P\fR are revised because the previous ones were somewhat confusing.

[MISC] The output device of helps is changed from stderr to stdout.

[MISC] Messages for termination during deinstallation and reinstallation are improved by showing the target port/package names at that time.

[BUG FIX] Glob patterns for package/port names were not fully supported.

[BUG FIX] Values of MARG_* and MENV_* (MAKE_ARGS and MAKE_ENV in pkgtools.conf(5)) were not working.

[BUG FIX] Globs of obsolete packages were not detected, so especially HOLD_PKGS and IGNORE_MOVED in pkgtools.conf(5) and portsreinstall.conf had lost their functionalities.

[BUG FIX] Values of IGNORE_MOVED partially overwrote HOLD_PKGS in pkgtools.conf(5).

[BUG FIX] Typographic and grammatical errors in the main script and documents are revised.
.TP
0.13.1 (29 October 2011)
[BUG FIX] Inspection of missing ports was incomplete.

[BUG FIX] Origin names with '+' were not correctly treated.

[IMPROVED] Inspection of dependencies of installed packages gets faster.
.TP
0.13.0 (28 August 2011)
[IMPROVED] Phase of "Order the ports considering dependencies" is accelerated.
.TP
0.12.0 (22 June 2011)
[NEW] \fB\-q\fR, \fB\-d\fR and \fB\-N\fR options are added.

[CHANGED] Settings for \fB\-x\fR and \fB\-s\fR options becomes to be transferred to restarted runs.
.TP
0.11.0 (17 May 2011)
[NEW] Causes of errors are added to the report of failed ports.

[CHANGED] Functionality of \fB\-t\fR option is changed and partly splitted into \fB\-T\fR.

[IMPROVED] Refetch after fetch failure becomes smarter so as not to clean up distfiles.

[MISC] Terminology 'abort' is corrected to be 'terminate'.
.TP
0.10.0 (11 Mar 2011)
[NEW] Version check for temporal database and portupgrade is added (as a template).

[BUG FIX] Old packages for ports whose package names was renamed were not deleted.

[BUG FIX] Duplicated cleans were executed after successful installation.
.TP
0.9.8 (02 Mar 2011)
[MISC] Installation methods of non-executable files in Makefile are improved again.
.TP
0.9.7 (02 Mar 2011)
[MISC] Installation methods of non-executable files in Makefile are improved.
.TP
0.9.6 (01 Mar 2011)
[BUG FIX] Fix at version 0.9.5 was incomplete.

[BUG FIX] The update date of 0.9.5 was wrong in the manpage.
.TP
0.9.5 (28 Feb 2011)
[BUG FIX] "install" target in Makefile installed non-executable files as executables.
.TP
0.9.4 (17 Jan 2011)
[BUG FIX] "all" target in Makefile was missing.
.TP
0.9.3 (16 Jan 2011)
[MISC] Makefile is modified to compress manpage in the build process.
.TP
0.9.2 (10 Jan 2011)
[MISC] The 2-Clause BSD License is applied from this version.

[NEW] Manpage is created.

[NEW] Makefile for installation/uninstallation is added.

[BUG FIX] Recovery from distfile checksum error was broken.
.TP
0.9.1 (27 Dec 2010)     
[BUG FIX] Wrong warning for \fB-p\fR/\fB-P\fR options in the first run.

[BUG FIX] Broken support of recursive chase of MOVED ports.

[BUG FIX] Option configuration menus were not accessable.

[BUG FIX] The mechanism of loading the configuration file was broken.

[BUG FIX] Optionally added taboo ports were not always effective in restart.
.TP
0.9.0 (21 Nov 2010)
First version.
.SH "SEE ALSO"
pkg_glob(1),
portupgrade(1),
pkgtools.conf(5),
ports(7),
portmaster(8)
.SH COPYRIGHT
This software is distributed under the 2-Clause BSD License.
.PP
(C)\ 2010\-2011\ Mamoru\ Sakaue,\ MwGhennndo,\ All\ Rights\ Reserved.
.PP
Email:\ sakaue.mamoru@samurai.mwghennn.net
.PP
Homepage:\ http://www.mwghennndo.com/softwares/portsreinstall/