Skip to main content
Version: 2.23 (prerelease)

nfpm_content_symlink


A symlink in an nFPM package (created on package install).

Backend: pants.backend.experimental.nfpm


dst

str
required

The symlink path (on package install).

When the package gets installed, a symlink will be installed at the 'dst' path. The symlink will point to the 'src' path (the symlink target).

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

src

str
required

The symlink target path (on package install).

When the package gets installed, a symlink will be installed at the 'dst' path. The symlink will point to the 'src' path (the symlink target).

This path is a path on the file system where the package will be installed. If this path is absolute, it is the absolute path to the symlink's target path. If this path is relative, it is relative to the 'dst' path, which is where the symlink will be created.

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

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.