1 | .\" |
---|
2 | .\" pkg-config manual page. |
---|
3 | .\" (C) Red Hat, Inc. based on gnome-config man page (C) Miguel de Icaza (miguel@gnu.org) |
---|
4 | .\" |
---|
5 | .TH pkg-config 1 |
---|
6 | .SH NAME |
---|
7 | pkg-config \- Return metainformation about installed libraries |
---|
8 | .SH SYNOPSIS |
---|
9 | .PP |
---|
10 | .B pkg-config |
---|
11 | [\-\-modversion] [\-\-help] [\-\-print-errors] [\-\-silence-errors] |
---|
12 | [\-\-cflags] [\-\-libs] [\-\-libs-only-L] |
---|
13 | [\-\-libs-only-l] [\-\-cflags-only-I] |
---|
14 | [\-\-variable=VARIABLENAME] |
---|
15 | [\-\-define-variable=VARIABLENAME=VARIABLEVALUE] |
---|
16 | [\-\-uninstalled] |
---|
17 | [\-\-exists] [\-\-atleast-version=VERSION] [\-\-exact-version=VERSION] |
---|
18 | [\-\-max-version=VERSION] [LIBRARIES...] |
---|
19 | .SH DESCRIPTION |
---|
20 | |
---|
21 | The \fIpkg-config\fP program is used to retrieve information about |
---|
22 | installed libraries in the system. It is typically used to compile |
---|
23 | and link against one or more libraries. Here is a typical usage |
---|
24 | scenario in a Makefile: |
---|
25 | .PP |
---|
26 | .nf |
---|
27 | program: program.c |
---|
28 | cc program.c `pkg-config --cflags --libs gnomeui` |
---|
29 | .fi |
---|
30 | .PP |
---|
31 | |
---|
32 | .PP |
---|
33 | \fIpkg-config\fP retrieves information about packages from |
---|
34 | special metadata files. These files are named after the package, |
---|
35 | with the extension \fI.pc\fP. By default, pkg-config looks in |
---|
36 | the directory \fIprefix\fP/lib/pkgconfig for these files; it will also |
---|
37 | look in the colon-separated (on Windows, semicolon-separated) |
---|
38 | list of directories specified by the |
---|
39 | PKG_CONFIG_PATH environment variable. |
---|
40 | |
---|
41 | .PP |
---|
42 | The package name specified on the \fIpkg-config\fP command line is |
---|
43 | defined to be the name of the metadata file, minus the \fI.pc\fP |
---|
44 | extension. If a library can install multiple versions simultaneously, |
---|
45 | it must give each version its own name (for example, GTK 1.2 might |
---|
46 | have the package name "gtk+" while GTK 2.0 has "gtk+-2.0"). |
---|
47 | |
---|
48 | .SH OPTIONS |
---|
49 | The following options are supported: |
---|
50 | .TP |
---|
51 | .I "--modversion" |
---|
52 | Requests that the version information of the libraries specified on |
---|
53 | the command line be displayed. If \fIpkg-config\fP can find all the |
---|
54 | libraries on the command line, each library's version string is |
---|
55 | printed to stdout, one version per line. In this case \fIpkg-config\fP |
---|
56 | exits successfully. If one or more libraries is unknown, |
---|
57 | \fIpkg-config\fP exits with a nonzero code, and the contents of stdout |
---|
58 | are undefined. |
---|
59 | .TP |
---|
60 | .I "--help" |
---|
61 | Displays a help message and terminates. |
---|
62 | |
---|
63 | .TP |
---|
64 | .I "--print-errors" |
---|
65 | If one or more of the modules on the command line, or their |
---|
66 | dependencies, are not found, or if an error occurs in parsing a |
---|
67 | \fI.pc\fP file, then this option will cause errors explaining the |
---|
68 | problem to be printed. With "predicate" options such as "--exists" |
---|
69 | \fIpkg-config\fP runs silently by default, because it's usually used |
---|
70 | in scripts that want to control what's output. This option can be used |
---|
71 | alone (to just print errors encountered locating modules on the |
---|
72 | command line) or with other options. The PKG_CONFIG_DEBUG_SPEW |
---|
73 | environment variable overrides this option. |
---|
74 | |
---|
75 | .TP |
---|
76 | .I "--silence-errors" |
---|
77 | If one or more of the modules on the command line, or their |
---|
78 | dependencies, are not found, or if an error occurs in parsing a |
---|
79 | \fI.pc\fP file, then this option will keep errors explaining the |
---|
80 | problem from being printed. With "predicate" options such as |
---|
81 | "--exists" \fIpkg-config\fP runs silently by default, because it's |
---|
82 | usually used in scripts that want to control what's output. So this |
---|
83 | option is only useful with options such as "--cflags" or |
---|
84 | "--modversion" that print errors by default. The PKG_CONFIG_DEBUG_SPEW |
---|
85 | environment variable overrides this option. |
---|
86 | |
---|
87 | .TP |
---|
88 | .I "--errors-to-stdout" |
---|
89 | If printing errors, print them to stdout rather than the default stderr |
---|
90 | |
---|
91 | .PP |
---|
92 | The following options are used to compile and link programs: |
---|
93 | .TP |
---|
94 | .I "--cflags" |
---|
95 | This prints pre-processor and compile flags required to compile the |
---|
96 | packages on the command line, including flags for all their |
---|
97 | dependencies. Flags are "compressed" so that each identical flag |
---|
98 | appears only once. \fIpkg-config\fP exits with a nonzero code if it |
---|
99 | can't find metadata for one or more of the packages on the command |
---|
100 | line. |
---|
101 | .TP |
---|
102 | .I "--libs" |
---|
103 | This option is identical to "--cflags", only it prints the link |
---|
104 | flags. As with "--cflags", duplicate flags are merged (maintaining |
---|
105 | proper ordering), and flags for dependencies are included in the |
---|
106 | output. |
---|
107 | .TP |
---|
108 | .I "--libs-only-L" |
---|
109 | This prints the -L/-R part of "--libs". That is, it defines the |
---|
110 | library search path but doesn't specify which libraries to link with. |
---|
111 | .TP |
---|
112 | .I "--libs-only-l" |
---|
113 | This prints the -l part of "--libs" for the libraries specified on |
---|
114 | the command line. Note that the union of "--libs-only-l" and |
---|
115 | "--libs-only-L" may be smaller than "--libs", due to flags such as |
---|
116 | -rdynamic. |
---|
117 | |
---|
118 | .TP |
---|
119 | .I "--variable=VARIABLENAME" |
---|
120 | This returns the value of a variable defined in a package's \fI.pc\fP |
---|
121 | file. Most packages define the variable "prefix", for example, so you |
---|
122 | can say: |
---|
123 | .nf |
---|
124 | $ pkg-config --variable=prefix glib-2.0 |
---|
125 | /usr/ |
---|
126 | .fi |
---|
127 | .TP |
---|
128 | .I "--define-variable=VARIABLENAME=VARIABLEVALUE" |
---|
129 | This sets a global value for a variable, overriding the value in any |
---|
130 | \fI.pc\fP files. Most packages define the variable "prefix", for |
---|
131 | example, so you can say: |
---|
132 | .nf |
---|
133 | $ pkg-config --print-errors --define-variable=prefix=/foo --variable=prefix glib-2.0 |
---|
134 | /foo |
---|
135 | .fi |
---|
136 | |
---|
137 | .TP |
---|
138 | .I "--uninstalled" |
---|
139 | Normally if you request the package "foo" and the package |
---|
140 | "foo-uninstalled" exists, \fIpkg-config\fP will prefer the |
---|
141 | "-uninstalled" variant. This allows compilation/linking against |
---|
142 | uninstalled packages. If you specify the "--uninstalled" option, |
---|
143 | \fIpkg-config\fP will return successfully if any "-uninstalled" |
---|
144 | packages are being used, and return failure (false) otherwise. |
---|
145 | (The "PKG_CONFIG_DISABLE_UNINSTALLED" environment variable keeps |
---|
146 | \fIpkg-config\fP from implicitly choosing "-uninstalled" packages, so |
---|
147 | if that variable is set, they will only have been used if you pass |
---|
148 | a name like "foo-uninstalled" on the command line explicitly.) |
---|
149 | |
---|
150 | .TP |
---|
151 | .I "--exists" |
---|
152 | .TP |
---|
153 | .I "--atleast-version=VERSION" |
---|
154 | .TP |
---|
155 | .I "--exact-version=VERSION" |
---|
156 | .TP |
---|
157 | .I "--max-version=VERSION" |
---|
158 | These options test whether the package or list of packages on the |
---|
159 | command line are known to \fIpkg-config\fP, and optionally |
---|
160 | whether the version number of a package meets certain contraints. |
---|
161 | If all packages exist and meet the specified version constraints, |
---|
162 | \fIpkg-config\fP exits successfully. Otherwise it exits unsuccessfully. |
---|
163 | |
---|
164 | Rather than using the version-test options, you can simply give a version |
---|
165 | constraint after each package name, for example: |
---|
166 | .nf |
---|
167 | $ pkg-config --exists 'glib-2.0 >= 1.3.4 libxml = 1.8.3' |
---|
168 | .fi |
---|
169 | Remember to use \-\-print-errors if you want error messages. |
---|
170 | |
---|
171 | .TP |
---|
172 | .I "--msvc-syntax" |
---|
173 | This option is available only on Windows. It causes \fIpkg-config\fP |
---|
174 | to output -l and -L flags in the form recognized by the Microsoft |
---|
175 | Visual C++ command-line compiler, \fIcl\fP. Specifically, instead of |
---|
176 | \fI-Lx:/some/path\fP it prints \fI/libpath:x/some/path\fP, and instead |
---|
177 | of \fI-lfoo\fP it prints \fIfoo.lib\fP. Note that the --libs output |
---|
178 | consists of flags for the linker, and should be placed on the cl |
---|
179 | command line after a /link switch. |
---|
180 | |
---|
181 | .TP |
---|
182 | .I "--dont-define-prefix" |
---|
183 | This option is available only on Windows. It prevents \fIpkg-config\fP |
---|
184 | from automatically trying to override the value of the variable |
---|
185 | "prefix" in each .pc file. |
---|
186 | |
---|
187 | .TP |
---|
188 | .I "--prefix-variable=PREFIX" |
---|
189 | Also this option is available only on Windows. It sets the name of the |
---|
190 | variable that \fIpkg-config\fP automatically sets as described above. |
---|
191 | |
---|
192 | .SH ENVIRONMENT VARIABLES |
---|
193 | |
---|
194 | .TP |
---|
195 | .I "PKG_CONFIG_PATH" |
---|
196 | A colon-separated (on Windows, semicolon-separated) |
---|
197 | list of directories to search for .pc files. |
---|
198 | The default directory will always be searched after searching the |
---|
199 | path; the default is \fIlibdir\fP/pkgconfig where \fIlibdir\fP |
---|
200 | is the libdir where \fIpkg-config\fP was installed. |
---|
201 | |
---|
202 | .TP |
---|
203 | .I "PKG_CONFIG_DEBUG_SPEW" |
---|
204 | If set, causes \fIpkg-config\fP to print all kinds of |
---|
205 | debugging information and report all errors. |
---|
206 | |
---|
207 | .TP |
---|
208 | .I "PKG_CONFIG_TOP_BUILD_DIR" |
---|
209 | A value to set for the magic variable \fIpc_top_builddir\fP |
---|
210 | which may appear in \fI.pc\fP files. If the environment variable is |
---|
211 | not set, the default value '$(top_builddir)' will be used. This |
---|
212 | variable should refer to the top builddir of the Makefile where the |
---|
213 | compile/link flags reported by \fIpkg-config\fP will be used. |
---|
214 | This only matters when compiling/linking against a package that hasn't |
---|
215 | yet been installed. |
---|
216 | |
---|
217 | .TP |
---|
218 | .I "PKG_CONFIG_DISABLE_UNINSTALLED" |
---|
219 | Normally if you request the package "foo" and the package |
---|
220 | "foo-uninstalled" exists, \fIpkg-config\fP will prefer the |
---|
221 | "-uninstalled" variant. This allows compilation/linking against |
---|
222 | uninstalled packages. If this environment variable is set, it |
---|
223 | disables said behavior. |
---|
224 | |
---|
225 | .TP |
---|
226 | .I "PKG_CONFIG_ALLOW_SYSTEM_CFLAGS" |
---|
227 | Don't strip -I/usr/include out of cflags. |
---|
228 | |
---|
229 | .TP |
---|
230 | .I "PKG_CONFIG_ALLOW_SYSTEM_LIBS" |
---|
231 | Don't strip -L/usr/lib out of libs |
---|
232 | |
---|
233 | .SH WINDOWS SPECIALITIES |
---|
234 | If a .pc file is found in a directory that matches the usual |
---|
235 | conventions (i.e., ends with \\lib\\pkgconfig), the prefix for that |
---|
236 | package is assumed to be the grandparent of the directory where the |
---|
237 | file was found, and the \fIprefix\fP variable is overridden for that |
---|
238 | file accordingly. |
---|
239 | |
---|
240 | In addition to the \fIPKG_CONFIG_PATH\fP environment variable, the |
---|
241 | Registry keys |
---|
242 | \fIHKEY_CURRENT_USER\\Software\\pkgconfig\\PKG_CONFIG_PATH\fP and |
---|
243 | \fIHKEY_LOCAL_MACHINE\\Software\\pkgconfig\\PKG_CONFIG_PATH\fP can be |
---|
244 | used to specify directories to search for .pc files. Each (string) |
---|
245 | value in these keys is treated as a directory where to look for .pc |
---|
246 | files. |
---|
247 | |
---|
248 | .SH AUTOCONF MACROS |
---|
249 | |
---|
250 | .TP |
---|
251 | .I "PKG_CHECK_MODULES(VARIABLEBASE,MODULELIST[,ACTION-IF-FOUND,[ACTION-IF-NOT-FOUND]])" |
---|
252 | |
---|
253 | The macro PKG_CHECK_MODULES can be used in \fIconfigure.in\fP to |
---|
254 | check whether modules exist. A typical usage would be: |
---|
255 | .nf |
---|
256 | PKG_CHECK_MODULES(MYSTUFF, gtk+-2.0 >= 1.3.5 libxml = 1.8.4) |
---|
257 | .fi |
---|
258 | |
---|
259 | This would result in MYSTUFF_LIBS and MYSTUFF_CFLAGS substitution |
---|
260 | variables, set to the libs and cflags for the given module list. |
---|
261 | If a module is missing or has the wrong version, by default configure |
---|
262 | will abort with a message. To replace the default action, |
---|
263 | specify an ACTION-IF-NOT-FOUND. PKG_CHECK_MODULES will not print any |
---|
264 | error messages if you specify your own ACTION-IF-NOT-FOUND. |
---|
265 | However, it will set the variable MYSTUFF_PKG_ERRORS, which you can |
---|
266 | use to display what went wrong. |
---|
267 | |
---|
268 | If you want to use MYSTUFF_LIBS and MYSTUFF_CFLAGS as Makefile.am |
---|
269 | variables (i.e. $(MYSTUFF_LIBS)) then you have to add |
---|
270 | AC_SUBST(MYSTUFF_LIBS) to your configure.in so automake can find the |
---|
271 | variable. You don't need to do this if you use the @MYSTUFF_LIBS@ |
---|
272 | syntax in your Makefile.am instead of $(MYSTUFF_LIBS). |
---|
273 | |
---|
274 | .SH METADATA FILE SYNTAX |
---|
275 | To add a library to the set of packages \fIpkg-config\fP knows about, |
---|
276 | simply install a \fI.pc\fP file. You should install this file to |
---|
277 | \fIlibdir\fP/pkgconfig. |
---|
278 | |
---|
279 | .PP |
---|
280 | Here is an example file: |
---|
281 | .nf |
---|
282 | # This is a comment |
---|
283 | prefix=/home/hp/unst # this defines a variable |
---|
284 | exec_prefix=${prefix} # defining another variable in terms of the first |
---|
285 | libdir=${exec_prefix}/lib |
---|
286 | includedir=${prefix}/include |
---|
287 | |
---|
288 | Name: GObject # human-readable name |
---|
289 | Description: Object/type system for GLib # human-readable description |
---|
290 | Version: 1.3.1 |
---|
291 | Requires: glib-2.0 = 1.3.1 |
---|
292 | Conflicts: foobar <= 4.5 |
---|
293 | Libs: -L${libdir} -lgobject-1.3 |
---|
294 | Cflags: -I${includedir}/glib-2.0 -I${libdir}/glib/include |
---|
295 | .fi |
---|
296 | |
---|
297 | .PP |
---|
298 | You would normally generate the file using configure, of course, so |
---|
299 | that the prefix, etc. are set to the proper values. |
---|
300 | |
---|
301 | .PP |
---|
302 | Files have two kinds of line: keyword lines start with a keyword plus |
---|
303 | a colon, and variable definitions start with an alphanumeric string |
---|
304 | plus an equals sign. Keywords are defined in advance and have special |
---|
305 | meaning to \fIpkg-config\fP; variables do not, you can have any |
---|
306 | variables that you wish (however, users may expect to retrieve the |
---|
307 | usual directory name variables). |
---|
308 | |
---|
309 | .PP |
---|
310 | Note that variable references are written "${foo}"; you can escape |
---|
311 | literal "${" as "$${". |
---|
312 | |
---|
313 | .TP |
---|
314 | .I "Name:" |
---|
315 | This field should be a human-readable name for the package. Note that |
---|
316 | it is not the name passed as an argument to \fIpkg-config\fP. |
---|
317 | .TP |
---|
318 | .I "Description:" |
---|
319 | This should be a brief description of the package |
---|
320 | .TP |
---|
321 | .I "Version:" |
---|
322 | This should be the most-specific-possible package version string. |
---|
323 | .TP |
---|
324 | .I "Requires:" |
---|
325 | This is a comma-separated list of packages that are required by your |
---|
326 | package. Flags from dependent packages will be merged in to the flags |
---|
327 | reported for your package. Optionally, you can specify the version |
---|
328 | of the required package (using the operators =, <, >, >=, <=); |
---|
329 | specifying a version allows \fIpkg-config\fP to perform extra sanity |
---|
330 | checks. You may only mention the same package one time on the |
---|
331 | .I "Requires:" |
---|
332 | line. If the version of a package is unspecified, any version will |
---|
333 | be used with no checking. |
---|
334 | .TP |
---|
335 | .I "Conflicts:" |
---|
336 | This optional line allows \fIpkg-config\fP to perform additional |
---|
337 | sanity checks, primarily to detect broken user installations. The |
---|
338 | syntax is the same as |
---|
339 | .I "Requires:" |
---|
340 | except that |
---|
341 | you can list the same package more than once here, for example |
---|
342 | "foobar = 1.2.3, foobar = 1.2.5, foobar >= 1.3", if you have reason to |
---|
343 | do so. If a version isn't specified, then your package conflicts with |
---|
344 | all versions of the mentioned package. |
---|
345 | If a user tries to use your package and a conflicting package at the |
---|
346 | same time, then \fIpkg-config\fP will complain. |
---|
347 | .TP |
---|
348 | .I "Libs:" |
---|
349 | This line should give the link flags specific to your package. |
---|
350 | Don't add any flags for required packages; \fIpkg-config\fP will |
---|
351 | add those automatically. |
---|
352 | |
---|
353 | .TP |
---|
354 | .I "Cflags:" |
---|
355 | This line should list the compile flags specific to your package. |
---|
356 | Don't add any flags for required packages; \fIpkg-config\fP will |
---|
357 | add those automatically. |
---|
358 | |
---|
359 | .SH AUTHOR |
---|
360 | |
---|
361 | \fIpkg-config\fP was written by James Henstridge, rewritten by Martijn |
---|
362 | van Beers, and rewritten again by Havoc Pennington. Tim Janik, Owen |
---|
363 | Taylor, and Raja Harinath submitted suggestions and some code. |
---|
364 | \fIgnome-config\fP was written by Miguel de Icaza, Raja Harinath and |
---|
365 | various hackers in the GNOME team. It was inspired by Owen Taylor's |
---|
366 | \fIgtk-config\fP program. |
---|
367 | |
---|
368 | .SH BUGS |
---|
369 | Hah! |
---|
370 | |
---|
371 | |
---|