From 0ab04876f2e82a350d6aa5be5ebb2f4be57c3ef4 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 19 Dec 2024 11:38:03 +0100 Subject: [PATCH] docs/package-notes: extend motivation and recommendations We described the "how", but not the "why". And the text was a bit dated, still mostly talking about core files. Let's make it more general and describe why a section is used. Add a recommendation/explanation for the debugInfoUrl field. --- docs/PACKAGE_METADATA_FOR_EXECUTABLE_FILES.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/PACKAGE_METADATA_FOR_EXECUTABLE_FILES.md b/docs/PACKAGE_METADATA_FOR_EXECUTABLE_FILES.md index 73454ceed17..1aa8734bced 100644 --- a/docs/PACKAGE_METADATA_FOR_EXECUTABLE_FILES.md +++ b/docs/PACKAGE_METADATA_FOR_EXECUTABLE_FILES.md @@ -27,6 +27,14 @@ Thus it becomes desirable to add additional metadata to a binary at build time, `systemd-coredump` and other services analyzing core files are able to extract said metadata simply from the core file itself, without external dependencies. +This metadata is stored as a section in the executable file, +so that it will be loaded into memory along with the text and data of the binary, +and will be preserved in a core dump. +This metadata can also be easily read from the file on disk, +so it can be used to identify provenience of files, +independently of any package management system, +even if the file is renamed or copied. + ## Implementation This document will attempt to define a common metadata format specification, so that @@ -81,6 +89,9 @@ these JSON objects are thus permitted to encode numeric values from these ranges as JSON numbers, and should not use numeric values not covered by these types and ranges. +If available, the metadata should also include the debuginfod server URL that can provide +the original executable, debuginfo and sources, to further facilitate debugging. + Reference implementations of [packaging tools for .deb and .rpm](https://github.com/systemd/package-notes) are available, and provide macros/helpers to include the note in binaries built by the package build system. -- 2.47.3