Add include_idl readme

include-idl-cli/Cargo.toml

@@ -1,9 +1,11 @@
 [package]
-name = "include-idl-cli"
+name = "solana-include-idl-cli"
+description = "CLI to parse IDL files from a program binary"
 version = "0.1.0"
 edition = "2021"
+license-file = "Apache-2.0"
 
 [dependencies]
 clap = { version = "4.5.7", features = ["derive"] }
 goblin = { version = "0.8.2" }
-include-idl = { path = "../include-idl", features = ["parse"] }
+solana-include-idl = { version = "^0", features = ["parse"], path = "../include-idl" }

include-idl-cli/README.md

@@ -0,0 +1,13 @@
+# `solana-include-idl-cli`
+
+A simple CLI to read an IDL file stored on a Solana program binary.
+
+```console
+Usage: solana-include-idl-cli parse <PATH>
+
+Arguments:
+  <PATH>  Path to the program binary
+
+Options:
+  -h, --help  Print help
+```

include-idl-cli/src/main.rs

@@ -1,5 +1,5 @@
 use clap::{Error, Parser, Subcommand};
-use include_idl::parse::parse_idl_from_program_binary;
+use solana_include_idl::parse::parse_idl_from_program_binary;
 use std::path::PathBuf;
 
 #[derive(Parser)]
@@ -11,8 +11,9 @@ struct Cli {
 
 #[derive(Subcommand)]
 enum Commands {
+    /// Read IDL from a solana program binary.
     Parse {
-        /// Read IDL from a solana program binary
+        /// Path to the program binary.
         path: PathBuf,
     },
 }

include-idl/Cargo.toml

@@ -1,11 +1,13 @@
 [package]
-name = "include-idl"
+name = "solana-include-idl"
+description = "A collection of macro and helpers to manage IDL stored on the program binary"
 version = "0.1.0"
 edition = "2021"
+license-file = "Apache-2.0"
 
 [features]
-shrink = ["flate2"]
-parse = ["flate2", "goblin", "serde_json"]
+shrink = ["dep:flate2"]
+parse = ["dep:flate2", "dep:goblin", "dep:serde_json"]
 
 [dependencies]
 flate2 = { version = "1.0", optional = true }

include-idl/README.md

@@ -0,0 +1,47 @@
+# `solana-include-idl`
+
+A collection of macro and helpers to manage IDLs stored on the program binary.
+
+IDL files describe the structure and API of a Solana program, facilitating easier integration and interaction with various client applications. This crate automates the task of publishing the IDL file by storing it as a separate ELF section within the program binary.
+
+## Usage
+
+The crate provides a macro that includes the type and contents of the IDL file in separate ELF sections on the program binary.
+
+* `.idl.type` contains the type of the IDL file.
+* `.idl.data` contains the IDL file itself.
+
+The macro takes two arguments:
+
+* `type`: The type of the IDL file. This should be one of the variants of the `IdlType` enum (e.g., `IdlType::Anchor` or `IdlType::Codama`).
+* `file`: The path to the IDL file.
+
+```rust
+use include_idl::{include_idl, parse::IdlType};
+
+include_idl!(IdlType::Codama, concat!(env!("OUT_DIR"), "/codama.idl.zip"));
+```
+
+In general, the macro is used in combination with a `build.rs` build script to compress the IDL file, reducing the space required on the program binary.
+
+To specify a build script, add a `build = "build.rs"` entry to your `Cargo.toml` file under the `[package]` section. Below is a `build.rs` example file that compresses an existing IDL file.
+
+```rust
+use std::env;
+use std::path::PathBuf;
+use include_idl::compress_idl;
+
+fn main() {
+    // Get the IDL path.
+    let idl_path = PathBuf::from("../api").join("idl.json");
+    // Compress the IDL file to a zip file.
+    let out_dir = env::var("OUT_DIR").unwrap();
+    let dest_path = PathBuf::from(out_dir).join("codama.idl.zip");
+
+    compress_idl(&idl_path, &dest_path);
+}
+```
+
+### Generating an IDL
+
+If you are using [Anchor](https://www.anchor-lang.com), this step is alredy done for your. If you are writing a native Solana program or using a framework that does not export and IDL, you can use [Codama](https://github.com/codama-idl/codama?tab=readme-ov-file#from-program-to-codama).

include-idl/src/lib.rs

@@ -21,14 +21,16 @@ pub use shrink::compress_idl;
 ///
 /// This macro takes two arguments:
 ///
-/// - `type`: The type of the IDL file. This should be one of the variants of the [`IdlType``] enum.
+/// - `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
+/// use include_idl::{include_idl, parse::IdlType};
+///
 /// include_idl!(IdlType::Codama, concat!(env!("OUT_DIR"), "/codama.idl.zip"));
 /// ```
 #[macro_export]

programs/asset/program/Cargo.toml

@@ -25,7 +25,7 @@ num-traits = "^0.2"
 solana-security-txt = "1.1.1"
 solana-program = "~1.16"
 thiserror = "^1.0"
-include-idl = { path = "../../../include-idl" }
+solana-include-idl = { path = "../../../include-idl" }
 
 [build-dependencies]
-include-idl = { path = "../../../include-idl", features = ["shrink"] }
+solana-include-idl = { path = "../../../include-idl", features = ["shrink"] }

programs/asset/program/build.rs

@@ -2,7 +2,7 @@ use std::env;
 use std::path::PathBuf;
 use std::process::Command;
 
-use include_idl::compress_idl;
+use solana_include_idl::compress_idl;
 
 fn main() {
     // Run shank to generate the IDL

programs/asset/program/src/lib.rs

@@ -12,7 +12,7 @@ pub mod instruction;
 pub mod processor;
 pub mod utils;
 
-use include_idl::{include_idl, parse::IdlType};
+use solana_include_idl::{include_idl, parse::IdlType};
 pub use solana_program;
 use solana_security_txt::security_txt;