Annotation of src/usr.bin/pkg-config/pkg-config.1, Revision 1.22
1.22 ! jasper 1: .\" $OpenBSD: pkg-config.1,v 1.21 2011/06/06 16:08:52 jasper Exp $
1.1 ckuethe 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: .\"
1.21 jasper 17: .Dd $Mdocdate: June 6 2011 $
1.6 jmc 18: .Dt PKG-CONFIG 1
1.1 ckuethe 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
28: The
29: .Nm
1.10 jmc 30: utility retrieves metadata about the installation of software packages.
1.1 ckuethe 31: This metadata includes version, compiler and linker flags, and dependency
32: information.
1.6 jmc 33: It is inspired by, and intended to operate as a drop-in replacement to,
34: the program of the same name available from freedesktop.org.
1.1 ckuethe 35: .Pp
36: Metadata is stored in files named after the package they describe; the
37: Yoyodyne package would likely be described by "yoyodyne.pc".
1.2 ckuethe 38: Not all software packages provide
39: .Nm
1.6 jmc 40: metadata.
1.15 jasper 41: Libraries from base install their metadata in
42: .Pa /usr/lib/pkgconfig ;
43: packages controlled by the
1.1 ckuethe 44: .Xr ports 7
1.2 ckuethe 45: system store their metadata, if provided, in
46: .Pa ${LOCALBASE}/lib/pkgconfig ;
47: the X Window System stores its metadata in
1.6 jmc 48: .Pa ${X11BASE}/lib/pkgconfig .
1.2 ckuethe 49: The
50: .Nm
51: utility will search these locations by default.
1.1 ckuethe 52: .Pp
1.2 ckuethe 53: Because
54: .Nm
55: attempts to output the full set of compiler or linker flags required to
56: use a package, it will also output the flags required for any prerequisite
57: packages.
1.6 jmc 58: If the "foo" package depends on the "bar" package, "pkg-config --cflags foo"
1.2 ckuethe 59: might output something like "-I/usr/local/include/foo
60: -I/usr/local/include/bar", even though the compiler flags for "bar" were not
61: explicitly requested.
1.1 ckuethe 62: .Pp
63: The options are as follows:
64: .Bl -tag -width Ds
1.7 jmc 65: .It Cm --atleast-pkgconfig-version Ar version
1.4 ckuethe 66: Exit with error if the version of
1.1 ckuethe 67: .Nm
1.12 jmc 68: is not greater than or equal to the specified version.
1.7 jmc 69: .It Cm --atleast-version Ar version
70: Exit with error if the specified package's version is not greater than
71: or equal to the specified version.
72: .It Cm --cflags
1.1 ckuethe 73: Return all compiler flags required to compile against the package.
1.7 jmc 74: .It Cm --cflags-only-I
1.1 ckuethe 75: Return only the include path flags required to compile against the package.
1.7 jmc 76: .It Cm --cflags-only-other
1.1 ckuethe 77: Return all compiler flags, other than the include path flags, required to
78: compile against the package.
1.7 jmc 79: .It Cm --debug
80: Enable internal development and debugging messages.
81: .It Cm --errors-to-stdout
82: Direct error messages to stdout rather than stderr.
83: .It Cm --exists
84: Return true if all the specified packages are installed.
1.9 jmc 85: This is the default operation.
86: .It Cm --help \*(Ba --usage
1.7 jmc 87: Print a help message and exit.
88: .It Cm --libs
1.8 jmc 89: Return all linker flags required to link against the package.
1.12 jmc 90: .It Cm --libs-only-L
91: Return only the library path (-L/path/to/lib) flags required to link
92: against the package.
1.7 jmc 93: .It Cm --libs-only-l
1.1 ckuethe 94: Return only the library (-lwhatever) flags required to link against
95: the package.
1.7 jmc 96: .It Cm --libs-only-other
1.1 ckuethe 97: Return linker flags, other than the library and path flags, required to
98: compile against the package.
1.7 jmc 99: .It Cm --list-all
100: List all installed packages and exit.
101: .It Cm --modversion
1.3 ckuethe 102: Fetch package version.
103: If no package is given,
104: .Nm
105: returns its own version.
1.7 jmc 106: .It Cm --print-errors
107: Print error messages and exit with an error when errors occur.
1.9 jmc 108: This is the default operation.
1.17 jasper 109: .It Cm --print-provides
110: Print all the modules the given package provides.
111: .It Cm --print-requires
112: Print all the modules the given package requires.
113: .It Cm --print-requires-private
114: Print all the modules the given package requires for static linking.
1.7 jmc 115: .It Cm --silence-errors
116: Do not print error messages, just exit with an error.
117: .It Cm --static
118: Return the compiler and/or linker flags required for static linking.
119: .It Cm --uninstalled
120: Allow packages not controlled by
121: .Nm
122: to be used.
123: .It Cm --variable Ar name
1.1 ckuethe 124: Fetch the value of the named variable.
1.7 jmc 125: .It Cm --version
126: Print version of
127: .Nm
128: and exit.
1.1 ckuethe 129: .El
130: .Sh ENVIRONMENT
1.16 jasper 131: .Bl -tag -width Ds
132: .It Ev PKG_CONFIG_DEBUG_SPEW
133: If set, this will cause
134: .Nm
135: to print various debugging information.
136: .It Ev PKG_CONFIG_DISABLE_UNINSTALLED
137: By default
138: .Nm
139: prefers a package named "foo-uninstalled" over "foo" when the package
140: "foo" is requested.
141: This allows linking/compiling against uninstalled packages.
142: Setting this flag disables the default behaviour.
143: .It Ev PKG_CONFIG_LIBDIR
144: This can be used to specify a colon-separated list of paths to search for
145: package files.
146: This will replace the default
147: .Nm
148: search directory.
1.22 ! jasper 149: .It Ev PKG_CONFIG_LOG
1.19 jasper 150: This is used to specify a log file to which
1.16 jasper 151: .Nm
152: will write the passed arguments.
1.1 ckuethe 153: .It Ev PKG_CONFIG_PATH
154: This can be used to specify a colon-separated list of paths to search for
155: package files.
156: If given, this list of paths is prepended to the standard search path.
1.18 jasper 157: .It Ev PKG_CONFIG_SYSROOT_DIR
158: This modifies
159: .Fl I
160: and
161: .Fl L
162: to use the target sysroot directory.
163: Thus -I/usr/local/include will become -I/target/usr/local/include when
1.19 jasper 164: PKG_CONFIG_SYSROOT_DIR is set to /target, which is useful when cross compiling
1.18 jasper 165: packages that use
166: .Nm .
1.16 jasper 167: .It Ev PKG_CONFIG_TOP_BUILD_DIR
168: If set
169: .Nm
170: uses the specified value for
171: .Em pc_top_builddir
172: instead of $(top_builddir).
1.1 ckuethe 173: .El
1.14 jmc 174: .Sh EXIT STATUS
175: .Ex -std pkg-config
1.1 ckuethe 176: .Sh SEE ALSO
177: .Xr pkg_info 1 ,
178: .Xr ports 7
179: .Sh HISTORY
180: The
181: .Nm
182: utility first appeared in
1.11 jmc 183: .Ox 4.1 .
1.20 jasper 184: .Sh AUTHORS
185: .Nm
186: was written by
187: .An Chris Kuethe Aq ckuethe@openbsd.org
188: as a replacement for the original freedesktop.org
189: .Nm
190: implementation.
191: It was later extended and kept in sync (where relevant) with the original
192: version by
193: .An Marc Espie Aq espie@openbsd.org
194: and
1.21 jasper 195: .An Jasper Lievisse Adriaanse Aq jasper@openbsd.org .