[pacman-dev] [PATCH 0/1] Add a BUILDINFO man page
While working on the reprodcible build project I found it handy to have some resources about the contents of the BUILDINFO file. This patch adds a man page about the structure of the BUILDINFO file, I've based it on the PKGBUILD man page. If this patch is accepted, I'll be motivated to add one for PKGINFO as well. Jelle van der Waa (1): Add BUILDINFO man page doc/BUILDINFO.5.txt | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/Makefile.am | 4 +++- 2 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 doc/BUILDINFO.5.txt -- 2.15.1
Add a new man page which describes the structure of a BUILDINFO file included in a package produced by makepkg. Signed-off-by: Jelle van der Waa <jelle@vdwaa.nl> --- doc/BUILDINFO.5.txt | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/Makefile.am | 4 +++- 2 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 doc/BUILDINFO.5.txt diff --git a/doc/BUILDINFO.5.txt b/doc/BUILDINFO.5.txt new file mode 100644 index 00000000..1a454497 --- /dev/null +++ b/doc/BUILDINFO.5.txt @@ -0,0 +1,65 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +BUILDINFO(5) +============ + +Name +---- +BUILDINFO - Arch Linux package build information file + + +Synopsis +-------- +BUILDINFO + + +Description +----------- +This manual page describes the format of a BUILDINFO file usually found in a +package created by makepkg. + +Contents +-------- +The following is a list of the contents and a description of the key value pairs +in a BUILDINFO file. + +*format*:: + Denotes the file format, represented by a number. + +*pkgname*:: + The name of the package. + +*pkgbase*:: + The name used to refer to the group of packages in the output of makepkg. + +*pkgver*:: + The version of the package including pkgrel and epoch. + +*pkgbuild_sha256sum*:: + The sha256sum of the PKGBUILD used to build the package. + +*packager*:: + The packager which has built the package. + +*builddate* + The build date of the package in epoch. + +*builddir*:: + The build directory from which makepkg has been invoked. + +*buildenv (array)*:: + The set BUILDENV from makepkg.conf. + +*options (array)*:: + A combination of the OPTIONS set in makekg.conf merged with the options set + in the used PKGBUILD. + +*installed (array)*:: + The installed packages at build time including the version of the package. + +See Also +-------- +linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5] + +include::footer.txt[] diff --git a/doc/Makefile.am b/doc/Makefile.am index 44e32996..bbf2af66 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -15,7 +15,8 @@ ASCIIDOC_MANS = \ PKGBUILD.5 \ makepkg.conf.5 \ pacman.conf.5 \ - libalpm.3 + libalpm.3 \ + BUILDINFO.5 DOXYGEN_MANS = $(wildcard man3/*.3) @@ -58,6 +59,7 @@ EXTRA_DIST = \ PKGBUILD-example.txt \ makepkg.conf.5.txt \ pacman.conf.5.txt \ + BUILDINFO.5.txt \ libalpm.3.txt \ footer.txt \ index.txt \ -- 2.15.1
On 01/01/18 at 02:53pm, Jelle van der Waa wrote:
Add a new man page which describes the structure of a BUILDINFO file included in a package produced by makepkg.
Signed-off-by: Jelle van der Waa <jelle@vdwaa.nl> --- doc/BUILDINFO.5.txt | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/Makefile.am | 4 +++- 2 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 doc/BUILDINFO.5.txt
diff --git a/doc/BUILDINFO.5.txt b/doc/BUILDINFO.5.txt new file mode 100644 index 00000000..1a454497 --- /dev/null +++ b/doc/BUILDINFO.5.txt @@ -0,0 +1,65 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +BUILDINFO(5) +============ + +Name +---- +BUILDINFO - Arch Linux package build information file
I know you copied this from PKGBUILD(5), but we really shouldn't be specifically referencing Arch in documentation other than as the upstream source or the expansion of ALPM. Just refer to makepkg here.
+ +Synopsis +-------- +BUILDINFO
I'm assuming you just copied PKGBUILD(5) here, but this is a pretty useless section. If we're going to have a Synopsis section, I would include some basic information like what BUILDINFO actually is (a description of a package's build environment), the version of the format that is being described, and the basic format (key-value pairs separated by '=', one value per line). Otherwise that information needs to be added to Description.
+ +Description +----------- +This manual page describes the format of a BUILDINFO file usually found in a +package created by makepkg. + +Contents +--------
To my knowledge, Contents is not a commonly used man page section, I'd just throw all of this in Description.
+The following is a list of the contents and a description of the key value pairs +in a BUILDINFO file. + +*format*:: + Denotes the file format, represented by a number.
Can we be more specific here? @Allan: do you intend to keep this as a plain integer or use something more complex for updates?
+*pkgname*:: + The name of the package. + +*pkgbase*:: + The name used to refer to the group of packages in the output of makepkg.
I find this wording is confusing. For packages, "group" typically refers to package groups, not split packages.
+*pkgver*:: + The version of the package including pkgrel and epoch. + +*pkgbuild_sha256sum*:: + The sha256sum of the PKGBUILD used to build the package.
In hex format.
+*packager*:: + The packager which has built the package. + +*builddate*
Missing ::
+ The build date of the package in epoch. + +*builddir*:: + The build directory from which makepkg has been invoked.
Not true; it's where the package is built.
+*buildenv (array)*:: + The set BUILDENV from makepkg.conf.
Nowhere is it described what it means for a key to be an array. It would probably be a good idea to specifically mention that disabled options may be included with at '!' prefix.
+*options (array)*:: + A combination of the OPTIONS set in makekg.conf merged with the options set + in the used PKGBUILD.
Ditto.
+*installed (array)*:: + The installed packages at build time including the version of the package.
The actual format of the package name and version should be described here. Looking at the actual code, this is also broken for any packages that include spaces in the name...
+See Also +-------- +linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5] + +include::footer.txt[] diff --git a/doc/Makefile.am b/doc/Makefile.am index 44e32996..bbf2af66 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -15,7 +15,8 @@ ASCIIDOC_MANS = \ PKGBUILD.5 \ makepkg.conf.5 \ pacman.conf.5 \ - libalpm.3 + libalpm.3 \ + BUILDINFO.5
DOXYGEN_MANS = $(wildcard man3/*.3)
@@ -58,6 +59,7 @@ EXTRA_DIST = \ PKGBUILD-example.txt \ makepkg.conf.5.txt \ pacman.conf.5.txt \ + BUILDINFO.5.txt \ libalpm.3.txt \ footer.txt \ index.txt \ -- 2.15.1
Thanks for the review! On 01/04/18 at 07:23pm, Andrew Gregory wrote:
On 01/01/18 at 02:53pm, Jelle van der Waa wrote:
+---- +BUILDINFO - Arch Linux package build information file
I know you copied this from PKGBUILD(5), but we really shouldn't be specifically referencing Arch in documentation other than as the upstream source or the expansion of ALPM. Just refer to makepkg here.
Yup, I agree wil adjust this.
+ +Synopsis +-------- +BUILDINFO
I'm assuming you just copied PKGBUILD(5) here, but this is a pretty useless section. If we're going to have a Synopsis section, I would include some basic information like what BUILDINFO actually is (a description of a package's build environment), the version of the format that is being described, and the basic format (key-value pairs separated by '=', one value per line). Otherwise that information needs to be added to Description.
I'll adjust this in v2.
+ +Description +----------- +This manual page describes the format of a BUILDINFO file usually found in a +package created by makepkg. + +Contents +--------
To my knowledge, Contents is not a commonly used man page section, I'd just throw all of this in Description.
Ack.
+The following is a list of the contents and a description of the key value pairs +in a BUILDINFO file. + +*format*:: + Denotes the file format, represented by a number.
Can we be more specific here? @Allan: do you intend to keep this as a plain integer or use something more complex for updates?
More specific as in? I guess "file format version" would be more specific?
+*pkgname*:: + The name of the package. + +*pkgbase*:: + The name used to refer to the group of packages in the output of makepkg.
I find this wording is confusing. For packages, "group" typically refers to package groups, not split packages.
Maybe the PKGBUILD man page needs a patch to reword this. I'll try to improve the text.
+*pkgver*:: + The version of the package including pkgrel and epoch. + +*pkgbuild_sha256sum*:: + The sha256sum of the PKGBUILD used to build the package.
In hex format.
+*packager*:: + The packager which has built the package. + +*builddate*
Missing ::
+ The build date of the package in epoch. + +*builddir*:: + The build directory from which makepkg has been invoked.
Not true; it's where the package is built.
+*buildenv (array)*:: + The set BUILDENV from makepkg.conf.
Nowhere is it described what it means for a key to be an array. It would probably be a good idea to specifically mention that disabled options may be included with at '!' prefix.
Do you mean I should describe what an array is? I guess that should be done in the Synopsis.
+*options (array)*:: + A combination of the OPTIONS set in makekg.conf merged with the options set + in the used PKGBUILD.
Ditto.
+*installed (array)*:: + The installed packages at build time including the version of the package.
The actual format of the package name and version should be described here. Looking at the actual code, this is also broken for any packages that include spaces in the name...
Spaces in a name is not legal I assume? -- Jelle van der Waa
On 06/01/18 09:56, Jelle van der Waa wrote:
+*format*:: + Denotes the file format, represented by a number. Can we be more specific here? @Allan: do you intend to keep this as a plain integer or use something more complex for updates? More specific as in? I guess "file format version" would be more specific?
It will stay an integer. A
On 01/06/18 at 12:56am, Jelle van der Waa wrote:
Thanks for the review!
On 01/04/18 at 07:23pm, Andrew Gregory wrote:
On 01/01/18 at 02:53pm, Jelle van der Waa wrote:
...
+ +*format*:: + Denotes the file format, represented by a number.
Can we be more specific here? @Allan: do you intend to keep this as a plain integer or use something more complex for updates?
More specific as in? I guess "file format version" would be more specific?
I meant more specific as in what kind of number (i.e. a plain positive integer as opposed to a float). ...
+*installed (array)*:: + The installed packages at build time including the version of the package.
The actual format of the package name and version should be described here. Looking at the actual code, this is also broken for any packages that include spaces in the name...
Spaces in a name is not legal I assume?
Unfortunately, what makepkg accepts as a valid package name and what libalpm accepts are not the same (improving that is on my TODO list). libalpm accepts any characters except '\n', '/', and NUL. The packages being listed weren't necessarily built by makepkg, so they can include the full range of characters that libalpm allows. I keep a list of the various pacman/alpm/makepkg restrictions here: https://wiki.archlinux.org/index.php/User:Apg#pacman_LIMITS
Add a new man page which describes the structure of a BUILDINFO file included in a package produced by makepkg. Signed-off-by: Jelle van der Waa <jelle@vdwaa.nl> --- doc/BUILDINFO.5.txt | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/Makefile.am | 4 +++- doc/PKGBUILD.5.txt | 2 +- 3 files changed, 72 insertions(+), 2 deletions(-) create mode 100644 doc/BUILDINFO.5.txt diff --git a/doc/BUILDINFO.5.txt b/doc/BUILDINFO.5.txt new file mode 100644 index 00000000..1038caf8 --- /dev/null +++ b/doc/BUILDINFO.5.txt @@ -0,0 +1,68 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +BUILDINFO(5) +============ + +Name +---- +BUILDINFO - Makepkg package build information file + + +Synopsis +-------- +This manual page describes the format of a BUILDINFO file usually found in a +package created by makepkg. The file contains a description of the package's +build environment. 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 +----------- + +This is a description of the contents of version '1' of the +BUILDINFO file format. + +*format*:: + Denotes the file format version, represented by a number. + +*pkgname*:: + The name of the package. + +*pkgbase*:: + + The base name of a package, usually the same as the pkgname except when + it's a split package. + +*pkgver*:: + The version of the package including pkgrel and epoch. + +*pkgbuild_sha256sum*:: + The sha256sum in hex format of the PKGBUILD used to build the package. + +*packager*:: + The packager which has built the package. + +*builddate*:: + The build date of the package in epoch. + +*builddir*:: + The build directory where the package has been build. + +*buildenv (array)*:: + The set BUILDENV from makepkg.conf. + +*options (array)*:: + A combination of the OPTIONS set in makekg.conf merged with the options set + in the used PKGBUILD. + +*installed (array)*:: + The installed packages at build time including the version of the package. + Formatted as "$pkgname-$pkgver-$pkgrel". + +See Also +-------- +linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5] + +include::footer.txt[] diff --git a/doc/Makefile.am b/doc/Makefile.am index 44e32996..bbf2af66 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -15,7 +15,8 @@ ASCIIDOC_MANS = \ PKGBUILD.5 \ makepkg.conf.5 \ pacman.conf.5 \ - libalpm.3 + libalpm.3 \ + BUILDINFO.5 DOXYGEN_MANS = $(wildcard man3/*.3) @@ -58,6 +59,7 @@ EXTRA_DIST = \ PKGBUILD-example.txt \ makepkg.conf.5.txt \ pacman.conf.5.txt \ + BUILDINFO.5.txt \ libalpm.3.txt \ footer.txt \ index.txt \ diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index 18bc2a19..ec2d6f82 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -6,7 +6,7 @@ PKGBUILD(5) Name ---- -PKGBUILD - Arch Linux package build description file +PKGBUILD - Makepkg build description file Synopsis -- 2.15.1
Add a new man page which describes the structure of a BUILDINFO file included in a package produced by makepkg. Signed-off-by: Jelle van der Waa <jelle@vdwaa.nl> --- doc/BUILDINFO.5.txt | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/Makefile.am | 4 +++- 2 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 doc/BUILDINFO.5.txt diff --git a/doc/BUILDINFO.5.txt b/doc/BUILDINFO.5.txt new file mode 100644 index 00000000..32c65c83 --- /dev/null +++ b/doc/BUILDINFO.5.txt @@ -0,0 +1,68 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +BUILDINFO(5) +============ + +Name +---- +BUILDINFO - Makepkg package build information file + + +Synopsis +-------- +This manual page describes the format of a BUILDINFO file usually found in a +package created by makepkg. The file contains a description of the package's +build environment. 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 +----------- + +This is a description of the contents of version '1' of the +BUILDINFO file format. + +*format*:: + Denotes the file format version, represented by a plain positive integer. + +*pkgname*:: + The name of the package. + +*pkgbase*:: + + The base name of a package, usually the same as the pkgname except when + it's a split package. + +*pkgver*:: + The version of the package including pkgrel and epoch. + +*pkgbuild_sha256sum*:: + The sha256sum in hex format of the PKGBUILD used to build the package. + +*packager*:: + The packager which has built the package. + +*builddate*:: + The build date of the package in epoch. + +*builddir*:: + The build directory where the package has been build. + +*buildenv (array)*:: + The set BUILDENV from makepkg.conf. + +*options (array)*:: + A combination of the OPTIONS set in makekg.conf merged with the options set + in the used PKGBUILD. + +*installed (array)*:: + The installed packages at build time including the version of the package. + Formatted as "$pkgname-$pkgver-$pkgrel". + +See Also +-------- +linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5] + +include::footer.txt[] diff --git a/doc/Makefile.am b/doc/Makefile.am index 44e32996..bbf2af66 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -15,7 +15,8 @@ ASCIIDOC_MANS = \ PKGBUILD.5 \ makepkg.conf.5 \ pacman.conf.5 \ - libalpm.3 + libalpm.3 \ + BUILDINFO.5 DOXYGEN_MANS = $(wildcard man3/*.3) @@ -58,6 +59,7 @@ EXTRA_DIST = \ PKGBUILD-example.txt \ makepkg.conf.5.txt \ pacman.conf.5.txt \ + BUILDINFO.5.txt \ libalpm.3.txt \ footer.txt \ index.txt \ -- 2.15.1
On 10/01/18 03:19, Jelle van der Waa wrote:
Add a new man page which describes the structure of a BUILDINFO file included in a package produced by makepkg.
Thanks. Some wording suggestions provided inline. A
Signed-off-by: Jelle van der Waa <jelle@vdwaa.nl> --- doc/BUILDINFO.5.txt | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/Makefile.am | 4 +++- 2 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 doc/BUILDINFO.5.txt
diff --git a/doc/BUILDINFO.5.txt b/doc/BUILDINFO.5.txt new file mode 100644 index 00000000..32c65c83 --- /dev/null +++ b/doc/BUILDINFO.5.txt @@ -0,0 +1,68 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +BUILDINFO(5) +============ + +Name +---- +BUILDINFO - Makepkg package build information file + + +Synopsis +-------- +This manual page describes the format of a BUILDINFO file usually found in a
s/usually// file found in the root of a package created by makepkg?
+package created by makepkg. The file contains a description of the package's +build environment. The information is formatted in key-value pairs separated +by a '=', one value per line, arrays are represented multiple keys with the
...per line. Arrays are...
+same value. + + +Description +----------- + +This is a description of the contents of version '1' of the +BUILDINFO file format. + +*format*:: + Denotes the file format version, represented by a plain positive integer. + +*pkgname*:: + The name of the package. + +*pkgbase*:: + + The base name of a package, usually the same as the pkgname except when + it's a split package.
except for split packages.
+ +*pkgver*:: + The version of the package including pkgrel and epoch. + +*pkgbuild_sha256sum*:: + The sha256sum in hex format of the PKGBUILD used to build the package. + +*packager*:: + The packager which has built the package.
The details of the packager that built the
+ +*builddate*:: + The build date of the package in epoch. + +*builddir*:: + The build directory where the package has been build.
The directory where the package was built.
+*buildenv (array)*:: + The set BUILDENV from makepkg.conf. +
The build enviroment sepcified in makepkg.conf.
+*options (array)*:: + A combination of the OPTIONS set in makekg.conf merged with the options set + in the used PKGBUILD.
The option set specified when building the package.
+ +*installed (array)*:: + The installed packages at build time including the version of the package.
...including the version infomration.
+ Formatted as "$pkgname-$pkgver-$pkgrel". + +See Also +-------- +linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5] + +include::footer.txt[] diff --git a/doc/Makefile.am b/doc/Makefile.am index 44e32996..bbf2af66 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -15,7 +15,8 @@ ASCIIDOC_MANS = \ PKGBUILD.5 \ makepkg.conf.5 \ pacman.conf.5 \ - libalpm.3 + libalpm.3 \ + BUILDINFO.5
DOXYGEN_MANS = $(wildcard man3/*.3)
@@ -58,6 +59,7 @@ EXTRA_DIST = \ PKGBUILD-example.txt \ makepkg.conf.5.txt \ pacman.conf.5.txt \ + BUILDINFO.5.txt \ libalpm.3.txt \ footer.txt \ index.txt \
Add a new man page which describes the structure of a BUILDINFO file included in a package produced by makepkg. Signed-off-by: Jelle van der Waa <jelle@vdwaa.nl> --- doc/BUILDINFO.5.txt | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/Makefile.am | 4 +++- 2 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 doc/BUILDINFO.5.txt diff --git a/doc/BUILDINFO.5.txt b/doc/BUILDINFO.5.txt new file mode 100644 index 00000000..b7a72831 --- /dev/null +++ b/doc/BUILDINFO.5.txt @@ -0,0 +1,67 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +BUILDINFO(5) +============ + +Name +---- +BUILDINFO - Makepkg package build information file + + +Synopsis +-------- +This manual page describes the format of a BUILDINFO file found in the root of +a package created by makepkg. The file contains a description of the package's +build environment. 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 +----------- + +This is a description of the contents of version '1' of the +BUILDINFO file format. + +*format*:: + Denotes the file format version, represented by a plain positive integer. + +*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. + +*pkgbuild_sha256sum*:: + The sha256sum in hex format of the PKGBUILD used to build the package. + +*packager*:: + The details of the packager that built the package. + +*builddate*:: + The build date of the package in epoch. + +*builddir*:: + The directory where the package was built. + +*buildenv (array)*:: + The build environment specified in makepkg.conf. + +*options (array)*:: + The options set specified when building the package. + +*installed (array)*:: + The installed packages at build time including the version information of + the package. Formatted as "$pkgname-$pkgver-$pkgrel". + +See Also +-------- +linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5] + +include::footer.txt[] diff --git a/doc/Makefile.am b/doc/Makefile.am index 44e32996..bbf2af66 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -15,7 +15,8 @@ ASCIIDOC_MANS = \ PKGBUILD.5 \ makepkg.conf.5 \ pacman.conf.5 \ - libalpm.3 + libalpm.3 \ + BUILDINFO.5 DOXYGEN_MANS = $(wildcard man3/*.3) @@ -58,6 +59,7 @@ EXTRA_DIST = \ PKGBUILD-example.txt \ makepkg.conf.5.txt \ pacman.conf.5.txt \ + BUILDINFO.5.txt \ libalpm.3.txt \ footer.txt \ index.txt \ -- 2.15.1
On 14/01/18 01:43, Jelle van der Waa wrote:
Add a new man page which describes the structure of a BUILDINFO file included in a package produced by makepkg.
Looks good to me. On my patchqueue. A
participants (3)
-
Allan McRae
-
Andrew Gregory
-
Jelle van der Waa