diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/bomtool.1 | 7 | ||||
| -rw-r--r-- | man/pc.5 | 120 | ||||
| -rw-r--r-- | man/pkgconf.1 | 52 | ||||
| -rw-r--r-- | man/spdxtool.1 | 127 |
4 files changed, 295 insertions, 11 deletions
diff --git a/man/bomtool.1 b/man/bomtool.1 index aac6c8014ea7..fe73411a87c0 100644 --- a/man/bomtool.1 +++ b/man/bomtool.1 @@ -38,6 +38,13 @@ Print the version number of the .Nm program to standard output and exit. Most other options and all command line arguments are ignored. +.It Fl -define-variable Ns = Ns Ar varname Ns = Ns Ar value +Define +.Ar varname +as +.Ar value . +Variables are used in query output, and some modules' results may change based +on the presence of a variable definition. .El .Sh ENVIRONMENT .Bl -tag -width indent @@ -7,7 +7,7 @@ .\" 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 +.Dd June 23, 2026 .Dt PC 5 .Os .Sh NAME @@ -74,6 +74,29 @@ ver-op = "<" / "<=" / "=" / "!=" / ">=" / ">" 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. +.Pp +The text is tokenised using POSIX shell word-splitting rules: unquoted +whitespace separates fragments, single and double quotes group text, and a +backslash escapes the following character. +A quote that is not itself escaped is consumed as a quoting delimiter and does +not appear in the resulting fragment. +To include a shell metacharacter \(em such as a quote, whitespace, a bracket, +a brace, or a glob character \(em literally in a fragment, escape it with a +backslash so that it survives tokenisation. +.Pp +For example, to make the toolchain receive the argument +.Bd -literal -offset indent +\-sFUNCS=["fnA","fnB"] +.Ed +escape the double quotes so they are not consumed as quoting: +.Bd -literal -offset indent +Libs: \-sFUNCS=[\e"fnA\e",\e"fnB\e"] +.Ed +.Pp +On output, such metacharacters are re-escaped so that the original fragment is +recovered when the consumer tokenises the output using the same shell +word-splitting rules; see the note on output escaping in +.Xr pkgconf 1 . .\" .El .Ss PROPERTY KEYWORDS @@ -97,11 +120,14 @@ 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) +Required compiler flags for static compilation only. +(optional; fragment list; pkgconf extension; introduced in pkgconf 0.9.3) +.It Cflags.shared +Required compiler flags for shared compilation only. +(optional; fragment list; pkgconf extension; introduced in pkgconf 3.0.0) .It Copyright A copyright attestation statement. -(optional; literal; pkgconf extension) +(optional; literal; pkgconf extension; introduced in pkgconf 1.9.3) .It Libs Required linking flags for this package. Libraries this package depends on for linking against it, which are not @@ -113,24 +139,94 @@ 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 Libs.shared +Required linking flags for this package that are only required for dynamic +linking. +Libraries this package depends on for linking against it dynamically, which are +not described as dependencies should be specified here. +(optional; fragment list; pkgconf extension; introduced in pkgconf 3.0.0) +.It Link.ABI +A comma-separated list of tags describing the application binary interfaces a +consumer must link this package against, such as +.Sy c++ +or +.Sy fortran . +Tags are case-insensitive and are normalized to lowercase. +This allows a build system to select the appropriate linker driver and runtime +when a package, or one of its dependencies, is implemented in a language whose +ABI differs from C. +The tag set is unioned across the dependency closure in the same manner as +.Sy Libs : +a package's own tags and those of its public +.Sy Requires +always apply, while +.Sy Requires.private +tags apply only when private dependencies are linked. +Unlike a runtime library load, ABI compatibility of the exposed interface +applies equally to shared and static linking. +A package with no +.Sy Link.ABI +property is treated as +.Sy c . +(optional; pkgconf extension; introduced in pkgconf 3.0.0) .It License The asserted SPDX license tag that should be applied to the given package. -(optional; literal; pkgconf extension) +One should try to determine the correct SPDX license tag for package +from the SPDX License list. If a standard license name isn't available, use the +LicenseRef-tag. For complex licensing details, utilize +SPDX expression notation. +It’s possible to assign multiple license tags in pc-file, which are +then merged together with an 'AND' when rendering output. +(optional; literal; pkgconf extension; introduced in pkgconf 1.9.0) +.It License.file +An absolute filesystem path to the installed file containing the full license +text for this package. +The path must refer to the license file as installed on the system, so that +it corresponds to the exact version and configuration described by this +.Sy .pc +file; pkgconf variable references such as +.Sy ${prefix} +or +.Sy ${datadir} , +which expand to absolute paths, may be used. +Relative paths are not supported. +This must not be a URL: use +.Sy Source +to reference an upstream location. +(optional; literal; pkgconf extension; introduced in pkgconf 3.0.0) .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) +(optional; literal; pkgconf extension; introduced in pkgconf 1.9.3) +.It Source +The asserted SPDX downloadLocation tag that should be applied to the given package. +Source should be URI contain tarball with exact version or Repository that contains +tag with version same as mentioned in version tag. It can be also be URI with hash +that is exact release point of the source. +(optional; literal; pkgconf extension; introduced in pkgconf 3.0.0) .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.internal +Required dependencies that must be met for the package to be usable for +static linking. +The main differences verses Requires.private are that CFLAGS will not be +included and the solver will not consider the dependency when solving for +CFLAGS only. +(optional; dependency list; pkgconf extension; introduced in pkgconf 1.5.0) .It Requires.private Required dependencies that must be met for the package to be usable for header inclusion and static linking. All dependencies must be satisfied or the pkg-config implementation must not use the package for header inclusion and static linking. (optional; dependency list) +.It Requires.shared +Required dependencies that are only traversed when not in static mode. This allows +a package to express dependencies that are only relevant when it is used as a +shared library. +(optional; dependency list; pkgconf extension; introduced in pkgconf 3.0.0) .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 @@ -140,7 +236,7 @@ Conflicts list, the package being considered is not usable. 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) +(optional; dependency list; pkgconf extension; introduced in pkgconf 1.1.0) .El .Ss EXTENSIONS Features that have been marked as a pkgconf extension are only guaranteed to work @@ -151,6 +247,16 @@ Accordingly, it is suggested that .Nm .pc files which absolutely depend on these extensions declare a requirement on the pkgconf virtual. +.Pp +In addition it should be noted that the pkgconf virtual is versioned, and thus +files which absolutely depend on these extensions can declare a requirement on +the specific pkgconf version which introduced the extension. +.Pp +As an example: +.Bd -literal +Requires: pkgconf >= 3.0.0 +Libs.shared: ... +.Ed .Sh EXAMPLES An example .pc file: .Bd -literal diff --git a/man/pkgconf.1 b/man/pkgconf.1 index df286a60593a..537c5869b972 100644 --- a/man/pkgconf.1 +++ b/man/pkgconf.1 @@ -7,7 +7,7 @@ .\" 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 +.Dd June 23, 2026 .Dt PKGCONF 1 .Os .Sh NAME @@ -32,6 +32,22 @@ to build software that uses the libraries given by the .Ar module arguments. .Pp +When printing compiler and linker flags, +.Nm +escapes shell metacharacters +.Pq such as quotes, whitespace, brackets, braces and glob characters +in each fragment with a backslash. +The output is intended to be re-tokenised by the consumer using POSIX shell +word-splitting rules, as build systems generally do; under those rules the +protective backslashes are removed and the original values are recovered. +Note that pasting the output directly into an unquoted command substitution, +for example +.Ql cc $(pkgconf \-\-libs foo) , +performs word-splitting and pathname expansion but does +.Em not +remove the backslashes, so a value containing such characters may reach the +toolchain with the escaping still present. +.Pp The .Xr pc 5 files are searched for along a path constructed from the @@ -79,6 +95,9 @@ command line and do not look at dependencies. Limited-output options: .Fl -validate , .Fl -license , +.Fl -license-file , +.Fl -link-abi , +.Fl -source , .Fl -uninstalled , and .Fl -env : @@ -120,7 +139,8 @@ General output options: .Fl -simulate , .Fl -digraph , .Fl -solution , -.Fl -fragment-tree : +.Fl -fragment-tree , +.Fl -newlines : These options do not limit dependency resolution. .El .Pp @@ -283,6 +303,29 @@ flags, or only the linker flags that are neither library path nor library flags, respectively. These options imply .Fl -print-errors . +.It Fl -link-abi +Print the set of link ABI tags +.Pq for example Sy c No or Sy c++ +that the +.Ar module +must be linked against, derived from the +.Sy Link.ABI +properties found across its dependency closure. +The tags from a package's own +.Sy Link.ABI +property and those of its public +.Sy Requires +always apply, while +.Sy Requires.private +tags apply only when linking statically +.Pq Fl -static . +A module with no link ABI requirements prints +.Sy c . +See +.Xr pc 5 +for details of the +.Sy Link.ABI +property. .It Fl -list-all Walk the module search path in the order of descending priority. For each @@ -385,6 +428,9 @@ output. This option is only available if the preprocessor macro .Dv PKGCONF_LITE was not defined during compilation. +.It Fl -newlines +Use newlines to separate individual CFLAGS or linker flag fragments +instead of spaces. .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. @@ -717,7 +763,6 @@ If not defined, the default list compiled into the program from the .Dv SYSTEM_INCLUDEDIR preprocessor macro is used instead. -This variable is a pkgconf-specific extension. Any directories listed in the environment variables .Ev CPATH , .Ev C_INCLUDE_PATH , @@ -737,7 +782,6 @@ If not defined, the default list compiled into the program from the .Dv SYSTEM_LIBDIR preprocessor macro is used instead. -This variable is a pkgconf-specific extension. .It Ev PKG_CONFIG_TOP_BUILD_DIR The value of the .Va pc_top_builddir diff --git a/man/spdxtool.1 b/man/spdxtool.1 new file mode 100644 index 000000000000..bc078f2d8748 --- /dev/null +++ b/man/spdxtool.1 @@ -0,0 +1,127 @@ +.\" Copyright (c) 2026 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 January 22, 2026 +.Dt SPDXTOOL 1 +.Os +.Sh NAME +.Nm spdxtool +.Nd a tool for generating SPDX Lite 3.0.1 profile software bills of material document +.Sh SYNOPSIS +.Nm +.Op Ar options +.Ar module ... +.Sh DESCRIPTION +.Nm +is a program which generates a JSON-LD formated SPDX Lite 3.0.1 software bill of +materials (SBOM) for a given set of pkg-config modules. +The output of this tool can then be translated into other SBOM +formats as necessary. + +More documention about SDPX 3.0.1 can be found from: +.Lk https://spdx.github.io/spdx-spec/v3.0.1/ +.Pp +The +.Ar options +are as follows: +.Bl -tag -width indent +.It Fl -about +Print the version number, the Copyright notice, and the license of the +.Nm +program to standard output and exit. +Most other options and all command line arguments are ignored. +.It Fl -version +Print the version number of the +.Nm +program to standard output and exit. +Most other options and all command line arguments are ignored. +.It Fl -agent-name +Set agent name-property +in /Core/Agent-class. Default is 'Default' +.It Fl -creation-time +Set create-property time in /Core/CreationInfo-class. +SPDX documentation recomends using ISO 8601-formated time which is: YYYY-MM-DDThh:mm:ssZ. +Default is document creation time. +.It Fl -creation-id +Set creation ID in /Core/CreationInfoc-class. +As ID in creation info mainly have special format and it's +default is '_:creationinfo_1'. +.It Fl -define-variable Ns = Ns Ar varname Ns = Ns Ar value +Define +.Ar varname +as +.Ar value . +Variables are used in query output, and some modules' results may change based +on the presence of a variable definition. +.El +.Sh ENVIRONMENT +.Bl -tag -width indent +.It Ev PKG_CONFIG_DEBUG_SPEW +If set, print debugging messages to stderr. +.It Ev PKG_CONFIG_IGNORE_CONFLICTS +If set, ignore +.Ic Conflicts +rules in modules. +Has the same effect as the +.Fl -ignore-conflicts +option in +.Xr pkgconf 1 +. +.It Ev PKG_CONFIG_LIBDIR +A colon-separated list of low-priority directories where +.Xr pc 5 +files are looked up. +The module search path is constructed by appending this list to +.Ev PKG_CONFIG_PATH , +which enjoys higher priority. +If +.Ev PKG_CONFIG_LIBDIR +is not defined, the default list compiled into the +.Nm +program from the +.Dv PKG_DEFAULT_PATH +preprocessor macro is appended instead. +If +.Ev PKG_CONFIG_LIBDIR +is defined but empty, nothing is appended. +.It Ev PKG_CONFIG_MAXIMUM_TRAVERSE_DEPTH +Impose a limit on the allowed depth in the dependency graph. +.It Ev PKG_CONFIG_PATH +A colon-separated list of high-priority directories where +.Xr pc 5 +files are looked up. +.It Ev PKG_CONFIG_PRELOADED_FILES +Colon-separated list of +.Xr pc 5 +files which are loaded before any other pkg-config files. +These packages are given highest priority over any other +.Xr pc 5 +files that would otherwise provide a given package. +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +Generating an SBOM for the package named foo: +.Dl $ spdxtool foo +.Dl { +.Dl "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld", +.Dl "@graph": [ +.Dl { +.Dl "type": "Agent", +.Dl "creationInfo": "_:creationinfo_1", +.Dl "spdxId": "https://github.com/pkgconf/pkgconf/Agent/default", +.Dl "name": "Default" +.Dl }, +.Dl { +.Dl "type": "CreationInfo", +.Dl "@id": "_:creationinfo_1", +.Dl [...] +.Sh SEE ALSO +.Xr pc 5 , +.Xr pkgconf 1 |