Skip to main content
Version: 2.23 (prerelease)

nfpm_archlinux_package

An Archlinux system package built by nFPM.

This will not install the package, only create an .tar.zst file that you can then distribute and install, e.g. via pkg.

See https://www.pantsbuild.org/nfpm-archlinux-package.

Backend: pants.backend.experimental.nfpm

package_name​

str
required

The package name.

version​

str
required

The package version (preferably following semver).

If 'version_schema' is not 'semver', then this should not be prefixed with a 'v' because some package managers, like deb, require the version start with a digit.

See the 'version_schema' field's help for more details about how this field gets parsed by nFPM when it is 'semver'.

arch​

str | None
default: 'amd64'

The package architecture.

This should be a valid GOARCH value (or GOARCH+GOARM) that nFPM can convert into the package-specific equivalent. Otherwise, pants tells nFPM to use this value as-is.

nFPM conversion from GOARCH to package-specific value is documented here: https://nfpm.goreleaser.com/goarch-to-pkg/

Use one of these values unless you need nFPM to use your value as-is: '386', 'all', 'amd64', 'arm5', 'arm6', 'arm7', 'arm64', 'loong64', 'mips', 'mipsle', 'mips64', 'mips64le', 'ppc64', 'ppc64le', 'riscv64', 's390', 's390x', 'sparc64', 'wasm'

conflicts​

Iterable[str] | None
default: None

A list of (virtual) packages that this package conflicts with.

Packages that conflict with each other cannot be installed at the same time.

The 'conflicts' field has the same syntax as the 'depends' field.

See: https://wiki.archlinux.org/title/PKGBUILD#conflicts https://man.archlinux.org/man/core/pacman/PKGBUILD.5.en

dependencies​

Iterable[str] | None
default: None

Addresses to other targets that this target depends on, e.g. ['helloworld/subdir:lib', 'helloworld/main.py:lib', '3rdparty:reqs#django'].

This augments any dependencies inferred by Pants, such as by analyzing your imports. Use pants dependencies or pants peek on this target to get the final result.

See https://www.pantsbuild.org/2.23/docs/using-pants/key-concepts/targets-and-build-files for more about how addresses are formed, including for generated targets. You can also run pants list :: to find all addresses in your project, or pants list dir to find all addresses defined in that directory.

If the target is in the same BUILD file, you can leave off the BUILD file path, e.g. :tgt instead of helloworld/subdir:tgt. For generated first-party addresses, use ./ for the file path, e.g. ./main.py:tgt; for all other generated targets, use :tgt#generated_name.

You may exclude dependencies by prefixing with !, e.g. ['!helloworld/subdir:lib', '!./sibling.txt']. Ignores are intended for false positives with dependency inference; otherwise, simply leave off the dependency from the BUILD file.

depends​

Iterable[str] | None
default: None

List of package dependencies (for package installers).

The 'depends' field has install-time dependencies that can use version selectors (with one of <, <=, =, >=, >).

  • "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.

See: https://wiki.archlinux.org/title/PKGBUILD#depends https://man.archlinux.org/man/core/pacman/PKGBUILD.5.en https://wiki.archlinux.org/title/Arch_package_guidelines#Package_dependencies

description​

str | None
default: None

A human-readable description of the target.

Use pants list --documented :: to see all targets with descriptions.

homepage​

str | None
default: None

The URL of this package's homepage like "https://example.com&#x22;.

This field is named "homepage" instead of "url" because that is the term used by nFPM, which adopted the term from deb packaging. The term "url" is used by apk, archlinux, and rpm packaging.

license​

str | None
default: None

The license of this package.

Where possible, please try to use the SPDX license identifiers (for example "Apache-2.0", "BSD-3-Clause", "GPL-3.0-or-later", or "MIT"): https://spdx.org/licenses/

For more complex cases, where the package includes software with multiple licenses, consider using an SPDX license expression: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/

See also these rpm-specific descriptions of how to set this field (this is helpful info even if you are not using rpm): https://docs.fedoraproject.org/en-US/legal/license-field/

