jammy (1) generate-package-notes.1.gz

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
       ⟨https://systemd.io/COREDUMP_PACKAGE_METADATA/⟩, 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
       ⟨https://systemd.io/COREDUMP_PACKAGE_METADATA/⟩

                                                    May 2021                           GENERATE-PACKAGE-NOTES(1)