idax-sys 0.2.3

# idax-sys

[![Crates.io](https://img.shields.io/crates/v/idax-sys.svg)](https://crates.io/crates/idax-sys)
[![Documentation](https://docs.rs/idax-sys/badge.svg)](https://docs.rs/idax-sys)
[![License: MIT](https://img.shields.io/crates/l/idax-sys.svg)](LICENSE)

Raw `extern "C"` FFI bindings to the [idax](https://github.com/19h/idax) C++ IDA SDK wrapper library, generated by [bindgen](https://crates.io/crates/bindgen).

**You almost certainly want the [`idax`](https://crates.io/crates/idax) crate instead**, which provides safe, idiomatic Rust wrappers around everything exposed here.

## What this crate provides

- **622 FFI function declarations** covering 27 IDA SDK domains (database, segments, functions, instructions, types, decompiler, debugger, and more)
- **115 C struct/enum/callback typedefs** for data transfer across the FFI boundary
- A **C shim layer** (`shim/idax_shim.h` + `shim/idax_shim.cpp`) that bridges `extern "C"` to the idax C++ API
- Automatic **bindgen** code generation at build time — the output lands in `$OUT_DIR/bindings.rs`

## Prerequisites

Building this crate requires:

1. **IDA SDK** — set the `IDASDK` environment variable to the SDK root directory (must contain an `include/` subdirectory)
2. **Pre-built `libidax.a`** — build the [idax](https://github.com/19h/idax) C++ project with CMake first. The build script searches these directories:
   - `<idax-root>/build/`
   - `<idax-root>/build/Release/`
   - `<idax-root>/build/Debug/`
   - `<idax-root>/cmake-build-release/`
   - `<idax-root>/cmake-build-debug/`
3. **C++23 compiler** — the shim is compiled with `cc` using `-std=c++23`
4. **Rust 2024 edition** (nightly or stable 1.85+)

## Installation

```toml
[dependencies]
idax-sys = "0.2"
```

## Build environment

```sh
# Point to your IDA SDK
export IDASDK=/path/to/idasdk

# Build idax C++ library first (from the idax repo root)
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

# Now cargo build will find libidax.a and the SDK
cargo build
```

## FFI conventions

The C shim follows consistent conventions documented in `shim/idax_shim.h`:

| Pattern | Convention |
|---------|-----------|
| **Error signaling** | Functions returning `int`: `0` = success, negative = error |
| **Error details** | Thread-local state via `idax_last_error_category()` / `idax_last_error_code()` / `idax_last_error_message()` |
| **String outputs** | Returned via `char**` out-params, `malloc`'d — free with `idax_free_string()` |
| **Array outputs** | Returned via pointer+count out-params, `malloc`'d — free with `free()` or the appropriate `_free()` function |
| **Opaque handles** | `void*` (e.g. `IdaxTypeHandle`) — free with the corresponding `idax_type_free()` etc. |
| **Boolean queries** | Return `1` = true, `0` = false (never negative) |

## Covered domains

| Domain | C prefix | Functions |
|--------|----------|-----------|
| Error handling | `idax_last_error_*`, `idax_free_*` | 5 |
| Database | `idax_database_*` | 28 |
| Address | `idax_address_*` | 19 |
| Segment | `idax_segment_*` | 20 |
| Function | `idax_function_*` | 37 |
| Instruction | `idax_instruction_*` | 39 |
| Data | `idax_data_*` | 32 |
| Name | `idax_name_*` | 16 |
| Cross-references | `idax_xref_*` | 16 |
| Comment | `idax_comment_*` | 18 |
| Search | `idax_search_*` | 8 |
| Analysis | `idax_analysis_*` | 12 |
| Types | `idax_type_*` | 44 |
| Entry points | `idax_entry_*` | 8 |
| Fixups | `idax_fixup_*` | 12 |
| Events | `idax_event_*` | 10 |
| Plugin | `idax_plugin_*` | 12 |
| Loader | `idax_loader_*` | 12 |
| Debugger | `idax_debugger_*` | 67 |
| Decompiler | `idax_decompiler_*` | 32 |
| Storage | `idax_storage_*` | 14 |
| Lumina | `idax_lumina_*` | 2 |
| Graph | `idax_graph_*` | 10 |
| UI | `idax_ui_*` | 42 |
| Lines | `idax_lines_*` | 2 |
| Diagnostics | `idax_diagnostics_*` | 7 |

## Architecture

```
  idax-sys (this crate)
       |
       |-- build.rs
       |     |-- compiles shim/idax_shim.cpp via `cc`
       |     |-- runs bindgen on shim/idax_shim.h
       |     |-- links libidax.a + IDA SDK dylibs
       |
       |-- src/lib.rs
             |-- include!(concat!(env!("OUT_DIR"), "/bindings.rs"))
```

## Linking

The build script links:

- `libidax.a` (static) — the idax C++ wrapper
- `libida.dylib` / `libida.so` (dynamic) — the IDA SDK runtime
- The platform C++ standard library (`libc++` on macOS, `libstdc++` on Linux)

## Safety

Everything in this crate is `unsafe`. Use the [`idax`](https://crates.io/crates/idax) crate for safe wrappers.

## License

MIT