1.. _module-pw_build_info: 2 3============= 4pw_build_info 5============= 6 7.. warning:: 8 This module is under construction and may not be ready for use. 9 10pw_build_info provides tooling, build integration, and libraries for generating, 11embedding, and parsing build-related information that is embedded into 12binaries. Simple numeric version numbering doesn't typically express things 13like where the binary originated, what devices it's compatible with, whether 14local changes were present when the binary was built, and more. pw_build_info 15simplifies the process of integrating rich version metadata to answer more 16complex questions about compiled binaries. 17 18------------- 19GNU Build IDs 20------------- 21This module provides C++ and python libraries for reading GNU build IDs 22generated by the link step of a C++ executable. These build IDs are essentially 23hashes of the final linked binary, meaning two identical binaries will have 24identical build IDs. This can be used to accurately identify matching 25binaries. 26 27Linux executables that depend on the ``build_id`` GN target will automatically 28generate GNU build IDs. Windows and macOS binaries cannot use this target as 29the implementation of GNU build IDs depends on the ELF file format. 30 31Embedded targets must first explicitly place the GNU build ID section into a 32non-info section of their linker script that is readable by the firmware. The 33following linker snippet may be copied into a read-only section (just like the 34.rodata or .text sections): 35 36.. literalinclude:: build_id_linker_snippet.ld 37 38This snippet may be placed directly into an existing section, as it is not 39required to live in its own dedicated section. When opting to create a 40dedicated section for the build ID to reside in, Pigweed recommends naming the 41section ``.note.gnu.build-id`` as it makes it slightly easier for tools to 42parse the build ID out of a binary. After the linker script has been properly 43set up, the ``build_id`` GN target may be used to read the build ID at 44runtime. 45 46Python API reference 47==================== 48 49.. py:function:: read_build_id_from_section(elf_file: BinaryIO) -> \ 50 Optional[bytes] 51 52 Reads a GNU build ID from an ELF binary by searching for a 53 ``.note.gnu.build-id`` section. 54 55.. py:function:: read_build_id_from_symbol(elf_file: BinaryIO) -> \ 56 Optional[bytes] 57 58 Reads a GNU build ID from an ELF binary by searching for a 59 ``gnu_build_id_begin`` symbol. This can be a rather slow operation. 60 61.. py:function:: read_build_id(elf_file: BinaryIO) -> Optional[bytes] 62 63 Reads a GNU build ID from an ELF binary, first checking for a GNU build ID 64 section and then falling back to search for a ``gnu_build_id_begin`` symbol. 65 66.. py:function:: find_matching_elf(uuid: bytes, search_dir: Path) -> \ 67 Optional[Path] 68 69 Recursively searches a directory for an ELF file with a matching UUID. 70 71 Warning: This can take on the order of several seconds. 72 73Python utility 74============== 75GNU build IDs can be parsed out of ELF files using the ``build_id`` python tool. 76Simply point the tool to a binary with a GNU build ID and the build ID will be 77printed out if it is found. 78 79.. code-block:: sh 80 81 $ python -m pw_build_info.build_id my_device_image.elf 82 d43cce74f18522052f77a1fa3fb7a25fe33f40dd 83