Annotation of src/usr.bin/pkg-config/pkg-config.1, Revision 1.27
1.27 ! ajacouto 1: .\" $OpenBSD: pkg-config.1,v 1.26 2012/03/19 10:25:17 ajacoutot 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.27 ! ajacouto 17: .Dd $Mdocdate: March 19 2012 $
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
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.
87: .It Cm --exists
88: Return true if all the specified packages are installed.
1.9 jmc 89: This is the default operation.
90: .It Cm --help \*(Ba --usage
1.7 jmc 91: Print a help message and exit.
92: .It Cm --libs
1.8 jmc 93: Return all linker flags required to link against the package.
1.12 jmc 94: .It Cm --libs-only-L
95: Return only the library path (-L/path/to/lib) flags required to link
96: against the package.
1.7 jmc 97: .It Cm --libs-only-l
1.1 ckuethe 98: Return only the library (-lwhatever) flags required to link against
99: the package.
1.7 jmc 100: .It Cm --libs-only-other
1.1 ckuethe 101: Return linker flags, other than the library and path flags, required to
102: compile against the package.
1.7 jmc 103: .It Cm --list-all
104: List all installed packages and exit.
105: .It Cm --modversion
1.3 ckuethe 106: Fetch package version.
107: If no package is given,
108: .Nm
109: returns its own version.
1.7 jmc 110: .It Cm --print-errors
111: Print error messages and exit with an error when errors occur.
1.9 jmc 112: This is the default operation.
1.17 jasper 113: .It Cm --print-provides
114: Print all the modules the given package provides.
115: .It Cm --print-requires
116: Print all the modules the given package requires.
117: .It Cm --print-requires-private
118: Print all the modules the given package requires for static linking.
1.7 jmc 119: .It Cm --silence-errors
120: Do not print error messages, just exit with an error.
121: .It Cm --static
122: Return the compiler and/or linker flags required for static linking.
123: .It Cm --uninstalled
124: Allow packages not controlled by
125: .Nm
126: to be used.
127: .It Cm --variable Ar name
1.1 ckuethe 128: Fetch the value of the named variable.
1.7 jmc 129: .It Cm --version
130: Print version of
131: .Nm
132: and exit.
1.1 ckuethe 133: .El
134: .Sh ENVIRONMENT
1.16 jasper 135: .Bl -tag -width Ds
136: .It Ev PKG_CONFIG_DEBUG_SPEW
137: If set, this will cause
138: .Nm
139: to print various debugging information.
140: .It Ev PKG_CONFIG_DISABLE_UNINSTALLED
141: By default
142: .Nm
143: prefers a package named "foo-uninstalled" over "foo" when the package
144: "foo" is requested.
145: This allows linking/compiling against uninstalled packages.
146: Setting this flag disables the default behaviour.
147: .It Ev PKG_CONFIG_LIBDIR
148: This can be used to specify a colon-separated list of paths to search for
149: package files.
150: This will replace the default
151: .Nm
152: search directory.
1.22 jasper 153: .It Ev PKG_CONFIG_LOG
1.19 jasper 154: This is used to specify a log file to which
1.16 jasper 155: .Nm
156: will write the passed arguments.
1.1 ckuethe 157: .It Ev PKG_CONFIG_PATH
158: This can be used to specify a colon-separated list of paths to search for
159: package files.
160: If given, this list of paths is prepended to the standard search path.
1.18 jasper 161: .It Ev PKG_CONFIG_SYSROOT_DIR
162: This modifies
163: .Fl I
164: and
165: .Fl L
166: to use the target sysroot directory.
167: Thus -I/usr/local/include will become -I/target/usr/local/include when
1.19 jasper 168: PKG_CONFIG_SYSROOT_DIR is set to /target, which is useful when cross compiling
1.18 jasper 169: packages that use
170: .Nm .
1.16 jasper 171: .It Ev PKG_CONFIG_TOP_BUILD_DIR
172: If set
173: .Nm
174: uses the specified value for
175: .Em pc_top_builddir
176: instead of $(top_builddir).
1.1 ckuethe 177: .El
1.14 jmc 178: .Sh EXIT STATUS
179: .Ex -std pkg-config
1.1 ckuethe 180: .Sh SEE ALSO
181: .Xr pkg_info 1 ,
182: .Xr ports 7
183: .Sh HISTORY
184: The
185: .Nm
186: utility first appeared in
1.11 jmc 187: .Ox 4.1 .
1.20 jasper 188: .Sh AUTHORS
189: .Nm
190: was written by
191: .An Chris Kuethe Aq ckuethe@openbsd.org
192: as a replacement for the original freedesktop.org
193: .Nm
194: implementation.
195: It was later extended and kept in sync (where relevant) with the original
196: version by
197: .An Marc Espie Aq espie@openbsd.org
198: and
1.21 jasper 199: .An Jasper Lievisse Adriaanse Aq jasper@openbsd.org .
1.23 jasper 200: .Sh CAVEATS
201: .Nm
202: is a re-implementation of the "original" freedesktop.org program.
203: While it tries to be compatible, there are several
204: design/functionality differences one should be aware of:
205: .Bl -tag -width Ds
206: .It Ev Conflicts
207: It was decided not to support the Conflicts keyword as there is
208: currently too little benefit from it in
209: .Ox
210: where the ports tree is supposed to prevent conflicts from arising
211: in the first place.
212: Lines with this keyword are not treated as errors, they are just ignored.
213: And they are not taken into account when
214: .Cm --print-errors
215: is passed.
216: .It Ev Cflags and -i
217: The
218: .Fl i
219: flag that can be encountered in Cflags is not treated differently from
220: .Fl I
221: in this implementation.
222: .It Ev Whitespace
223: .Nm
224: does not go to great lengths to try to fix whitespace abuse.
225: Whitespace in Libs and Cflags lines that are escaped using \e are
226: treated correctly.
227: But strings enclosed in quotation marks that contain whitespaces are not.
228: .El