vendor/object/src/lib.rs

   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 and some executable 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 a COFF/ELF/Mach-O object and then writing it out.
  28 //!
  29 //! ## Low level executable writers
  30 //!
  31 //! [write::elf::Writer] and [write::pe::Writer] allow writing executable files.
  32 //!
  33 //! ## Example for unified read API
  34 //!  ```no_run
  35 //! # #[cfg(feature = "read")]
  36 //! use object::{Object, ObjectSection};
  37 //! use std::error::Error;
  38 //! use std::fs;
  39 //!
  40 //! /// Reads a file and displays the content of the ".boot" section.
  41 //! fn main() -> Result<(), Box<dyn Error>> {
  42 //! # #[cfg(all(feature = "read", feature = "std"))] {
  43 //!   let bin_data = fs::read("./multiboot2-binary.elf")?;
  44 //!   let obj_file = object::File::parse(&*bin_data)?;
  45 //!   if let Some(section) = obj_file.section_by_name(".boot") {
  46 //!     println!("{:#x?}", section.data()?);
  47 //!   } else {
  48 //!     eprintln!("section not available");
  49 //!   }
  50 //! # }
  51 //!   Ok(())
  52 //! }
  53 //! ```
  54
  55 #![deny(missing_docs)]
  56 #![deny(missing_debug_implementations)]
  57 #![no_std]
  58 // Style.
  59 #![allow(clippy::collapsible_if)]
  60 #![allow(clippy::comparison_chain)]
  61 #![allow(clippy::match_like_matches_macro)]
  62 #![allow(clippy::single_match)]
  63 #![allow(clippy::type_complexity)]
  64 // Occurs due to fallible iteration.
  65 #![allow(clippy::should_implement_trait)]
  66 // Unit errors are converted to other types by callers.
  67 #![allow(clippy::result_unit_err)]
  68 // Clippy is wrong.
  69 #![allow(clippy::transmute_ptr_to_ptr)]
  70 // Worse readability sometimes.
  71 #![allow(clippy::collapsible_else_if)]
  72
  73 #[cfg(feature = "cargo-all")]
  74 compile_error!("'--all-features' is not supported; use '--features all' instead");
  75
  76 #[cfg(any(feature = "read_core", feature = "write_core"))]
  77 #[allow(unused_imports)]
  78 #[macro_use]
  79 extern crate alloc;
  80
  81 #[cfg(feature = "std")]
  82 #[allow(unused_imports)]
  83 #[macro_use]
  84 extern crate std;
  85
  86 mod common;
  87 pub use common::*;
  88
  89 #[macro_use]
  90 pub mod endian;
  91 pub use endian::*;
  92
  93 #[macro_use]
  94 pub mod pod;
  95 pub use pod::*;
  96
  97 #[cfg(feature = "read_core")]
  98 pub mod read;
  99 #[cfg(feature = "read_core")]
 100 pub use read::*;
 101
 102 #[cfg(feature = "write_core")]
 103 pub mod write;
 104
 105 #[cfg(feature = "archive")]
 106 pub mod archive;
 107 #[cfg(feature = "elf")]
 108 pub mod elf;
 109 #[cfg(feature = "macho")]
 110 pub mod macho;
 111 #[cfg(any(feature = "coff", feature = "pe"))]
 112 pub mod pe;