From 8a3173ede8421b9deee1956e348405f42220023b Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Thu, 2 Jan 2025 16:46:22 -0600 Subject: [PATCH] nfpm: Improve field doc rendering on website (#21807) The formatting of the nfpm field documentation was slightly mangled on the website. This is an attempt to improve that. --- src/python/pants/backend/nfpm/fields/all.py | 2 +- src/python/pants/backend/nfpm/fields/apk.py | 52 ++++++++--------- .../pants/backend/nfpm/fields/archlinux.py | 28 ++++----- .../pants/backend/nfpm/fields/contents.py | 18 +++--- src/python/pants/backend/nfpm/fields/deb.py | 36 ++++++------ src/python/pants/backend/nfpm/fields/rpm.py | 58 +++++++++---------- 6 files changed, 97 insertions(+), 97 deletions(-) diff --git a/src/python/pants/backend/nfpm/fields/all.py b/src/python/pants/backend/nfpm/fields/all.py index 583cdc7f40a..d904ab59342 100644 --- a/src/python/pants/backend/nfpm/fields/all.py +++ b/src/python/pants/backend/nfpm/fields/all.py @@ -106,7 +106,7 @@ class NfpmArchField(StringField): https://nfpm.goreleaser.com/goarch-to-pkg/ Use one of these values unless you need nFPM to use your value as-is: - {", ".join(repr(arch.value) for arch in NfpmArch.__members__.values())} + `{" | ".join(repr(arch.value) for arch in NfpmArch.__members__.values())}` """ ) diff --git a/src/python/pants/backend/nfpm/fields/apk.py b/src/python/pants/backend/nfpm/fields/apk.py index f322929a56b..a5eb66dd02b 100644 --- a/src/python/pants/backend/nfpm/fields/apk.py +++ b/src/python/pants/backend/nfpm/fields/apk.py @@ -58,9 +58,9 @@ class NfpmApkReplacesField(NfpmPackageRelationshipsField): This field takes a simple list of package names, like this: - - "bash" - - "git" - - "pkgconfig" + - "bash" + - "git" + - "pkgconfig" See: https://wiki.alpinelinux.org/wiki/Apk_spec#PKGINFO_Format @@ -91,14 +91,14 @@ class NfpmApkProvidesField(NfpmPackageRelationshipsField): Here are some examples extracted a variety of random packages: - - "cmd:bash=5.2.15-r0" - - "cmd:git=2.38.5-r0" - - "cmd:gio=2.74.6-r0" - - "so:libgio-2.0.so.0=0.7400.6" - - "so:libglib-2.0.so.0=0.7400.6" - - "py3.10:pkgconfig=1.5.5-r1" - - "pc:libpkgconf=1.9.4" - - "pkgconfig=1" + - "cmd:bash=5.2.15-r0" + - "cmd:git=2.38.5-r0" + - "cmd:gio=2.74.6-r0" + - "so:libgio-2.0.so.0=0.7400.6" + - "so:libglib-2.0.so.0=0.7400.6" + - "py3.10:pkgconfig=1.5.5-r1" + - "pc:libpkgconf=1.9.4" + - "pkgconfig=1" See: https://wiki.alpinelinux.org/wiki/Apk_spec#PKGINFO_Format @@ -138,19 +138,19 @@ class NfpmApkDependsField(NfpmPackageRelationshipsField): Example package dependencies (which do not have a prefix): - - "git" - - "git=2.40.1-r0" + - "git" + - "git=2.40.1-r0" Example absolute path dependencies (which start with `/`): - - "/bin/sh" + - "/bin/sh" Example shared object dependencies (which have a `so:` prefix): - - "so:libc.musl-x86_64.so.1" - - "so:libcurl.so.4" - - "so:libpcre2-8.so.0" - - "so:libz.so.1" + - "so:libc.musl-x86_64.so.1" + - "so:libcurl.so.4" + - "so:libpcre2-8.so.0" + - "so:libz.so.1" WARNING: This is NOT the same as the 'dependencies' field! It does not accept pants-style dependencies like target addresses. @@ -187,14 +187,14 @@ class NfpmApkScriptsField(NfpmPackageScriptsField): The script types are the terms used by nFPM. For reference, Alpine Linux uses the following terms in the APKBUILD file instead: - | nFPM term | APKBUILD term | - +-------------+----------------+ - | preinstall | pre-install | - | postinstall | post-install | - | preupgrade | pre-upgrade | - | postupgrade | post-upgrade | - | preremove | pre-deinstall | - | postremove | post-deinstall | + | nFPM term | APKBUILD term | + +-------------+----------------+ + | preinstall | pre-install | + | postinstall | post-install | + | preupgrade | pre-upgrade | + | postupgrade | post-upgrade | + | preremove | pre-deinstall | + | postremove | post-deinstall | Please consult the Alpine Linux docs to understand when `apk` will run each of these scripts, how it handles a failure, and what failure means diff --git a/src/python/pants/backend/nfpm/fields/archlinux.py b/src/python/pants/backend/nfpm/fields/archlinux.py index 9081269ebce..61b41a91b37 100644 --- a/src/python/pants/backend/nfpm/fields/archlinux.py +++ b/src/python/pants/backend/nfpm/fields/archlinux.py @@ -107,9 +107,9 @@ class NfpmArchlinuxProvidesField(NfpmPackageRelationshipsField): Because the "baz" package implicitly provides its own name, this list should not include "baz". - - "foo" - - "bar=1.0.0" - - "libbaz.so=2" + - "foo" + - "bar=1.0.0" + - "libbaz.so=2" If several packages declare the same '{NfpmArchlinuxProvidesField.alias}', then they might need to declare that they conflict with each other @@ -140,9 +140,9 @@ class NfpmArchlinuxDependsField(NfpmPackageRelationshipsField): The '{NfpmArchlinuxDependsField.alias}' field has install-time dependencies that can use version selectors (with one of `<`, `<=`, `=`, `>=`, `>`). - - "git" - - "tcpdump<5" - - "foobar>=1.8.0" + - "git" + - "tcpdump<5" + - "foobar>=1.8.0" WARNING: This is NOT the same as the 'dependencies' field! It does not accept pants-style dependencies like target addresses. @@ -192,14 +192,14 @@ class NfpmArchlinuxScriptsField(NfpmPackageScriptsField): by adding a shell function for each of your script files where your script becomes the body of that function. These functions are: - | nFPM script | `.INSTALL` function | - +-------------+---------------------+ - | preinstall | pre_install | - | postinstall | post_install | - | preupgrade | pre_upgrade | - | postupgrade | post_upgrade | - | preremove | pre_remove | - | postremove | post_remove | + | nFPM script | `.INSTALL` function | + +-------------+---------------------+ + | preinstall | pre_install | + | postinstall | post_install | + | preupgrade | pre_upgrade | + | postupgrade | post_upgrade | + | preremove | pre_remove | + | postremove | post_remove | So, if you provide a `preinstall` script, the `.INSTALL` scriptlet would contain: diff --git a/src/python/pants/backend/nfpm/fields/contents.py b/src/python/pants/backend/nfpm/fields/contents.py index daf982339e5..98a57b8edd5 100644 --- a/src/python/pants/backend/nfpm/fields/contents.py +++ b/src/python/pants/backend/nfpm/fields/contents.py @@ -127,21 +127,21 @@ class NfpmContentFileModeField(IntField): For example to specify world readable/executable and user writable, these are equivalent: - - `0o755` - - `'755'` - - `'rwxr-xr-x'` + - `0o755` + - `'755'` + - `'rwxr-xr-x'` Another example for a file with read/write permissions for only the user: - - `0o600` - - `'600'` - - `'rw-------'` + - `0o600` + - `'600'` + - `'rw-------'` Another example for a file with the group sticky bit set: - - `0o2660` - - `'2660'` - - `'rw-rwS---'` + - `0o2660` + - `'2660'` + - `'rw-rwS---'` WARNING: If you forget to include the `0o` prefix on a numeric octal, then it will be interpreted as an integer which is probably not what you want. diff --git a/src/python/pants/backend/nfpm/fields/deb.py b/src/python/pants/backend/nfpm/fields/deb.py index b2ec5acc4fe..8f4d38f5039 100644 --- a/src/python/pants/backend/nfpm/fields/deb.py +++ b/src/python/pants/backend/nfpm/fields/deb.py @@ -200,8 +200,8 @@ class NfpmDebProvidesField(NfpmPackageRelationshipsField): For example, these declare virtual packages foo and bar. - - "foo" - - "bar (=1.0.0)" + - "foo" + - "bar (=1.0.0)" If several packages declare the same '{NfpmDebProvidesField.alias}', then they might need to declare that they conflict with each other @@ -225,9 +225,9 @@ class NfpmDebDependsField(NfpmPackageRelationshipsField): in parentheses) or use `|` to specify package alternatives that equally satisfy a dependency. - - "git" - - "libc6 (>= 2.2.1)" - - "default-mta | mail-transport-agent" + - "git" + - "libc6 (>= 2.2.1)" + - "default-mta | mail-transport-agent" Make sure to include package dependencies of this package as well as any packages required by the `postinstall`, `postupgrade`, or `preremove` scripts. @@ -314,8 +314,8 @@ class NfpmDebConflictsField(NfpmPackageRelationshipsField): foo (version 2.5 or less) and bar packages, so they must be uninstalled before this package can be installed. - - "foo (<2.6)" - - "bar" + - "foo (<2.6)" + - "bar" See: https://www.debian.org/doc/debian-policy/ch-relationships.html#conflicting-binary-packages-conflicts """ @@ -341,8 +341,8 @@ class NfpmDebBreaksField(NfpmPackageRelationshipsField): only if foo version 2.5 or less is installed and it breaks package bar no matter what version is installed. - - "foo (<2.6)" - - "bar" + - "foo (<2.6)" + - "bar" See: https://www.debian.org/doc/debian-policy/ch-relationships.html#packages-which-break-other-packages-breaks """ @@ -388,15 +388,15 @@ class NfpmDebScriptsField(NfpmPackageScriptsField): The script types are the names used by nFPM. For reference, Debian uses the following file names instead: - | nFPM script | Debian file | - +-------------+-------------+ - | preinstall | preinst | - | postinstall | postinst | - | preremove | prerm | - | postremove | postrm | - | config | config | - | templates | templates | - | rules | rules | + | nFPM script | Debian file | + +-------------+-------------+ + | preinstall | preinst | + | postinstall | postinst | + | preremove | prerm | + | postremove | postrm | + | config | config | + | templates | templates | + | rules | rules | The `pre*` and `post*` scripts are used by `dpkg` at various stages of installing, upgrading, and removing the deb package. diff --git a/src/python/pants/backend/nfpm/fields/rpm.py b/src/python/pants/backend/nfpm/fields/rpm.py index a219621a59a..af28c417902 100644 --- a/src/python/pants/backend/nfpm/fields/rpm.py +++ b/src/python/pants/backend/nfpm/fields/rpm.py @@ -158,9 +158,9 @@ class NfpmRpmProvidesField(NfpmPackageRelationshipsField): The list can include virtual package names and/or file paths. For example the `bash` package includes these in '{NfpmRpmProvidesField.alias}': - - "bash" - - "/bin/sh" - - "/bin/bash" + - "bash" + - "/bin/sh" + - "/bin/bash" This means another package could also provide alternative implementations for the "bash" package name and could provide "/bin/sh" and/or "/bin/bash". @@ -185,9 +185,9 @@ class NfpmRpmDependsField(NfpmPackageRelationshipsField): use version selectors (with one of `<`, `<=`, `=`, `>=`, `>` surrounded by spaces), where the version is formatted: `[epoch:]version[-release]` - - "git" - - "bash < 5" - - "perl >= 9:5.00502-3" + - "git" + - "bash < 5" + - "perl >= 9:5.00502-3" The rpm file header uses the term "requires" for this. This field is named "{NfpmRpmDependsField.alias}" because that is the term used by nFPM. @@ -290,24 +290,24 @@ class NfpmRpmCompressionField(StringField): Here are several gzip examples with and without the optional compression level (-1 means use the default level which is 5; 9 is the max). - '{NfpmRpmCompressionAlgorithm.gzip.value}:9' - '{NfpmRpmCompressionAlgorithm.gzip.value}:0' - '{NfpmRpmCompressionAlgorithm.gzip.value}:-1' - '{NfpmRpmCompressionAlgorithm.gzip.value}:5' - '{NfpmRpmCompressionAlgorithm.gzip.value}' + - '{NfpmRpmCompressionAlgorithm.gzip.value}:9' + - '{NfpmRpmCompressionAlgorithm.gzip.value}:0' + - '{NfpmRpmCompressionAlgorithm.gzip.value}:-1' + - '{NfpmRpmCompressionAlgorithm.gzip.value}:5' + - '{NfpmRpmCompressionAlgorithm.gzip.value}' Here are several zstd examples. Note that nFPM uses a library that only defines four named compression levels, and then maps the zstd integer levels to those. You may specify the zstd level as an integer, or using these names: https://github.com/klauspost/compress/tree/master/zstd#status - '{NfpmRpmCompressionAlgorithm.zstd.value}:fastest' - '{NfpmRpmCompressionAlgorithm.zstd.value}:default' - '{NfpmRpmCompressionAlgorithm.zstd.value}:better' - '{NfpmRpmCompressionAlgorithm.zstd.value}:best' - '{NfpmRpmCompressionAlgorithm.zstd.value}:3' - '{NfpmRpmCompressionAlgorithm.zstd.value}:9' - '{NfpmRpmCompressionAlgorithm.zstd.value}' + - '{NfpmRpmCompressionAlgorithm.zstd.value}:fastest' + - '{NfpmRpmCompressionAlgorithm.zstd.value}:default' + - '{NfpmRpmCompressionAlgorithm.zstd.value}:better' + - '{NfpmRpmCompressionAlgorithm.zstd.value}:best' + - '{NfpmRpmCompressionAlgorithm.zstd.value}:3' + - '{NfpmRpmCompressionAlgorithm.zstd.value}:9' + - '{NfpmRpmCompressionAlgorithm.zstd.value}' """ ) @@ -368,15 +368,15 @@ class NfpmRpmScriptsField(NfpmPackageScriptsField): uses the following scriptlet tag names instead and runs them before/after the indicated phase: - | nFPM term | RPM scriptlet | RPM phase | - +-------------+---------------+-------------+ - | preinstall | %pre | install | - | postinstall | %post | install | - | preremove | %preun | uninstall | - | postremove | %postun | uninstall | - | pretrans | %pretrans | transaction | - | posttrans | %posttrans | transaction | - | verify | %verifyscript | verify | + | nFPM term | RPM scriptlet | RPM phase | + +-------------+---------------+-------------+ + | preinstall | %pre | install | + | postinstall | %post | install | + | preremove | %preun | uninstall | + | postremove | %postun | uninstall | + | pretrans | %pretrans | transaction | + | posttrans | %posttrans | transaction | + | verify | %verifyscript | verify | Please consult the RPM docs to understand what is required of these scripts. @@ -396,8 +396,8 @@ class NfpmRpmGhostContents(StringSequenceField): A list of files that this package owns, but that this package does not include. Examples of ghosted files include: - - A log file or a state file that does not exist until runtime. - - A binary that is managed by 'alternatives'. + - A log file or a state file that does not exist until runtime. + - A binary that is managed by 'alternatives'. RPM specs use the `%ghost` directive to list these ghosted files.