objdiff Documentation

The Arch trait is the core abstraction for handling architecture-specific logic in objdiff. It allows the library to support multiple instruction sets (like x86, ARM, MIPS, etc.) through a unified interface.

Key responsibilities of an Arch implementation include:

• Instruction Scanning: Using scan_instructions_internal to identify instruction boundaries, opcodes, and potential branch destinations.
• Instruction Display: Using display_instruction to format mnemonics and arguments for the UI.
• Detailed Comparison: Using process_instruction to parse instruction arguments for deep diffing.
• Data Analysis: Providing data_flow_analysis and guess_data_type to interpret how instructions interact with data.
• UI Enrichment: Providing symbol_hover, symbol_context, instruction_hover, and instruction_context to supply metadata to the user interface.

Implementations of Arch are typically instantiated via the new_arch helper function, which selects the correct architecture based on the provided object::File.

pub trait Arch: Any + Debug + Send + Sync {
    fn scan_instructions_internal(
        &self,
        address: u64,
        code: &[u8],
        section_index: usize,
        relocations: &[Relocation],
        diff_config: &DiffObjConfig,
    ) -> Result<Vec<InstructionRef>>;

    fn display_instruction(
        &self,
        resolved: ResolvedInstructionRef,
        diff_config: &DiffObjConfig,
        cb: &mut dyn FnMut(InstructionPart) -> Result<()>,
    ) -> Result<()>;

    // ... other methods
}

The project configuration (loaded via try_project_config) supports several key fields that control how objdiff behaves within a specific directory:

• custom_make: Custom make command.
• custom_args: Arguments for the custom make command.
• target_dir: The directory where target object files are located (relative to the project directory).
• base_dir: The base directory for object files (relative to the project directory).
• build_base: Boolean flag indicating if the base directory should be built.
• build_target: Boolean flag indicating if the target directory should be built.
• watch_patterns: A list of glob patterns for files to watch.
• ignore_patterns: A list of glob patterns for files to ignore.
• units: A list of object units defined in the project.
• options: Project-wide options applied to DiffObjConfig via apply_project_options.

Individual units within the units list can also define their own options, which are applied specifically to that unit's diff configuration.

The MappingConfig struct allows you to control how symbols are paired during a diff. This is useful when symbols have different names in different objects but represent the same entity.

Key fields:

• mappings: A BTreeMap<String, String> for manual symbol-to-symbol name mappings (Left Name $\rightarrow$ Right Name).
• selecting_left: An Option<String> specifying a symbol name in the left object. When set, the engine will automatically attempt to find and match all compatible symbols in the right object to this specific symbol, providing match percentages for them.
• selecting_right: An Option<String> specifying a symbol name in the right object. When set, the engine will attempt to find and match all compatible symbols in the left object to this specific symbol.

let mapping_config = MappingConfig {
    mappings: BTreeMap::from([("foo".to_string(), "bar".to_string())]),
    selecting_left: Some("main".to_string()),
    selecting_right: None,
};

The AppConfig struct holds the persistent settings for the objdiff GUI. It includes paths for the project, target, and base object directories, build settings, and file watching patterns.

Key fields include:

• project_dir: The root directory of the current project.
• target_obj_dir: The directory containing the 'target' object files.
• base_obj_dir: The directory containing the 'base' object files.
• watch_patterns: A list of Glob patterns used to trigger rebuilds on file changes.
• ignore_patterns: A list of Glob patterns to exclude from watching.
• rebuild_on_changes: A boolean that, when true, automatically re-runs the build and diff when watched files are modified.

#[derive(Clone, serde::Deserialize, serde::Serialize)]
pub struct AppConfig {
    pub version: u32,
    pub custom_make: Option<String>,
    pub custom_args: Option<Vec<String>>,
    pub selected_wsl_distro: Option<String>,
    pub project_dir: Option<Utf8PlatformPathBuf>,
    pub target_obj_dir: Option<Utf8PlatformPathBuf>,
    pub base_obj_dir: Option<Utf8PlatformPathBuf>,
    pub selected_obj: Option<ObjectConfig>,
    pub build_base: bool,
    pub build_target: bool,
    pub rebuild_on_changes: bool,
    pub auto_update_check: bool,
    pub watch_patterns: Vec<Glob>,
    pub ignore_patterns: Vec<Glob>,
    pub recent_projects: Vec<String>,
    pub diff_obj_config: DiffObjConfig,
}