| 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" )] |
|---|
| 66 | compile_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 ] |
|---|
| 71 | extern crate alloc; |
|---|
| 72 | |
|---|
| 73 | #[cfg (feature = "std" )] |
|---|
| 74 | #[allow (unused_imports)] |
|---|
| 75 | #[macro_use ] |
|---|
| 76 | extern crate std; |
|---|
| 77 | |
|---|
| 78 | mod common; |
|---|
| 79 | pub use common::*; |
|---|
| 80 | |
|---|
| 81 | #[macro_use ] |
|---|
| 82 | pub mod endian; |
|---|
| 83 | pub use endian::*; |
|---|
| 84 | |
|---|
| 85 | #[macro_use ] |
|---|
| 86 | pub mod pod; |
|---|
| 87 | pub use pod::*; |
|---|
| 88 | |
|---|
| 89 | #[cfg (feature = "read_core" )] |
|---|
| 90 | pub mod read; |
|---|
| 91 | #[cfg (feature = "read_core" )] |
|---|
| 92 | pub use read::*; |
|---|
| 93 | |
|---|
| 94 | #[cfg (feature = "write_core" )] |
|---|
| 95 | pub mod write; |
|---|
| 96 | |
|---|
| 97 | #[cfg (feature = "build_core" )] |
|---|
| 98 | pub mod build; |
|---|
| 99 | |
|---|
| 100 | #[cfg (feature = "archive" )] |
|---|
| 101 | pub mod archive; |
|---|
| 102 | #[cfg (feature = "elf" )] |
|---|
| 103 | pub mod elf; |
|---|
| 104 | #[cfg (feature = "macho" )] |
|---|
| 105 | pub mod macho; |
|---|
| 106 | #[cfg (any(feature = "coff" , feature = "pe" ))] |
|---|
| 107 | pub mod pe; |
|---|
| 108 | #[cfg (feature = "xcoff" )] |
|---|
| 109 | pub mod xcoff; |
|---|
| 110 | |
|---|
