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
50#[cfg(feature = "cargo-all")]
51compile_error!("'--all-features' is not supported; use '--features all' instead");
52
53#[cfg(any(feature = "read_core", feature = "write_core"))]
54#[allow(unused_imports)]
55#[macro_use]
56extern crate alloc;
57
58#[cfg(feature = "std")]
59#[allow(unused_imports)]
60#[macro_use]
61extern crate std;
62
63mod common;
64pub use common::*;
65
66#[macro_use]
67pub mod endian;
68pub use endian::*;
69
70#[macro_use]
71pub mod pod;
72pub use pod::*;
73
74#[cfg(feature = "read_core")]
75pub mod read;
76#[cfg(feature = "read_core")]
77pub use read::*;
78
79#[cfg(feature = "write_core")]
80pub mod write;
81
82#[cfg(feature = "build_core")]
83pub mod build;
84
85#[cfg(feature = "archive")]
86pub mod archive;
87#[cfg(feature = "elf")]
88pub mod elf;
89#[cfg(feature = "macho")]
90pub mod macho;
91#[cfg(any(feature = "coff", feature = "pe"))]
92pub mod pe;
93#[cfg(feature = "xcoff")]
94pub mod xcoff;