From fef3293467d6a0349d889f12ff84f6e9ec29ff9e Mon Sep 17 00:00:00 2001 From: William Pitcock Date: Fri, 15 Dec 2017 18:53:59 -0600 Subject: [PATCH] man: add pc(5) mdoc (closes #148) --- Makefile.am | 3 +- man/pc.5 | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++ man/pkgconf.1 | 3 +- 3 files changed, 146 insertions(+), 2 deletions(-) create mode 100644 man/pc.5 diff --git a/Makefile.am b/Makefile.am index 05a1feb..a664b29 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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 diff --git a/man/pc.5 b/man/pc.5 new file mode 100644 index 0000000..94ae3fa --- /dev/null +++ b/man/pc.5 @@ -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 diff --git a/man/pkgconf.1 b/man/pkgconf.1 index a396f7a..ea00ac2 100644 --- a/man/pkgconf.1 +++ b/man/pkgconf.1 @@ -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