nFPM does not yet generate the debian/copyright file, so this field is technically unused for now. Even for deb, we recommend using this field to document the software license for this package. See also these pages about specifying a license for deb packaging: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/#license-specification https://wiki.debian.org/Proposals/CopyrightFormat#Differences_between_DEP5_and_SPDX

mtime​

str | None
default: '1980-01-01T00:00:00Z'

The file modification time as an RFC 3339 formatted string.

For example: 2008-01-02T15:04:05Z

The format is defined in RFC 3339: https://rfc-editor.org/rfc/rfc3339.html

NOTE: This field does NOT set the mtime for package contents. It sets the build time in package metadata (for package types that have that metadata), as well as the file modification time for files that nFPM generates in the package. To set the mtime for package contents, use the file_mtime field on the relevant nfpm_content_* targets.

The default value is '1980-01-01T00:00:00Z'. You may also override the default value by setting [nfpm].default_mtime in pants.toml, or by setting the SOURCE_DATE_EPOCH environment variable.

See also: https://reproducible-builds.org/docs/timestamps/

output_path​

str | None
default: '${spec_path_normalized}/${target_name_normalized}${file_suffix}'

Where the built directory tree should be located.

If undefined, this will use the path to the BUILD file, followed by the target name. For example, src/project/packaging:rpm would be src.project.packaging/rpm/.

Regardless of whether you use the default or set this field, the package's file name will have the packaging system's conventional filename (as understood by nFPM). So, an rpm using the default for this field, the target src/project/packaging:rpm might have a final path like src.project.packaging/rpm/projectname-1.2.3-1.x86_64.rpm. Similarly, for deb, the target src/project/packaging:deb might have a final path like src.project.packaging/deb/projectname_1.2.3+git-1_x86_64.deb. The other packagers have their own formats as well.

When running pants package, this path will be prefixed by --distdir (e.g. dist/).

Warning: setting this value risks naming collisions with other package targets you may have.

packager​

str | None
default: None

The name and email address of the packager or packager organization.

The 'packager' is used to identify who actually packaged the software, as opposed to the author of the software, or the maintainer of an archlinux PKGBUILD.

The name is first, then the email address inside angle brackets <> (in RFC5322 format). For example: "Foo Bar <[email protected]>" This format is the conventional format; it not a hard requirement.

If not set, nFPM uses "Unknown Packager" by default (as does makepkg).

See: https://man.archlinux.org/man/BUILDINFO.5 https://wiki.archlinux.org/title/Makepkg#Packager_information

pkgbase​

str | None
default: None

The base name of an Archlinux package.

For split packages, 'pkgbase' specifies the name of the group of packages. For all other packages, this is the same as package name (known as 'pkgname' by Archlinux packaging tools). If unset, nFPM will use the package name as the default value for the 'pkgbase' field.

See: https://man.archlinux.org/man/BUILDINFO.5 https://wiki.archlinux.org/title/PKGBUILD#pkgbase

provides​

Iterable[str] | None
default: None

A list of (virtual) packages or shared libraries that this package provides.

Each entry can be either a package name or a shared library (which ends with ".so"). You can specify a version on both package names and shared libraries. If specified, the version must use = (not <, <=, etc).

Make sure to include any shared libraries (.so files) that this package installs if they provide an external API for other packages to use.

Do not include the 'package_name' (known by 'pkgname' in Archlinux) in the list of 'provides' as that is implicit.

For example, package "baz" could declare that it also provides virtual packages "foo" and "bar" as well as the "libbaz.so" v2 shared object. Because the "baz" package implicitly provides its own name, this list should not include "baz".

  • "foo" - "bar=1.0.0" - "libbaz.so=2"

If several packages declare the same 'provides', then they might need to declare that they conflict with each other using 'conflicts' if, for example, they also install a binary with the same path. Packages that have the same package (or virtual package) in both 'provides' and 'conflicts' are considered alternative packages that cannot be installed at the same time. If those package only include an entry in 'provides' and not in 'conflicts', then they CAN be installed at the same time.

See: https://wiki.archlinux.org/title/PKGBUILD#provides https://man.archlinux.org/man/core/pacman/PKGBUILD.5.en https://wiki.archlinux.org/title/Arch_package_guidelines#Package_relations

