# ==============================================================================
# portsreinstall library script
# - Help messages -
-# Copyright (C) 2013 Mamoru Sakaue, MwGhennndo, All Rights Reserved.
+# Copyright (C) 2018 Mamoru Sakaue, MwGhennndo, All Rights Reserved.
# This software is distributed under the 2-Clause BSD License.
# ==============================================================================
# ============= Output a short help =============
usage_short ()
{
- fold -s -w `misc_get_console_column_size` << eof
-USAGE: ${APPNAME} [OPTIONS] [--] [command]
-
-[OPTIONS]
- <Group 1: Just show messages and exit without operation>
- -H : Show a long help whose content is the same as the manual page.
- -h : Show this short help.
- -V : Show the current version.
- <Group 2: Effective anytime>
- -a : Suppress messages to be batch-friendly.
- -i : Include new targets to the "needed" list.
- -M : Reset group 4 option settings.
- <Group 3: Effective only with redo command>
- -L : Reload configuration files and reset group 6 option settings.
- -N : Reset group 5 option settings.
- <Group 4: Saved and transferred to restarted runs, renewable by -M option>
- -A : Only non-interactive ports are (re)installed.
- -B : Exclude run-time dependencies in evaluation of dependencies.
- -b : Include build-time dependencies in evaluation of dependencies.
- -C : Skip "make config" by applying default port options if unconfigured.
- -c : Suppress cleaning the temporary database even if its obsolete.
- -D : Suppress entire inspection of distinfo in the ports tree.
- -d : Do not clean up obsolete or unused distfiles.
- -G : Use prebuilt packages for ports with the default configurations.
- -g : Keep ports-mgmt/pkg untouched.
- -I : Only interactive ports are (re)installed.
- -k : Keep ${APPNAME} itself untouched.
- -l : Use legacy packages when prebuilt pkgng packages are missing.
- -n : No operation is carried out (just for seeing what will be done).
- -q : Only new ports and their run-time requirements are reinstalled.
- -s : Build of vulnerable ports are avoided by triggering errors.
- -X : Deselect all deinstallation candidates.
- -Y : Select all deinstallation candidates.
- <Group 5: Saved and transferred to restarted runs, renewable by -N option>
- -O glob1[:glob2[:...]] : Reinstall only target ports themselves.
- -o : Ignore ports which are outside of target scopes of -O, -T or -t options.
- -T glob1[:glob2[:...]] : Reinstall only target ports and their requirements.
- -t glob1[:glob2[:...]] : Reinstall only target ports and their dependents.
- <Group 6: Saved and transferred to restarted runs, renewable by -L option>
- -P : Import settings from pkgtools.conf(5) as the secondary if exists.
- -p : Import settings from pkgtools.conf(5) as the primary if exists (default).
- -Q : Ignore pkgtools.conf(5) even if it exists.
-
- *NOTE*
- The configuration of options annotated as "saved and transferred to restarted runs" are saved in the temporary database by the first run after cleaning the database. In the following runs, the corresponding option settings are loaded from the saved configuration if executed with no option or exactly the same option set as the saved one. Otherwise, the option settings are renewed for possible ones and the others are loaded from the saved configuration. Then the saved configuration is updated with the renewed settings.
-
-[ARGUMENTS]
- command: do [all] (default) | [do] prepare | redo [all] | redo prepare
- | clean [normal] | clean force | reset [all] | reset keepopts
- | ok add globs... | ok del globs...
- | taboo add globs... | taboo del globs...
- | noneed add globs... | noneed del globs...
- | reselect leaves | reselect obsolete
- | save [dir] | load path | glob globs... | options
- | reconf globs... | forget globs...
- | show todo | show done | show resolved | show failure | show redo
- | show taboo | show need | show noneed | show restored | show deleted
- | show conflict | show requirements glob... | show dependents glob...
- | show initrequirements glob... | show initdependents glob...
-
-[DESCRIPTIONS]
- 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, you can execute with no option nor argument. If portupgrade(1) is installed, compatibility with it is taken into account by importing pkgtools.conf(5) and rebuilding the package database.
-eof
+ usage_short_content | fold -s -w `misc_get_console_column_size`
}
+# ============= Content of the short help =============
+usage_short_content () { :; }
+
# ============= Output a long help =============
usage_long ()
{
- zcat "`whereis -qm \"${APPNAME}\"`" | nroff -man
-# fold -s -w `misc_get_console_column_size` << eof
-#
-# USAGE: ${APPNAME} [OPTIONS] [--] [command]
-#
-# [OPTIONS]
-# If duplicated or conflicting ones are set, last ones are effective. The end of options can be explicitly specified by "--". Short options can be given in compact forms, for example, "-i -q -P" to be "-iqP".
-# <Group 1: Just show messages and exit without operation>
-# -h
-# --help
-# --short-help
-# Show a short help.
-# -H
-# --long-help
-# Show this long help.
-# -V
-# --show-version
-# Show the current version.
-# <Group 2: Effective anytime>
-# -a
-# --batch-mode
-# Suppress messages so as to be friendly for batch operations.
-# The output format for show command is changed to be more batch-friendly.
-# It is noted that Log output in build/installation processes are not
-# suppressed.
-# -M
-# --reset-minor-options
-# Reset option settings for minor controls.
-# Option settings for group 4 are once reset and replaced with
-# the newly specified ones.
-# <Group 3: Effective only in the initial run by redo command>
-# -N
-# --reset-targets
-# Re-scan installed packages and reset option settings for target
-# specification.
-# This option is effective only with "redo" command.
-# Option settings for group 5 are once reset and replaced with
-# the newly specified ones.
-# -L
-# --reload-conf
-# Reload configuration files.
-# This option is effective only with "redo" command.
-# Option settings for group 6 are once reset and replaced with
-# the newly specified ones.
-# <Group 4: Saved and transferred to restarted runs, renewable with -M option>
-# Option settings in this group are saved at the first "do" or "prepare" run,
-# and transferred to the following runs. Reset of the saved values for this
-# group is available by appending "-M" with newly specified options.
-# -C
-# --apply-default-config
-# The temporary database is built by skipping executing "make config" and
-# applying default port options if unconfigured.
-# -A
-# --non-interactive-ports-only
-# Operations of (re)installation are made only on ports which do not
-# require manual interaction.
-# This option conflicts with -I.
-# -I
-# --interactive-ports-only
-# Operations of (re)installation are made only on ports which require
-# manual interaction.
-# This option conflicts with -A.
-# -s
-# --avoid-vulnerability-check
-# 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.
-# -q
-# --skip-unchanged-ports
-# Only new ports and their dependents are reinstalled.
-# This option is convenient when the all of the major version of
-# the system and configurations of ports (options and knobs) are
-# unchanged.
-# The behavior can be modified by -b option.
-# -b
-# --include-buildtime-dependencies
-# Include build-time dependencies in evaluation of dependencies.
-# This option affects behaviors of "-t", "-T" and "-q" options.
-# -B
-# --exclude-runtime-dependencies
-# Exclude run-time dependencies in evaluation of dependencies.
-# This option affects behaviors of "-t", "-T and "-q" options.
-# -d
-# --keep-distfiles
-# Do not clean up obsolete or unused distfiles.
-# -k
-# --suppress-self-upadte
-# Keep ${APPNAME} itself untouched.
-# This option suppresses upgrade, deinstallation and reinstallation of
-# the currently installed ${APPNAME}.
-# -g
-# --suppress-pkgng-upadte
-# Keep ports-mgmt/pkg untouched.
-# This option suppresses upgrade, deinstallation and reinstallation of
-# the currently installed ports-mgmt/pkg (pkgng).
-# -c
-# --suppress-clean-obsolete-database
-# Suppress cleaning the temporary database even if its obsolete.
-# This option suppresses the default behavior that the temporary database
-# is automatically cleaned up if it is older than the ports tree or
-# ${APPNAME} itself is to be upgraded.
-# Use of this option may cause unexpected results and basically
-# unrecommended.
-# -D
-# --suppress-entire-inspection-distinfo
-# Suppress entire inspection of distinfo files in the ports tree as a
-# preparation for deleting obsolete distfiles.
-# By default, viz., without this option, all distfiles are preserved
-# unless being obsolete in the current version of the ports tree.
-# For this purpose, entire inspection of distinfo files in the ports tree
-# is carried out in order to get the complete list of distfiles.
-# This inspection can take an extremely long time if the ports tree is
-# located in file systems with low access speeds.
-# With this option specified, distfiles for ports are deleted unless they
-# are initially installed, added due to -i option, or required by any of
-# the installed or added ports.
-# -n
-# --dry-run
-# No operation is carried out (just for seeing what will be done).
-# This option is effective for "do" and "redo" commands so that no
-# deinstallation and (re)installation process is actually carried out.
-# By this option, ports/packages to be deinstalled or (re)installed can be
-# confirmed without making changes to the current situation of packages.
-# -X
-# --deselect-all
-# Automatically deselect all candidates for deinstallation of leaf or
-# obsolete ports.
-# This option conflicts with "-Y" option.
-# -Y
-# --select-all
-# Automatically select all candidates for deinstallation of leaf or
-# obsolete ports.
-# This option conflicts with "-X" option.
-# <Group 5: Saved and transferred to restarted runs, renewable with -N option>
-# Option settings in this group are saved at the first "do" or "prepare" run,
-# and transferred to the following runs. Reset of the saved values for this
-# group is available in the initial run of "redo" command by appending "-N"
-# with newly specified options.
-# -t glob1[:glob2[:...]]
-# --target-and-dependents=glob1[:glob2[:...]]
-# Reinstall only the specified target ports and their dependents.
-# Target ports must be already installed.
-# Target ports which are obsolete are deinstalled.
-# Dependencies are inspected for all installed packages as well as usual.
-# Combination with options "-T" or "-O" is available.
-# The behavior can be modified by "-B", "-b", "-i" and "-o" options.
-# -T glob1[:glob2[:...]]
-# --target-and-requirements=glob1[:glob2[:...]]
-# Reinstall only the specified target ports and their requirements.
-# Target ports must be already installed.
-# Target ports which are obsolete are deinstalled.
-# Dependencies are inspected for all installed packages as well as usual.
-# Combination with options "-t" or "-O" is available.
-# The behavior can be modified by "-B", "-b", "-i" and "-o" options.
-# -O glob1[:glob2[:...]]
-# --target-only-itself=glob1[:glob2[:...]]
-# Reinstall only the specified target ports themselves.
-# Target ports must be already installed.
-# Target ports which are obsolete are deinstalled.
-# Dependencies are inspected for all installed packages as well as usual.
-# Combination with options "-t" or "-T" is available.
-# The behavior can be modified by "-B", "-b", "-i" and "-o" options.
-# -i
-# --add-targets-to-needed
-# Include not-yet-installed targets to newly install.
-# This option is available only when given with "-O", "-t" or "-T"
-# options.
-# Each of globs specified by "-O", "-t" or "-T" options must match one
-# unique port.
-# For each ambiguous glob, if any, a dialog is displayed for selecting
-# ports to install.
-# -o
-# --only-target-scope
-# Inspect dependencies only for currently specified targets, already
-# inspected ones in former runs, and their least requirements so as to
-# grow the temporary database in the least level.
-# This option is available only when given with "-O", "-t" or "-T"
-# options.
-# If given with "-t", targets themselves and their not-yet-installed
-# direct requirements are (re)installed but already-installed requirements
-# are kept untouched even their ports are updated.
-# Dependents of "-t" targets are (re)installed only if they are least
-# requirements of other targets or already inspected in former runs.
-# If given with "-T", targets themselves and their direct requirements are
-# (re)installed.
-# This option is effective for saving times in pinpoint upgrades or new
-# installation, however, becomes less effective if the temporary database
-# has been already built for the all installed ports.
-# Typically, when the temporary database has not been built,
-# ${APPNAME} -oiO glob
-# is the quickest way to install a new package whose port glob is "glob".
-# <Group 6: Saved and transferred to restarted runs, renewable with -L option>
-# Option settings in this group are saved at the first "do" or "prepare" run,
-# and transferred to the following runs. Reset of the saved values for this
-# group is available in the initial run of "redo" command by appending "-L"
-# with newly specified options.
-# -p
-# --load-pkgtoolsconf-as-default
-# Import settings from pkgtools.conf(5) as the primary (default).
-# This option is effective only when ports-mgmt/portupgrade* is installed.
-# For duplicated configurations, values in pkgtools.conf are applied
-# first and then those in ${APPNAME}.conf are.
-# This option overrides preceding "-P" option.
-# -P
-# --load-pkgtoolsconf-as-override
-# Import settings from pkgtools.conf(5) as the secondary.
-# This option is effective only when ports-mgmt/portupgrade* is installed.
-# For duplicated configurations, values in ${APPNAME}.conf
-# are applied first and then those in pkgtools.conf are.
-# This option overrides preceding "-p" option.
-# -Q
-# --ignore-pkgtoolsconf
-# Ignore pkgtools.conf(5) even if it exists.
-#
-# *NOTE*
-# The configuration of options annotated as "saved and transferred to restarted/following runs" are saved in the temporary database by the first run after cleaning the database. In the following runs, the corresponding option settings are loaded from the saved configuration unless explicitly reset by -L, -M or -N option which updates the saved configuration.
-#
-# [ARGUMENTS]
-# command: (For optional operations or confirmation)
-# {one of the following commands}
-# do [all] : Full execution (default)
-# [do] prepare : Just (continue to (re-)) build the temporary database
-# redo [all] : Execute again for failed ports and their dependents
-# redo prepare : Just rebuild the temporary database for the redo process
-# clean [normal] : Clean up the temporary database
-# clean force : Clean up the temporary database forcedly
-# reset [all]: Reset the temporary database by keeping the initial snapshot
-# reset keepopts: Same as "reset all" but option settings are also kept
-# ok add glob1 [glob2 ...] : Register manually resolved ports
-# ok del glob1 [glob2 ...] : Deregister manually resolved ports
-# taboo add glob1 [glob2 ...]: Register taboo ports
-# taboo del glob1 [glob2 ...]: Deregister taboo ports
-# noneed add glob1 [glob2 ...]: Register unnecessary ports
-# noneed del glob1 [glob2 ...]: Deregister unnecessary ports
-# reselect leaves: Reselect leaf ports to delete
-# reselect obsolete: Reselect obsolete ports to delete
-# save [dir] : Save the current temporary database as a .tar.gz archive
-# load path : Load a temporary database archive
-# glob glob [glob2 ...] : Evaluate port globs and show matched origins
-# options : Show saved option settings and expected effects of -L, -M and -N
-# reconf glob [glob2 ...] : Reset information on the ports
-# forget glob [glob2 ...] : Remove information on for added ports
-# show [args] : Show the list of ports to be reinstalled
-# todo : Ports to be reinstalled in the current do/redo process
-# (default)
-# done : Already reinstalled ports
-# resolved : Manually reinstalled ports
-# failure : Failed ports
-# redo : Ports succeeded once but to be reinstalled in the next redo
-# process
-# pending : Ports to be reinstalled after success in their
-# requirements
-# taboo : Taboo ports
-# noneed : Unnecessary ports
-# deleted : Obsolete ports to be or have been deleted
-# conflict : Conflicting ports which are temporarily deleted
-# requirements glob1 [glob2 ...] : Ports required by matching ports
-# dependents glob1 [glob2 ...] : Ports depending on matching ports
-#
-# [CONFIGURATION FILE]
-# ${CONFFILE}
-#
-# [NOTATIONS]
-# A "glob" is an extended regular expression or a shell-type glob pattern matching either of a unique name, package names or port origins. The glob syntax is compatible with portupgrade(1) and its accompaniments such as portsdb(1) and ports_glob(1). If a glob starts with a colon ":", the following string is parsed as an extended regular expression, and otherwise a shell-type glob. A shell-type glob is evaluated by matching an asterisk "*" to an arbitrary string of an arbitrary length, a question mark "?" to an arbitrary single character, characters "..." enclosed in a bracket "[...]" to a single character as one of the characters and characters "..." in a bracket "[!...]" to a single character matching none of the characters. Here, the evaluation of the bracket is actually done by passing it to an extended regular expression by simply converting the prefix "[!" to "[^". A glob is recognized as a unique name (package name without the version part) if no slash "/" or any special character for an extended
-# regular expression or a shell-type glob is included in the pattern. For example, all of "zip" "zip-3.?", "zip-*", "zip-[0-9]*" and ":^zip-[[:digit:]]+\.*" can match zip-3.0; "archivers/unzip*" can match both of "archivers/unzip" and "archivers/unzip-iconv".
-#
-# [DESCRIPTIONS]
-# This utility is a ports/packages management tool which upgrades packages to be as much as consistent regarding their dependencies. The implementation of thie utility is designed for smart entire reinstallation of installed packages which takes a very long time. In a standard case, the entire reinstallation will procede in the following step:
-# 1. Clean up a temporary database which stores the all information used for the whole task of reinstallation;
-# 2. Record the snapshot of the all installed packages as the initial point of reinstallation;
-# 3. Build up the database to store settings of the all (re/de)installing packages to be the latest version within the current ports tree;
-# 4. Select obsolete packages or new leaf ports/packages to deinstall or exclude if any;
-# 5. Execute the actual (re/de)installation by "do" command;
-# 6. If some ports failed, execute the (re/de)installation again by "redo" command;
-# 7. Repeat this process until the all available ports succeed.
-# A typical instance of acutally executed commands for upgrading packages could be as follows:
-# portsnap fetch update
-# ${APPNAME} -q
-# ( End up with some failed ports )
-# ${APPNAME} redo
-# ( End up with some failed ports )
-# ... Countermeasure to failures ...
-# ${APPNAME} redo
-# ( End up with some failed ports )
-# .
-# .
-# .
-# ${APPNAME} redo
-# ( All available ports succeed )
-# Here, in case of entire reinstallation after a major verion upgrade of the operating system, "-q" option should be removed.
-#
-# This utility has a flexible and robust feature of interrupt/restart operations which allows the users to run only when the machine is free and terminate when it becomes busy on demand. Concretely, the users can stop the process by CTRL+C (or even by unexpected termination) and restart from the stopped point at any stage throughout the whole task, i.e., from the beginning of prepation of the temporary database to the end of (re/de)installation. This functionality allows the users, 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.
-#
-# Compatibility with portupgrade(1) is well considered if it is installed; settings in pkgtools.conf(5) are reflected and the portupgrade database is updated at the end of each do/redo run. The main difference of this utility with portupgrade(1) or portmaster(8) is that this utility is optimized for on-the-fly entire entire upgrade of the packages environment to be as complete as possible while the latter are for partial upgrade to get the latest versions available as quickly as possible by applying the least "patches" to the environment. While this utility also has options for partial upgrade (-t, -T and -O), they are intended as auxiliary modification of (re)installing packages. Many of the UPDATING advisories on trouble shooting in packages upgrade will be unecessary to follow if the users use this utility instead of portupgrade(1) or portmaster(8).
-#
-# In the simplest case, all a user has to do toward complete reinstallation is execute this utility without any arguments (corresponding to "do" 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 "ok add" command and then execute with "redo" command. This task is continued until successful completion.
-#
-# 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.
-#
-# If this utility has been installed by ports/packages and the corresponding port is renewed, upgrade of this utility is carried out first and then the following processes are continued by the new version after cleaning up the temporary database.
-#
-# The scheme of this utility is divided into the temporary database construction phase and the reinstallation phase.
-# Execution by "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 the previously terminated process is restarted, completed minor phases are skipped.
-#
-# 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".
-#
-# When option(s) "-O", "-t" or "-T" is/are given in the initial run of "do" or "redo" commands, only the targets and their required or dependent ports are reinstalled (or deleted if obsolete).
-# This specification is effective until the completion of the run.
-# Run by "redo" command without the options inherits the previous settings.
-# Meanwhile, run by "redo" command with the options resets the previous settings, and inspects the dependencies again if new ports are to be installed.
-#
-# 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 "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 "pkg_delete -f {package}" (conventional package), "pkg delete -f {package}" (new generation package, pkgng) or execute "make deinstall" at the corresponding port directory, then execute "${APPNAME} ok add \$glob" where "\$glob" 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 glob of execute "${APPNAME} ok add \$glob" where "\$glob" is the ports the concerned port, and then restart this utility by "redo" command.
-#
-# The current package system is automatically detected according to the OS version whose serial number is obtained by "sysctl -n kern.osreldate" and configuration of /etc/make.conf; pkgng is used for serial versions from 800505 (just before 8.1-RELEASE) to before 1000017 (10-CURRENT) if "WITH_PKGNG=yes" is set and for 1000017 or later if "WITHOUT_PKGNG=yes" is not set.
-#
-# 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.
-#
-# If you run into confusion, it may be a good idea to clean up the temporary database by executing "${APPNAME} clean" and start again from the first.
-# eof
+ zcat "${MYPREFIX}/man/man8/${APPNAME}.8.gz" | nroff -man
}
OSDN Git Service
