From dccaaad3be97b9141e09972beb477b9464245ec1 Mon Sep 17 00:00:00 2001 From: febo Date: Fri, 1 Nov 2024 16:32:05 +0000 Subject: [PATCH] Add commemts --- include-idl-cli/src/main.rs | 7 ++----- include-idl/Cargo.toml | 2 -- include-idl/src/lib.rs | 25 +++++++++++++++++++++++++ include-idl/src/parse.rs | 5 +++++ include-idl/src/shrink.rs | 13 +++++-------- 5 files changed, 37 insertions(+), 15 deletions(-) diff --git a/include-idl-cli/src/main.rs b/include-idl-cli/src/main.rs index 891824e..f6cb75b 100644 --- a/include-idl-cli/src/main.rs +++ b/include-idl-cli/src/main.rs @@ -1,9 +1,6 @@ -use std::path::PathBuf; - -// use goblin::error::Result; -use include_idl::parse::parse_idl_from_program_binary; - use clap::{Error, Parser, Subcommand}; +use include_idl::parse::parse_idl_from_program_binary; +use std::path::PathBuf; #[derive(Parser)] #[command(version, about, long_about = None)] diff --git a/include-idl/Cargo.toml b/include-idl/Cargo.toml index 4e60941..8b10438 100644 --- a/include-idl/Cargo.toml +++ b/include-idl/Cargo.toml @@ -3,8 +3,6 @@ name = "include-idl" version = "0.1.0" edition = "2021" -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html - [features] shrink = ["flate2"] parse = ["flate2", "goblin", "serde_json"] diff --git a/include-idl/src/lib.rs b/include-idl/src/lib.rs index 62ad235..8a07ca0 100644 --- a/include-idl/src/lib.rs +++ b/include-idl/src/lib.rs @@ -1,3 +1,5 @@ +//! This crate provides a way to include IDL files in a program binary. + pub mod parse; #[cfg(feature = "shrink")] @@ -6,6 +8,29 @@ mod shrink; #[cfg(feature = "shrink")] pub use shrink::compress_idl; +/// Include an IDL file in the program binary. +/// +/// This macro creates two ELF sections in the program binary: +/// - `.idl.type` contains the type of the IDL file. +/// - `.idl.data` contains the IDL file itself. +/// +/// In general you should use this macro in conbination with a `build.rs` build script +/// that compresses the IDL file to reduce the final size of the program binary. +/// +/// # Arguments +/// +/// This macro takes two arguments: +/// +/// - `type`: The type of the IDL file. This should be one of the variants of the [`IdlType``] enum. +/// - `file`: The path to the IDL file. +/// +/// # Example +/// +/// Include the following in your `lib.rs` file: +/// +/// ```ignore +/// include_idl!(IdlType::Codama, concat!(env!("OUT_DIR"), "/codama.idl.zip")); +/// ``` #[macro_export] macro_rules! include_idl { ($type:path, $file:expr) => { diff --git a/include-idl/src/parse.rs b/include-idl/src/parse.rs index e6b572c..3c5889d 100644 --- a/include-idl/src/parse.rs +++ b/include-idl/src/parse.rs @@ -13,7 +13,10 @@ pub const IDL_TYPE_SECTION: &str = ".idl.type"; /// Name of the section containing the IDL data. pub const IDL_DATA_SECTION: &str = ".idl.data"; +/// `str` representation of the Anchor IDL type. const ANCHOR_IDL_TYPE: &str = "anchor"; + +/// `str` representation of the Codama IDL type. const CODAMA_IDL_TYPE: &str = "codama"; /// Defines the IDL type. @@ -53,6 +56,7 @@ impl std::str::FromStr for IdlType { } } +/// Parses the IDL data from the program binary. #[cfg(feature = "parse")] pub fn parse_idl_from_program_binary(buffer: &[u8]) -> goblin::error::Result<(IdlType, Value)> { let elf = Elf::parse(buffer)?; @@ -97,6 +101,7 @@ pub fn parse_idl_from_program_binary(buffer: &[u8]) -> goblin::error::Result<(Id } } +/// Retrieves the location and size of an ELF section data. #[cfg(feature = "parse")] #[inline(always)] fn get_section_data_offset(buffer: &[u8], offset: usize) -> (usize, usize) { diff --git a/include-idl/src/shrink.rs b/include-idl/src/shrink.rs index 4472314..8bf74bc 100644 --- a/include-idl/src/shrink.rs +++ b/include-idl/src/shrink.rs @@ -1,14 +1,11 @@ -#[cfg(feature = "shrink")] +use flate2::{write::ZlibEncoder, Compression}; use std::{ fs::File, io::{Read, Write}, path::PathBuf, }; -#[cfg(feature = "shrink")] -use flate2::{write::ZlibEncoder, Compression}; - -#[cfg(feature = "shrink")] +/// Compresses the IDL JSON file using zlib and writes the compressed data to a file. pub fn compress_idl(idl_path: &PathBuf, dest_path: &PathBuf) { let mut idl_json = File::open(idl_path).unwrap(); let mut json_contents = String::new(); @@ -16,15 +13,15 @@ pub fn compress_idl(idl_path: &PathBuf, dest_path: &PathBuf) { .read_to_string(&mut json_contents) .expect("Failed to read JSON file"); - // Compress the JSON contents using zlib + // Compress the JSON contents using zlib. let mut encoder = ZlibEncoder::new(Vec::new(), Compression::default()); encoder .write_all(json_contents.as_bytes()) .expect("Failed to compress JSON data"); let compressed_data = encoder.finish().expect("Failed to finish compression"); - // Get the output directory for the build script - // Write the compressed data to a file in the output directory + // Get the output directory for the build script and write the compressed + // data to a file in the output directory. let mut output_file = File::create(dest_path).expect("Failed to create output file"); output_file .write_all(&compressed_data)