[pacman-dev] [PATCH] doc: Add a man page describing PKGINFO
From: Jelle van der Waa <jelle@archlinux.org> Describe the PKGINFO format which resides in a package produced makepkg. --- doc/Makefile.am | 4 +- doc/PKGINFO.5.asciidoc | 86 ++++++++++++++++++++++++++++++++++++++++++ doc/meson.build | 1 + 3 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 doc/PKGINFO.5.asciidoc diff --git a/doc/Makefile.am b/doc/Makefile.am index 5c575832..634388e8 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -16,7 +16,8 @@ MANPAGES = \ pacman.conf.5 \ libalpm.3 \ BUILDINFO.5 \ - pacman-conf.8 + pacman-conf.8 \ + PKGINFO.5 DOXYGEN_MANS = $(wildcard man3/*.3) @@ -47,6 +48,7 @@ EXTRA_DIST = \ makepkg.conf.5.asciidoc \ pacman.conf.5.asciidoc \ BUILDINFO.5.asciidoc \ + PKGINFO.5.asciidoc \ libalpm.3.asciidoc \ footer.asciidoc \ index.asciidoc \ diff --git a/doc/PKGINFO.5.asciidoc b/doc/PKGINFO.5.asciidoc new file mode 100644 index 00000000..2da25c5b --- /dev/null +++ b/doc/PKGINFO.5.asciidoc @@ -0,0 +1,86 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +PKGINFO(5) +========== + +Name +---- +PKGINFO - package information file + + +Synopsis +-------- +This manual page describes the format of a PKGINFO file found in the root of +a package created by makepkg. The file contains a description of the package's +information. The information is formatted in key-value pairs separated by +a '=', one value per line. Arrays are represented multiple keys with the same +value. + + +Description +----------- + +*pkgname*:: + The name of the package. + +*pkgbase*:: + The base name of a package, usually the same as the pkgname except for + split packages. + +*pkgver*:: + The version of the package including pkgrel and epoch. + +*pkgdesc*:: + A description of the package. + +*url*:: + The upstream of the package. + +*builddate*:: + The build date of the package in epoch. + +*packager*:: + The packager of the package formatted Foo <foo@bar.com>. + +*size*:: + The size of the package. + +*arch*:: + The architecture of the package. + +*license*:: + The license of the package. + +*replaces (array)*:: + An array of packages this package should replace. + +*group (array)*:: + An array of symbolic names that represent groups of packages. + +*conflict (array)*:: + An array of packages that will conflict with this package. + +*provides (array)*:: + An array of "virtual provisions" this package provides. + +*backup (array)*:: + An array of file names. + +*depend (array)*:: + The dependencies of the package. + +*optdepend (array)*:: + The optional dependencies of the package. + +*makedepend (array)*:: + The make dependencies of the package. + +*checkdepend (array)*:: + The check dependencies of the package. + +See Also +-------- +linkman:makepkg[8], linkman:pkgbuild[5] + +include::footer.asciidoc[] diff --git a/doc/meson.build b/doc/meson.build index a5bcd5b3..2f966616 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -12,6 +12,7 @@ manpages = [ { 'name': 'libalpm.3' }, { 'name': 'BUILDINFO.5' }, { 'name': 'pacman-conf.8' }, + { 'name': 'PKGINFO.5' }, ] sitepages = [ -- 2.22.0
On 22/6/19 7:39 am, Jelle van der Waa wrote:
From: Jelle van der Waa <jelle@archlinux.org>
Describe the PKGINFO format which resides in a package produced makepkg. --- doc/Makefile.am | 4 +- doc/PKGINFO.5.asciidoc | 86 ++++++++++++++++++++++++++++++++++++++++++ doc/meson.build | 1 + 3 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 doc/PKGINFO.5.asciidoc
diff --git a/doc/Makefile.am b/doc/Makefile.am index 5c575832..634388e8 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -16,7 +16,8 @@ MANPAGES = \ pacman.conf.5 \ libalpm.3 \ BUILDINFO.5 \ - pacman-conf.8 + pacman-conf.8 \ + PKGINFO.5
DOXYGEN_MANS = $(wildcard man3/*.3)
@@ -47,6 +48,7 @@ EXTRA_DIST = \ makepkg.conf.5.asciidoc \ pacman.conf.5.asciidoc \ BUILDINFO.5.asciidoc \ + PKGINFO.5.asciidoc \ libalpm.3.asciidoc \ footer.asciidoc \ index.asciidoc \ diff --git a/doc/PKGINFO.5.asciidoc b/doc/PKGINFO.5.asciidoc new file mode 100644 index 00000000..2da25c5b --- /dev/null +++ b/doc/PKGINFO.5.asciidoc @@ -0,0 +1,86 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +PKGINFO(5) +========== + +Name +---- +PKGINFO - package information file + + +Synopsis +-------- +This manual page describes the format of a PKGINFO file found in the root of +a package created by makepkg. The file contains a description of the package's +information. The information is formatted in key-value pairs separated by +a '=', one value per line. Arrays are represented multiple keys with the same +value.
Suggested edit: The file contains the package's metadata formatted in key-value pairs, separated by a '=' and with one value per line.
+ +Description +----------- + +*pkgname*:: + The name of the package. + +*pkgbase*:: + The base name of a package, usually the same as the pkgname except for + split packages. + +*pkgver*:: + The version of the package including pkgrel and epoch. + +*pkgdesc*:: + A description of the package.
A description of the software contained in the package.
+ +*url*:: + The upstream of the package.
upstream url
+*builddate*:: + The build date of the package in epoch. + +*packager*:: + The packager of the package formatted Foo <foo@bar.com>.
usually formatted "Name <Email>" (there is not restriction on format)
+ +*size*:: + The size of the package.
in (units)
+*arch*:: + The architecture of the package. + +*license*:: + The license of the package. + +*replaces (array)*:: + An array of packages this package should replace.
packages that this package
+ +*group (array)*:: + An array of symbolic names that represent groups of packages. +
Delete symbolic?
+*conflict (array)*:: + An array of packages that will conflict with this package. + +*provides (array)*:: + An array of "virtual provisions" this package provides. + +*backup (array)*:: + An array of file names.
More info needed for context please. Bad example: An array of file names that are handled according to pacman's rules
+*depend (array)*:: + The dependencies of the package. + +*optdepend (array)*:: + The optional dependencies of the package. + +*makedepend (array)*:: + The make dependencies of the package. + +*checkdepend (array)*:: + The check dependencies of the package. + +See Also +-------- +linkman:makepkg[8], linkman:pkgbuild[5] + +include::footer.asciidoc[] diff --git a/doc/meson.build b/doc/meson.build index a5bcd5b3..2f966616 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -12,6 +12,7 @@ manpages = [ { 'name': 'libalpm.3' }, { 'name': 'BUILDINFO.5' }, { 'name': 'pacman-conf.8' }, + { 'name': 'PKGINFO.5' }, ]
sitepages = [
From: Jelle van der Waa <jelle@archlinux.org> Describe the PKGINFO format which resides in a package produced makepkg. --- doc/Makefile.am | 4 +- doc/PKGINFO.5.asciidoc | 87 ++++++++++++++++++++++++++++++++++++++++++ doc/meson.build | 1 + 3 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 doc/PKGINFO.5.asciidoc diff --git a/doc/Makefile.am b/doc/Makefile.am index 5c575832..634388e8 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -16,7 +16,8 @@ MANPAGES = \ pacman.conf.5 \ libalpm.3 \ BUILDINFO.5 \ - pacman-conf.8 + pacman-conf.8 \ + PKGINFO.5 DOXYGEN_MANS = $(wildcard man3/*.3) @@ -47,6 +48,7 @@ EXTRA_DIST = \ makepkg.conf.5.asciidoc \ pacman.conf.5.asciidoc \ BUILDINFO.5.asciidoc \ + PKGINFO.5.asciidoc \ libalpm.3.asciidoc \ footer.asciidoc \ index.asciidoc \ diff --git a/doc/PKGINFO.5.asciidoc b/doc/PKGINFO.5.asciidoc new file mode 100644 index 00000000..101ba34c --- /dev/null +++ b/doc/PKGINFO.5.asciidoc @@ -0,0 +1,87 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +PKGINFO(5) +========== + +Name +---- +PKGINFO - package information file + + +Synopsis +-------- +This manual page describes the format of a PKGINFO file found in the root of +a package created by makepkg. The file contains a description of the package's +information. The information is formatted in key-value pairs separated by +a '=', one value per line. Arrays are represented multiple keys with the same +value. + + +Description +----------- + +*pkgname*:: + The name of the package. + +*pkgbase*:: + The base name of a package, usually the same as the pkgname except for + split packages. + +*pkgver*:: + The version of the package including pkgrel and epoch. + +*pkgdesc*:: + A description of the software contained in the package. + +*url*:: + The upstream url of the package. + +*builddate*:: + The build date of the package in epoch. + +*packager*:: + The packager of the package formatted "Name <Email>". + +*size*:: + The size of the package in bytes. + +*arch*:: + The architecture of the package. + +*license*:: + The license of the package. + +*replaces (array)*:: + An array of packages that this package should replace. + +*group (array)*:: + An array of names that represent groups of packages. + +*conflict (array)*:: + An array of packages that will conflict with this package. + +*provides (array)*:: + An array of "virtual provisions" this package provides. + +*backup (array)*:: + An array of file names, which should be backed up if the package is removed + or upgraded. + +*depend (array)*:: + The dependencies of the package. + +*optdepend (array)*:: + The optional dependencies of the package. + +*makedepend (array)*:: + The make dependencies of the package. + +*checkdepend (array)*:: + The check dependencies of the package. + +See Also +-------- +linkman:makepkg[8], linkman:pkgbuild[5] + +include::footer.asciidoc[] diff --git a/doc/meson.build b/doc/meson.build index a5bcd5b3..2f966616 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -12,6 +12,7 @@ manpages = [ { 'name': 'libalpm.3' }, { 'name': 'BUILDINFO.5' }, { 'name': 'pacman-conf.8' }, + { 'name': 'PKGINFO.5' }, ] sitepages = [ -- 2.22.0
On 06/28/19 at 08:55pm, Jelle van der Waa wrote:
From: Jelle van der Waa <jelle@archlinux.org>
Describe the PKGINFO format which resides in a package produced makepkg. --- doc/Makefile.am | 4 +- doc/PKGINFO.5.asciidoc | 87 ++++++++++++++++++++++++++++++++++++++++++ doc/meson.build | 1 + 3 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 doc/PKGINFO.5.asciidoc
diff --git a/doc/Makefile.am b/doc/Makefile.am index 5c575832..634388e8 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -16,7 +16,8 @@ MANPAGES = \ pacman.conf.5 \ libalpm.3 \ BUILDINFO.5 \ - pacman-conf.8 + pacman-conf.8 \ + PKGINFO.5
DOXYGEN_MANS = $(wildcard man3/*.3)
@@ -47,6 +48,7 @@ EXTRA_DIST = \ makepkg.conf.5.asciidoc \ pacman.conf.5.asciidoc \ BUILDINFO.5.asciidoc \ + PKGINFO.5.asciidoc \ libalpm.3.asciidoc \ footer.asciidoc \ index.asciidoc \ diff --git a/doc/PKGINFO.5.asciidoc b/doc/PKGINFO.5.asciidoc new file mode 100644 index 00000000..101ba34c --- /dev/null +++ b/doc/PKGINFO.5.asciidoc @@ -0,0 +1,87 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +/////
A few have sneaked in since the removal, but we don't include vim modelines anymore.
+PKGINFO(5) +========== + +Name +---- +PKGINFO - package information file + + +Synopsis +-------- +This manual page describes the format of a PKGINFO file found in the root of +a package created by makepkg. The file contains a description of the package's +information. The information is formatted in key-value pairs separated by +a '=', one value per line. Arrays are represented multiple keys with the same +value.
Key-value pairs are separated by " = ", not "=". Arrays are represented by repeating the same key multiple times, each line presumably has a different value, not the same one. Empty lines and lines beginning with "#" are ignored.
+ + +Description +----------- + +*pkgname*:: + The name of the package. + +*pkgbase*:: + The base name of a package, usually the same as the pkgname except for + split packages. + +*pkgver*:: + The version of the package including pkgrel and epoch.
This should include the actual format.
+*pkgdesc*:: + A description of the software contained in the package. + +*url*:: + The upstream url of the package.
packaged software.
+*builddate*:: + The build date of the package in epoch. + +*packager*:: + The packager of the package formatted "Name <Email>".
Neither makepkg nor libalpm says anything about the format of this field, neither should this documentation.
+*size*:: + The size of the package in bytes.
"installation size" or "packaged files", it is not the size of the package itself.
+*arch*:: + The architecture of the package. + +*license*:: + The license of the package.
License is an array.
+*replaces (array)*:: + An array of packages that this package should replace. + +*group (array)*:: + An array of names that represent groups of packages.
Groups to which this package belongs.
+*conflict (array)*:: + An array of packages that will conflict with this package. + +*provides (array)*:: + An array of "virtual provisions" this package provides. + +*backup (array)*:: + An array of file names, which should be backed up if the package is removed + or upgraded. + +*depend (array)*:: + The dependencies of the package. + +*optdepend (array)*:: + The optional dependencies of the package. + +*makedepend (array)*:: + The make dependencies of the package. + +*checkdepend (array)*:: + The check dependencies of the package.
This should document the format for dependency values.
+See Also +-------- +linkman:makepkg[8], linkman:pkgbuild[5] + +include::footer.asciidoc[] diff --git a/doc/meson.build b/doc/meson.build index a5bcd5b3..2f966616 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -12,6 +12,7 @@ manpages = [ { 'name': 'libalpm.3' }, { 'name': 'BUILDINFO.5' }, { 'name': 'pacman-conf.8' }, + { 'name': 'PKGINFO.5' }, ]
sitepages = [ -- 2.22.0
On 6/28/19 2:55 PM, Jelle van der Waa wrote:
From: Jelle van der Waa <jelle@archlinux.org>
Describe the PKGINFO format which resides in a package produced makepkg. As mentioned on IRC, there's a lot of duplication with the PKGBUILD fields, so I'd feel better if we could somehow document just a list of fields and say that their contents are derived from the PKGBUILD(5) meaning.
The PKGINFO manpage should just describe the format of the file (as given in the suggested synopsis) and pointers to where the relevant metadata comes from. Some PKGINFO keys are specific to the built package, e.g. size, builddate, or mean something different, like arch/pkgver -- we should document why and how they differ. -- Eli Schwartz Bug Wrangler and Trusted User
On 06/29/19 at 11:18pm, Eli Schwartz wrote:
On 6/28/19 2:55 PM, Jelle van der Waa wrote:
From: Jelle van der Waa <jelle@archlinux.org>
Describe the PKGINFO format which resides in a package produced makepkg. As mentioned on IRC, there's a lot of duplication with the PKGBUILD fields, so I'd feel better if we could somehow document just a list of fields and say that their contents are derived from the PKGBUILD(5) meaning.
The PKGINFO manpage should just describe the format of the file (as given in the suggested synopsis) and pointers to where the relevant metadata comes from.
Some PKGINFO keys are specific to the built package, e.g. size, builddate, or mean something different, like arch/pkgver -- we should document why and how they differ.
This is low-level documentation. If we're going to document the file format, we should document it as libalpm sees it, not just the flavor that makepkg generates. For example, all of the dependency fields, that includes provides, replaces, and conflicts, can have an optional description even though makepkg doesn't allow one. There are only a handful of fields that actually map directly.
participants (4)
-
Allan McRae
-
Andrew Gregory
-
Eli Schwartz
-
Jelle van der Waa