Skip to main content
Version: 2.24 (prerelease)

nfpm_content_file

A file (of any type) that should be copied into an nFPM package.

The file comes from either the 'source' field or from any of the targets listed in the 'dependencies' field. The file may be a workspace file, a generated file, or even a package.

The '<class 'pants.backend.nfpm.fields.contents.NfpmContentSrcField'>' field tells nFPM where the file is in the sandbox. The '<class 'pants.backend.nfpm.fields.contents.NfpmContentDstField'>' field tells nFPM where the file should be installed by the nFPM-generated package.

Backend: pants.backend.experimental.nfpm

dst​

str
required

The absolute install path for a packaged file.

When the package gets installed, the file from 'src' will be installed using the absolute path in 'dst'.

This path is an absolute path on the file system where the package will be installed.

content_type​

'' | 'config' | 'config|noreplace' | 'doc' | 'license' | 'readme' | None
default: ''

The nFPM content type for the packaged file.

The content type can be either

  • '': a normal file (the default), or
  • 'config': a config file.

For RPM packaged files, the content type can also be one of:

  • 'config|noreplace',
  • 'doc',
  • 'license', and
  • 'readme'.

The 'config|noreplace' type is used for RPM's %config(noreplace) option. For packagers other than RPM, using 'config|noreplace' is the same as 'config' and the remaining RPM-specific types are the same as '', a normal file.

This field only supports file-specific nFPM content types. Please use these targets for non-file content:

  • For 'dir' content, use targets nfpm_content_dir and nfpm_content_dirs.
  • For 'symlink' content, use targets nfpm_content_symlink and nfpm_content_symlinks.
  • For RPM 'ghost' content, use field 'ghost_contents' on target nfpm_rpm_package.

The nFPM 'tree' content type is not supported. Before passing the list of package contents to nFPM, pants expands target generators and any globs, so the 'tree' content type does not make sense.

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.24/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.

description​

str | None
default: None

A human-readable description of the target.

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

file_group​

str | None
default: 'root'

Name of the group that should own this packaged file or directory.

This is like the GROUP arg in chown: https://www.mankier.com/1/chown

file_mode​

int | str | None
default: None

A file mode as a numeric octal, an string octal, or a symbolic representation.

NB: In most cases, you should set this field and not rely on the default value. Pants only tracks the executable bit for workspace files. So, this field defaults to 0o755 for executable files and 0o644 for files that are not executable.

You may specify the file mode as: an octal, an octal string, or a symbolic string. If you specify a numeric octal (not as a string), make sure to include python's octal prefix: 0o like in 0o644. If you specify the octal as a string, the Oo prefix is optional (like 644). If you specify a symbolic file mode string, you must provide 9 characters with "-" in place of any absent permissions (like 'rw-r--r--').

For example to specify world readable/executable and user writable, these are equivalent:

  • 0o755 - '755' - 'rwxr-xr-x'

Another example for a file with read/write permissions for only the user:

  • 0o600 - '600' - 'rw-------'

Another example for a file with the group sticky bit set:

  • 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. For example, 755 (no quotes) will be processed as 0o1363 (symbolically that would be '-wxrw--wt') which is probably not what you intended. Pants cannot detect errors like this, so be careful to either use a string or include the 0o octal prefix.

file_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

Though nFPM supports pulling mtime from the src file or directory in most cases, the pants nfpm backend does not support this. Reading the mtime from the filesystem is problematic because Pants does not track the mtime of files and does not propagate any file mtime into the sandboxes. Reasons for this include: git does not track mtime, timestamps like mtime cause many issues for reproducible packaging builds, and reproducible builds are required for pants to provide its fine-grained caches.

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/

file_owner​

str | None
default: 'root'

Username that should own this packaged file or directory.

This is like the OWNER arg in chown: https://www.mankier.com/1/chown

source​

str | None
default: None

A file that should be copied into an nFPM package (optional).

Either specify a file with 'source', or use 'dependencies' to add a dependency on the target that owns the file.

If both 'src' and 'source' are populated, then the file in 'source' will be placed in the sandbox at the 'src' path (similar to how the 'relocated_files' target works).

src​

str | None
default: None

A file path that should be included in the package.

When the package gets installed, the file from 'src' will be installed using the absolute path in 'dst'.

This path should be relative to the sandbox. The path should point to a generated file or a real file sourced from the workspace.

Either 'src' or 'source' is required. If the 'source' field is provided, then the 'src' defaults to the file referenced in the 'source' field.

If both 'src' and 'source' are populated, then the file in 'source' will be placed in the sandbox at the 'src' path (similar to how the 'relocated_files' target works).

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.