1.\" $OpenBSD: pkg-config.1,v 1.35 2020/09/15 07:18:45 jasper Exp $ 2.\" 3.\" Copyright (c) 2006 Chris Kuethe <ckuethe@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 15 2020 $ 18.Dt PKG-CONFIG 1 19.Os 20.Sh NAME 21.Nm pkg-config 22.Nd fetch metadata about installed software packages 23.Sh SYNOPSIS 24.Nm pkg-config 25.Op Ar options 26.Ar pkg-name Op Ar pkg-name ... 27.Sh DESCRIPTION 28The 29.Nm 30utility retrieves metadata about the installation of software packages. 31This metadata includes version, compiler and linker flags, and dependency 32information. 33It is inspired by, and intended to operate as a drop-in replacement to, 34the program of the same name available from freedesktop.org. 35.Pp 36Metadata is stored in files named after the package they describe; the 37Yoyodyne package would likely be described by "yoyodyne.pc". 38Not all software packages provide 39.Nm 40metadata. 41Libraries from base install their metadata in 42.Pa /usr/lib/pkgconfig ; 43packages controlled by the 44.Xr ports 7 45system store their metadata in 46.Pa ${LOCALBASE}/lib/pkgconfig 47and 48.Pa ${LOCALBASE}/share/pkgconfig ; 49the X Window System stores its metadata in 50.Pa ${X11BASE}/lib/pkgconfig 51and 52.Pa ${X11BASE}/share/pkgconfig . 53The 54.Nm 55utility will search these locations by default. 56.Pp 57Because 58.Nm 59attempts to output the full set of compiler or linker flags required to 60use a package, it will also output the flags required for any prerequisite 61packages. 62If the "foo" package depends on the "bar" package, "pkg-config --cflags foo" 63might output something like "-I/usr/local/include/foo 64-I/usr/local/include/bar", even though the compiler flags for "bar" were not 65explicitly requested. 66.Pp 67The options are as follows: 68.Bl -tag -width Ds 69.It Cm --atleast-pkgconfig-version Ar version 70Exit with error if the version of 71.Nm 72is not greater than or equal to the specified version. 73.It Cm --atleast-version Ar version 74Exit with error if the specified package's version is not greater than 75or equal to the specified version. 76.It Cm --cflags 77Return all compiler flags required to compile against the package. 78.It Cm --cflags-only-I 79Return only the include path flags required to compile against the package. 80.It Cm --cflags-only-other 81Return all compiler flags, other than the include path flags, required to 82compile against the package. 83.It Cm --debug 84Enable internal development and debugging messages. 85.It Cm --errors-to-stdout 86Direct error messages to stdout rather than stderr. 87.It Cm --exact-version Ar version 88Exit with error if the specified packages's version does not equal the 89specified version. 90.It Cm --exists 91Return true if all the specified packages are installed. 92This is the default operation. 93.It Cm --help | --usage 94Print a help message and exit. 95.It Cm --libs 96Return all linker flags required to link against the package. 97.It Cm --libs-only-L 98Return only the library path (-L/path/to/lib) flags required to link 99against the package. 100.It Cm --libs-only-l 101Return only the library (-lwhatever) flags required to link against 102the package. 103.It Cm --libs-only-other 104Return linker flags, other than the library and path flags, required to 105compile against the package. 106.It Cm --list-all 107List all installed packages and exit. 108.It Cm --max-version Ar version 109Exit with error if the specified package's version is greater than 110the specified version. 111.It Cm --modversion 112Fetch package version. 113If no package is given, 114.Nm 115returns its own version. 116.It Cm --print-errors 117Print error messages and exit with an error when errors occur. 118This is the default operation. 119.It Cm --print-provides 120Print all the modules the given package provides. 121.It Cm --print-requires 122Print all the modules the given package requires. 123.It Cm --print-requires-private 124Print all the modules the given package requires for static linking. 125.It Cm --silence-errors 126Do not print error messages, just exit with an error. 127.It Cm --static 128Return the compiler and/or linker flags required for static linking. 129.It Cm --uninstalled 130Allow packages not controlled by 131.Nm 132to be used. 133.It Cm --validate 134Validate the package without processing its dependencies. 135.It Cm --variable Ar name 136Fetch the value of the named variable. 137.It Cm --version 138Print version of 139.Nm 140and exit. 141.El 142.Sh ENVIRONMENT 143.Bl -tag -width Ds 144.It Ev PKG_CONFIG_DEBUG_SPEW 145If set, this will cause 146.Nm 147to print various debugging information. 148.It Ev PKG_CONFIG_DISABLE_UNINSTALLED 149By default 150.Nm 151prefers a package named "foo-uninstalled" over "foo" when the package 152"foo" is requested. 153This allows linking/compiling against uninstalled packages. 154Setting this flag disables the default behaviour. 155.It Ev PKG_CONFIG_LIBDIR 156This can be used to specify a colon-separated list of paths to search for 157package files. 158This will replace the default 159.Nm 160search directory. 161.It Ev PKG_CONFIG_LOG 162This is used to specify a log file to which 163.Nm 164will write the passed arguments. 165.It Ev PKG_CONFIG_PATH 166This can be used to specify a colon-separated list of paths to search for 167package files. 168If given, this list of paths is prepended to the standard search path. 169.It Ev PKG_CONFIG_SYSROOT_DIR 170This modifies 171.Fl I 172and 173.Fl L 174to use the target sysroot directory. 175Thus -I/usr/local/include will become -I/target/usr/local/include when 176PKG_CONFIG_SYSROOT_DIR is set to /target, which is useful when cross compiling 177packages that use 178.Nm . 179.It Ev PKG_CONFIG_SYSTEM_INCLUDE_PATH 180When set to a list of paths, separated by :, these paths will be excluded from 181the output of include paths set with 182.Fl I . 183.It Ev PKG_CONFIG_TOP_BUILD_DIR 184If set 185.Nm 186uses the specified value for 187.Em pc_top_builddir 188instead of $(top_builddir). 189.It Ev PKG_CONFIG_$PACKAGE_$VARIABLE 190Override the $VARIABLE in $PACKAGE with the given value. 191.El 192.Sh EXIT STATUS 193.Ex -std pkg-config 194.Sh SEE ALSO 195.Xr pkg_info 1 , 196.Xr ports 7 197.Sh HISTORY 198The 199.Nm 200utility first appeared in 201.Ox 4.1 . 202.Sh AUTHORS 203.An -nosplit 204.Nm 205was written by 206.An Chris Kuethe Aq Mt ckuethe@openbsd.org 207as a replacement for the original freedesktop.org 208.Nm 209implementation. 210It was later extended and kept in sync (where relevant) with the original 211version by 212.An Marc Espie Aq Mt espie@openbsd.org 213and 214.An Jasper Lievisse Adriaanse Aq Mt jasper@openbsd.org . 215.Sh CAVEATS 216.Nm 217is a re-implementation of the "original" freedesktop.org program. 218While it tries to be compatible, there are several 219design/functionality differences one should be aware of: 220.Bl -tag -width Ds 221.It Ev Conflicts 222It was decided not to support the Conflicts keyword as there is 223currently too little benefit from it in 224.Ox 225where the ports tree is supposed to prevent conflicts from arising 226in the first place. 227Lines with this keyword are not treated as errors, they are just ignored. 228And they are not taken into account when 229.Cm --print-errors 230is passed. 231.It Ev Cflags and -i 232The 233.Fl i 234flag that can be encountered in Cflags is not treated differently from 235.Fl I 236in this implementation. 237.It Ev Whitespace 238.Nm 239does not go to great lengths to try to fix whitespace abuse. 240Whitespace in Libs and Cflags lines that are escaped using \e are 241treated correctly. 242But strings enclosed in quotation marks that contain whitespaces are not. 243.El 244