encounter
/
objdiff
mirror of https://github.com/encounter/objdiff.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README.md

This commit is contained in:
Luke Street 2023-08-12 14:41:19 -04:00
parent 3970bc8acf
commit 21cdf268f0
1 changed files with 24 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
README.md
View File

@ -16,10 +16,11 @@ See [Usage](#usage) for more information.
## Usage ## 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 For example, if the target ("expected") object is located at `build/asm/MetroTRK/mslsupp.o` and the base ("actual")
is located at `build/src/MetroTRK/mslsupp.o`, the following configuration would be used: object is located at `build/src/MetroTRK/mslsupp.o`, the following configuration would be used:
- Target build directory: `build/asm` - Target build directory: `build/asm`
- Base build directory: `build/src` - Base build directory: `build/src`
@ -38,14 +39,19 @@ See [Configuration](#configuration) for more information.
## Configuration ## 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 ```json5
// objdiff.json // objdiff.json
{ {
"custom_make": "ninja", "custom_make": "ninja",
"target_dir": "build/mp1.0/asm", "target_dir": "build/asm",
"base_dir": "build/mp1.0/src", "base_dir": "build/src",
"build_target": true, "build_target": true,
"watch_patterns": [ "watch_patterns": [
"*.c", "*.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. 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. - `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**. 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`). - `build_target`: If true, objdiff will tell the build system to build the target objects before diffing (e.g.
This is useful if the target objects are not built by default or can change based on project configuration or edits to assembly files. `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. 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. 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. - `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`. - `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. - `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. - `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. Used to support MWCC's `-inline deferred` option, which reverses the order of functions in the object file.
## License ## License
@ -96,6 +103,5 @@ at your option.
### Contribution ### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
additional terms or conditions.