man: add pc(5) mdoc (closes #148)
William Pitcock
parent
cf96c562e1
commit
fef3293467
|
|
@ -135,7 +135,8 @@ libpkgconf_la_LDFLAGS = -no-undefined -version-info 2:0:0 -export-symbols-regex
|
|||
|
||||
dist_man_MANS = \
|
||||
man/pkgconf.1 \
|
||||
man/pkg.m4.7
|
||||
man/pkg.m4.7 \
|
||||
man/pc.5
|
||||
|
||||
pkgconf_LDADD = libpkgconf.la
|
||||
pkgconf_SOURCES = main.c getopt_long.c renderer-msvc.c
|
||||
|
|
|
|||
|
|
@ -0,0 +1,142 @@
|
|||
.\" 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 an 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
|
||||
.\"
|
||||
.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
|
||||
.\"
|
||||
.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 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 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
|
||||
.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
|
||||
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
|
||||
|
|
@ -207,4 +207,5 @@ Displaying the CFLAGS of a package:
|
|||
.Dl $ pkgconf --cflags foo
|
||||
.Dl -fPIC -I/usr/include/foo
|
||||
.Sh SEE ALSO
|
||||
.Xr pkg.m4 7
|
||||
.Xr pkg.m4 7 ,
|
||||
.Xr pc 5
|
||||
|
|
|
|||
Loading…
Reference in New Issue