Skip to content

Commit d282bde

Browse files
emesareemesare
committed
Update readme and include that directly in the rustdocs
1 parent 556918b commit d282bde

File tree

4 files changed

+85
-134
lines changed

4 files changed

+85
-134
lines changed

‎rust/README.md‎

Lines changed: 83 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,82 @@
1-
# BinaryNinja-rs
1+
# binaryninja-rs
22

3-
<img align="right" src="assets/under_construction.png" width="175" height="175" alt="Construction">
3+
Official Rust bindings for [Binary Ninja].
44

5-
> :warning: **These bindings are in a very early beta, only have partial support for the core APIs and are still actively under development. Compatibility _will_ break and conventions _will_ change! They are being used for core Binary Ninja features however, so we expect much of what is already there to be reliable enough to build on, just don't be surprised if your plugins/scripts need to hit a moving target.**
5+
- [Getting Started](#getting-started)
6+
- [Examples](https://github.com/Vector35/binaryninja-api/tree/dev/rust/examples)
7+
- [Documentation](https://dev-rust.binary.ninja/)
68

7-
> :warning: This project requires Rust version `1.83.0`
9+
## WARNING
810

9-
## Documentation
11+
These bindings are still actively under development. Compatibility _will_ break and conventions _will_ change!
12+
It is encouraged that you reference a specific commit to avoid having your plugin/application break when the API changes.
13+
To specify a specific commit see the cargo documentation [here](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#choice-of-commit).
1014

11-
Documentation can be found at https://dev-rust.binary.ninja/
15+
**MSRV**: The Rust version specified in the `Cargo.toml`.
1216

13-
### Offline Documentation
17+
## Example
1418

15-
Offline documentation can be generated like any other rust crate, using `cargo doc`.
19+
```rust
20+
use binaryninja::headless::Session;
21+
use binaryninja::binaryview::{BinaryViewBase, BinaryViewExt};
1622

17-
```shell
18-
git clone https://github.com/Vector35/binaryninja-api
19-
cd rust && cargo doc --open
20-
```
23+
fn main() {
24+
let headless_session = Session::new().expect("Failed to initialize session");
25+
let bv = headless_session
26+
.load("/bin/cat")
27+
.expect("Couldn't open `/bin/cat`");
28+
29+
println!("Filename: `{}`", bv.file().filename());
30+
println!("File size: `{:#x}`", bv.len());
31+
println!("Function count: {}", bv.functions().len());
32+
33+
for func in &bv.functions() {
34+
println!("{}:", func.symbol().full_name());
35+
}
36+
}
2137

22-
## Contributing
38+
```
2339

24-
:warning: If you're thinking of contributing to the Rust API, we encourage you to join the #rust-api channel in our Slack: https://slack.binary.ninja, especially for large-effort PRs.
40+
## Getting Started
2541

26-
## Dependencies
42+
### Requirements
2743

2844
- Having BinaryNinja installed (and your license registered)
2945
- Clang
3046
- Rust
3147

32-
## How to use
48+
### To link to Binary Ninja
49+
50+
Writing a standalone executable _or_ a plugin requires that you link to `binaryninjacore` directly. The process of locating that however
51+
is done for you within the `binaryninjacore-sys` crate. Because linker arguments are _not_ transitive for executables you
52+
must specify them within your `build.rs`.
53+
54+
`Cargo.toml`:
55+
```toml
56+
[dependencies]
57+
binaryninja = { git = "https://github.com/Vector35/binaryninja-api.git", branch = "dev"}
58+
# Locates binaryninjacore on your system.
59+
binaryninjacore-sys = { git = "https://github.com/Vector35/binaryninja-api.git", branch = "dev"}
60+
```
61+
62+
`build.rs`:
63+
```rust
64+
fn main() {
65+
let link_path =
66+
std::env::var_os("DEP_BINARYNINJACORE_PATH").expect("DEP_BINARYNINJACORE_PATH not specified");
67+
68+
println!("cargo::rustc-link-lib=dylib=binaryninjacore");
69+
println!("cargo::rustc-link-search={}", link_path.to_str().unwrap());
70+
71+
#[cfg(not(target_os = "windows"))]
72+
{
73+
println!(
74+
"cargo::rustc-link-arg=-Wl,-rpath,{0},-L{0}",
75+
link_path.to_string_lossy()
76+
);
77+
}
78+
}
79+
```
3380

3481
### To write a plugin:
3582

@@ -39,9 +86,6 @@ Plugins are loaded at runtime and as such will have their own initialization rou
3986
```toml
4087
[lib]
4188
crate-type = ["cdylib"]
42-
43-
[dependencies]
44-
binaryninja = {git = "https://github.com/Vector35/binaryninja-api.git", branch = "dev"}
4589
```
4690

4791
`lib.rs`:
@@ -58,42 +102,33 @@ pub extern "C" fn CorePluginInit() -> bool {
58102

59103
### To write a standalone executable:
60104

61-
Writing a standalone executable requires that you link to `binaryninjacore` directly. The process of locating that however
62-
is done for you within the `binaryninjacore-sys` crate. Because linker arguments are _not_ transitive for executables you
63-
must specify them within your `build.rs`.
105+
If you have a headless supporting license you are able to use Binary Ninja as a regular dynamically loaded library.
64106

65-
`Cargo.toml`:
66-
```toml
67-
[dependencies]
68-
binaryninja = { git = "https://github.com/Vector35/binaryninja-api.git", branch = "dev"}
69-
# Locates binaryninjacore on your system.
70-
binaryninjacore-sys = { git = "https://github.com/Vector35/binaryninja-api.git", branch = "dev"}
71-
```
107+
Standalone executables must initialize the core themselves. `binaryninja::headless::init()` to initialize the core, and
108+
`binaryninja::headless::shutdown()` to shutdown the core. Prefer using `binaryninja::headless::Session` as it will
109+
shut down for you once it is dropped.
72110

73-
`build.rs`:
111+
`main.rs`:
74112
```rust
75113
fn main() {
76-
let link_path =
77-
std::env::var_os("DEP_BINARYNINJACORE_PATH").expect("DEP_BINARYNINJACORE_PATH specified");
78-
79-
println!("cargo::rustc-link-lib=dylib=binaryninjacore");
80-
println!("cargo::rustc-link-search={}", link_path.to_str().unwrap());
81-
82-
#[cfg(not(target_os = "windows"))]
83-
{
84-
println!(
85-
"cargo::rustc-link-arg=-Wl,-rpath,{0},-L{0}",
86-
link_path.to_string_lossy()
87-
);
88-
}
114+
// You must initialize the core to use Binary Ninja.
115+
let session = binaryninja::headless::Session::new().expect("Failed to initialize!");
116+
// Once `session` is dropped, the core will be shutdown!
89117
}
118+
```
119+
120+
## Offline Documentation
90121

122+
Offline documentation can be generated like any other rust crate, using `cargo doc`.
123+
124+
```shell
125+
git clone https://github.com/Vector35/binaryninja-api
126+
cd rust && cargo doc --open
91127
```
92128

93-
- All standalone binaries should call both `binaryninja::headless::init()` and `binaryninja::headless::shutdown()`.
94-
- Prefer using `binaryninja::headless::Session`, it will call shutdown for you.
95-
- All standalone binaries need to provide a `build.rs`.
96-
- Or otherwise provide binaryninjacore to the rpath.
129+
## Contributing
130+
131+
If you're thinking of contributing to the Rust API, we encourage you to join the #rust-api channel in our [Slack](https://slack.binary.ninja), especially for large-effort PRs.
97132

98133
---
99134

@@ -107,3 +142,4 @@ This project makes use of:
107142
[log license]: https://github.com/rust-lang/log/blob/master/LICENSE-MIT
108143
[rayon]: https://github.com/rayon-rs/rayon
109144
[rayon license]: https://github.com/rayon-rs/rayon/blob/master/LICENSE-MIT
145+
[Binary Ninja]: https://binary.ninja

‎rust/assets/under_construction.png‎

-98.8 KB
Binary file not shown.

‎rust/src/headless.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -246,7 +246,7 @@ impl Session {
246246
/// Before calling new you must make sure that the license is retrievable, otherwise the core won't be able to initialize.
247247
///
248248
/// If you cannot otherwise provide a license via `BN_LICENSE_FILE` environment variable or the Binary Ninja user directory
249-
/// you can call [`Session::new_with_license`] instead of this function.
249+
/// you can call [`Session::new_with_opts`] instead of this function.
250250
pub fn new() -> Result<Self, InitializationError> {
251251
if license_location().is_some() {
252252
// We were able to locate a license, continue with initialization.

‎rust/src/lib.rs‎

Lines changed: 1 addition & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -21,92 +21,7 @@
2121
#![doc(html_favicon_url = "/favicon.ico")]
2222
#![doc(html_logo_url = "/logo.png")]
2323
#![doc(issue_tracker_base_url = "https://github.com/Vector35/binaryninja-api/issues/")]
24-
25-
//! This crate is the official [Binary Ninja] API wrapper for Rust.
26-
//!
27-
//! [Binary Ninja] is an interactive disassembler, decompiler, and binary analysis platform for reverse engineers, malware analysts, vulnerability researchers, and software developers that runs on Windows, macOS, and Linux. Our extensive API can be used to create and customize loaders, add or augment architectures, customize the UI, or automate any workflow (types, patches, decompilation...anything!).
28-
//!
29-
//! If you're just getting started with [Binary Ninja], you may wish to check out the [Getting Started Guide]
30-
//!
31-
//! If you have questions, we'd love to answer them in [our public Slack], and if you find any issues, please [file an issue] or [submit a PR].
32-
//!
33-
//! ---
34-
//! # Warning
35-
//!
36-
//! <img align="right" src="../under_construction.png" width="175" height="175">
37-
//!
38-
//! > ⚠️ **These bindings are in a very early beta, only have partial support for the core APIs and are still actively under development. Compatibility _will_ break and conventions _will_ change! They are being used for core Binary Ninja features however, so we expect much of what is already there to be reliable enough to build on, just don't be surprised if your plugins/scripts need to hit a moving target.**
39-
//!
40-
//! > ⚠️ This project runs on Rust version `1.83.0`
41-
//!
42-
//! ---
43-
//!
44-
//! # Examples
45-
//!
46-
//! There are two distinct ways to use this crate:
47-
//! 1. [Writing a Plugin](#writing-a-plugin)
48-
//! 2. [Writing a Script](#writing-a-script)
49-
//!
50-
//! ## Writing a Plugin
51-
//!
52-
//! Create a new library (`cargo new --lib <plugin-name>`) and include the following in your `Cargo.toml`:
53-
//!
54-
//! ```toml
55-
//! [lib]
56-
//! crate-type = ["cdylib"]
57-
//!
58-
//! [dependencies]
59-
//! binaryninja = {git = "https://github.com/Vector35/binaryninja-api.git", branch = "dev"}
60-
//! ```
61-
//!
62-
//! In `lib.rs` you'll need to provide a `CorePluginInit` or `UIPluginInit` function for Binary Ninja to call.
63-
//!
64-
//! See [`command`] for the different actions you can provide and how to register your plugin with [Binary Ninja].
65-
//!
66-
//! ## Writing a Script:
67-
//!
68-
//! "Scripts" are binaries (`cargo new --bin <script-name>`), and have some specific requirements:
69-
//!
70-
//! ### build.rs
71-
//!
72-
//! Because [the only official method of providing linker arguments to a crate is through that crate's `build.rs`], all scripts need to provide their own `build.rs` so they can probably link with Binary Ninja.
73-
//!
74-
//! The most up-to-date version of the suggested [`build.rs` is here].
75-
//!
76-
//! ### `main.rs`
77-
//!
78-
//! Standalone binaries need to initialize Binary Ninja before they can work. You can do this through [`headless::Session`], or [`headless::init()`] at start and [`headless::shutdown()`] at shutdown.
79-
//!
80-
//! ```no_run
81-
//! // This loads all the core architecture, platform, etc plugins
82-
//! // Standalone executables need to call this, but plugins do not
83-
//! let headless_session = binaryninja::headless::Session::new().unwrap();
84-
//!
85-
//! println!("Loading binary...");
86-
//! let bv = headless_session
87-
//! .load("/bin/cat")
88-
//! .expect("Couldn't open `/bin/cat`");
89-
//!
90-
//! // Your code here...
91-
//! ```
92-
//!
93-
//! ### `Cargo.toml`
94-
//!
95-
//! ```toml
96-
//! [dependencies]
97-
//! binaryninja = { git = "https://github.com/Vector35/binaryninja-api.git", branch = "dev"}
98-
//! ```
99-
//!
100-
//! See the [examples] on GitHub for more comprehensive examples.
101-
//!
102-
//! [Binary Ninja]: https://binary.ninja/
103-
//! [Getting Started Guide]: https://docs.binary.ninja/
104-
//! [our public Slack]: https://join.slack.com/t/binaryninja/shared_invite/zt-3u4vu3ja-IGUF4ZWNlD7ER2ulvICvuQ
105-
//! [file an issue]: https://github.com/Vector35/binaryninja-api/issues
106-
//! [submit a PR]: https://github.com/Vector35/binaryninja-api/pulls
107-
//! [the only official method of providing linker arguments to a crate is through that crate's `build.rs`]: https://github.com/rust-lang/cargo/issues/9554
108-
//! [`build.rs` is here]: https://github.com/Vector35/binaryninja-api/blob/dev/rust/examples/template/build.rs
109-
//! [examples]: https://github.com/Vector35/binaryninja-api/tree/dev/rust/examples
24+
#![doc = include_str!("../README.md")]
11025

11126
#[doc(hidden)]
11227
pub extern crate binaryninjacore_sys;

0 commit comments

Comments
 (0)