A local diffing tool for decompilation projects
Go to file
Luke Street 26932b2e44 Support `min_version` field in `objdiff.json` 2023-09-09 23:54:25 -04:00
.github/workflows ci: Update before apt-get install 2023-01-16 10:55:26 -05:00
assets Document configuration file & more cleanup 2023-08-12 14:18:09 -04:00
src Support `min_version` field in `objdiff.json` 2023-09-09 23:54:25 -04:00
.gitignore Initial commit 2022-09-08 17:19:20 -04:00
Cargo.lock Support `min_version` field in `objdiff.json` 2023-09-09 23:54:25 -04:00
Cargo.toml Support `min_version` field in `objdiff.json` 2023-09-09 23:54:25 -04:00
LICENSE-APACHE Version 0.2.0 2022-12-06 17:53:32 -05:00
LICENSE-MIT Version 0.2.0 2022-12-06 17:53:32 -05:00
README.md Project configuration fixes & improvements 2023-09-03 09:28:46 -04:00
build.rs Update all dependencies 2023-05-11 02:47:57 -04:00
deny.toml Update all dependencies (again) 2023-07-06 10:37:57 -04:00
rustfmt.toml Initial commit 2022-09-08 17:19:20 -04:00

README.md

objdiff Build Status

A local diffing tool for decompilation projects.

Supports:

  • PowerPC 750CL (GameCube & Wii)
  • MIPS (Nintendo 64)

See Usage for more information.

Symbol Screenshot Diff Screenshot

Usage

objdiff works by comparing two relocatable object files (.o). The objects are expected to have the same relative path from the "target" and "base" directories.

For example, if the target ("expected") object is located at build/asm/MetroTRK/mslsupp.o and the base ("actual") object is located at build/src/MetroTRK/mslsupp.o, the following configuration would be used:

  • Target build directory: build/asm
  • Base build directory: build/src
  • Object: MetroTRK/mslsupp.o

objdiff will then execute the build system from the project directory to build both objects:

$ make build/asm/MetroTRK/mslsupp.o # Only if "Build target object" is enabled
$ make build/src/MetroTRK/mslsupp.o

The objects will then be compared and the results will be displayed in the UI.

See Configuration for more information.

Configuration

While not required (most settings can be specified in the UI), projects can add an objdiff.json (or objdiff.yaml, objdiff.yml) file to configure the tool automatically. The configuration file must be located in the root project directory.

If your project has a generator script (e.g. configure.py), it's recommended to generate the objdiff configuration file as well. You can then add objdiff.json to your .gitignore to prevent it from being committed.

// objdiff.json
{
  "custom_make": "ninja",

  // Only required if objects use "path" instead of "target_path" and "base_path".
  "target_dir": "build/asm",
  "base_dir": "build/src",

  "build_target": true,
  "watch_patterns": [
    "*.c",
    "*.cp",
    "*.cpp",
    "*.h",
    "*.hpp",
    "*.py"
  ],
  "objects": [
    {
      "name": "main/MetroTRK/mslsupp",

      // Option 1: Relative to target_dir and base_dir
      "path": "MetroTRK/mslsupp.o",
      // Option 2: Explicit paths from project root
      // Useful for more complex directory layouts
      "target_path": "build/asm/MetroTRK/mslsupp.o",
      "base_path": "build/src/MetroTRK/mslsupp.o",
      
      "reverse_fn_order": false
    },
    // ...
  ]
}

custom_make (optional): By default, objdiff will use make to build the project.
If the project uses a different build system (e.g. ninja), specify it here.

target_dir (optional): Relative from the root of the project, this where the "target" or "expected" objects are located.
These are the intended result of the match.

base_dir (optional): Relative from the root of the project, this is where the "base" or "actual" objects are located.
These are objects built from the current source code.

build_target: If true, objdiff will tell the build system to build the target objects before diffing (e.g. make path/to/target.o).
This is useful if the target objects are not built by default or can change based on project configuration or edits to assembly files.
Requires the build system to be configured properly.

watch_patterns (optional): A list of glob patterns to watch for changes. (Supported syntax)
If any of these files change, objdiff will automatically rebuild the objects and re-compare them.
If not specified, objdiff will use the default patterns listed above.

objects (optional): If specified, objdiff will display a list of objects in the sidebar for easy navigation.

name (optional): The name of the object in the UI. If not specified, the object's path will be used.

path: Relative path to the object from the target_dir and base_dir.
Requires target_dir and base_dir to be specified.

target_path: Path to the target object from the project root.
Required if path is not specified.

base_path: Path to the base object from the project root.
Required if path is not specified.

reverse_fn_order (optional): Displays function symbols in reversed order.
Used to support MWCC's -inline deferred option, which reverses the order of functions in the object file.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.