forked from openkylin/package-notes
137 lines
3.7 KiB
Groff
137 lines
3.7 KiB
Groff
.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
|