symbolic_ppdb/lib.rs
1//! Provides support for reading Portable PDB files,
2//! specifically line information resolution for functions.
3//!
4//! [Portable PDB](https://github.com/dotnet/runtime/blob/main/docs/design/specs/PortablePdb-Metadata.md)
5//! is a debugging information file format for Common Language Infrastructure (CLI) languages.
6//! It is an extension of the [ECMA-335 format](https://www.ecma-international.org/wp-content/uploads/ECMA-335_6th_edition_june_2012.pdf).
7//!
8//! # Functionality
9//!
10//! * Parse Portable PDB files with [`PortablePdb::parse`].
11//! * Convert Portable PDB files to [`PortablePdbCaches`](PortablePdbCache) with
12//! [`PortablePdbCacheConverter::process_portable_pdb`].
13//! * Serialize `PortablePdbCaches` with [`PortablePdbCacheConverter::serialize`]
14//! and parse them with [`PortablePdbCache::parse`].
15//! * Look up line information for a function on a `PortablePdbCache` with
16//! [`PortablePdbCache::lookup`].
17//!
18//! ## Example
19//! ```
20//! use symbolic_testutils::fixture;
21//! use symbolic_ppdb::{LineInfo, PortablePdb, PortablePdbCacheConverter, PortablePdbCache};
22//!
23//! let buf = std::fs::read(fixture("windows/portable.pdb")).unwrap();
24//! let pdb = PortablePdb::parse(&buf).unwrap();
25//!
26//! let mut converter = PortablePdbCacheConverter::new();
27//! converter.process_portable_pdb(&pdb).unwrap();
28//! let mut buf = Vec::new();
29//! converter.serialize(&mut buf).unwrap();
30//!
31//! let cache = PortablePdbCache::parse(&buf).unwrap();
32//! let line_info = cache.lookup(7, 10).unwrap();
33//! assert_eq!(line_info.line, 81);
34//! ```
35//!
36//! # Structure of a Portable PDB file
37//!
38//! An ECMA-335 file is divided into sections called _streams_. The possible streams are:
39//!
40//! * `#~` ("metadata"), comprising information about classes, methods, modules, &c.,
41//! organized into tables adhering to various schemas. The original ECMA-335 tables
42//! are described in Section II.22 of the ECMA-335 spec, the tables added by Portable PDB are described
43//! in the Portable PDB spec.
44//! The [`MethodDebugInformation`](https://github.com/dotnet/runtime/blob/main/docs/design/specs/PortablePdb-Metadata.md#methoddebuginformation-table-0x31)
45//! table is of particular interest to `symbolic`, as it contains
46//! line information for functions.
47//! * `#Strings`, comprising null-terminated UTF-8 strings.
48//! * `#GUID`, a list of GUIDs.
49//! * `#US` ("user strings"), comprising UTF-16 encoded strings.
50//! * `#Blob`, comprising blobs of data that don't fit in any of the other streams.
51//!
52//! The Portable PDB format extends ECMA-335 by the addition of another steam, `#PDB`, as well
53//! as several tables to the `#~` stream.
54
55#![warn(missing_docs)]
56
57mod cache;
58mod format;
59
60pub use cache::lookup::LineInfo;
61pub use cache::writer::PortablePdbCacheConverter;
62pub use cache::{CacheError, CacheErrorKind, PortablePdbCache};
63pub use format::{Document, EmbeddedSource, FormatError, FormatErrorKind, PortablePdb};