.TH GENERATE\-PACKAGE\-NOTES 1 "May 2021"
.SH NAME
generate\-package\-notes \- generate a linker script for package metadata
.SH SYNOPSIS
.B generate\-package\-notes
.RI [ OPTION ...]
.SH 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
.IR \%.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.
.PP
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.
.PP
Thus it becomes desirable to add additional metadata to a binary
at build time, so that
.BR \%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.
.PP
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
.UR https://systemd.io/COREDUMP_PACKAGE_METADATA/
.B Package Metadata for Core Files
.UE ,
and hopefully shared among all vendors.
.PP
.B generate\-package\-notes
generates a linker script on standard output,
which can then be used at build time via
.I \%LDFLAGS="\-Wl,\-dT,/path/to/generated/script"
to include the note in the binary.
If a Debian package is built using the
.BR dh (1)
sequencer, the generation can be partly automated using
.BR \%dh_package_notes (1).
.SH OPTIONS
.TP
.BI \-\-package\-type= TYPE
Set the key
.I type
to
.IR TYPE .
This defaults to
.IR package ,
but for Debian packages it should be set to
.IR deb .
.TP
.BI \-\-package\-name= NAME
Set the key
.I name
to
.IR 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.
.TP
.BI \-\-package\-version= VERSION
Set the key
.I version
to
.IR 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.
.TP
.BI \-\-package\-architecture= ARCHITECTURE
Set the key
.I architecture
to
.IR ARCHITECTURE .
This defaults to the empty string, but for Debian packages it should
be set to the Debian architecture identifier of the binary.
.TP
.TP
.BI \-\-root= PATH
When reading files, for example /usr/lib/system-release-cpe and /usr/lib/os-release,
open them relatively to the specified directory.
.TP
.BI \-\-cpe= CPE
Set the key
.I osCpe
to
.IR CPE .
If the special value
.I 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.
.TP
.BI \-\-rpm= PACKAGE \- VERSION
Set the keys
.I type
to
.BR rpm ,
.I name
to
.IR PACKAGE ,
and
.I version
to
.IR VERSION .
Overrides
.BR \-\-package\-type ,
.BR \-\-package\-name ,
.BR \-\-package\-architecture ,
and
.BR \-\-package\-version .
.TP
.BI \-\-debug\-info\-url= URL
Set the key
.I debugInfoUrl
to
.IR URL .
By default this key is omitted, but for Debian packages it should
be set to the official Debian debuginfod server address
.IR https://debuginfod.debian.org/ .
.TP
.BR \-h ", " \-\-help
Show a short help message and exit.
.SH SEE ALSO
.ad l
.nh
.BR dh_package_notes (1),
.BR systemd\-coredump (8),
.UR https://systemd.io/COREDUMP_PACKAGE_METADATA/
.B Package Metadata for Core Files
.UE