Annotation of src/usr.bin/pkg-config/pkg-config.1, Revision 1.31
1.31 ! bentley 1: .\" $OpenBSD: pkg-config.1,v 1.30 2013/07/16 00:07:52 schwarze 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.31 ! bentley 17: .Dd $Mdocdate: July 16 2013 $
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.28 espie 45: system store their metadata in
1.26 ajacouto 46: .Pa ${LOCALBASE}/lib/pkgconfig
47: and
48: .Pa ${LOCALBASE}/share/pkgconfig ;
1.2 ckuethe 49: the X Window System stores its metadata in
1.26 ajacouto 50: .Pa ${X11BASE}/lib/pkgconfig
51: and
52: .Pa ${X11BASE}/share/pkgconfig .
1.2 ckuethe 53: The
54: .Nm
55: utility will search these locations by default.
1.1 ckuethe 56: .Pp
1.2 ckuethe 57: Because
58: .Nm
59: attempts to output the full set of compiler or linker flags required to
60: use a package, it will also output the flags required for any prerequisite
61: packages.
1.6 jmc 62: If the "foo" package depends on the "bar" package, "pkg-config --cflags foo"
1.2 ckuethe 63: might output something like "-I/usr/local/include/foo
64: -I/usr/local/include/bar", even though the compiler flags for "bar" were not
65: explicitly requested.
1.1 ckuethe 66: .Pp
67: The options are as follows:
68: .Bl -tag -width Ds
1.7 jmc 69: .It Cm --atleast-pkgconfig-version Ar version
1.4 ckuethe 70: Exit with error if the version of
1.1 ckuethe 71: .Nm
1.12 jmc 72: is not greater than or equal to the specified version.
1.7 jmc 73: .It Cm --atleast-version Ar version
74: Exit with error if the specified package's version is not greater than
75: or equal to the specified version.
76: .It Cm --cflags
1.1 ckuethe 77: Return all compiler flags required to compile against the package.
1.7 jmc 78: .It Cm --cflags-only-I
1.1 ckuethe 79: Return only the include path flags required to compile against the package.
1.7 jmc 80: .It Cm --cflags-only-other
1.1 ckuethe 81: Return all compiler flags, other than the include path flags, required to
82: compile against the package.
1.7 jmc 83: .It Cm --debug
84: Enable internal development and debugging messages.
85: .It Cm --errors-to-stdout
86: Direct error messages to stdout rather than stderr.
1.29 jasper 87: .It Cm --exact-version Ar version
88: Exit with error if the specified packages's version does not equal the
89: specified version.
1.7 jmc 90: .It Cm --exists
91: Return true if all the specified packages are installed.
1.9 jmc 92: This is the default operation.
1.31 ! bentley 93: .It Cm --help | --usage
1.7 jmc 94: Print a help message and exit.
95: .It Cm --libs
1.8 jmc 96: Return all linker flags required to link against the package.
1.12 jmc 97: .It Cm --libs-only-L
98: Return only the library path (-L/path/to/lib) flags required to link
99: against the package.
1.7 jmc 100: .It Cm --libs-only-l
1.1 ckuethe 101: Return only the library (-lwhatever) flags required to link against
102: the package.
1.7 jmc 103: .It Cm --libs-only-other
1.1 ckuethe 104: Return linker flags, other than the library and path flags, required to
105: compile against the package.
1.7 jmc 106: .It Cm --list-all
107: List all installed packages and exit.
1.29 jasper 108: .It Cm --max-version Ar version
109: Exit with error if the specified package's version is greater than
110: the specified version.
1.7 jmc 111: .It Cm --modversion
1.3 ckuethe 112: Fetch package version.
113: If no package is given,
114: .Nm
115: returns its own version.
1.7 jmc 116: .It Cm --print-errors
117: Print error messages and exit with an error when errors occur.
1.9 jmc 118: This is the default operation.
1.17 jasper 119: .It Cm --print-provides
120: Print all the modules the given package provides.
121: .It Cm --print-requires
122: Print all the modules the given package requires.
123: .It Cm --print-requires-private
124: Print all the modules the given package requires for static linking.
1.7 jmc 125: .It Cm --silence-errors
126: Do not print error messages, just exit with an error.
127: .It Cm --static
128: Return the compiler and/or linker flags required for static linking.
129: .It Cm --uninstalled
130: Allow packages not controlled by
131: .Nm
132: to be used.
133: .It Cm --variable Ar name
1.1 ckuethe 134: Fetch the value of the named variable.
1.7 jmc 135: .It Cm --version
136: Print version of
137: .Nm
138: and exit.
1.1 ckuethe 139: .El
140: .Sh ENVIRONMENT
1.16 jasper 141: .Bl -tag -width Ds
142: .It Ev PKG_CONFIG_DEBUG_SPEW
143: If set, this will cause
144: .Nm
145: to print various debugging information.
146: .It Ev PKG_CONFIG_DISABLE_UNINSTALLED
147: By default
148: .Nm
149: prefers a package named "foo-uninstalled" over "foo" when the package
150: "foo" is requested.
151: This allows linking/compiling against uninstalled packages.
152: Setting this flag disables the default behaviour.
153: .It Ev PKG_CONFIG_LIBDIR
154: This can be used to specify a colon-separated list of paths to search for
155: package files.
156: This will replace the default
157: .Nm
158: search directory.
1.22 jasper 159: .It Ev PKG_CONFIG_LOG
1.19 jasper 160: This is used to specify a log file to which
1.16 jasper 161: .Nm
162: will write the passed arguments.
1.1 ckuethe 163: .It Ev PKG_CONFIG_PATH
164: This can be used to specify a colon-separated list of paths to search for
165: package files.
166: If given, this list of paths is prepended to the standard search path.
1.18 jasper 167: .It Ev PKG_CONFIG_SYSROOT_DIR
168: This modifies
169: .Fl I
170: and
171: .Fl L
172: to use the target sysroot directory.
173: Thus -I/usr/local/include will become -I/target/usr/local/include when
1.19 jasper 174: PKG_CONFIG_SYSROOT_DIR is set to /target, which is useful when cross compiling
1.18 jasper 175: packages that use
176: .Nm .
1.16 jasper 177: .It Ev PKG_CONFIG_TOP_BUILD_DIR
178: If set
179: .Nm
180: uses the specified value for
181: .Em pc_top_builddir
182: instead of $(top_builddir).
1.1 ckuethe 183: .El
1.14 jmc 184: .Sh EXIT STATUS
185: .Ex -std pkg-config
1.1 ckuethe 186: .Sh SEE ALSO
187: .Xr pkg_info 1 ,
188: .Xr ports 7
189: .Sh HISTORY
190: The
191: .Nm
192: utility first appeared in
1.11 jmc 193: .Ox 4.1 .
1.20 jasper 194: .Sh AUTHORS
195: .Nm
196: was written by
1.30 schwarze 197: .An Chris Kuethe Aq Mt ckuethe@openbsd.org
1.20 jasper 198: as a replacement for the original freedesktop.org
199: .Nm
200: implementation.
201: It was later extended and kept in sync (where relevant) with the original
202: version by
1.30 schwarze 203: .An Marc Espie Aq Mt espie@openbsd.org
1.20 jasper 204: and
1.30 schwarze 205: .An Jasper Lievisse Adriaanse Aq Mt jasper@openbsd.org .
1.23 jasper 206: .Sh CAVEATS
207: .Nm
208: is a re-implementation of the "original" freedesktop.org program.
209: While it tries to be compatible, there are several
210: design/functionality differences one should be aware of:
211: .Bl -tag -width Ds
212: .It Ev Conflicts
213: It was decided not to support the Conflicts keyword as there is
214: currently too little benefit from it in
215: .Ox
216: where the ports tree is supposed to prevent conflicts from arising
217: in the first place.
218: Lines with this keyword are not treated as errors, they are just ignored.
219: And they are not taken into account when
220: .Cm --print-errors
221: is passed.
222: .It Ev Cflags and -i
223: The
224: .Fl i
225: flag that can be encountered in Cflags is not treated differently from
226: .Fl I
227: in this implementation.
228: .It Ev Whitespace
229: .Nm
230: does not go to great lengths to try to fix whitespace abuse.
231: Whitespace in Libs and Cflags lines that are escaped using \e are
232: treated correctly.
233: But strings enclosed in quotation marks that contain whitespaces are not.
234: .El