object/lib.rs
1//! # `object`
2//!
3//! The `object` crate provides a unified interface to working with object files
4//! across platforms. It supports reading relocatable object files and executable files,
5//! and writing relocatable object files and some executable files.
6//!
7//! ## Raw struct definitions
8//!
9//! Raw structs are defined for: [ELF](elf), [Mach-O](macho), [PE/COFF](pe),
10//! [XCOFF](xcoff), [archive].
11//! Types and traits for zerocopy support are defined in the [`pod`] and [`endian`] modules.
12//!
13//! ## Unified read API
14//!
15//! The [`read`] module provides a unified read API using the [`read::Object`] trait.
16//! There is an implementation of this trait for [`read::File`], which allows reading any
17//! file format, as well as implementations for each file format.
18//!
19//! ## Low level read API
20//!
21//! The [`read#modules`] submodules define helpers that operate on the raw structs.
22//! These can be used instead of the unified API, or in conjunction with it to access
23//! details that are not available via the unified API.
24//!
25//! ## Unified write API
26//!
27//! The [`mod@write`] module provides a unified write API for relocatable object files
28//! using [`write::Object`]. This does not support writing executable files.
29//!
30//! ## Low level write API
31//!
32//! The [`mod@write#modules`] submodules define helpers for writing the raw structs.
33//!
34//! ## Build API
35//!
36//! The [`mod@build`] submodules define helpers for building object files, either from
37//! scratch or by modifying existing files.
38//!
39//! ## Shared definitions
40//!
41//! The crate provides a number of definitions that are used by both the read and write
42//! APIs. These are defined at the top level module, but none of these are the main entry
43//! points of the crate.
44
45#![deny(missing_docs)]
46#![deny(missing_debug_implementations)]
47#![no_std]
48#![warn(rust_2018_idioms)]
49// Style.
50#![allow(clippy::collapsible_else_if)]
51#![allow(clippy::collapsible_if)]
52#![allow(clippy::collapsible_match)]
53#![allow(clippy::comparison_chain)]
54#![allow(clippy::field_reassign_with_default)]
55#![allow(clippy::manual_flatten)]
56#![allow(clippy::match_like_matches_macro)]
57#![allow(clippy::single_match)]
58#![allow(clippy::type_complexity)]
59// Occurs due to fallible iteration.
60#![allow(clippy::should_implement_trait)]
61// Unit errors are converted to other types by callers.
62#![allow(clippy::result_unit_err)]
63
64#[cfg(feature = "cargo-all")]
65compile_error!("'--all-features' is not supported; use '--features all' instead");
66
67#[cfg(any(feature = "read_core", feature = "write_core"))]
68#[allow(unused_imports)]
69#[macro_use]
70extern crate alloc;
71
72#[cfg(feature = "std")]
73#[allow(unused_imports)]
74#[macro_use]
75extern crate std;
76
77mod common;
78pub use common::*;
79
80#[macro_use]
81pub mod endian;
82pub use endian::*;
83
84#[macro_use]
85pub mod pod;
86pub use pod::*;
87
88#[cfg(feature = "read_core")]
89pub mod read;
90#[cfg(feature = "read_core")]
91pub use read::*;
92
93#[cfg(feature = "write_core")]
94pub mod write;
95
96#[cfg(feature = "build_core")]
97pub mod build;
98
99#[cfg(feature = "archive")]
100pub mod archive;
101#[cfg(feature = "elf")]
102pub mod elf;
103#[cfg(feature = "macho")]
104pub mod macho;
105#[cfg(any(feature = "coff", feature = "pe"))]
106pub mod pe;
107#[cfg(feature = "xcoff")]
108pub mod xcoff;