diff --git a/README.md b/README.md index 2e97be32..943d421f 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ FreeBSD [![Cirrus CI Badge](https://api.cirrus-ci.com/github/capstone-rust/capst Bindings to the [capstone library][upstream] disassembly framework. +The `Capstone` struct is the main interface to the library. # Requirements @@ -27,7 +28,6 @@ See the [`capstone-sys`](capstone-sys) page for the requirements and supported p # Example - ```rust extern crate capstone; @@ -86,11 +86,10 @@ fn main() { } } ``` - Produces: -``` +```plain Found 4 instructions 0x1000: pushq %rbp diff --git a/capstone-rs/Cargo.toml b/capstone-rs/Cargo.toml index 1575fb38..ba17d7ff 100644 --- a/capstone-rs/Cargo.toml +++ b/capstone-rs/Cargo.toml @@ -7,7 +7,7 @@ keywords = ["disassemble"] license = "MIT" name = "capstone" repository = "https://github.com/capstone-rust/capstone-rs" -readme = "README.md" +readme = "../README.md" edition = "2018" version = "0.11.0" diff --git a/capstone-rs/src/lib.rs b/capstone-rs/src/lib.rs index 43d18a42..1e66178b 100644 --- a/capstone-rs/src/lib.rs +++ b/capstone-rs/src/lib.rs @@ -1,118 +1,4 @@ -//! Bindings to the [capstone library][upstream] disassembly framework. -//! -//! This crate is a wrapper around the -//! [Capstone disassembly library](http://www.capstone-engine.org/), -//! a "lightweight multi-platform, multi-architecture disassembly framework." -//! -//! The [`Capstone`](struct.Capstone.html) struct is the main interface to the library. -//! -//! ```rust -//! extern crate capstone; -//! -//! use capstone::prelude::*; -//! -//! const X86_CODE: &'static [u8] = b"\x55\x48\x8b\x05\xb8\x13\x00\x00\xe9\x14\x9e\x08\x00\x45\x31\xe4"; -//! -//! /// Print register names -//! fn reg_names(cs: &Capstone, regs: &[RegId]) -> String { -//! let names: Vec = regs.iter().map(|&x| cs.reg_name(x).unwrap()).collect(); -//! names.join(", ") -//! } -//! -//! /// Print instruction group names -//! fn group_names(cs: &Capstone, regs: &[InsnGroupId]) -> String { -//! let names: Vec = regs.iter().map(|&x| cs.group_name(x).unwrap()).collect(); -//! names.join(", ") -//! } -//! -//! fn main() { -//! let cs = Capstone::new() -//! .x86() -//! .mode(arch::x86::ArchMode::Mode64) -//! .syntax(arch::x86::ArchSyntax::Att) -//! .detail(true) -//! .build() -//! .expect("Failed to create Capstone object"); -//! -//! let insns = cs.disasm_all(X86_CODE, 0x1000) -//! .expect("Failed to disassemble"); -//! println!("Found {} instructions", insns.len()); -//! for i in insns.as_ref() { -//! println!(); -//! println!("{}", i); -//! -//! let detail: InsnDetail = cs.insn_detail(&i).expect("Failed to get insn detail"); -//! let arch_detail: ArchDetail = detail.arch_detail(); -//! let ops = arch_detail.operands(); -//! -//! let output: &[(&str, String)] = &[ -//! ("insn id:", format!("{:?}", i.id().0)), -//! ("bytes:", format!("{:?}", i.bytes())), -//! ("read regs:", reg_names(&cs, detail.regs_read())), -//! ("write regs:", reg_names(&cs, detail.regs_write())), -//! ("insn groups:", group_names(&cs, detail.groups())), -//! ]; -//! -//! for &(ref name, ref message) in output.iter() { -//! println!("{:4}{:12} {}", "", name, message); -//! } -//! -//! println!("{:4}operands: {}", "", ops.len()); -//! for op in ops { -//! println!("{:8}{:?}", "", op); -//! } -//! } -//! } -//! ``` -//! -//! Produces: -//! -//! ```txt -//! Found 4 instructions -//! -//! 0x1000: pushq %rbp -//! insn id: 580 -//! bytes: [85] -//! read regs: rsp -//! write regs: rsp -//! insn groups: mode64 -//! operands: 1 -//! X86Operand(X86Operand { size: 8, avx_bcast: X86_AVX_BCAST_INVALID, avx_zero_opmask: false, op_type: Reg(RegId(36)) }) -//! -//! 0x1001: movq 0x13b8(%rip), %rax -//! insn id: 442 -//! bytes: [72, 139, 5, 184, 19, 0, 0] -//! read regs: -//! write regs: -//! insn groups: -//! operands: 2 -//! X86Operand(X86Operand { size: 8, avx_bcast: X86_AVX_BCAST_INVALID, avx_zero_opmask: false, op_type: Mem(X86OpMem(x86_op_mem { segment: 0, base: 41, index: 0, scale: 1, disp: 5048 })) }) -//! X86Operand(X86Operand { size: 8, avx_bcast: X86_AVX_BCAST_INVALID, avx_zero_opmask: false, op_type: Reg(RegId(35)) }) -//! -//! 0x1008: jmp 0x8ae21 -//! insn id: 266 -//! bytes: [233, 20, 158, 8, 0] -//! read regs: -//! write regs: -//! insn groups: jump -//! operands: 1 -//! X86Operand(X86Operand { size: 8, avx_bcast: X86_AVX_BCAST_INVALID, avx_zero_opmask: false, op_type: Imm(568865) }) -//! -//! 0x100d: xorl %r12d, %r12d -//! insn id: 327 -//! bytes: [69, 49, 228] -//! read regs: -//! write regs: rflags -//! insn groups: -//! operands: 2 -//! X86Operand(X86Operand { size: 4, avx_bcast: X86_AVX_BCAST_INVALID, avx_zero_opmask: false, op_type: Reg(RegId(222)) }) -//! X86Operand(X86Operand { size: 4, avx_bcast: X86_AVX_BCAST_INVALID, avx_zero_opmask: false, op_type: Reg(RegId(222)) }) -//! -//! ``` -//! -//! [upstream]: http://capstone-engine.org/ -//! - +#![doc = include_str!("../../README.md")] #![no_std] // The `vec` macro cannot be imported directly since it conflicts with the `vec` module diff --git a/scripts/update_readme_code_sample.sh b/scripts/update_readme_code_sample.sh deleted file mode 100755 index e5dbda58..00000000 --- a/scripts/update_readme_code_sample.sh +++ /dev/null @@ -1,39 +0,0 @@ -#!/usr/bin/env bash -# Copy code snippet from src/lib.rs and paste into README.md code sample - -set -euo pipefail - -cd "$(dirname $0)/.." - -# Replace items between markers (including markers) with stdin -# Set REPLACE_MARKERS=1 to OVERWRITE the marker lines -marker_patch() { - local input="$1"; shift - local start_marker="$1"; shift - local end_marker="$1"; shift - - local line_num_pat='s/^\([^:]*\):.*$/\1/g' - - BEGIN_GEN="$(cat "$input" | grep -n "$start_marker" | sed "$line_num_pat")" - END_GEN="$(cat "$input" | grep -n "$end_marker" | sed "$line_num_pat")" - head_num=$(expr "$BEGIN_GEN" - 1) - tail_num=$(expr "$END_GEN" + 1) - - if [ "${REPLACE_MARKERS:+Z}" != "Z" ]; then - head_num=$(expr "$head_num" + 1) - tail_num=$(expr "$tail_num" - 1) - fi - - tmp_file="$(mktemp /tmp/marker-patch-XXXXXX)" - - cat \ - <(head -n "$head_num" "$input") \ - - \ - <(tail -n +"$tail_num" "$input") \ - > "$tmp_file" - - mv "$tmp_file" "$input" -} - -cat capstone-rs/src/lib.rs | sed -n '/```rust/,/```/p' | sed -E 's,^//! ?,,' \ - | marker_patch README.md "" ""