Crate buildid

Source
Expand description

Examine the build-id and similar values for your library or executable

println!("{:?}", buildid::build_id())

build-id is a value which is guaranteed to change when any of the component objects of a binary change. A change in the build-id does not guarantee that the executable or it’s components are actually different. Two distinct executables may have a different build-id if they were modified after linking (for example, by chrpath or similar).

build-id is intended to be sufficient to identify the appropriate debug information to use for a given object, and is used for this purpose by gdb and other debuggers.

build-id is also used by mesa as a key component in their caching of shaders (changes in the build-id cause the cache to be discarded).

Executables and shared objects contain build-ids. Using buildid::build_id() will return the build-id for the object that includes buildid (this crate). For example, if you write a shared object (shared library) using this crate, and provide a way to get the build-id in it’s external API, that call will return the build-id of the shared object/library (not the executable).

By default, the buildid crate will pick the best build-id lookup function it can for your platform. If one is not available, it may fail to compile. If you have a custom build-id lookup mechanism you want to tell buildid about, enabling one of the features may help.

§Optional Features

For all of the build-id lookup customization features, we recommend only setting them in top-level crates than have a complete understanding of the final link step for the executable.

§buildid-symbol-start-end

When enabled, assume the presence of 2 symbols named “__build_id_start” and “__build_id_end”, and use these to find the build-id. For gnu linkers, these symbols exist and can be used automatically.

If they aren’t present for some reason, one can provide the symbols by using a custom ldscript (linker script). See buildid-linker-symbols for a linker script mechanism to provide these.

This method takes precedence over automatically enable build-id lookup methods, and over buildid-section-inject.

§buildid-custom-inject

When enabled, assume that a function int build_id__get(unsigned char **build_id, size_t *len) is provided (with C linkage) that can locate and return the build-id. The build_id__get must return 1 if a build-id is located (and modify the build_id and len arguments to point to the memory containing the build-id and to contain the number of bytes in the build-id respectively), return 0 if no build-id exists, and return a negative error code if an unexpected error occurred. This method takes precedence over all other build-id lookup methods (if enabled).

§buildid-section-inject

When enabled, inject our own symbol into the section where build id is expected to be located, and use the build-time environment variable BUILD_ID_SIZE to determine how many bytes to read. This method will only function on some platforms (basically: GNU ones). Note that BUILD_ID_SIZE must be set correctly, and differs for GNU ld (bfd) and LLVM lld.

Note that in all cases this works, buildid-symbol-start-end is likely to work and be more reliable.

This method takes precedence over the default lookup methods if enabled.

§buildid-linker-symbols

When enabled, depend on the buildid-linker-symbols crate to automatically create the symbols needed by buildid-symbol-start-end on gnu-like linkers.

§Platform Details

  • On unix variants other than those with apple as the vendor, the .note.gnu.build-id is used. Note that GNU LD and LLD generate different sized build-ids using different hash functions. Unless additional features are enabled, the .note.gnu.build-id is located via dl_iterate_phdr().
  • On Apple unix variants (MacOS), the LC_UUID (loader command uuid) is returned directly as a slice.
  • On windows, the module is parsed for a CodeView descriptor containing a GUID (which is returned directly as a slice). If mingw is used, the same info will appear in the .buildid section, but this lookup method is not used by this library.
  • On wasm, no data is provided

§Ensuring build-id is enabled

  • On windows when using mingw, build-id may not be enabled by default. To enable, set RUSTFLAGS=“-Clink-args=-Wl,–build-id” in the environment before running cargo. The same argument works for any system using GNU LD or compatible.

  • On most linux platforms, build-id is enabled by default by gcc. Sometimes clang on the same platform does not have build-id enabled though. Set RUSTFLAGS="-Clink-args=-Wl,--build-id" to ensure build id is enabled for clang or gcc

  • MacOS appears to enable build-id (LC_UUID) by default, with no change needed.

  • Windows MSVC appears to enable build-id (CodeView GUID) by default, with no change needed.

Functions§

  • If present, return the build-id or platform equivalent