1.\" Copyright (c) 2017 pkgconf authors (see AUTHORS). 2.\" 3.\" Permission to use, copy, modify, and/or distribute this software for any 4.\" purpose with or without fee is hereby granted, provided that the above 5.\" copyright notice and this permission notice appear in all copies. 6.\" 7.\" This software is provided 'as is' and without any warranty, express or 8.\" implied. In no event shall the authors be liable for any damages arising 9.\" from the use of this software. 10.Dd December 15, 2017 11.Dt PC 5 12.Os 13.Sh NAME 14.Nm file.pc 15.Nd pkg-config file format 16.Sh DESCRIPTION 17pkg-config files provide a useful mechanism for storing various information 18about libraries and packages on a given system. 19Information stored by 20.Nm .pc 21files include compiler and linker flags necessary to use a given library, as 22well as any other relevant metadata. 23.Pp 24These 25.Nm .pc 26files are processed by a utility called 27.Nm pkg-config , 28of which 29.Nm pkgconf 30is an implementation. 31.\" 32.Ss FILE SYNTAX 33The 34.Nm .pc 35file follows a format inspired by RFC822. 36Comments are prefixed by a pound sign, hash sign or octothorpe (#), and variable 37assignment is similar to POSIX shell. 38Properties are defined using RFC822-style stanzas. 39.\" 40.Ss VARIABLES 41.\" 42Variable definitions start with an alphanumeric string, followed by an equal sign, 43and then the value the variable should contain. 44.Pp 45Variable references are always written as "${variable}". 46It is possible to escape literal "${" as "$${". 47.\" 48.Ss PROPERTIES 49.\" 50Properties are set using RFC822-style stanzas which consist of a keyword, followed 51by a colon (:) and then the value the property should be set to. 52Variable substitution is always performed regardless of property type. 53.Pp 54There are three types of property: 55.\" 56.Bl -tag -width indent 57.\" 58.It Literal 59The property will be set to the text of the value. 60.\" 61.It Dependency List 62The property will be set to a list of dependencies parsed from the 63text. 64Dependency lists are defined by this ABNF syntax: 65.Bd -literal 66package-list = *WSP *( package-spec *( package-sep ) ) 67package-sep = WSP / "," 68.\" 69package-spec = package-key [ ver-op package-version ] 70ver-op = "<" / "<=" / "=" / "!=" / ">=" / ">" 71.Ed 72.\" 73.It Fragment List 74The property will be set to a list of fragments parsed from the text. 75The input text must be in a format that is suitable for passing to a POSIX 76shell without any shell expansions after variable substitution has been done. 77.\" 78.El 79.Ss PROPERTY KEYWORDS 80.Bl -tag -width indent 81.\" 82.It Name 83The displayed name of the package. 84(mandatory; literal) 85.It Version 86The version of the package. 87(mandatory; literal) 88.It Description 89A description of the package. 90(mandatory; literal) 91.It URL 92A URL to a webpage for the package. 93This is used to recommend where newer versions of the package can be acquired. 94(mandatory; literal) 95.It Cflags 96Required compiler flags. 97These flags are always used, regardless of whether static compilation is requested. 98(optional; fragment list) 99.It Cflags.private 100Required compiler flags for static compilation. 101(optional; fragment list; pkgconf extension) 102.It Copyright 103A copyright attestation statement. 104(optional; literal; pkgconf extension) 105.It Libs 106Required linking flags for this package. 107Libraries this package depends on for linking against it, which are not 108described as dependencies should be specified here. 109(optional; fragment list) 110.It Libs.private 111Required linking flags for this package that are only required when linking 112statically. 113Libraries this package depends on for linking against it statically, which are 114not described as dependencies should be specified here. 115(optional; fragment list) 116.It License 117The asserted SPDX license tag that should be applied to the given package. 118(optional; literal; pkgconf extension) 119.It Maintainer 120The preferred contact for the maintainer. This should be in the format of a 121name followed by an e-mail address or website. 122(optional; literal; pkgconf extension) 123.It Requires 124Required dependencies that must be met for the package to be usable. 125All dependencies must be satisfied or the pkg-config implementation must not use 126the package. 127(optional; dependency list) 128.It Requires.private 129Required dependencies that must be met for the package to be usable for header 130inclusion and static linking. 131All dependencies must be satisfied or the pkg-config implementation must not use 132the package for header inclusion and static linking. 133(optional; dependency list) 134.It Conflicts 135Dependencies that must not be met for the package to be usable. 136If any package in the proposed dependency solution match any dependency in the 137Conflicts list, the package being considered is not usable. 138(optional; dependency list) 139.It Provides 140Dependencies that may be provided by an alternate package. 141If a package cannot be found, the entire package collection is scanned for 142providers which can match the requested dependency. 143(optional; dependency list; pkgconf extension) 144.El 145.Ss EXTENSIONS 146Features that have been marked as a pkgconf extension are only guaranteed to work 147with the pkgconf implementation of pkg-config. 148Other implementations may or may not support the extensions. 149.Pp 150Accordingly, it is suggested that 151.Nm .pc 152files which absolutely depend on these extensions declare a requirement on the 153pkgconf virtual. 154.Sh EXAMPLES 155An example .pc file: 156.Bd -literal 157# This is a comment 158prefix=/home/kaniini/pkg # this defines a variable 159exec_prefix=${prefix} # defining another variable with a substitution 160libdir=${exec_prefix}/lib 161includedir=${prefix}/include 162 163Name: libfoo # human-readable name 164Description: an example library called libfoo # human-readable description 165Copyright: Copyright (c) 2022 pkgconf project authors 166License: Apache-2.0 167Maintainer: the pkgconf project <http://www.pkgconf.org> 168Version: 1.0 169URL: http://www.pkgconf.org 170Requires: libbar > 2.0.0 171Conflicts: libbaz <= 3.0.0 172Libs: -L${libdir} -lfoo 173Libs.private: -lm 174Cflags: -I${includedir}/libfoo 175.Ed 176.Sh SEE ALSO 177.Xr pkgconf 1 , 178.Xr pkg.m4 7 179