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

                                                    May 2021                           GENERATE-PACKAGE-NOTES(1)