docs: convert pc(5) to scdoc
parent
a93336864d
commit
5494e8a91a
GPG Key ID:
4A9208A2455077A7
177
man/pc.5
177
man/pc.5
|
|
@ -1,177 +0,0 @@
|
|||
.\" Copyright (c) 2017 pkgconf authors (see AUTHORS).
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and/or distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" This software is provided 'as is' and without any warranty, express or
|
||||
.\" implied. In no event shall the authors be liable for any damages arising
|
||||
.\" from the use of this software.
|
||||
.Dd December 15, 2017
|
||||
.Dt PC 5
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm file.pc
|
||||
.Nd pkg-config file format
|
||||
.Sh DESCRIPTION
|
||||
pkg-config files provide a useful mechanism for storing various information
|
||||
about libraries and packages on a given system.
|
||||
Information stored by
|
||||
.Nm .pc
|
||||
files include compiler and linker flags necessary to use a given library, as
|
||||
well as any other relevant metadata.
|
||||
.Pp
|
||||
These
|
||||
.Nm .pc
|
||||
files are processed by a utility called
|
||||
.Nm pkg-config ,
|
||||
of which
|
||||
.Nm pkgconf
|
||||
is an implementation.
|
||||
.\"
|
||||
.Ss FILE SYNTAX
|
||||
The
|
||||
.Nm .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.
|
||||
.\"
|
||||
.Ss VARIABLES
|
||||
.\"
|
||||
Variable definitions start with an alphanumeric string, followed by an equal sign,
|
||||
and then the value the variable should contain.
|
||||
.Pp
|
||||
Variable references are always written as "${variable}".
|
||||
It is possible to escape literal "${" as "$${".
|
||||
.\"
|
||||
.Ss 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.
|
||||
.Pp
|
||||
There are three types of property:
|
||||
.\"
|
||||
.Bl -tag -width indent
|
||||
.\"
|
||||
.It Literal
|
||||
The property will be set to the text of the value.
|
||||
.\"
|
||||
.It Dependency List
|
||||
The property will be set to a list of dependencies parsed from the
|
||||
text.
|
||||
Dependency lists are defined by this ABNF syntax:
|
||||
.Bd -literal
|
||||
package-list = *WSP *( package-spec *( package-sep ) )
|
||||
package-sep = WSP / ","
|
||||
.\"
|
||||
package-spec = package-key [ ver-op package-version ]
|
||||
ver-op = "<" / "<=" / "=" / "!=" / ">=" / ">"
|
||||
.Ed
|
||||
.\"
|
||||
.It 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.
|
||||
.\"
|
||||
.El
|
||||
.Ss PROPERTY KEYWORDS
|
||||
.Bl -tag -width indent
|
||||
.\"
|
||||
.It Name
|
||||
The displayed name of the package.
|
||||
(mandatory; literal)
|
||||
.It Version
|
||||
The version of the package.
|
||||
(mandatory; literal)
|
||||
.It Description
|
||||
A description of the package.
|
||||
(mandatory; literal)
|
||||
.It 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)
|
||||
.It Cflags
|
||||
Required compiler flags.
|
||||
These flags are always used, regardless of whether static compilation is requested.
|
||||
(optional; fragment list)
|
||||
.It Cflags.private
|
||||
Required compiler flags for static compilation.
|
||||
(optional; fragment list; pkgconf extension)
|
||||
.It Copyright
|
||||
A copyright attestation statement.
|
||||
(optional; literal; pkgconf extension)
|
||||
.It 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)
|
||||
.It 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)
|
||||
.It License
|
||||
The asserted SPDX license tag that should be applied to the given package.
|
||||
(optional; literal; pkgconf extension)
|
||||
.It 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)
|
||||
.It 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)
|
||||
.It 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)
|
||||
.It 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)
|
||||
.It 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)
|
||||
.El
|
||||
.Ss 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.
|
||||
.Pp
|
||||
Accordingly, it is suggested that
|
||||
.Nm .pc
|
||||
files which absolutely depend on these extensions declare a requirement on the
|
||||
pkgconf virtual.
|
||||
.Sh EXAMPLES
|
||||
An example .pc file:
|
||||
.Bd -literal
|
||||
# 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
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr pkgconf 1 ,
|
||||
.Xr pkg.m4 7
|
||||
|
|
@ -0,0 +1,166 @@
|
|||
PC(5)
|
||||
|
||||
; 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)
|
||||
|
|
@ -5,7 +5,7 @@ PKGCONF(1)
|
|||
|
||||
# NAME
|
||||
|
||||
pkgconf - a system for configuring build dependency information
|
||||
pkgconf — a system for configuring build dependency information
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue