idalib

When calling FFI functions in methods that operate on an IDB (or derived types), you must bind the owning type to the lifetime of the IDB to ensure memory safety. This is typically achieved using PhantomData to carry the lifetime.

pub struct MyStruct<'a> {
    _marker: PhantomData<&'a IDB>,
}

Imports must be organized into three distinct groups separated by whitespace, in the following order:

1. Standard library imports (std)
2. External library imports
3. Same crate imports (crate)

Rules for imports:

• Do not nest modules in imports (e.g., avoid use module1::blah::{module2::bleep::Type}).
• Do not use single-line nested braces for multiple standard library imports (e.g., avoid use std::{collections::{HashMap, HashSet}, path::{Path, PathBuf}};).
• Use separate use statements for different paths within the same group.

// CORRECT
use std::collections::{HashMap, HashSet};
use std::path::{Path, PathBuf};

use serde::Serialize;
use tokio::fs;

use crate::models::DataModel;
use crate::utils::helper;

Use the following commands to enforce the project's style and linting requirements:

• Formatting: Use cargo fmt with specific configuration for import granularity and grouping.
• Linting: Use cargo clippy to find issues and cargo clippy --fix to resolve them automatically.
• Custom Lints: Use dylint with the project's specific pattern to run custom style checks.

# Format code
cargo fmt -- --config imports_granularity=Module,group_imports=StdExternalCrate

# Lint code
cargo clippy --no-deps
cargo clippy --fix

# Run custom lints
cargo dylint --git https://github.com/xorpse/rust-style --pattern '*'

# If dylint is not installed
cargo install cargo-dylint dylint-link

To use the specialized skills for contributing to idalib-rs projects within the Claude environment, install the idalib plugin and the idalib-rust-skills package using the following commands:

1. Add the idalib-rs/idalib plugin to the marketplace.
2. Install the idalib-rust-skills@idalib-rs package.

After installation, you can invoke the style guidelines by running /idalib-rust-style.

/plugin marketplace add idalib-rs/idalib
/plugin install idalib-rust-skills@idalib-rs
/idalib-rust-style

To expose new IDA SDK functionality that is not currently implemented in idalib:

1. Modify the idasdk-sys crate to include the new low-level bindings.
2. Add appropriate high-level Rust wrappers in the idalib crate.
3. Submit a pull request.

Note: Before starting development, you must ensure the IDA SDK submodule is checked out:

git submodule update --init --recursive

A minimal working project requires idalib as a dependency and idalib-build as a build dependency. You must use a build.rs file to configure linkage.

Cargo.toml

[dependencies]
idalib = "0.10"

[build-dependencies]
idalib-build = "0.10"

build.rs

fn main() -> Result<(), Box<dyn std::error::Error>> {
    idalib_build::configure_linkage()?;
    Ok(())
}

src/main.rs

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let idb = idalib::IDB::open("/path/to/binary")?;

    // ...

    Ok(())
}

The idalib plugin system follows a structured lifecycle managed by a bridge (via PlugmodWrapper).

1. Initialization (init): The plugin is instantiated. The init method is responsible for taking the initial IDA and IDB contexts and returning the plugin instance.
2. Execution (run): The run method is invoked with a usize argument. The bridge automatically handles retrieving the current IDB and creating a new IDA instance to pass to your plugin.
3. Termination (term): When the plugin is being unloaded or closed, term is called to allow for graceful cleanup.

If run or term returns an Err, the error is formatted and sent to the IDA message log using the internal msg function, prefixed with the plugin's name.

The decompiler API provides three primary abstractions for interacting with Hex-Rays decompilation data:

1. CFunction: Represents a decompiled function. It is the entry point for accessing the function's pseudocode or its structural body.
2. CBlock: Represents a basic block within a function's control flow graph.
3. CInsn: Represents an individual instruction within a CBlock.

Before performing any IDA operations, you must initialize the library. This must be called from the main thread. Calling it from any other thread will trigger an assertion failure. Initialization sets the TVHEADLESS environment variable to 1 internally.

use idalib::ida;

fn main() -> Result<(), idalib::IDAError> {
    ida::init_library()?;
    // ... perform IDA tasks
    Ok(())
}

When not running as an IDA plugin, you can use IDBOpenOptions to configure how a database is opened. This allows you to specify a custom IDB path, a specific file type, whether to save changes on close, and whether to enable automatic analysis.

Use the builder pattern to configure these options before calling .open(path).

use idalib::IDB;
use std::path::Path;

let mut options = IDBOpenOptions::new()
    .idb(Path::new("my_database.i64"))
    .file_type("i64")
    .save(true)
    .auto_analyse(true);

let idb = options.open(Path::new("input_file"))?;