From d4748fe4bb203912e14a34306fe82e69c3b98ad3 Mon Sep 17 00:00:00 2001 From: Andrea Pappacoda Date: Sun, 21 Aug 2022 17:53:39 +0200 Subject: [PATCH 1/5] docs: convert pkgconf.1 to scdoc format Fixes https://github.com/pkgconf/pkgconf/issues/257 --- AUTHORS | 1 + man/pkgconf.1 | 231 --------------------------------------------- man/pkgconf.1.scd | 233 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 234 insertions(+), 231 deletions(-) delete mode 100644 man/pkgconf.1 create mode 100644 man/pkgconf.1.scd diff --git a/AUTHORS b/AUTHORS index 9ba1de4..225de0b 100644 --- a/AUTHORS +++ b/AUTHORS @@ -3,6 +3,7 @@ Alexander Tsoy Alexpux Alon Bar-Lev Alyx +Andrea Pappacoda Ariadne Conill Baptiste Daroussin Baptiste Daroussin diff --git a/man/pkgconf.1 b/man/pkgconf.1 deleted file mode 100644 index 8c3f0cb..0000000 --- a/man/pkgconf.1 +++ /dev/null @@ -1,231 +0,0 @@ -.\" Copyright (c) 2011, 2012, 2013, 2014, 2015, 2016 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 November 15, 2016 -.Dt PKGCONF 1 -.Os -.Sh NAME -.Nm pkgconf -.Nd a system for configuring build dependency information -.Sh SYNOPSIS -.Nm -.Op Ar options -.Op Ar list of modules -.Sh DESCRIPTION -.Nm -is a program which helps to configure compiler and linker flags for -development libraries. -This allows build systems to detect other dependencies and use them with the -system toolchain. -.Sh GENERAL OPTIONS -.Bl -tag -width indent -.It Fl -version -Display the supported pkg-config version and exit. -.It Fl -atleast-pkgconfig-version Ns = Ns Ar VERSION -Exit with error if we do not support the requested pkg-config version. -.It Fl -errors-to-stdout -Print all errors on the main output stream instead of the error output stream. -.It Fl -silence-errors -Do not display any errors at all. -.It Fl -list-all -Walk all directories listed in the -.Va PKG_CONFIG_PATH -environmental variable and display information on packages which have registered -information there. -.It Fl -simulate -Simulates resolving a dependency graph based on the requested modules on the -command line. -Dumps a series of trees denoting pkgconf's resolver state. -.It Fl -no-cache -Skip caching packages when they are loaded into the internal resolver. -This may result in an alternate dependency graph being computed. -.It Fl -ignore-conflicts -Ignore -.Sq Conflicts -rules in modules. -.It Fl -env-only -Learn about pkgconf's configuration strictly from environmental variables. -.It Fl -validate Ar package ... -Validate specific -.Sq .pc -files for correctness. -.It Fl -maximum-traverse-depth Ns = Ns Ar DEPTH -Impose a limit on the allowed depth in the dependency graph. -For example, a depth of 2 will restrict the resolver from acting on child -dependencies of modules added to the resolver's solution. -.It Fl -static -Compute a deeper dependency graph and use compiler/linker flags intended for -static linking. -.It Fl -shared -Compute a simple dependency graph that is only suitable for shared linking. -.It Fl -pure -Treats the computed dependency graph as if it were pure. -This is mainly intended for use with the -.Fl -static -flag. -.It Fl -no-provides -Ignore -.Sq Provides -rules in modules when resolving dependencies. -.It Fl -with-path Ns = Ns Ar PATH -Adds a new module search path to pkgconf's dependency resolver. -Paths added in this way are given preference before other paths. -.It Fl -define-prefix -Attempts to determine the prefix variable to use for CFLAGS and LIBS entry relocations. -This is mainly useful for platforms where framework SDKs are relocatable, such as Windows. -.It Fl -dont-define-prefix -Disables the -.Sq define-prefix -feature. -.It Fl -prefix-variable Ns = Ns Ar VARIABLE -Sets the -.Sq prefix -variable used by the -.Sq define-prefix -feature. -.It Fl -relocate Ns = Ns Ar PATH -Relocates a path using the pkgconf_path_relocate API. -This is mainly used by the testsuite to provide a guaranteed interface -to the system's path relocation backend. -.It Fl -dont-relocate-paths -Disables the path relocation feature. -.El -.Sh MODULE-SPECIFIC OPTIONS -.Bl -tag -width indent -.It Fl -atleast-version Ns = Ns Ar VERSION -Exit with error if a module's version is less than the specified version. -.It Fl -exact-version Ns = Ns Ar VERSION -Exit with error if a module's version is not exactly the specified version. -.It Fl -max-version Ns = Ns Ar VERSION -Exit with error if a module's version is greater than the specified version. -.It Fl -exists -Exit with a non-zero result if the dependency resolver was unable to find all of -the requested modules. -.It Fl -uninstalled -Exit with a non-zero result if the dependency resolver uses an -.Sq uninstalled -module as part of its solution. -.It Fl -no-uninstalled -Forbids the dependency resolver from considering 'uninstalled' modules as part -of a solution. -.El -.Sh QUERY-SPECIFIC OPTIONS -.Bl -tag -width indent -.It Fl -cflags , Fl -cflags-only-I , Fl -cflags-only-other -Display either all CFLAGS, only -.Fl I -CFLAGS or only CFLAGS that are not -.Fl I . -.It Fl -libs , Fl -libs-only-L , Fl -libs-only-l , Fl -libs-only-other -Display either all linker flags, only -.Fl L -linker flags, only -.Fl l -linker flags or only linker flags that are not -.Fl L -or -.Fl l . -.It Fl -keep-system-cflags , Fl -keep-system-libs -Keep CFLAGS or linker flag fragments that would be filtered due to being -included by default in the compiler. -.It Fl -define-variable Ns = Ns Ar VARNAME Ns = Ns Ar VALUE -Define -.Va VARNAME -as -.Va VALUE . -Variables are used in query output, and some modules' results may change based -on the presence of a variable definition. -.It Fl -print-variables -Print all seen variables for a module to the output channel. -.It Fl -print-provides -Print all relevant -.Sq Provides -entries for a module to the output channel. -.It Fl -variable Ns = Ns Ar VARNAME -Print the value of -.Va VARNAME . -.It Fl -print-requires , Fl -print-requires-private -Print the modules included in either the -.Va Requires -field or the -.Va Requires.private -field. -.It Fl -digraph -Dump the dependency resolver's solution as a graphviz -.Sq dot -file. -This can be used with graphviz to visualize module interdependencies. -.It Fl -path -Display the filenames of the -.Sq .pc -files used by the dependency resolver for a given dependency set. -.It Fl -env Ns = Ns Ar VARNAME -Print the requested values as variable declarations in a similar format as the -.Xr env 1 -command. -.It Fl -fragment-filter Ns = Ns Ar TYPES -Filter the fragment lists for the specified types. -.It Fl -modversion -Print the version of the queried module. -.El -.Sh ENVIRONMENT -.Bl -tag -width indent -.It Va PKG_CONFIG_PATH -List of secondary directories where -.Sq .pc -files are looked up. -.It Va PKG_CONFIG_LIBDIR -List of primary directories where -.Sq .pc -files are looked up. -.It Va PKG_CONFIG_SYSROOT_DIR -.Sq sysroot -directory, will be prepended to every path defined in -.Va PKG_CONFIG_PATH . -Useful for cross compilation. -.It Va PKG_CONFIG_TOP_BUILD_DIR -Provides an alternative setting for the -.Sq pc_top_builddir -global variable. -.It Va PKG_CONFIG_PURE_DEPGRAPH -If set, enables the same behaviour as the -.Fl -pure -flag. -.It Va PKG_CONFIG_SYSTEM_INCLUDE_PATH -List of paths that are considered system include paths by the toolchain. -This is a pkgconf-specific extension. -.It Va PKG_CONFIG_SYSTEM_LIBRARY_PATH -List of paths that are considered system library paths by the toolchain. -This is a pkgconf-specific extension. -.It Va PKG_CONFIG_DISABLE_UNINSTALLED -If set, enables the same behaviour as the -.Fl -no-uninstalled -flag. -.It Va PKG_CONFIG_LOG -.Sq logfile -which is used for dumping audit information concerning installed module versions. -.It Va PKG_CONFIG_DEBUG_SPEW -If set, enables additional debug logging. -The format of the debug log messages is implementation-specific. -.It Va PKG_CONFIG_DONT_RELOCATE_PATHS -If set, disables the path relocation feature. -.It Va PKG_CONFIG_MSVC_SYNTAX -If set, uses MSVC syntax for fragments. -.It Va PKG_CONFIG_FDO_SYSROOT_RULES -If set, follow the sysroot prefixing rules that freedesktop.org pkg-config uses. -.It Va DESTDIR -If set to PKG_CONFIG_SYSROOT_DIR, assume that PKG_CONFIG_FDO_SYSROOT_RULES is set. -.El -.Sh EXAMPLES -Displaying the CFLAGS of a package: -.Dl $ pkgconf --cflags foo -.Dl -fPIC -I/usr/include/foo -.Sh SEE ALSO -.Xr pc 5 , -.Xr pkg.m4 7 diff --git a/man/pkgconf.1.scd b/man/pkgconf.1.scd new file mode 100644 index 0000000..093a1c9 --- /dev/null +++ b/man/pkgconf.1.scd @@ -0,0 +1,233 @@ +PKGCONF(1) + +; SPDX-FileCopyrightText: 2022 pkgconf authors +; SPDX-License-Identifier: ISC + +# NAME + +pkgconf - a system for configuring build dependency information + +# SYNOPSIS + +*pkgconf* [_options_] [_list of modules_] + +# DESCRIPTION + +*pkgconf* is a program which helps to configure compiler and linker flags for +development libraries. This allows build systems to detect other dependencies +and use them with the system toolchain. + +# GENERAL OPTIONS + +*--version* + Display the supported pkg-config version and exit. + +*--atleast-pkgconfig-version*=_VERSION_ + Exit with error if we do not support the requested pkg-config version. + +*--errors-to-stdout* + Print all errors on the main output stream instead of the error output + stream. + +*--silence-errors* + Do not display any errors at all. + +*--list-all* + Walk all directories listed in the _PKG_CONFIG_PATH_ environmental variable + and display information on packages which have registered information there. + +*--simulate* + Simulates resolving a dependency graph based on the requested modules on + the command line. Dumps a series of trees denoting pkgconf's resolver state. + +*--no-cache* + Skip caching packages when they are loaded into the internal resolver. + This may result in an alternate dependency graph being computed. + +*--ignore-conflicts* + Ignore ‘Conflicts’ rules in modules. + +*--env-only* + Learn about pkgconf's configuration strictly from environmental variables. + +*--validate* _package ..._ + Validate specific ‘.pc’ files for correctness. + +*--maximum-traverse-depth*=_DEPTH_ + Impose a limit on the allowed depth in the dependency graph. For example, + a depth of 2 will restrict the resolver from acting on child dependencies + of modules added to the resolver's solution. + +*--static* + Compute a deeper dependency graph and use compiler/linker flags intended + for static linking. + +*--shared* + Compute a simple dependency graph that is only suitable for shared linking. + +*--pure* + Treats the computed dependency graph as if it were pure. This is mainly + intended for use with the *--static* flag. + +*--no-provides* + Ignore ‘Provides’ rules in modules when resolving dependencies. + +*--with-path*=_PATH_ + Adds a new module search path to pkgconf's dependency resolver. Paths added + in this way are given preference before other paths. + +*--define-prefix* + Attempts to determine the prefix variable to use for CFLAGS and LIBS entry + relocations. This is mainly useful for platforms where framework SDKs are + relocatable, such as Windows. + +*--dont-define-prefix* + Disables the ‘define-prefix’ feature. + +*--prefix-variable*=_VARIABLE_ + Sets the ‘prefix’ variable used by the ‘define-prefix’ feature. + +*--relocate*=_PATH_ + Relocates a path using the pkgconf_path_relocate API. This is mainly used + by the testsuite to provide a guaranteed interface to the system's path + relocation backend. + +*--dont-relocate-paths* + Disables the path relocation feature. + +# MODULE-SPECIFIC OPTIONS + +*--atleast-version*=_VERSION_ + Exit with error if a module's version is less than the specified version. + +*--exact-version*=_VERSION_ + Exit with error if a module's version is not exactly the specified version. + +*--max-version*=_VERSION_ + Exit with error if a module's version is greater than the specified + version. + +*--exists* + Exit with a non-zero result if the dependency resolver was unable to find + all of the requested modules. + +*--uninstalled* + Exit with a non-zero result if the dependency resolver uses an + ‘uninstalled’ module as part of its solution. + +*--no-uninstalled* + Forbids the dependency resolver from considering 'uninstalled' modules as + part of a solution. + +# QUERY-SPECIFIC OPTIONS + +*--cflags*, *--cflags-only-I*, *--cflags-only-other* + Display either all CFLAGS, only *-I* CFLAGS or only CFLAGS that are not + *-I*. + +*--libs*, *--libs-only-L*, *--libs-only-l*, *--libs-only-other* + Display either all linker flags, only *-L* linker flags, only *-l* linker + flags or only linker flags that are not *-L* or *-l*. + +*--keep-system-cflags*, *--keep-system-libs* + Keep CFLAGS or linker flag fragments that would be filtered due to being + included by default in the compiler. + +*--define-variable*=_VARNAME_=_VALUE_ + Define _VARNAME_ as _VALUE_. Variables are used in query output, and some + modules' results may change based on the presence of a variable definition. + +*--print-variables* + Print all seen variables for a module to the output channel. + +*--print-provides* + Print all relevant ‘Provides’ entries for a module to the output channel. + +*--variable*=_VARNAME_ + Print the value of _VARNAME_. + +*--print-requires*, *--print-requires-private* + Print the modules included in either the Requires field or the + Requires.private field. + +*--digraph* + Dump the dependency resolver's solution as a graphviz ‘dot’ file. This can + be used with graphviz to visualize module interdependencies. + +*--path* + Display the filenames of the ‘.pc’ files used by the dependency resolver for + a given dependency set. + +*--env*=_VARNAME_ + Print the requested values as variable declarations in a similar format as + the *env*(1) command. + +*--fragment-filter*=_TYPES_ + Filter the fragment lists for the specified types. + +*--modversion* + Print the version of the queried module. + +# ENVIRONMENT + +_PKG_CONFIG_PATH_ + List of secondary directories where ‘.pc’ files are looked up. + +_PKG_CONFIG_LIBDIR_ + List of primary directories where ‘.pc’ files are looked up. + +_PKG_CONFIG_SYSROOT_DIR_ + ‘sysroot’ directory, will be prepended to every path defined in + PKG_CONFIG_PATH. Useful for cross compilation. + +_PKG_CONFIG_TOP_BUILD_DIR_ + Provides an alternative setting for the ‘pc_top_builddir’ global variable. + +_PKG_CONFIG_PURE_DEPGRAPH_ + If set, enables the same behaviour as the *--pure* flag. + +_PKG_CONFIG_SYSTEM_INCLUDE_PATH_ + List of paths that are considered system include paths by the toolchain. + This is a pkgconf-specific extension. + +_PKG_CONFIG_SYSTEM_LIBRARY_PATH_ + List of paths that are considered system library paths by the toolchain. + This is a pkgconf-specific extension. + +_PKG_CONFIG_DISABLE_UNINSTALLED_ + If set, enables the same behaviour as the *--no-uninstalled* flag. + +_PKG_CONFIG_LOG_ + ‘logfile’ which is used for dumping audit information concerning installed + module versions. + +_PKG_CONFIG_DEBUG_SPEW_ + If set, enables additional debug logging. The format of the debug log + messages is implementation-specific. + +_PKG_CONFIG_DONT_RELOCATE_PATHS_ + If set, disables the path relocation feature. + +_PKG_CONFIG_MSVC_SYNTAX_ + If set, uses MSVC syntax for fragments. + +_PKG_CONFIG_FDO_SYSROOT_RULES_ + If set, follow the sysroot prefixing rules that freedesktop.org pkg-config + uses. + +_DESTDIR_ + If set to _PKG_CONFIG_SYSROOT_DIR_, assume that + _PKG_CONFIG_FDO_SYSROOT_RULES_ is set. + +# EXAMPLES + +Displaying the CFLAGS of a package: + +``` +$ pkgconf --cflags foo +-fPIC -I/usr/include/foo +``` + +# SEE ALSO + +*pc*(5), *pkg.m4*(7) -- 2.41.0 From 0d2fdc3a6615fbf974146c60675f58f088d8ac2f Mon Sep 17 00:00:00 2001 From: Andrea Pappacoda Date: Sun, 21 Aug 2022 17:59:36 +0200 Subject: [PATCH 2/5] docs: sort pkgconf(1) options --- man/pkgconf.1.scd | 238 +++++++++++++++++++++++----------------------- 1 file changed, 119 insertions(+), 119 deletions(-) diff --git a/man/pkgconf.1.scd b/man/pkgconf.1.scd index 093a1c9..d8d6ab8 100644 --- a/man/pkgconf.1.scd +++ b/man/pkgconf.1.scd @@ -19,63 +19,9 @@ and use them with the system toolchain. # GENERAL OPTIONS -*--version* - Display the supported pkg-config version and exit. - *--atleast-pkgconfig-version*=_VERSION_ Exit with error if we do not support the requested pkg-config version. -*--errors-to-stdout* - Print all errors on the main output stream instead of the error output - stream. - -*--silence-errors* - Do not display any errors at all. - -*--list-all* - Walk all directories listed in the _PKG_CONFIG_PATH_ environmental variable - and display information on packages which have registered information there. - -*--simulate* - Simulates resolving a dependency graph based on the requested modules on - the command line. Dumps a series of trees denoting pkgconf's resolver state. - -*--no-cache* - Skip caching packages when they are loaded into the internal resolver. - This may result in an alternate dependency graph being computed. - -*--ignore-conflicts* - Ignore ‘Conflicts’ rules in modules. - -*--env-only* - Learn about pkgconf's configuration strictly from environmental variables. - -*--validate* _package ..._ - Validate specific ‘.pc’ files for correctness. - -*--maximum-traverse-depth*=_DEPTH_ - Impose a limit on the allowed depth in the dependency graph. For example, - a depth of 2 will restrict the resolver from acting on child dependencies - of modules added to the resolver's solution. - -*--static* - Compute a deeper dependency graph and use compiler/linker flags intended - for static linking. - -*--shared* - Compute a simple dependency graph that is only suitable for shared linking. - -*--pure* - Treats the computed dependency graph as if it were pure. This is mainly - intended for use with the *--static* flag. - -*--no-provides* - Ignore ‘Provides’ rules in modules when resolving dependencies. - -*--with-path*=_PATH_ - Adds a new module search path to pkgconf's dependency resolver. Paths added - in this way are given preference before other paths. - *--define-prefix* Attempts to determine the prefix variable to use for CFLAGS and LIBS entry relocations. This is mainly useful for platforms where framework SDKs are @@ -84,16 +30,70 @@ and use them with the system toolchain. *--dont-define-prefix* Disables the ‘define-prefix’ feature. +*--dont-relocate-paths* + Disables the path relocation feature. + +*--env-only* + Learn about pkgconf's configuration strictly from environmental variables. + +*--errors-to-stdout* + Print all errors on the main output stream instead of the error output + stream. + +*--ignore-conflicts* + Ignore ‘Conflicts’ rules in modules. + +*--list-all* + Walk all directories listed in the _PKG_CONFIG_PATH_ environmental variable + and display information on packages which have registered information there. + +*--maximum-traverse-depth*=_DEPTH_ + Impose a limit on the allowed depth in the dependency graph. For example, + a depth of 2 will restrict the resolver from acting on child dependencies + of modules added to the resolver's solution. + +*--no-cache* + Skip caching packages when they are loaded into the internal resolver. + This may result in an alternate dependency graph being computed. + +*--no-provides* + Ignore ‘Provides’ rules in modules when resolving dependencies. + *--prefix-variable*=_VARIABLE_ Sets the ‘prefix’ variable used by the ‘define-prefix’ feature. +*--pure* + Treats the computed dependency graph as if it were pure. This is mainly + intended for use with the *--static* flag. + *--relocate*=_PATH_ Relocates a path using the pkgconf_path_relocate API. This is mainly used by the testsuite to provide a guaranteed interface to the system's path relocation backend. -*--dont-relocate-paths* - Disables the path relocation feature. +*--shared* + Compute a simple dependency graph that is only suitable for shared linking. + +*--silence-errors* + Do not display any errors at all. + +*--simulate* + Simulates resolving a dependency graph based on the requested modules on + the command line. Dumps a series of trees denoting pkgconf's resolver state. + +*--static* + Compute a deeper dependency graph and use compiler/linker flags intended + for static linking. + +*--with-path*=_PATH_ + Adds a new module search path to pkgconf's dependency resolver. Paths added + in this way are given preference before other paths. + +*--validate* _package ..._ + Validate specific ‘.pc’ files for correctness. + +*--version* + Display the supported pkg-config version and exit. # MODULE-SPECIFIC OPTIONS @@ -103,61 +103,36 @@ and use them with the system toolchain. *--exact-version*=_VERSION_ Exit with error if a module's version is not exactly the specified version. -*--max-version*=_VERSION_ - Exit with error if a module's version is greater than the specified - version. - *--exists* Exit with a non-zero result if the dependency resolver was unable to find all of the requested modules. -*--uninstalled* - Exit with a non-zero result if the dependency resolver uses an - ‘uninstalled’ module as part of its solution. +*--max-version*=_VERSION_ + Exit with error if a module's version is greater than the specified + version. *--no-uninstalled* Forbids the dependency resolver from considering 'uninstalled' modules as part of a solution. +*--uninstalled* + Exit with a non-zero result if the dependency resolver uses an + ‘uninstalled’ module as part of its solution. + # QUERY-SPECIFIC OPTIONS *--cflags*, *--cflags-only-I*, *--cflags-only-other* Display either all CFLAGS, only *-I* CFLAGS or only CFLAGS that are not *-I*. -*--libs*, *--libs-only-L*, *--libs-only-l*, *--libs-only-other* - Display either all linker flags, only *-L* linker flags, only *-l* linker - flags or only linker flags that are not *-L* or *-l*. - -*--keep-system-cflags*, *--keep-system-libs* - Keep CFLAGS or linker flag fragments that would be filtered due to being - included by default in the compiler. - *--define-variable*=_VARNAME_=_VALUE_ Define _VARNAME_ as _VALUE_. Variables are used in query output, and some modules' results may change based on the presence of a variable definition. -*--print-variables* - Print all seen variables for a module to the output channel. - -*--print-provides* - Print all relevant ‘Provides’ entries for a module to the output channel. - -*--variable*=_VARNAME_ - Print the value of _VARNAME_. - -*--print-requires*, *--print-requires-private* - Print the modules included in either the Requires field or the - Requires.private field. - *--digraph* Dump the dependency resolver's solution as a graphviz ‘dot’ file. This can be used with graphviz to visualize module interdependencies. -*--path* - Display the filenames of the ‘.pc’ files used by the dependency resolver for - a given dependency set. - *--env*=_VARNAME_ Print the requested values as variable declarations in a similar format as the *env*(1) command. @@ -165,27 +140,74 @@ and use them with the system toolchain. *--fragment-filter*=_TYPES_ Filter the fragment lists for the specified types. +*--libs*, *--libs-only-L*, *--libs-only-l*, *--libs-only-other* + Display either all linker flags, only *-L* linker flags, only *-l* linker + flags or only linker flags that are not *-L* or *-l*. + *--modversion* Print the version of the queried module. +*--keep-system-cflags*, *--keep-system-libs* + Keep CFLAGS or linker flag fragments that would be filtered due to being + included by default in the compiler. + +*--path* + Display the filenames of the ‘.pc’ files used by the dependency resolver for + a given dependency set. + +*--print-provides* + Print all relevant ‘Provides’ entries for a module to the output channel. + +*--print-requires*, *--print-requires-private* + Print the modules included in either the Requires field or the + Requires.private field. + +*--print-variables* + Print all seen variables for a module to the output channel. + +*--variable*=_VARNAME_ + Print the value of _VARNAME_. + # ENVIRONMENT -_PKG_CONFIG_PATH_ - List of secondary directories where ‘.pc’ files are looked up. +_DESTDIR_ + If set to _PKG_CONFIG_SYSROOT_DIR_, assume that + _PKG_CONFIG_FDO_SYSROOT_RULES_ is set. + +_PKG_CONFIG_DEBUG_SPEW_ + If set, enables additional debug logging. The format of the debug log + messages is implementation-specific. + +_PKG_CONFIG_DISABLE_UNINSTALLED_ + If set, enables the same behaviour as the *--no-uninstalled* flag. + +_PKG_CONFIG_DONT_RELOCATE_PATHS_ + If set, disables the path relocation feature. + +_PKG_CONFIG_FDO_SYSROOT_RULES_ + If set, follow the sysroot prefixing rules that freedesktop.org pkg-config + uses. _PKG_CONFIG_LIBDIR_ List of primary directories where ‘.pc’ files are looked up. -_PKG_CONFIG_SYSROOT_DIR_ - ‘sysroot’ directory, will be prepended to every path defined in - PKG_CONFIG_PATH. Useful for cross compilation. +_PKG_CONFIG_LOG_ + ‘logfile’ which is used for dumping audit information concerning installed + module versions. -_PKG_CONFIG_TOP_BUILD_DIR_ - Provides an alternative setting for the ‘pc_top_builddir’ global variable. +_PKG_CONFIG_MSVC_SYNTAX_ + If set, uses MSVC syntax for fragments. + +_PKG_CONFIG_PATH_ + List of secondary directories where ‘.pc’ files are looked up. _PKG_CONFIG_PURE_DEPGRAPH_ If set, enables the same behaviour as the *--pure* flag. +_PKG_CONFIG_SYSROOT_DIR_ + ‘sysroot’ directory, will be prepended to every path defined in + PKG_CONFIG_PATH. Useful for cross compilation. + _PKG_CONFIG_SYSTEM_INCLUDE_PATH_ List of paths that are considered system include paths by the toolchain. This is a pkgconf-specific extension. @@ -194,30 +216,8 @@ _PKG_CONFIG_SYSTEM_LIBRARY_PATH_ List of paths that are considered system library paths by the toolchain. This is a pkgconf-specific extension. -_PKG_CONFIG_DISABLE_UNINSTALLED_ - If set, enables the same behaviour as the *--no-uninstalled* flag. - -_PKG_CONFIG_LOG_ - ‘logfile’ which is used for dumping audit information concerning installed - module versions. - -_PKG_CONFIG_DEBUG_SPEW_ - If set, enables additional debug logging. The format of the debug log - messages is implementation-specific. - -_PKG_CONFIG_DONT_RELOCATE_PATHS_ - If set, disables the path relocation feature. - -_PKG_CONFIG_MSVC_SYNTAX_ - If set, uses MSVC syntax for fragments. - -_PKG_CONFIG_FDO_SYSROOT_RULES_ - If set, follow the sysroot prefixing rules that freedesktop.org pkg-config - uses. - -_DESTDIR_ - If set to _PKG_CONFIG_SYSROOT_DIR_, assume that - _PKG_CONFIG_FDO_SYSROOT_RULES_ is set. +_PKG_CONFIG_TOP_BUILD_DIR_ + Provides an alternative setting for the ‘pc_top_builddir’ global variable. # EXAMPLES -- 2.41.0 From 74e782bc4749a68bdc315ffa24c2efa389ba4d0f Mon Sep 17 00:00:00 2001 From: Andrea Pappacoda Date: Sun, 21 Aug 2022 22:18:58 +0200 Subject: [PATCH 3/5] docs: convert pc(5) to scdoc --- man/pc.5 | 177 ---------------------------------------------- man/pc.5.scd | 169 +++++++++++++++++++++++++++++++++++++++++++ man/pkgconf.1.scd | 2 +- 3 files changed, 170 insertions(+), 178 deletions(-) delete mode 100644 man/pc.5 create mode 100644 man/pc.5.scd diff --git a/man/pc.5 b/man/pc.5 deleted file mode 100644 index f4ec4eb..0000000 --- a/man/pc.5 +++ /dev/null @@ -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 -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/pc.5.scd b/man/pc.5.scd new file mode 100644 index 0000000..a5565d9 --- /dev/null +++ b/man/pc.5.scd @@ -0,0 +1,169 @@ +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 +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) diff --git a/man/pkgconf.1.scd b/man/pkgconf.1.scd index d8d6ab8..ba298ff 100644 --- a/man/pkgconf.1.scd +++ b/man/pkgconf.1.scd @@ -5,7 +5,7 @@ PKGCONF(1) # NAME -pkgconf - a system for configuring build dependency information +pkgconf — a system for configuring build dependency information # SYNOPSIS -- 2.41.0 From 930d9067cea0d2f92a34786bf82d034147ff5e7f Mon Sep 17 00:00:00 2001 From: Andrea Pappacoda Date: Sun, 21 Aug 2022 22:19:19 +0200 Subject: [PATCH 4/5] build(meson): generate and install scdoc manpages --- man/meson.build | 22 ++++++++++++++++++++++ meson.build | 13 ++++++++----- 2 files changed, 30 insertions(+), 5 deletions(-) create mode 100644 man/meson.build diff --git a/man/meson.build b/man/meson.build new file mode 100644 index 0000000..3584157 --- /dev/null +++ b/man/meson.build @@ -0,0 +1,22 @@ +manpages = { + 'pc': 5, + 'pkgconf': 1 +} + +foreach page, section : manpages + name = '@0@.@1@'.format(page, section) + input = name + '.scd' + tgt = custom_target( + input, + input: files(input), + output: name, + capture: true, + feed: true, + command: scdoc, + install: true, + install_dir: get_option('mandir') / 'man@0@'.format(section), + ) +endforeach + +install_man('pkg.m4.7') +install_man('pkgconf-personality.5') diff --git a/meson.build b/meson.build index 0d42d42..83cbcb1 100644 --- a/meson.build +++ b/meson.build @@ -1,7 +1,7 @@ project('pkgconf', 'c', version : '1.9.3', license : 'ISC', - meson_version : '>=0.49', + meson_version : '>=0.59', default_options : ['c_std=c99'], ) @@ -124,10 +124,13 @@ kyuafile = configure_file(input : 'Kyuafile.in', output : 'Kyuafile', configurat test('kyua', kyua_exe, args : ['--config=none', 'test', '--kyuafile', kyuafile, '--build-root', meson.current_build_dir()]) subdir('tests') -install_man('man/pkgconf.1') -install_man('man/pkg.m4.7') -install_man('man/pc.5') -install_man('man/pkgconf-personality.5') +# https://github.com/mesonbuild/meson/issues/1550 +# https://github.com/mesonbuild/meson/pull/9342 +scdoc = find_program('scdoc', required: false) +if scdoc.found() + subdir('man') +endif + install_data('pkg.m4', install_dir: 'share/aclocal') install_data('AUTHORS', install_dir: 'share/doc/pkgconf') install_data('README.md', install_dir: 'share/doc/pkgconf') -- 2.41.0 From c20b862c1a2942af5f6948801a1564eb2189d1bf Mon Sep 17 00:00:00 2001 From: Andrea Pappacoda Date: Sun, 21 Aug 2022 22:34:14 +0200 Subject: [PATCH 5/5] ci: install scdoc On Debian, install gcc and libc-dev instead of build-essential, as it drags in useless dependencies and its description explicitly says that it should only be installed if you need to build Debian packages. Also stop using meson's implicit setup command, as it's now discouraged: https://github.com/mesonbuild/meson/pull/10701 --- .github/workflows/test.yml | 14 +++++++------- .woodpecker.yml | 12 ++++++------ 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 46277af..708413b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -35,7 +35,7 @@ jobs: # the code assumes msvc style printf atm export CFLAGS=-D__USE_MINGW_ANSI_STDIO=0 - meson -Dtests=false _build + meson setup -Dtests=false _build meson compile -C _build debian-meson: @@ -49,11 +49,11 @@ jobs: - name: Update system and add dependencies run: | apt-get update - apt-get install -y kyua atf-sh build-essential meson + apt-get install -y kyua atf-sh gcc libc-dev meson scdoc - name: Build run: | - meson _build -Dwerror=true + meson setup _build -Dwerror=true meson compile -C _build - name: Run tests @@ -71,11 +71,11 @@ jobs: - name: Update system and add dependencies run: | apt-get update - apt-get install -y kyua atf-sh build-essential meson + apt-get install -y kyua atf-sh gcc libc-dev meson scdoc - name: Build run: | - meson _build -Db_sanitize=address + meson setup _build -Db_sanitize=address meson compile -C _build - name: Run tests @@ -95,7 +95,7 @@ jobs: - name: Update system and add dependencies run: | apt-get update - apt-get install -y kyua atf-sh build-essential autoconf libtool + apt-get install -y kyua atf-sh gcc libc-dev make autoconf libtool - name: Build run: | @@ -122,7 +122,7 @@ jobs: - name: Build run: | - meson _build -Dwerror=true + meson setup _build -Dwerror=true meson compile -C _build - name: Run tests diff --git a/.woodpecker.yml b/.woodpecker.yml index 65cd986..c42bffa 100644 --- a/.woodpecker.yml +++ b/.woodpecker.yml @@ -3,8 +3,8 @@ pipeline: image: debian:testing commands: - apt-get update - - apt-get install -y kyua atf-sh build-essential meson - - meson _build -Dwerror=true + - apt-get install -y kyua atf-sh gcc libc-dev meson scdoc + - meson setup _build -Dwerror=true - meson compile -C _build - meson test -v -C _build when: @@ -18,8 +18,8 @@ pipeline: - ASAN_OPTIONS="exitcode=7" commands: - apt-get update - - apt-get install -y kyua atf-sh build-essential meson - - meson _build -Db_sanitize=address + - apt-get install -y kyua atf-sh gcc libc-dev meson scdoc + - meson setup _build -Db_sanitize=address - meson compile -C _build - meson test -v -C _build when: @@ -31,7 +31,7 @@ pipeline: image: debian:testing commands: - apt-get update - - apt-get install -y kyua atf-sh build-essential autoconf libtool + - apt-get install -y kyua atf-sh gcc libc-dev make autoconf libtool - ./autogen.sh - ./configure - make -j @@ -45,7 +45,7 @@ pipeline: image: alpine commands: - apk add -U --no-cache kyua atf build-base meson - - meson _build -Dwerror=true + - meson setup _build -Dwerror=true - meson compile -C _build - meson test -v -C _build when: -- 2.41.0