pkgdepdb.1.in

.\"mdoc
.Dd June 6, 2013
.Dt PKGDEPDB 1
.Os
.Sh NAME
.Nm pkgdepdb
.Nd read Arch package archive files, and print the required library names
.Sh SYNOPSIS
.Nm pkgdepdb
.Op Cm options
.Op Ar files...
.Pp
.Nm pkgdepdb
.Fl r
.Op Cm options
.Ar package_names...
.Sh DESCRIPTION
Commandline interface for managing and querying a package database.
It manages a database of library dependencies of packages without requiring to
unpack or install them to a temporary location. Packages are virtually
installed into the database instead, which means it will extract information
about ELF files inside an archive, and, if present, read the contained
.Pa .PKGINFO
file.
.Pp
Instead of working on a database it can optionally also just print out
ELF information from an archive, which is similar to extracting and running
readelf on the files.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl h , Fl -help
Show the usage message.
.It Fl -version
Show version info.
.It Fl d , Fl -db= Ns Ar file
(Config var: database)
.br
Specifies the database filename to use. If it exists it will be read,
otherwise a new database will be put into place.
.Pp
If the filename ends in
.Cm .gz
then gzip compression will be used.
.It Fl i , Fl -install
Install mode: commit (install) the provided package files into the
database.
.It Fl r , Fl -remove
Delete mode: delete (uninstall) the listed packages from the database.
In this mode, the non-option parameters are package names, not package
archive files!
.It Fl -wipe
Wipe database: remove all packages, but keep settings and rules.
Useful to clean up and start over without having to re-add all the
library paths and rules.
.It Fl -touch
Touch the database: re-write out the database even if no modifications
are made. This can be used to bring the database format version up to
version 8 or newer. Starting with version 8 object and package references
are stored more efficiently.
.It Fl -rm-files
Strip the database of its file-list. Causes the database to be stored
as if it was created with \(dqfile_lists=off\(dq / \(dq--files=off\(dq.
.It Fl n , Fl -rename= Ns Ar name
Change the database's contained name. This does not affect the
filename. The database-name is currently not used anywhere except when
using the -I option to show it.
.It Fl -integrity
Perform a dependency integrity check: Look for orphaned object files
in the database. Look for missing dependencies of packages, and go
through all packages and see if it misses dependencies (considering
it, its dependencies, optional dependencies, and the base packages to
be installed). Also check for conflicts in dependency chains.
.It Fl -dry
Dry run: do not commit the changes to the database file.
.It Fl v , Fl -verbose
Increase the verbosity level. May be specified multiple times. Default
verbosity level is 0.
.It Fl q , Fl -quiet
(Config var: quiet=<yes|no>)
.br
Not the opposite of
.Fl v
but rather disables progress-messages.
.It Fl -depends=<yes|no>
(Config var: package_depends)
.br
Enable or disable package-dependency tracking. While disabled, newly
installed packages will not contain any dependency or
optional-dependency information.
.It Fl -files Ns , Fl -files=<yes|no> Ns , Fl -no-files
(Config var: file_lists)
.br
When enabled, newly installed packages will contain a list of all their
contained files, even non-ELF files,
with these exceptions: .PKGINFO, .INSTALL and .MTREE
.It Fl J , Fl -json= Ns Ar MODE
(Config var: json)
.br
Change the json mode. By default json will not be used anywhere.
.Ar MODE
can start with a
.Ql +
or
.Ql -
to add or remove json modes, otherwise the json mode will be set to
exactly the specified mode.
.br
The following modes are recognized:
.Bl -dash -compact
.It
.Ar all Ns , Ar a Ns :
Use json for both query outputs and to store the database.
.It
.Ar off Ns , Ar no Ns , Ar none Ns , Ar n Ns :
Don't use json anywhere. (subtracting this does nothing).
.It
.Ar on Ns , Ar query Ns , Ar q Ns :
Use json for query outputs.
.It
.Ar db Ns :
Use json to store the database.
.El
.Pp
.Em WARNING Ns :
There is no support to read json formatted databases yet.
.It Fl R , Fl -rule= Ns Ar RULECOMMAND
Modify the databases ruleset. See the
.Sx RULES
section.
.It Fl j Ar COUNT
(Config var: jobs)
.br
When thread support is enabled, this limits the number of jobs
running simultaneously to at most
.Ar COUNT Ns .
.El
.Pp
The following query options are available:
.Bl -tag -width Ds
.It Fl I , Fl -info
Show some general information about the database: The database format
version and the database's name.
.It Fl L , Fl -list
Show the list of installed binaries and libraries and the dependencies
they find or lack.
.It Fl M , Fl -missing
Show the list of missing files grouped by binary/library files.
.It Fl F , Fl -found
For all binaries and libraries, show which files are found
successfully.
.It Fl P , Fl -pkgs
Show a list of installed packages. With
.Fl v
the list of contained object files is shown for each package as well.
.It Fl -ls
List the packages' file lists.
.El
.Pp
The following query filters are available:
.Bl -tag -width Ds
.It Fl b , Fl -broken
Filter for: -P
.br
Only show packages with broken libraries.
.br
Changes the behavior of
.Fl v
to only show libraries with missing files as well.
Verbosity level 2
.Po Fl vv Pc
can be used to show the list of missing libraries for each broken
library.
.It Fl f , Fl -filter= Ns Ar FILTER
Add a filter rule to the query. These can affect packages as well as
libraries.
.br
Filters which start with an exclamation mark \(dq!\(dq are
negated. Meaning only packages NOT matching this rule will be considered.
.br
Generally, filters consist of 2 parts: the attribute that is matched,
and a matching string. After the attribute, there's either an \(dq=\(dq
signifying an exact match, a \(dq:\(dq signifying a shell-like glob, or
a \(dq/\(dq which starts a regular expression.
.br
Regex matches can actually start with any character which don't already
have a different meaning, but not with alphanumeric characters. The regex
ends at the end of the command, which can optionally contain the unquote
character at the end, and an optional \(dqi\(dq flag to make the regex
case insensitive. This means you can use \(dq@foo@i\(dq as well as
\(dq/foo\(dq. Note that for \(dq(\(dq, \(dq[\(dq, \(dq{\(dq and \(dq<\(dq
the closing quote characters are \(dq)\(dq, \(dq]\(dq, \(dq}\(dq and
\(dq>\(dq respectively.
An example of a negated filter would be: \(dq-f!name=boost\(dq, which would
cause the \(dqboost\(dq package to be ignored.
.It Fl f Ns name= Ns Ar NAME
Only consider packages matching the provided name.
.It Fl f Ns group= Ns Ar GROUP
Only consider packages part of the provided group.
.It Fl f Ns depends= Ns Ar PACKAGENAME
Only consider packages depending on the provided package.
.It Fl f Ns makedepends= Ns Ar PACKAGENAME
Only consider packages with the provided package as compile-time dependency.
.It Fl f Ns checkdepends= Ns Ar PACKAGENAME
Only consider packages with the provided package as check dependency.
.It Fl f Ns optdepends= Ns Ar PACKAGENAME
Only consider packages with the provided package as optional dependency.
.It Fl f Ns alldepends= Ns Ar PACKAGENAME
Only consider packages with the provided package as dependency or optional
dependency.
.It Fl f Ns pkglib Ns Ar FILTER Ns Ar = Ns Ar NAME
Only consider packages which contain at least one library matching the
\(dq-flibFILTER\(dq filter with the provided pattern.
.It Fl f Ns provides= Ns Ar NAME
Check the package's list of provided packages.
.It Fl f Ns conflicts= Ns Ar NAME
The package must conflict with the provided one.
.It Fl f Ns replaces= Ns Ar NAME
The package must be marked as replacing the provided package.
.It Fl f Ns contains= Ns Ar PATH
A file matching the provided path has to be present in the package.
.It Fl f Ns broken
This rule has no match string. Consider only broken packages. Contrary to
the
.Fl b
option, this will not change the output of the current query.
.It Fl f Ns libname= Ns Ar NAME
Only consider libraries matching the provided name.
.It Fl f Ns libpath= Ns Ar NAME
Only consider libraries matching the provided path (includes directory,
a slash and the filename, paths are sanitized and will not contain ./ or
double slashes).
.It Fl f Ns libdepends= Ns Ar NAME
Only consider libraries which link against the provided library.
.It Fl f Ns librpath= Ns Ar NAME
Only consider libraries with a matching rpath set.
.It Fl f Ns librunpath= Ns Ar NAME
Only consider libraries with a matching runpath set.
.It Fl f Ns libinterp= Ns Ar NAME
Only consider libraries with a matching interpreter requested.
.It Fl f Ns file= Ns Ar NAME
Only show files matching a certain name.
.El
.Pp
The following options are used to modify the library search paths used
by the database. The database file will only be updated if an actual
change appears.
.Pp
Directories can only exist once in the path. When adding an already
existing path to the list, the old path will be moved by reordering.
.Pp
.Em IMPORTANT:
Changes to the library path do not cause link information
to be updated. Especially prepending/inserting or deleting library
paths can have huge effects on which libraries will be used by which
object, so in order to keep a consistent state, use the
.Fl -relink
option after changing library paths.
.Bl -tag -width Ds
.It Fl -relink
Recreate the complete link information with the updated library paths.
.It Fl -ld-append= Ns Ar dir
Add to the end of the list.
.It Fl -ld-prepend= Ns Ar dir
Prepend to the front of the list.
.It Fl -ld-delete= Ns Ar dir
Delete from the list.
.It Fl -ld-insert= Ns Ar pos Ns : Ns Ar dir
Insert the directory at the specified index.
.It Fl -ld-clear
Remove all paths from the db.
.El
.Sh RULES
In order to make it easier to maintain packages, the ability to add
additional rules to the database has been added. For instance, the
freebsd-kernel package in ArchBSD contains the file
.Pa /boot/kernel/kernel
which also contains an ELF header which has an entry claiming it
depends on the file
.Pa hack.So Ns . br
This file can be ignored with file-ignore rule.
.Pp
Another set of rules are package-specific library-paths. These are
useful when a package sets the LD_LIBRARY_PATH variable. These rules
only match the package's name,
.Em not
its version!
.Pp
The currently active rules are shown with the
.Fl -info
query, which includes IDs for each rule which can be used as a
shortcut during modification.
.Pp
Here's the list of rule modification commands:
.Bl -tag -width Ds
.It Fl -rule Cm ignore: Ns Ar file
Add a file-ignore rule. These are unique and will not create
duplicates.
.It Fl -rule Cm unignore: Ns Ar file
Remove the file-ignore rule matching exactly the provided file.
.It Fl -rule Cm unignore-id: Ns Ar fileID
Remove the file-ignore rule with the provided ID as shown using the
.Fl -info
query.
.It Fl -rule Cm assume-found: Ns Ar name
Assume that a library of that name is always found.
.It Fl -rule Cm unassume-found: Ns Ar name
Remove the assume-found rule matching exactly the provided name.
.It Fl -rule Cm unassume-found-id: Ns Ar ID
Remove the assume-found rule with the provided ID as shown using the
.Fl -info
query.
.It Fl -rule Cm pkg-ld-clear: Ns Ar package
Remove the package specific library path list for the provided
package.
.It Fl -rule Cm pkg-ld-append: Ns Ar package Ns Ar path
Append the specified path to the specified package's library path list.
.It Fl -rule Cm pkg-ld-prepend: Ns Ar package Ns Ar path
Prepend the specified path to the specified package's library path list.
.It Fl -rule Cm pkg-ld-insert: Ns Ar package Ns Ar ID Ns Ar path
Insert the specified path to the specified package's library path list
before the index matching the ID as seen using the
.Fl -info
query.
.It Fl -rule Cm pkg-ld-delete: Ns Ar package Ns Ar path
Remove the specified path from the package's library path list.
.It Fl -rule Cm pkg-ld-delete-id: Ns Ar package Ns Ar ID
Remove the specified path from the package's library path list using
the path's ID.
.It Fl -rule Cm base-add: Ns Ar PKG
Add the provided package to the list of base packages. The package
does not need to exist. It's merely a list of strings.
.It Fl -rule Cm base-remove: Ns Ar PKG
Remove an existing package from the base package list by name.
.It Fl -rule Cm base-remove-id: Ns Ar ID
Remove an existing package from the base package list by id as shown
via the
.Fl info
query.
.El
.Sh EXAMPLES
When no database or database-action is specified, the provided archive
files are read, and for each ELF object (binary or library) a list of
required libraries is printed. This is similar to using
.Cm readelf Fl d
on the contents while grepping for
.Ql NEEDED Ns .
.Bd -literal -offset indent
$ pkgdepdb /var/cache/pacman/pkg/lua-5.2.1-4-x86_64.pkg.tar.xz
lua : /usr/lib/liblua.so NEEDS libm.so.5
lua : /usr/lib/liblua.so NEEDS libc.so.7
(...)
.Ed
.Pp
When a database is provided with the
.Fl d
switch, database related actions can be performed, such as installing
packages, querying, or modifying the library path used in the DB.
.Pp
Here's an example which updates or creates a database:
.Bd -literal -offset indent
$ pkgdepdb -d dep.core.db.gz -i freebsd-world-9.1-4-x86_64.pkg.tar.xz
*** loading packages...
  freebsd-world-9.1-4-x86_64.pkg.tar.xz
*** packages loaded...
*** installing packages
*** writing compressed database
$
.Ed
.Pp
The created file can be queried for various information, like a list
of packages or a list of missing libraries:
.Bd -literal -offset indent
$ pkgdepdb -d dep.core.db.gz -P
*** reading compressed database
Packages:
  -> freebsd-world - 9.1-4
.Ed
.Bd -literal -offset indent
$ pkgdepdb -d dep.core.db.gz -M
*** reading compressed database
Missing:
  -> /usr/bin / gperf
    misses: libstdc++.so.6
  -> /usr/bin / grodvi
    misses: libstdc++.so.6
(...)
.Ed
.Sh CONFIG
pkgdepdb tries to read configuration files in the following order:
.Bl -enum -compact
.It
~/.pkgdepdb/config
.It
%%SYSCONFDIR%%/pkgdepdb.conf
.El
.Pp
The configuration can contain comment lines starting with #, empty
lines as well as the following all-optional entries:
.Bd -literal -offset indent
# Default database (as if the --db parameter was used)
database = /path/to/default/database
# Default verbosity level (amount of -v parameters)
verbosity = 1
# Be quiet (as if the -q parameter was used)
quiet = true
# or:
# quiet = false
# read package 'depend', 'makedepend' and 'optdepend' entries from .PKGINFO
# and use them if they are present in the database
package_depends = true
# or false
# The json option works just like --json
json = off
# When thread support is enabled, limit the maximum number of jobs:
jobs = 4
.Ed
.Pp
.Em NOTE Ns :
The default database entry strips leading whitespaces, but
.Em NOT
trailing whitespaces. Anything after the first non-white character is
copied as-is.
.Sh BUGS
Currently symlinks are treated as file-copies, and they are followed
at package-load time, this means that there cannot be cross-package
library-symlinks.
.Pp
Symlinks aren't kept in the database either, so broken symlinks are
silently ignored.
.Pp
Support to store symlinks permanently in the database should be added
at some point.
.Pp
The current behavior should work fine in most cases, as packages
rarely link to files from other packages.
.Sh FILES
.Bl -dash -compact
.It
.Pa ~/.pkgdepdb/config
.It
.Pa %%SYSCONFDIR%%/pkgdepdb.conf
.El
.Sh AUTHOR
See <http://github.com/Blub/pkgdepdb>.