pkg_replace.1

.\" $Id: pkg_replace.1,v 1.2 2007/01/25 12:25:56 securedog Exp $
.\"
.\" Modified by Ken DEGUCHI (August  8, 2024)"
.Dd August  8, 2024
.Dt PKG_REPLACE 1
.Os
.Sh NAME
.Nm pkg_replace
.Nd a utility for upgrading installed packages
.Sh SYNOPSIS
.Nm
.Op Fl abBcCddfFhiJknNOpPPqrRRuUvVwW
.Op Fl \-all
.Op Fl \-automatic
.Op Fl \-batch
.Op Fl \-backup-package | Fl \-no-backup-package
.Op Fl \-clean | Fl \-no-clean
.Op Fl \-cleanup | Fl \-no-cleanup
.Op Fl \-cleandeps | Fl \-no-cleandeps
.Op Fl \-config | Fl \-no-config
.Op Fl \-force-config | Fl \-no-force-config
.Op Fl \-debug
.Op Fl \-makedb
.Op Fl \-no-backup
.Op Fl \-no-configfile
.Op Fl \-vebose | Fl \-no-verbose
.Op Fl \-version
.Op Fl j Ar jobs
.Op Fl l Ar file
.Op Fl L Ar prefix
.Op Fl m Ar make_args
.Op Fl M Ar make_env
.Op Fl t Ar make_target
.Op Fl x Ar pkgname
.Op Fl X Ar pkgname
.Oo
.Op Ar pkgname\fR[=\fIpackage\fR]
.Op Ar package
.Op Ar glob
.Op Ar pkgorigin
.Ar ...
.Oc
.Sh DESCRIPTION
The
.Nm
command is used to upgrade installed packages.
.Sh OPTIONS
The following options are supported:
.Bl -tag -width "-l FILE"
.Pp
.It Fl a , Fl \-all
Do with all the installed packages.
.Pp
.It Fl \-automatic
Set automatic flag for the package.
This affects the operation of pkg-autoremove(8).
.Pp
.It Fl b , Fl \-backup-package
Keep backup packages of the old versions.
By default, the created backup package will be deleted after installation.
See also,
.Fl \-no-backup-package
.Pp
.It Fl B , Fl \-no-backup
Do not backup old packages before uninstall old packages.
.Pp
.It Fl \-batch
Run an upgrading process in a batch mode (with BATCH=yes).
.Pp
.It Fl c , Fl \-config
Do
.Dq Li make config-conditional
before build.
See also,
.Fl \-no-config .
.It Fl C , Fl \-force-config
Do
.Dq Li make config
before build.
See also,
.Fl \-no-force-config .
.Pp
.It Fl \-clean
Do
.Dq Li make clean
before build.
See also,
.Fl w , Fl \-no-clean .
.Pp
.It Fl \-cleandeps
Clean files that record dependencies in the
.Ar PKG_REPLACE_DB_DIR .
This option overrides
.Fl \-no-cleandeps .
By default,
.Nm
do not clean files in the
.Ar PKG_REPLACE_DB_DIR .
This option should be useful when the dependencies of packages are new or modified.
See also,
.Fl dd , Fl RR .
.It Fl \-cleanup
Do
.Dq Li make clean
after build.
This is the default.
See also,
.Fl W , Fl \-no-cleanup .
.Pp
.It Fl d , Fl R
In addition to the specified packages,
replace all packages that required by those packages as well.
.Pp
.It Fl dd , Fl RR
Strictly checking dependencies more than
.Fl d, Fl R,
e.g. build dependencies.
However, this mode is slow.
So,
.Nm
creates files that record dependencies in the
.Ar PKG_REPLACE_DB_DIR
directory to run as fast as possible.
See config file,
.Ar pkg_replace.conf.sample .
If you set
.Fl \-cleandeps ,
.Nm
clean these files in the
.Ar PKG_REPLACE_DB_DIR .
.Pp
This option may fail when there are dependency problems
(e.g., packages have looped dependencies, packages removed the ports tree).
Especially, be careful when using
.Fl a
option at the same time.
.Pp
.It Fl \-debug
Debug mode.
Execute with
.Dq Li set -x
option.
.Pp
.It Fl f
Force to replace packages.
.Pp
.It Fl F
Fetch distfiles or packages, do not replace.
.Pp
.It Fl h
Show help and exit.
.Pp
.It Fl i
Turn on interactive mode.
.Pp
.It Fl j Ar jobs
Number of parallel jobs.
Default value gets from `sysctl -n hw.ncpu`.
.Pp
.It Fl J
Do not install the target packages, but install the dependencies.
.Pp
.It Fl k
Force the upgrade of a package even if some of the requisite packages have failed to upgrade in advance.
.Pp
.It Fl l Ar FILE
Save the results to
.Ar FILE .
By default,
.Nm
does not save results.
.Pp
.It Fl L Ar PREFIX
Save the logs in the files that begins with
.Ar PREFIX .
.It Fl m Ar ARGS
Specify arguments to append to each
.Xr make 1
command.
Please see section
.Ar EXAMPLES.
.Pp
.It Fl \-makedb
Create files that record dependencies of packages in the
.Ar PKG_REPLACE_DB_DIR .
.Pp
.It Fl M Ar ARGS
Specify arguments to prepend to each
.Xr make 1
command.
.Pp
.It Fl n
Do not actually replace any packages.
.It Fl \-no-backup-package
Do not keep backup packages the old versions.
Override
.Fl b .
.Pp
.It Fl \-no-cleandeps
Do not clean the
.Ar PKG_REPLACE_DB_DIR .
This is the default.
See also,
.Fl dd , Fl RR .
.Pp
.It Fl \-no-configfile
Do not read the configuration file
.Ar pkg_replace.conf .
.Pp
.It Fl \-no-config
Do not
.Dq Li make config-conditional
bofore build.
Override
.Fl \-config .
.Pp
.It Fl \-no-force-config
Do not
.Dq Li make config
bofore build.
Override
.Fl \-force-config .
.Pp
.It Fl \-no-verbose
Turn off verbose output.
Override
.Fl v , Fl \-verbose .
.It Fl N
Install new packages, do not replace.
.Pp
.It Fl O
Do not check the dependencies before building the target packages.
.Pp
.It Fl p
Do
.Dq Li make package .
.Pp
.It Fl P
Use binary packages instead of installing from source.
.Nm
finds them from the directory specified by
.Va PKGREPOSITORY ,
and the remote site specified by
.Va PACKAGEROOT .
.Pp
.It Fl PP
Be forced to use binary packages.
Never use the port even if a package is not available either locally or remotely.
.Pp
.It Fl r
In addition to the specified packages,
replace all packages that depend on those packages as well.
.Pp
.It Fl t Ar make_target
Do
.Dq Li make make_target
only.
.Pp
.It Fl U
Unlock packages before deinstall packages and lock packages again after install.
.Pp
.It Fl u
Do not preserve old shared libraries.
By default,
.Nm
preserves old shared libraries in
.Va PKGCOMPATDIR .
But if the new library and the old library have the same name, the old library is removed from
.Va PKGCOMPATDIR .
.Pp
.It Fl v , Fl \-verbose
Turn on verbose output.
.Pp
.It Fl V
List the installed packages that need updating.
.Pp
.It Fl \-version
Print pkg_replace version.
.Pp
.It Fl w , Fl \-no-clean
Do not
.Dq Li make clean
before each build.
This is the default.
See also,
.Fl \-clean
.Pp
.It Fl W , Fl \-no-cleanup
Do not
.Dq Li make clean
after each installation.
See also,
.Fl \-cleanup
.Pp
.It Fl x Ar glob
Do not replace packages matching the specified glob pattern.
.Pp
.It Fl X Ar glob
Remove the libraries in
.Va PKGCOMPATDIR ,
when the specified packages have the libraries with the same name as the one in
.Va PKGCOMPATDIR .
This may be useful when there are errors due to a mixture of old and new libraries.
.Pp
.El
.Sh VARIABLES
See also,
.Va pkg_replace.conf .
.Bl -tag -width ".Ev XXXXXXXXXXXXXXXXXX"
.It Ev Va PACKAGEROOT
Default is
.Va https://pkg.FreeBSD.org .
.It Ev Va PKGCOMPATDIR
Defaut location is
.Va %%PKGCOMPATDIR%% .
.It Ev Va PKGREPOSITORY
Default location is
.Va /var/cache/pkg/All .
.It Ev Va PKG_REPLACE_DB_DIR
Default location is
.Va /var/db/pkg_replace .
.El
.Pp
.Sh EXAMPLES
.Bl -bullet
.It
pkgname and glob examples:
.Ar name-version ,
.Ar name
and
.Ar shell glob .
.Pp
.Dl glib-2.36.3_2, glib and 'glib*' or glib\e*
.Pp
.It
pkgorigin examples:
.Ar pkgorigin
and
.Ar pkgorigin@flavor .
.Pp
.Dl devel/glib20 and graphics/py-cairo@py37
.Pp
.It
Path: Absolute and relative paths are allowed.
.Pp
.Dl pkg_replace glib=../glib20-new
.Dl or
.Dl pkg_replace glib=/home/foo/ports/glib20
.It
Install
.Ar glib :
.Pp
.Dl pkg_replace -N devel/glib20
.It
Install
.Ar py-cairo
with
.Ar FLAVOR=py37 :
.Pp
.Dl pkg_replace -N graphics/py-cairo@py37
.It
Replace
.Ar glib :
.Pp
.Dl pkg_replace glib
.It
Replace
.Ar perl
and all packages that depend on it:
.Pp
.Dl pkg_replace -r perl
.It
If the
.Ar xterm
package is already installed, replace it with
.Ar xterm-220 :
.Pp
.Dl pkg_replace /usr/ports/packages/All/xterm-220.tbz
.It
Replace
.Ar XFree86-libraries
with
.Ar /usr/ports/x11/xorg-libraries:
.Pp
.Dl pkg_replace XFree86-libraries=/usr/ports/x11/xorg-libraries
.It
Replace
.Ar XFree86-libraries
with pkgorigin:
.Ar x11/xorg-libraries:
.Pp
.Dl pkg_replace XFree86-libraries=x11/xorg-libraries
.It
Replace
.Ar XFree86-libraries
with
.Ar /var/tmp/xorg-libraries-6.9.0
package:
.Pp
.Dl pkg_replace XFree86-libraries=/var/tmp/xorg-libraries-6.9.0.tbz
.It
Replace
.Ar graphics/py-cairo
with
.Ar FLAVOR=py37 :
.Pp
.Dl pkg_replace -m FLAVOR=py37 graphics/py-cairo
.Dl or
.Dl pkg_replace graphics/py-cairo@py37
.It
Do
.Dq Li make configure
only:
.Pp
.Dl pkg_replace -t configure pkgname
.El
.Sh COMPATIBILITY
The
.Xr portupgrade 1
options
.Fl A , B , D , e , o , q , s , S
and
.Fl y
are no longer supported.
.Sh SEE ALSO
.Xr portupgrade 1 ,
.Xr pkg 8 ,
.Xr ports 7 ,
.Sh AUTHORS
.An Securedog Aq securedog@users.sourceforge.jp
.An Ken DEGUCHI Aq kdeguchi@sz.tokoha-u.ac.jp
.Sh BUGS
Sure to be some.