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::needless_lifetimes)]
58#![allow(clippy::single_match)]
59#![allow(clippy::type_complexity)]
60// Occurs due to fallible iteration.
61#![allow(clippy::should_implement_trait)]
62// Unit errors are converted to other types by callers.
63#![allow(clippy::result_unit_err)]
64
65#[cfg(feature = "cargo-all")]
66compile_error!("'--all-features' is not supported; use '--features all' instead");
67
68#[cfg(any(feature = "read_core", feature = "write_core"))]
69#[allow(unused_imports)]
70#[macro_use]
71extern crate alloc;
72
73#[cfg(feature = "std")]
74#[allow(unused_imports)]
75#[macro_use]
76extern crate std;
77
78mod common;
79pub use common::*;
80
81#[macro_use]
82pub mod endian;
83pub use endian::*;
84
85#[macro_use]
86pub mod pod;
87pub use pod::*;
88
89#[cfg(feature = "read_core")]
90pub mod read;
91#[cfg(feature = "read_core")]
92pub use read::*;
93
94#[cfg(feature = "write_core")]
95pub mod write;
96
97#[cfg(feature = "build_core")]
98pub mod build;
99
100#[cfg(feature = "archive")]
101pub mod archive;
102#[cfg(feature = "elf")]
103pub mod elf;
104#[cfg(feature = "macho")]
105pub mod macho;
106#[cfg(any(feature = "coff", feature = "pe"))]
107pub mod pe;
108#[cfg(feature = "xcoff")]
109pub mod xcoff;