.\" portsreinstall\-chroot(8) manual page
.\" Copyright (C) 2018 Mamoru Sakaue, MwGhennndo, All Rights Reserved.
.\" ==================================================================================
-.TH PORTSREINSTALL\-CHROOT 8 "29 June 2018" "FreeBSD" "FreeBSD System Manager's Manual"
+.TH PORTSREINSTALL\-CHROOT 8 "13 September 2018" "FreeBSD" "FreeBSD System Manager's Manual"
.SH NAME
portsreinstall\-chroot \- Support utility for \fBportsreinstall\fR(8) to build packages in a virtual environment
.SH SYNOPSIS
command
]
.SH DESCRIPTION
-This utility is updates packages based on \fBports\fR(7) by creating and using a \fBchroot\fR(8) environment and \fBportsreinstall\fR(8).
+ This utility assists to update packages by creating and using \fBchroot\fR(8) environment for building. The ch\fBchroot\fR(8)root environment is first created by forking the host environment, and the user is asked to complete update of packages at the \fBchroot\fR(8) environment.
.SH RESTRICTION
When this utility is executed inside a \fBchroot\fR(8) or \fBjail\fR(8) virtual environment as the target, the execution MAY be terminated at the process of mounting and unmounting file systems.
In this case, the user should follow a message which addresses to execute \fBportsreinstall\-chroot\-mount\fR(8) at the grand host environment.
One of the following \fIcommands\fR can be given for optional operations or confirmation.
.TP
\fBdo\fR
-(Default) Execute the whole process from creation of a builder \fBchroot\fR(8) environment to package update of the host system.
+(Default) Execute the whole process from creation of a builder \fBchroot\fR(8) environment to package update of the host system, where the flow corresponds to \fBmount\fR, \fBenter\fR, \fBportsreinstall packupgrade create\fR at the builder chroot, \fBportsreinstall packupgrade crop\fR at the builder chroot, \fBsync\fR, then \fBportsreinstall\-upgrade\fR at the host, in order.
.TP
\fBauto\fR [\fIoptions\fR] [\fIarguments\fR]
-Automatically execute \fBportsreinstall\fR(8) in the whole process from creation of a builder \fBchroot\fR(8) environment to package update of the host system.
+Automatically execute \fBportsreinstall\fR(8) in the builder \fBchroot\fR(8) environment instead of the \fBenter\fR stage in the conventional \fBdo\fR process.
If given, \fIoptions\fR and \fIarguments\fR are passed to \fBportsreinstall\fR(8).
-If the reinstallation inside the builder \fBchroot\fR(8) environment is marked complete at the exit with zero status from \fBportsreinstall\fR(8) regardless of the options or arguments, the following processes toward the package update of the host system are automatically carried out.
In case of the lost of the lower layer image of unionfs by its bug, the file system will be automatically recovered by re-mounting.
.TP
\fBenter\fR
\fBsync\fR
Synchronize the files affecting package installation (packages, distfiles, port options, ports/packages management tools configurations) of the host environment to the builder.
.TP
+\fBdestroy\fR
+Destroy the builder \fBchroot\fR(8) environment.
+The difference from \fBclean\fR command is that the saved options are preserved.
+.TP
\fBclean\fR
.PD 0
.TP
.PD 0
.TP
\fB\-\-no\-opening\-message\fR
-Suppress the credit and opening messages.
+Suppress the credit, opening and terminating messages.
Option \fB\-a\fR takes higher priority over this option.
.PD
.SS Group 3: Saved and not renewable until cleaning
-.IP \fB\-b\fR
+.IP \fB\-b\fR \fIbasedir\fR
.PD 0
.TP
-\fB\-\-basedir\fR
+\fB\-\-basedir\fR=\fIbasedir\fR
Specifies the base directory of the \fBchroot\fR(8) environment.
The default is "/home/.portsreinstall\-chroot".
.PD
Forcibly invalidate the privilege of the current environment for mounting/unmounting file systems.
This option can be meaningful when this utility is executed inside a \fBchroot\fR(8) or \fBjail\fR(8) virtual environment.
.PD
-.IP \fB\-e\fR\ \fIdir1\fR[\fB,\fIdir2\fR[\fB,\fR...]]
+.IP \fB\-e\fR \fIdir1\fR[\fB,\fIdir2\fR[\fB,\fR...]]
.PD 0
.TP
\fB\-\-extra\-dirs\fR=\fIdir1\fR[\fB,\fIdir2\fR[\fB,\fR...]]
This option should be set if any of the above directories contain symbolic links referring to outside of the default directories, or if any package build/installation is customized to refer to outside of them.
The delimiter is comma (",") by default and changeable by \fB\-E\fR option.
.PD
+.IP \fB\-f\fR
+.PD 0
+.TP
+\fB\-\-fullcourse\fR
+Carry out the \fBdo\fR process as the "full course" automatic mode where update of the ports tree and package repository are done first at the target host environment and thhen operation in the builder \fBchroot\fR(8) environment is started by cleaning of the temporary database and execution of \fBportsreinstall\fR(8) initiated with option \fB\-CGSjqx\fR (\fB\-CGSYajqx\fR if \fB\-a\fR option is set).
+Resuming \fBdo\fR command automatically executes \fBportsreinstall\fR(8) in the builder \fBchroot\fR(8) environment.
+With \fB\-a\fR option, the all detected leaf and obsolete packages will be deleted.
+.PD
+.IP \fB\-g\fR
+.PD 0
+.TP
+\fB\-\-upgraded\-system\fR
+Adjust the all operations to be suitable as post-processes after system upgrade.
+Concretely, the full course mode is adjusted to reinstall the all ports by removing \fB\-q\fR option of \fBportsreinstall\fR(8).
+.PD
.IP \fB\-P\fR
.PD 0
.TP
.SH DETAILS
.SS Overview
This utility is a supporting tool of \fBportsreinstall\fR(8) to build packages in a \fBchroot\fR(8) environment "forked" from the host environment which is the final target of upgrading.
-On-the-fly smart entire upgrade of all installed ports and robustness against termination/restart is pursued by this tool.
+On-the-fly smart entire upgrade of all installed ports and robustness against termination/restart is pursued by this utility.
.PP
The forked environment is created by \fBnullfs\fR(5) and \fBmount_unionfs\fR(8) onto the host environment.
Fetched/deleted distfiles and created/fetched/deleted packages are synchronized at the host to the forked environment.
.SS Example
The conventional flow of using this utility will be as follows:
.PP
-1. In the host (target) environment, update the ports tree and the package repository catalog.
-.RS
-root@[host]#
-.B portsnap fetch update
-.RE
-.RS
-root@[host]#
-.B pkg update
-.RE
-2. Execute \fBportsreinstall\fR(8) in a "forked" builder \fBchroot\fR(8) environment by launching from this utility.
-The sample set of options will be one of the convenient choices for building in the \fBchroot\fR(8) environment.
+1. In the host (target) environment, execute this utility by the full course mode.
.RS
root@[host]#
-.B portsreinstall\-chroot auto -CGqx
+.B portsreinstall\-chroot -f
.RE
-3. After successful build of the temporary database, \fBportsreinstall\fR(8) may show select dialogues for leaf and obsolete ports/packages.
+2. After successful build of the temporary database, \fBportsreinstall\fR(8) may show select dialogues for leaf and obsolete ports/packages.
Note that the choice made here can be changed afterward without any fatal risk as long as the current builder \fBchroot\fR(8) environment is preserved even after the upgrade of the host environment.
.PP
-4. \fBportsreinstall\fR(8) will continue to build, (re)install and deinstall processes, which take very long and impose a high load.
+3. \fBportsreinstall\fR(8) will continue to build, (re)install and deinstall processes, which take very long and impose a high load.
You may want to interrupt the execution to cool down or shutdown your machine for your work or travel.
In this case, press Ctrl+C at any point so that \fBportsreinstall\fR(8) will stop by preserving its progress marker information in the temporary database and this utility will unmount the builder \fBchroot\fR(8) environment.
Some network troubles in fetching distfiles or packages may be resolved by terminating the process once.
.RS
.B Ctrl+C
.RE
-5. At any convenient time, restart the processes.
+4. At any convenient time, restart the processes.
Note that no option should be speified here.
.RS
root@[host]#
.B portsreinstall\-chroot auto
.RE
-6. The process may stop with some failures which cannot be resolved automatically.
+5. The process may stop with some failures which cannot be resolved automatically.
It may be mismatches of port option configurations of dependencies, unrecognized conflict or essential conflict between needed packages.
In this case, you will need to enter the builder \fBchroot\fR(8) environment for the manual troubleshooting.
.RS
root@[host]#
.B portsreinstall\-chroot enter
.RE
-7. Then the you will be prompted in the builder \fBchroot\fR(8) environment.
+6. Then the you will be prompted in the builder \fBchroot\fR(8) environment.
.RS
root@[chroot]#
.RE
-8. Troubleshooting may be done by modifying the configuration files or struggling with \fBfreeze\fR/\fBtaboo\fR/\fBescape\fR/\fBok\fR/\fBneed\fR/\fBnoneed\fR/\fBreselect\fR/\fBreconf\fR commands of \fBportsreinstall\fR(8) referring to information obtained by \fBshow\fR command of \fBportsreinstall\fR(8).
+7. Troubleshooting may be done by modifying the configuration files or struggling with \fBfreeze\fR/\fBtaboo\fR/\fBescape\fR/\fBok\fR/\fBneed\fR/\fBnoneed\fR/\fBreselect\fR/\fBreconf\fR commands of \fBportsreinstall\fR(8) referring to information obtained by \fBshow\fR command of \fBportsreinstall\fR(8).
After such possible patchwork, exit from the builder \fBchroot\fR(8) environment.
.RS
root@[chroot]#
.B exit
.RE
-9. Retry to continue the processes by executing
+8. Retry to continue the processes by executing
.RS
root@[host]#
.B portsreinstall\-chroot auto
root@[host]#
.B portsreinstall\-chroot auto -L redo
.RE
-10. When the all necessary upgrade is completed inside the builder \fBchroot\fR(8) environment, you will be asked whether to reflect the upgrade to the host environment.
+9. When the all necessary upgrade is completed inside the builder \fBchroot\fR(8) environment, you will be asked whether to reflect the upgrade to the host environment.
If you select Yes here, package archiving in the builder \fBchroot\fR(8) environment, synchronization of package files, distfiles, port option database and configuration files for \fBportsreinstall\fR(8), and the update of the packages at the host environment will be automatically carried out.
Here, again, Ctrl+C interruption and unintentional termination will be recovered by simple re-exeution of this utility.
.SH "ENVIRONMENT VARIABLES"
See also the corresponding section of \fBportsreinstall\fR(8).
The variables are conveyed to the forked environment from the target host.
.SH HISTORY
-See the corresponding section of \fBportsreinstall\fR(8).
-This utility first appeared in \fBportsreinstall\fR(8) version 4.0.0.
+This utility first appeared as a part of \fBportsreinstall\fR(8) version 4.0.0 released on June 29, 2018.
.SH "SEE ALSO"
\fBchroot\fR(8)
\fBportsreinstall\fR(8),
OSDN Git Service
