diff --git a/README.md b/README.md index e0f972d..47d39f6 100644 --- a/README.md +++ b/README.md @@ -16,10 +16,11 @@ See [Usage](#usage) for more information. ## 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. +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: +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` @@ -38,14 +39,19 @@ See [Configuration](#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. +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. ```json5 // objdiff.json { "custom_make": "ninja", - "target_dir": "build/mp1.0/asm", - "base_dir": "build/mp1.0/src", + "target_dir": "build/asm", + "base_dir": "build/src", "build_target": true, "watch_patterns": [ "*.c", @@ -72,18 +78,19 @@ While **not required** (most settings can be specified in the UI), projects can These are the **intended result** of the match. - `base_dir`: 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. +- `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](https://docs.rs/globset/latest/globset/#syntax)) +- `watch_patterns` _(optional)_: A list of glob patterns to watch for changes. + ([Supported syntax](https://docs.rs/globset/latest/globset/#syntax)) If any of these files change, objdiff will automatically rebuild the objects and re-compare them. - `objects` _(optional)_: If specified, objdiff will display a list of objects in the sidebar for easy navigation. - - `path`: Relative path to the object from the `target_dir` and `base_dir`. - - `name` _(optional)_: The name of the object in the UI. If not specified, the object's `path` will be used. - - `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. - - + - `path`: Relative path to the object from the `target_dir` and `base_dir`. + - `name` _(optional)_: The name of the object in the UI. If not specified, the object's `path` will be used. + - `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 @@ -96,6 +103,5 @@ 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. +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.