path: root/usr.bin/pkg-config/pkg-config.1

.\"	$OpenBSD: pkg-config.1,v 1.37 2022/03/31 17:27:26 naddy Exp $
.\"
.\"	Copyright (c) 2006 Chris Kuethe <ckuethe@openbsd.org>
.\"
.\"	Permission to use, copy, modify, and distribute this software for any
.\"	purpose with or without fee is hereby granted, provided that the above
.\"	copyright notice and this permission notice appear in all copies.
.\"
.\"	THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\"	WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\"	MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\"	ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\"	WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\"	ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\"	OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: March 31 2022 $
.Dt PKG-CONFIG 1
.Os
.Sh NAME
.Nm pkg-config
.Nd fetch metadata about installed software packages
.Sh SYNOPSIS
.Nm pkg-config
.Op Ar options
.Ar pkg-name Op Ar pkg-name ...
.Sh DESCRIPTION
The
.Nm
utility retrieves metadata about the installation of software packages.
This metadata includes version, compiler and linker flags, and dependency
information.
It is inspired by, and intended to operate as a drop-in replacement to,
the program of the same name available from freedesktop.org.
.Pp
Metadata is stored in files named after the package they describe; the
Yoyodyne package would likely be described by "yoyodyne.pc".
Not all software packages provide
.Nm
metadata.
Libraries from base install their metadata in
.Pa /usr/lib/pkgconfig ;
packages controlled by the
.Xr ports 7
system store their metadata in
.Pa /usr/local/lib/pkgconfig
and
.Pa /usr/local/share/pkgconfig ;
the X Window System stores its metadata in
.Pa /usr/X11R6/lib/pkgconfig
and
.Pa /usr/X11R6/share/pkgconfig .
The
.Nm
utility will search these locations by default.
.Pp
Because
.Nm
attempts to output the full set of compiler or linker flags required to
use a package, it will also output the flags required for any prerequisite
packages.
If the "foo" package depends on the "bar" package, "pkg-config --cflags foo"
might output something like "-I/usr/local/include/foo
-I/usr/local/include/bar", even though the compiler flags for "bar" were not
explicitly requested.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Cm --atleast-pkgconfig-version Ar version
Exit with error if the version of
.Nm
is not greater than or equal to the specified version.
.It Cm --atleast-version Ar version
Exit with error if the specified package's version is not greater than
or equal to the specified version.
.It Cm --cflags
Return all compiler flags required to compile against the package.
.It Cm --cflags-only-I
Return only the include path flags required to compile against the package.
.It Cm --cflags-only-other
Return all compiler flags, other than the include path flags, required to
compile against the package.
.It Cm --debug
Enable internal development and debugging messages.
.It Cm --errors-to-stdout
Direct error messages to stdout rather than stderr.
.It Cm --exact-version Ar version
Exit with error if the specified packages's version does not equal the
specified version.
.It Cm --exists
Return true if all the specified packages are installed.
This is the default operation.
.It Cm --help | --usage
Print a help message and exit.
.It Cm --libs
Return all linker flags required to link against the package.
.It Cm --libs-only-L
Return only the library path (-L/path/to/lib) flags required to link
against the package.
.It Cm --libs-only-l
Return only the library (-lwhatever) flags required to link against
the package.
.It Cm --libs-only-other
Return linker flags, other than the library and path flags, required to
compile against the package.
.It Cm --list-all
List all installed packages and exit.
.It Cm --max-version Ar version
Exit with error if the specified package's version is greater than
the specified version.
.It Cm --modversion
Fetch package version.
If no package is given,
.Nm
returns its own version.
.It Cm --print-errors
Print error messages and exit with an error when errors occur.
This is the default operation.
.It Cm --print-provides
Print all the modules the given package provides.
.It Cm --print-requires
Print all the modules the given package requires.
.It Cm --print-requires-private
Print all the modules the given package requires for static linking.
.It Cm --silence-errors
Do not print error messages, just exit with an error.
.It Cm --static
Return the compiler and/or linker flags required for static linking.
.It Cm --uninstalled
Allow packages not controlled by
.Nm
to be used.
.It Cm --validate
Validate the package without processing its dependencies.
.It Cm --variable Ar name
Fetch the value of the named variable.
.It Cm --version
Print version of
.Nm
and exit.
.El
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev PKG_CONFIG_DEBUG_SPEW
If set, this will cause
.Nm
to print various debugging information.
.It Ev PKG_CONFIG_DISABLE_UNINSTALLED
By default
.Nm
prefers a package named "foo-uninstalled" over "foo" when the package
"foo" is requested.
This allows linking/compiling against uninstalled packages.
Setting this flag disables the default behaviour.
.It Ev PKG_CONFIG_LIBDIR
This can be used to specify a colon-separated list of paths to search for
package files.
This will replace the default
.Nm
search directory.
.It Ev PKG_CONFIG_LOG
This is used to specify a log file to which
.Nm
will write the passed arguments.
.It Ev PKG_CONFIG_PATH
This can be used to specify a colon-separated list of paths to search for
package files.
If given, this list of paths is prepended to the standard search path.
.It Ev PKG_CONFIG_SYSROOT_DIR
This modifies
.Fl I
and
.Fl L
to use the target sysroot directory.
Thus -I/usr/local/include will become -I/target/usr/local/include when
PKG_CONFIG_SYSROOT_DIR is set to /target, which is useful when cross compiling
packages that use
.Nm .
.It Ev PKG_CONFIG_SYSTEM_INCLUDE_PATH
When set to a list of paths, separated by :, these paths will be excluded from
the output of include paths set with
.Fl I .
.It Ev PKG_CONFIG_TOP_BUILD_DIR
If set,
.Nm
uses the specified value for
.Em pc_top_builddir
instead of $(top_builddir).
.It Ev PKG_CONFIG_$PACKAGE_$VARIABLE
Override the $VARIABLE in $PACKAGE with the given value.
.El
.Sh EXIT STATUS
.Ex -std pkg-config
.Sh SEE ALSO
.Xr pkg_info 1 ,
.Xr ports 7
.Sh HISTORY
The
.Nm
utility first appeared in
.Ox 4.1 .
.Sh AUTHORS
.An -nosplit
.Nm
was written by
.An Chris Kuethe Aq Mt ckuethe@openbsd.org
as a replacement for the original freedesktop.org
.Nm
implementation.
It was later extended and kept in sync (where relevant) with the original
version by
.An Marc Espie Aq Mt espie@openbsd.org
and
.An Jasper Lievisse Adriaanse Aq Mt jasper@openbsd.org .
.Sh CAVEATS
.Nm
is a re-implementation of the "original" freedesktop.org program.
While it tries to be compatible, there are several
design/functionality differences one should be aware of:
.Bl -tag -width Ds
.It Ev Conflicts
It was decided not to support the Conflicts keyword as there is
currently too little benefit from it in
.Ox
where the ports tree is supposed to prevent conflicts from arising
in the first place.
Lines with this keyword are not treated as errors, they are just ignored.
And they are not taken into account when
.Cm --print-errors
is passed.
.It Ev Cflags and -i
The
.Fl i
flag that can be encountered in Cflags is not treated differently from
.Fl I
in this implementation.
.It Ev Whitespace
.Nm
does not go to great lengths to try to fix whitespace abuse.
Whitespace in Libs and Cflags lines that are escaped using \e are
treated correctly.
But strings enclosed in quotation marks that contain whitespaces are not.
.El