1 //! # `object`
2 //!
3 //! The `object` crate provides a unified interface to working with object files
4 //! across platforms. It supports reading object files and executable files,
5 //! and writing object files.
6 //!
7 //! ## Raw struct definitions
8 //!
9 //! Raw structs are defined for: [ELF](elf), [Mach-O](macho), [PE/COFF](pe), [archive].
10 //! Types and traits for zerocopy support are defined in [pod] and [endian].
11 //!
12 //! ## Unified read API
13 //!
14 //! The [read::Object] trait defines the unified interace. This trait is implemented
15 //! by [read::File], which allows reading any file format, as well as implementations
16 //! for each file format: [ELF](read::elf::ElfFile), [Mach-O](read::macho::MachOFile),
17 //! [COFF](read::coff::CoffFile), [PE](read::pe::PeFile), [Wasm](read::wasm::WasmFile).
18 //!
19 //! ## Low level read API
20 //!
21 //! In addition to the unified read API, the various `read` modules define helpers that
22 //! operate on the raw structs. These also provide traits that abstract over the differences
23 //! between 32-bit and 64-bit versions of the file format.
24 //!
25 //! ## Unified write API
26 //!
27 //! [write::Object] allows building an object and then writing it out.
28 //!
29 //! ## Example for unified read API
30 //!  ```no_run
31 //! use object::{Object, ObjectSection};
32 //! use std::error::Error;
33 //! use std::fs;
34 //!
35 //! /// Reads a file and displays the content of the ".boot" section.
36 //! fn main() -> Result<(), Box<dyn Error>> {
37 //!   let bin_data = fs::read("./multiboot2-binary.elf")?;
38 //!   let obj_file = object::File::parse(&*bin_data)?;
39 //!   if let Some(section) = obj_file.section_by_name(".boot") {
40 //!     println!("{:#x?}", section.data()?);
41 //!   } else {
42 //!     eprintln!("section not available");
43 //!   }
44 //!   Ok(())
45 //! }
46 //! ```
47 
48 #![deny(missing_docs)]
49 #![deny(missing_debug_implementations)]
50 #![no_std]
51 // Style.
52 #![allow(clippy::collapsible_if)]
53 #![allow(clippy::comparison_chain)]
54 #![allow(clippy::match_like_matches_macro)]
55 #![allow(clippy::single_match)]
56 #![allow(clippy::type_complexity)]
57 // Occurs due to fallible iteration.
58 #![allow(clippy::should_implement_trait)]
59 // Unit errors are converted to other types by callers.
60 #![allow(clippy::result_unit_err)]
61 // Clippy is wrong.
62 #![allow(clippy::transmute_ptr_to_ptr)]
63 
64 #[cfg(feature = "cargo-all")]
65 compile_error!("'--all-features' is not supported; use '--features all' instead");
66 
67 #[cfg(feature = "read_core")]
68 #[allow(unused_imports)]
69 #[macro_use]
70 extern crate alloc;
71 
72 #[cfg(feature = "std")]
73 #[allow(unused_imports)]
74 #[macro_use]
75 extern crate std;
76 
77 mod common;
78 pub use common::*;
79 
80 #[macro_use]
81 pub mod endian;
82 pub use endian::*;
83 
84 #[macro_use]
85 pub mod pod;
86 pub use pod::*;
87 
88 #[cfg(feature = "read_core")]
89 pub mod read;
90 #[cfg(feature = "read_core")]
91 pub use read::*;
92 
93 #[cfg(feature = "write_core")]
94 pub mod write;
95 
96 #[cfg(feature = "archive")]
97 pub mod archive;
98 #[cfg(feature = "elf")]
99 pub mod elf;
100 #[cfg(feature = "macho")]
101 pub mod macho;
102 #[cfg(any(feature = "coff", feature = "pe"))]
103 pub mod pe;
104