replaces​

Iterable[str] | None
default: None

A list of packages that this package replaces or obsoletes.

This allows for combining packages or splitting them up. When pacman does a sysupgrade operation, it will immediately replace the listed packages with this package. This option is ignored during pacman sync or upgrade operations.

See: https://wiki.archlinux.org/title/PKGBUILD#replaces https://man.archlinux.org/man/core/pacman/PKGBUILD.5.en

scripts​

dict | None
default: None

Map of install script source files for the Archlinux package.

This maps the script type (key) to the script source file (value). Each of the script source file(s) must be provided via 'dependencies'. nFPM will package all of these scripts in a single .INSTALL scriptlet file 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 |

So, if you provide a preinstall script, the .INSTALL scriptlet would contain:

function pre_install() {
# Your preinstall script's contents get embedded here.
}

Here are several things to keep in mind when writing your scripts:

  • Your scripts are actually functions, so use return instead of exit.
  • pacman uses /bin/sh to source .INSTALL and run the function(s).
  • pacman runs these in a chroot.
  • The current directory is the root of the chroot.

Please consult the Archlinux docs to understand when pacman will run each of these functions and what arguments the functions will receive.

See: https://wiki.archlinux.org/title/pacman#What_happens_during_package_install/upgrade/removal https://man.archlinux.org/man/core/pacman/PKGBUILD.5.en#INSTALL/UPGRADE/REMOVE_SCRIPTING https://wiki.archlinux.org/title/PKGBUILD#install

tags​

Iterable[str] | None
default: None

Arbitrary strings to describe a target.

For example, you may tag some test targets with 'integration_test' so that you could run pants --tag='integration_test' test :: to only run on targets with that tag.

version_epoch​

int | None
default: None

A package with a higher version epoch will always be considered newer. This is primarily useful when the version numbering scheme has changed.

Debian and RPM documentation warn against using epoch in most cases: https://www.debian.org/doc/debian-policy/ch-controlfields.html#epochs-should-be-used-sparingly https://rpm-packaging-guide.github.io/#epoch

When this field is None (the default) nFPM will use "" for deb packages, and "0" for rpm packages.

N.B.: The nFPM documentation incorrectly notes that nFPM can parse this from the 'version' field; the nFPM code actually does not replace or update this.

version_prerelease​

str | None
default: None

This is a pre-release indicator like "alpha" or "beta" and often includes a numeric component like "rc1" and "rc2".

For apk and archlinux, version and prerelease are merely concatenated. For deb and rpm, prerelease is typically prefixed with a "~" in the version.

nFPM extracts the default for this from 'version' if it is semver compatible. If you set 'version_prerelease', then any prerelease component of 'version' gets discarded.

version_release​

int | None
default: 1

The release or revision number for a given package version.

Increment the release each time you release the same version of the package. Often, these releases allow for correcting metadata about a package or to rebuild something that was broken in a previous release of that version.

Reset this to 1 whenever you bump the 'version' field.

N.B.: nFPM does NOT parse this from the 'version' field.

version_schema​

'none' | 'semver' | None
default: 'semver'

Which schema the 'version' field follows.

nFPM only supports two schemas for now: semver, none

If this is "none", then nFPM will use 'version' as-is.

If this is "semver", then nFPM will parse 'version' into its constituent parts using a lenient algorithm: It will strip a v prefix and will accept versions with fewer than 3 components, like v1.2. If parsing fails, then the version is used as-is. If parsing succeeds, nFPM replaces config options with the parsed components.

The 'version' field always gets replaced with a dotted 3 part version (Major.Minor.Patch).

The 'version_prerelease' field is only updated if not set. It gets the "dev", "alpha", "rc", or similar parsed prerelease indicator.

The 'version_metadata' field is only updated if not set. This will be set with "git" when the version contains "+git" and similar metadata tags.

The 'version_release' and 'version_epoch' fields are NOT replaced by components parsed from 'version'.

N.B.: Some of these fields are not available for all package types.

This field is named "version" because that is the term used by nFPM. Though deb and rpm packaging also use "version", this is known as "pkgver" in apk and archlinux packaging.