Annotation of src/usr.bin/pkg-config/pkg-config.1, Revision 1.37
1.37 ! naddy 1: .\" $OpenBSD: pkg-config.1,v 1.36 2021/12/26 02:53:17 kn 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.37 ! naddy 17: .Dd $Mdocdate: December 26 2021 $
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.36 kn 46: .Pa /usr/local/lib/pkgconfig
1.26 ajacouto 47: and
1.36 kn 48: .Pa /usr/local/share/pkgconfig ;
1.2 ckuethe 49: the X Window System stores its metadata in
1.36 kn 50: .Pa /usr/X11R6/lib/pkgconfig
1.26 ajacouto 51: and
1.36 kn 52: .Pa /usr/X11R6/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.
1.32 jasper 133: .It Cm --validate
134: Validate the package without processing its dependencies.
1.7 jmc 135: .It Cm --variable Ar name
1.1 ckuethe 136: Fetch the value of the named variable.
1.7 jmc 137: .It Cm --version
138: Print version of
139: .Nm
140: and exit.
1.1 ckuethe 141: .El
142: .Sh ENVIRONMENT
1.16 jasper 143: .Bl -tag -width Ds
144: .It Ev PKG_CONFIG_DEBUG_SPEW
145: If set, this will cause
146: .Nm
147: to print various debugging information.
148: .It Ev PKG_CONFIG_DISABLE_UNINSTALLED
149: By default
150: .Nm
151: prefers a package named "foo-uninstalled" over "foo" when the package
152: "foo" is requested.
153: This allows linking/compiling against uninstalled packages.
154: Setting this flag disables the default behaviour.
155: .It Ev PKG_CONFIG_LIBDIR
156: This can be used to specify a colon-separated list of paths to search for
157: package files.
158: This will replace the default
159: .Nm
160: search directory.
1.22 jasper 161: .It Ev PKG_CONFIG_LOG
1.19 jasper 162: This is used to specify a log file to which
1.16 jasper 163: .Nm
164: will write the passed arguments.
1.1 ckuethe 165: .It Ev PKG_CONFIG_PATH
166: This can be used to specify a colon-separated list of paths to search for
167: package files.
168: If given, this list of paths is prepended to the standard search path.
1.18 jasper 169: .It Ev PKG_CONFIG_SYSROOT_DIR
170: This modifies
171: .Fl I
172: and
173: .Fl L
174: to use the target sysroot directory.
175: Thus -I/usr/local/include will become -I/target/usr/local/include when
1.19 jasper 176: PKG_CONFIG_SYSROOT_DIR is set to /target, which is useful when cross compiling
1.18 jasper 177: packages that use
178: .Nm .
1.35 jasper 179: .It Ev PKG_CONFIG_SYSTEM_INCLUDE_PATH
180: When set to a list of paths, separated by :, these paths will be excluded from
181: the output of include paths set with
182: .Fl I .
1.16 jasper 183: .It Ev PKG_CONFIG_TOP_BUILD_DIR
1.37 ! naddy 184: If set,
1.16 jasper 185: .Nm
186: uses the specified value for
187: .Em pc_top_builddir
188: instead of $(top_builddir).
1.33 jasper 189: .It Ev PKG_CONFIG_$PACKAGE_$VARIABLE
190: Override the $VARIABLE in $PACKAGE with the given value.
1.1 ckuethe 191: .El
1.14 jmc 192: .Sh EXIT STATUS
193: .Ex -std pkg-config
1.1 ckuethe 194: .Sh SEE ALSO
195: .Xr pkg_info 1 ,
196: .Xr ports 7
197: .Sh HISTORY
198: The
199: .Nm
200: utility first appeared in
1.11 jmc 201: .Ox 4.1 .
1.20 jasper 202: .Sh AUTHORS
1.34 schwarze 203: .An -nosplit
1.20 jasper 204: .Nm
205: was written by
1.30 schwarze 206: .An Chris Kuethe Aq Mt ckuethe@openbsd.org
1.20 jasper 207: as a replacement for the original freedesktop.org
208: .Nm
209: implementation.
210: It was later extended and kept in sync (where relevant) with the original
211: version by
1.30 schwarze 212: .An Marc Espie Aq Mt espie@openbsd.org
1.20 jasper 213: and
1.30 schwarze 214: .An Jasper Lievisse Adriaanse Aq Mt jasper@openbsd.org .
1.23 jasper 215: .Sh CAVEATS
216: .Nm
217: is a re-implementation of the "original" freedesktop.org program.
218: While it tries to be compatible, there are several
219: design/functionality differences one should be aware of:
220: .Bl -tag -width Ds
221: .It Ev Conflicts
222: It was decided not to support the Conflicts keyword as there is
223: currently too little benefit from it in
224: .Ox
225: where the ports tree is supposed to prevent conflicts from arising
226: in the first place.
227: Lines with this keyword are not treated as errors, they are just ignored.
228: And they are not taken into account when
229: .Cm --print-errors
230: is passed.
231: .It Ev Cflags and -i
232: The
233: .Fl i
234: flag that can be encountered in Cflags is not treated differently from
235: .Fl I
236: in this implementation.
237: .It Ev Whitespace
238: .Nm
239: does not go to great lengths to try to fix whitespace abuse.
240: Whitespace in Libs and Cflags lines that are escaped using \e are
241: treated correctly.
242: But strings enclosed in quotation marks that contain whitespaces are not.
243: .El
![[BACK]](/icons/back.gif){kind=icon}
Return to pkg-config.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / pkg-config