170 lines
5.5 KiB
Markdown
170 lines
5.5 KiB
Markdown
PC(5)
|
|
|
|
; SPDX-FileCopyrightText: 2022 pkgconf authors
|
|
; SPDX-License-Identifier: ISC
|
|
|
|
; TODO: old manpages often have two spaces after a full stop, as a newline in
|
|
; mdoc seem to mean no newline but two spaces in the output.
|
|
; Should I do the same?
|
|
|
|
# NAME
|
|
|
|
*file.pc* — pkg-config file format
|
|
|
|
# DESCRIPTION
|
|
|
|
pkg-config files provide a useful mechanism for storing various information
|
|
about libraries and packages on a given system. Information stored by *.pc*
|
|
files include compiler and linker flags necessary to use a given library, as
|
|
well as any other relevant metadata.
|
|
|
|
These *.pc* files are processed by a utility called pkg-config, of which pkgconf
|
|
is an implementation.
|
|
|
|
## FILE SYNTAX
|
|
|
|
The *.pc* file follows a format inspired by RFC822. Comments are prefixed by a
|
|
pound sign, hash sign or octothorpe (#), and variable assignment is similar to
|
|
POSIX shell. Properties are defined using RFC822-style stanzas.
|
|
|
|
## VARIABLES
|
|
|
|
Variable definitions start with an alphanumeric string, followed by an equal
|
|
sign, and then the value the variable should contain.
|
|
|
|
Variable references are always written as "${variable}". It is possible to
|
|
escape literal "${" as "$${".
|
|
|
|
## PROPERTIES
|
|
|
|
Properties are set using RFC822-style stanzas which consist of a keyword,
|
|
followed by a colon (:) and then the value the property should be set to.
|
|
Variable substitution is always performed regardless of property type.
|
|
|
|
There are three types of property:
|
|
|
|
Literal
|
|
The property will be set to the text of the value.
|
|
|
|
Dependency List
|
|
The property will be set to a list of dependencies parsed from the text.
|
|
Dependency lists are defined by this ABNF syntax:
|
|
|
|
```
|
|
package-list = *WSP *( package-spec *( package-sep ) )
|
|
package-sep = WSP / ","
|
|
package-spec = package-key [ ver-op package-version ]
|
|
ver-op = "<" / "<=" / "=" / "!=" / ">=" / ">"
|
|
```
|
|
|
|
Fragment List
|
|
The property will be set to a list of fragments parsed from the text. The
|
|
input text must be in a format that is suitable for passing to a POSIX shell
|
|
without any shell expansions after variable substitution has been done.
|
|
|
|
## PROPERTY KEYWORDS
|
|
|
|
Name
|
|
The displayed name of the package. (mandatory; literal)
|
|
|
|
Version
|
|
The version of the package. (mandatory; literal)
|
|
|
|
Description
|
|
A description of the package. (mandatory; literal)
|
|
|
|
URL
|
|
A URL to a webpage for the package. This is used to recommend where newer
|
|
versions of the package can be acquired. (mandatory; literal)
|
|
|
|
Cflags
|
|
Required compiler flags. These flags are always used, regardless of whether
|
|
static compilation is requested. (optional; fragment list)
|
|
|
|
Cflags.private
|
|
Required compiler flags for static compilation. (optional; fragment list;
|
|
pkgconf extension)
|
|
|
|
Copyright
|
|
A copyright attestation statement. (optional; literal; pkgconf extension)
|
|
|
|
Libs
|
|
Required linking flags for this package. Libraries this package depends on
|
|
for linking against it, which are not described as dependencies should be
|
|
specified here. (optional; fragment list)
|
|
|
|
Libs.private
|
|
Required linking flags for this package that are only required when linking
|
|
statically. Libraries this package depends on for linking against it
|
|
statically, which are not described as dependencies should be specified
|
|
here. (optional; fragment list)
|
|
|
|
License
|
|
The asserted SPDX license tag that should be applied to the given package.
|
|
(optional; literal; pkgconf extension)
|
|
|
|
Maintainer
|
|
The preferred contact for the maintainer. This should be in the format of a
|
|
name followed by an e-mail address or website. (optional; literal; pkgconf
|
|
extension)
|
|
|
|
Requires
|
|
Required dependencies that must be met for the package to be usable. All
|
|
dependencies must be satisfied or the pkg-config implementation must not use
|
|
the package. (optional; dependency list)
|
|
|
|
Requires.private
|
|
Required dependencies that must be met for the package to be usable for
|
|
static linking. All dependencies must be satisfied or the pkg-config
|
|
implementation must not use the package for static linking. (optional;
|
|
dependency list)
|
|
|
|
Conflicts
|
|
Dependencies that must not be met for the package to be usable. If any
|
|
package in the proposed dependency solution match any dependency in the
|
|
Conflicts list, the package being considered is not usable. (optional;
|
|
dependency list)
|
|
|
|
Provides
|
|
Dependencies that may be provided by an alternate package. If a package
|
|
cannot be found, the entire package collection is scanned for providers
|
|
which can match the requested dependency. (optional; dependency list;
|
|
pkgconf extension)
|
|
|
|
## EXTENSIONS
|
|
|
|
Features that have been marked as a pkgconf extension are only guaranteed to
|
|
work with the pkgconf implementation of pkg-config. Other implementations may or
|
|
may not support the extensions.
|
|
|
|
Accordingly, it is suggested that *.pc* files which absolutely depend on these
|
|
extensions declare a requirement on the pkgconf virtual.
|
|
|
|
# EXAMPLES
|
|
|
|
An example *.pc* file:
|
|
|
|
```
|
|
# This is a comment
|
|
prefix=/home/kaniini/pkg # this defines a variable
|
|
exec_prefix=${prefix} # defining another variable with a substitution
|
|
libdir=${exec_prefix}/lib
|
|
includedir=${prefix}/include
|
|
|
|
Name: libfoo # human-readable name
|
|
Description: an example library called libfoo # human-readable description
|
|
Copyright: Copyright (c) 2022 pkgconf project authors
|
|
License: Apache-2.0
|
|
Maintainer: the pkgconf project <http://www.pkgconf.org>
|
|
Version: 1.0
|
|
URL: http://www.pkgconf.org
|
|
Requires: libbar > 2.0.0
|
|
Conflicts: libbaz <= 3.0.0
|
|
Libs: -L${libdir} -lfoo
|
|
Libs.private: -lm
|
|
Cflags: -I${includedir}/libfoo
|
|
```
|
|
|
|
# SEE ALSO
|
|
*pkgconf*(1), *pkg.m4*(7)
|