.Dd September 20, 2016
.Dt XBPS-INSTALL 1
.Sh NAME
.Nm xbps-install
.Nd XBPS utility to (re)install and update packages
.Sh SYNOPSIS
.Nm xbps-install
.Op OPTIONS
.Op PKG...
.Sh DESCRIPTION
The
.Nm
utility installs, reinstalls, downgrades and updates packages in the target root directory.
The argument
.Ar PKG
is a package expression, which is explained in the
.Em PACKAGE EXPRESSION
section. If package is installed, it will be updated to the version available in repositories
matching the
.Em PACKAGE EXPRESSION .
Otherwise it will be installed, or reinstalled/downgraded if
.Fl f , Fl -force
option is set.
.Sh PACKAGE EXPRESSION
A package expression is a form to match a pattern; currently xbps
supports 3 ways to specify them:
.Bl -dash
.It
by package name, i.e:
.Dq Sy foo .
.It
by exact package name and version, i.e:
.Dq Sy foo-1.0_1 .
.It
by specifying a package name and version separated by any of the following version comparators:
.Pp
.Bl -item -compact
.It
.Sy <
less than
.It
.Sy >
greater than
.It
.Sy <=
less or equal than
.It
.Sy >=
greater or equal than
.Pp
Example:
.Dq Sy foo>=2.0 .
.El
.El
.Pp
The first repository matching the package expression wins.
.Sh OPTIONS
.Bl -tag -width -x
.It Fl A, Fl -automatic
Enables automatic installation mode, i.e. package will be treated as orphan
if no package is depending on it directly.
.No See Fl -mode Sy auto No in Xr xbps-pkgdb 1 .
.It Fl C, Fl -config Ar dir
Specifies a path to the XBPS configuration directory.
If the first character is not '/' then it's a relative path of
.Ar rootdir .
.It Fl c, Fl -cachedir Ar dir
Specifies a path to the cache directory, where binary packages are stored.
If the first character is not '/' then it's a relative path of
.Ar rootdir .
.It Fl d, Fl -debug
Enables extra debugging shown to stderr.
.It Fl f, Fl -force
Force downgrade installation (if package version in repos is less than installed version),
or reinstallation (if package version in repos is the same) to the target
.Ar PKG ,
overwriting regular package files and symlinks (if they have been modified) but
.Em preserving configuration files .
If
.Fl f
is specified twice all files will be unpacked, even
.Em configuration files .
.It Fl h, Fl -help
Show the help message.
.It Fl i, Fl -ignore-conf-repos
Ignore repositories defined in configuration files.
Only repositories specified in the command line via
.Ar --repository
will be used.
.It Fl M, Fl -memory-sync
For remote repositories, the data is fetched and stored in memory for the current
operation. This ignores the existing on-disk repository archives in rootdir.
.It Fl n, Fl -dry-run
Dry-run mode. Show what actions would be done but don't do anything. The current output
prints 6 arguments: "<pkgver> <action> <arch> <repository> <installedsize> <downloadsize>".
.It Fl R
Enable repository mode. This mode explicitly looks in repositories, rather
than looking in the target root directory.
.It Fl -repository=url
Appends the specified repository to the top of the list. The
.Ar url
argument expects a URL to the repository for remote repositories or
a path for local repositories. Note that remote repositories must be signed
using
.Xr xbps-rindex 1 .
This option can be specified multiple times.
.It Fl r, Fl -rootdir Ar dir
Specifies a full path for the target root directory.
.It Fl S, Fl -sync
Synchronize remote repository index files.
.It Fl U, Fl -unpack-only
If set, packages to be installed or upgraded in the transaction won't be configured,
just unpacked. That means that those packages should be reconfigured via
.Xr xbps-reconfigure 1 .
.It Fl u, Fl -update
Performs a full system upgrade: all installed packages
.Pq except those on Sy hold , No see Fl -mode Sy hold No in Xr xbps-pkgdb 1
will be updated to the greatest
versions that were found in repositories.
.It Fl v, Fl -verbose
Enables verbose messages.
.It Fl y, Fl -yes
Assume yes to all questions and avoid interactive questions.
.It Fl V, Fl -version
Show the version information.
.El
.Sh ENVIRONMENT
.Bl -tag -width XBPS_TARGET_ARCH
.It Sy XBPS_ARCH
Overrides
.Xr uname 2
machine result with this value. Useful to install packages with a fake
architecture.
.It Sy XBPS_TARGET_ARCH
Sets the target architecture to this value. This variable differs from
.Sy XBPS_ARCH
in that it allows you to install packages partially, because
configuration phase is skipped (the target binaries might not be compatible with
the native architecture).
.El
.Sh FILES
.Bl -tag -width /var/db/xbps/.<pkgname>-files.plist
.It Ar /etc/xbps.d
Default configuration directory.
.It Ar /usr/share/xbps.d
Default system configuration directory.
.It Ar /var/db/xbps/.<pkgname>-files.plist
Package files metadata.
.It Ar /var/db/xbps/pkgdb-0.38.plist
Default package database (0.38 format). Keeps track of installed packages and properties.
.It Ar /var/cache/xbps
Default cache directory to store downloaded binary packages.
.El
.Sh SEE ALSO
.Xr xbps-checkvers 1 ,
.Xr xbps-create 1 ,
.Xr xbps-dgraph 1 ,
.Xr xbps-fbulk 1 ,
.Xr xbps-pkgdb 1 ,
.Xr xbps-query 1 ,
.Xr xbps-reconfigure 1 ,
.Xr xbps-remove 1 ,
.Xr xbps-rindex 1 ,
.Xr xbps-uchroot 1 ,
.Xr xbps-uunshare 1 ,
.Xr xbps.d 5
.Sh AUTHORS
.An Juan Romero Pardines <xtraeme@gmail.com>
.Sh BUGS
Probably, but I try to make this not happen. Use it under your own
responsibility and enjoy your life.
.Pp
Report bugs at https://github.com/voidlinux/xbps/issues