generate-package-notes - Man Page

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.

--cpe=CPE

Set the key osCpe to CPE. This defaults to the value of the CPE_NAME field in the first of /etc/os-release or /usr/lib/os-release that exists. Otherwise the key osCpe is omitted in the note.

--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

Info

May 2021