data/xbps.7: add an introductory manpage

[classabbyamp]

this gives an overview of the project, including the basic uses of various tools and some core concepts.

XBPS(7)                Miscellaneous Information Manual                XBPS(7)

NAME
     xbps – Introduction and concepts

DESCRIPTION
     The X Binary Package System (XBPS) is a binary package system designed
     and implemented from scratch.  Its goal is to be fast, easy to use, bug-
     free, featureful and portable as much as possible.

     The primary interface of XBPS is its suite of tools, including
     xbps-install(1) for installing packages, xbps-remove(1) for removing
     packages, and xbps-query(1) for searching repositories and querying
     package properties.  A C library is also available, called libxbps.

PACKAGES
     An XBPS package is a compressed archive of the package's files and
     metadata.

     Packages can also include scripts that run during installation and
     removal, during the “configuration” phase.  These scripts can be re-run
     with xbps-reconfigure -f.

     Packages can be checked for issues with xbps-pkgdb(1).  If a package
     reports errors, it should be reinstalled with xbps-install -f.

     Packages can mark files as conf_files, which will prevent them from being
     replaced upon package update if modified.

PACKAGE EXPRESSIONS
     Packages can be referred to in several ways.  A package expression is a
     form to match a pattern; currently xbps supports 3 ways to specify them:

     -   by package name, i.e: “foo”.

     -   by exact package name and version, i.e: “foo-1.0_1”.

     -   by specifying a package name and version separated by any of the
         following version comparators:

         < less than
         > greater than
         <= less or equal than
         >= greater or equal than

         Example: “foo>=2.0”.

     The first repository matching the package expression wins.

PACKAGE MODES
     An installed package can have some specific modes of operation.  Package
     modes can be changed with xbps-pkgdb(1).  Currently the following modes
     are available:

     hold
         The package is on hold mode.  Packages in this mode won't be updated
         unless it's explicitely declared to be updated.  The only way to
         update packages in this mode is by using the -f, --force option.  To
         list packages in this mode use xbps-query -H.

     manual
         The package is in manual mode of installation and won't be considered
         for removal when running xbps-remove -o.  To list packages in this
         mode use xbps-query -m.

     repolock
         A package in repolock mode will only accept updates that are
         available in the same repository that was used for installing.  To
         list packages in this mode use xbps-query --list-repolock-pkgs.

REPOSITORIES
     An XBPS repository is a directory containing XBPS packages and an
     <arch>-repodata repository index file.  If the repository is remote
     (served via a web server), packages must be RSA-signed.

     In XBPS configuration and command-line flags, repositories are specified
     by a complete url or absolute path to the directory where the
     <arch>-repodata resides.  To synchronize configured remote repositories
     locally, use xbps-install -S.

     Repositories are created and managed with xbps-rindex(1).

FILES
     /etc/xbps.d                          Default configuration directory.
                                          See also xbps.d(5).

     /usr/share/xbps.d                    Default system configuration
                                          directory.  See also xbps.d(5).

     /var/db/xbps/.<pkgname>-files.plist  Package files metadata.

     /var/db/xbps/pkgdb-0.38.plist        Default package database (0.38
                                          format).  Keeps track of installed
                                          packages and properties.

     /var/cache/xbps                      Default cache directory to store
                                          downloaded binary packages.

ENVIRONMENT
     XBPS_ARCH         Overrides uname(2) machine result with this value.

     XBPS_TARGET_ARCH  Sets the target architecture to this value.

     XBPS_SYSLOG       Overrides the xbps.d(5) syslog=true|false configuration
                       option.

SEE ALSO
     xbps-alternatives(1), xbps-create(1), xbps-dgraph(1), xbps-fbulk(1),
     xbps-fetch(1), xbps-install(1), xbps-pkgdb(1), xbps-query(1),
     xbps-reconfigure(1), xbps-remove(1), xbps-rindex(1), xbps.d(5),
     https://github.com/void-linux/xbps, https://xbps-api-docs.voidlinux.org

AUTHORS
     Juan Romero Pardines <[email protected]>
     Duncan Overbruck <[email protected]>

BUGS
     Probably, but I try to make this not happen. Use it under your own
     responsibility and enjoy your life.

     Report bugs at https://github.com/void-linux/xbps/issues

Void Linux                       May 20, 2025                       Void Linux