Struct GsymBuilder 

pub struct GsymBuilder { /* private fields */ }

Version-independent, deterministic GSYM construction API.

Add FileEntry values and Function records, then encode with Self::to_bytes or Self::write_to. The same inputs and options always produce the same bytes, so output can be compared or content-addressed.

Two things to know while building:

• Self::add_file interns entries. Adding the same directory and basename twice returns the same FileIndex, and index zero is permanently the empty entry.
• Self::add_function validates as it goes and rejects an empty name, a reversed range, or a line row outside the function. Cross-record checks that need the whole model, such as file references, run at encode time.

Functions may be added in any order. Setters take and return self, so they chain, while add_file and add_function take &mut self.

Example

use gsym::{AddressRange, Function, Gsym, GsymBuilder};

let mut builder = GsymBuilder::new().base_address(0x1000);
builder.add_function(Function::new(
    AddressRange::new(0x1010, 0x1020),
    b"example",
))?;

let bytes = builder.to_bytes()?;
let gsym = Gsym::parse(bytes)?;
assert_eq!(gsym.lookup(0x1014)?.unwrap().frames()[0].name, b"example");

Implementations

impl GsymBuilder

pub fn new() -> Self

Creates an empty builder using default options.

pub fn with_options(options: BuilderOptions) -> Self

Creates an empty builder using options.

pub const fn options(&self) -> &BuilderOptions

Returns the active builder options.

pub const fn version(self, version: GsymVersion) -> Self

Selects the output GSYM version.

Defaults to GsymVersion::V1, which current tooling reads. Selecting GsymVersion::V2 lifts v1’s 4 GiB offset limits and 20-byte build-ID limit but needs LLVM 23 or newer on the reading side. Encoding reports v1 limit errors and does not change versions automatically.

pub const fn endian(self, endian: Endian) -> Self

Selects the output byte order.

pub const fn base_address(self, address: u64) -> Self

Sets the image base address.

Leave it unset to use the lowest function address, which is what a standalone file wants. Set it to the base address of the image the data came from, so lookups can use that image’s virtual addresses.

pub fn build_id(self, build_id: impl Into<Vec<u8>>) -> Self

Sets the opaque build identifier stored in the GSYM header.

pub const fn repair_zero_sized_functions(self, enabled: bool) -> Self

Enables or disables final zero-sized-function repair.

pub const fn function_set(self, policy: FunctionSetPolicy) -> Self

Selects how functions sharing an address range are finalized.

pub const fn merge_equal_address_functions(self, enabled: bool) -> Self

Enables or disables merged records for equal-address functions.

pub const fn function_set_policy(&self) -> FunctionSetPolicy

Returns how equal-range functions will be finalized.

pub fn executable_ranges( self, ranges: impl IntoIterator<Item = AddressRange>, ) -> Self

Replaces the executable ranges used for liveness and size repair.

pub fn add_file(&mut self, file: FileEntry) -> Result<FileIndex>

Intern a source file and return its stable one-based index. Index zero is permanently reserved for the empty file.

Repeated calls with an equal entry return the same index without adding a row, so callers can intern per line row instead of maintaining their own map.

Errors

Returns an error if the table exceeds the GSYM u32 index space.

use gsym::{FileEntry, GsymBuilder};

let mut builder = GsymBuilder::new();
let first = builder.add_file(FileEntry::new(b"/src", b"main.rs"))?;
let again = builder.add_file(FileEntry::new(b"/src", b"main.rs"))?;
assert_eq!(first, again);
assert_eq!(builder.files().len(), 2); // reserved entry plus main.rs

pub fn add_function(&mut self, function: Function) -> Result<()>

Adds a validated function record.

Insertion order does not matter. Line rows must already be sorted within the function, and inline ranges must nest inside their parent.

Errors

Returns an error for an empty name, invalid range, oversized function, or line outside the function range.

pub fn files(&self) -> &[FileEntry]

Returns the interned file table, including reserved index zero.

pub fn functions(&self) -> &[Function]

Returns functions in insertion order before writer finalization.

pub fn write_to(self, output: impl Write) -> Result<()>

Encodes this builder into output.

Errors

Returns an error when the model cannot be represented by the selected GSYM version or when writing fails.

pub fn to_bytes(self) -> Result<Vec<u8>>

Encodes this builder into a byte vector.

Errors

Returns an error when the model cannot be represented by the selected GSYM version.

Trait Implementations

impl Debug for GsymBuilder

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GsymBuilder

fn default() -> Self

Returns the “default value” for a type.