NAME¶

generate-package-notes - generate a linker script for package metadata

SYNOPSIS¶

generate-package-notes [OPTION...]

DESCRIPTION¶

ELF binaries get stamped with a unique, build-time generated hex string identifier called build-id, which gets embedded as an ELF note called .note.gnu.build-id. In most cases, this allows to associate a stripped binary with its debugging information. It is used, for example, to dynamically fetch DWARF symbols from a debuginfo server, or to query the local package manager and find out the package metadata or, again, the DWARF symbols or program sources.

However, this usage of the build-id requires either local metadata, usually set up by the package manager, or access to a remote server over the network. Both of those might be unavailable or forbidden.

Thus it becomes desirable to add additional metadata to a binary at build time, so that systemd-coredump(8) and other services analyzing core files are able to extract said metadata simply from the core file itself, without external dependencies. The metadata is embedded in a single ELF header section, in a key-value JSON format.

The metadata format is intentionally left open, so that vendors can add their own information. A set of well-known keys is defined in the document Package Metadata for Core Files, and hopefully shared among all vendors.

generate-package-notes generates a linker script on standard output, which can then be used at build time via LDFLAGS="-Wl,-dT,/path/to/generated/script" to include the note in the binary. If a Debian package is built using the dh(1) sequencer, the generation can be partly automated using dh_package_notes(1).

OPTIONS¶

--package-type=TYPE

Set the key type to TYPE. This defaults to package, but for Debian packages it should be set to deb.

--package-name=NAME

Set the key name to NAME. This defaults to the empty string, but for Debian packages it should be set to the name of the binary package containing the binary.

--package-version=VERSION

Set the key version to VERSION. This defaults to the empty string, but for Debian packages it should be set to the Debian version of the binary package containing the binary.

--package-architecture=ARCHITECTURE

Set the key architecture to ARCHITECTURE. This defaults to the empty string, but for Debian packages it should be set to the Debian architecture identifier of the binary.

--root=PATH

When reading files, for example /usr/lib/system-release-cpe and /usr/lib/os-release, open them relatively to the specified directory.

--cpe=CPE

Set the key osCpe to CPE. If the special value auto is passed, then the content of the /usr/lib/system-release-cpe file, or the value of CPE_NAME from os-release if the former was not found, will be used.

--rpm=PACKAGE-VERSION

Set the keys type to rpm, name to PACKAGE, and version to VERSION. Overrides --package-type, --package-name, --package-architecture, and --package-version.

--debug-info-url=URL

Set the key debugInfoUrl to URL. By default this key is omitted, but for Debian packages it should be set to the official Debian debuginfod server address https://debuginfod.debian.org/.

-h, --help

Show a short help message and exit.

SEE ALSO¶

dh_package_notes(1), systemd-coredump(8), Package Metadata for Core Files