Skip to content

Commit 68606df

Browse files
encounterencounter
committed
Add config.schema.json & update README.md
1 parent b4650b6 commit 68606df

File tree

2 files changed

+255
-36
lines changed

2 files changed

+255
-36
lines changed

‎README.md

Lines changed: 34 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -49,91 +49,89 @@ See [Configuration](#configuration) for more information.
4949

5050
## Configuration
5151

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

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

59-
```json5
60-
// objdiff.json
58+
```json
6159
{
60+
"$schema": "https://raw.githubusercontent.com/encounter/objdiff/main/config.schema.json",
6261
"custom_make": "ninja",
6362
"custom_args": [
6463
"-d",
6564
"keeprsp"
6665
],
67-
68-
// Only required if objects use "path" instead of "target_path" and "base_path".
69-
"target_dir": "build/asm",
70-
"base_dir": "build/src",
71-
72-
"build_target": true,
66+
"build_target": false,
67+
"build_base": true,
7368
"watch_patterns": [
7469
"*.c",
7570
"*.cp",
7671
"*.cpp",
72+
"*.cxx",
7773
"*.h",
74+
"*.hp",
7875
"*.hpp",
79-
"*.py"
76+
"*.hxx",
77+
"*.s",
78+
"*.S",
79+
"*.asm",
80+
"*.inc",
81+
"*.py",
82+
"*.yml",
83+
"*.txt",
84+
"*.json"
8085
],
81-
"objects": [
86+
"units": [
8287
{
8388
"name": "main/MetroTRK/mslsupp",
84-
85-
// Option 1: Relative to target_dir and base_dir
86-
"path": "MetroTRK/mslsupp.o",
87-
// Option 2: Explicit paths from project root
88-
// Useful for more complex directory layouts
8989
"target_path": "build/asm/MetroTRK/mslsupp.o",
9090
"base_path": "build/src/MetroTRK/mslsupp.o",
91-
92-
"reverse_fn_order": false
93-
},
94-
// ...
91+
"metadata": {}
92+
}
9593
]
9694
}
9795
```
9896

97+
### Schema
98+
99+
View [config.schema.json](config.schema.json) for all available options. The below list is a summary of the most important options.
100+
99101
`custom_make` _(optional)_: By default, objdiff will use `make` to build the project.
100102
If the project uses a different build system (e.g. `ninja`), specify it here.
101103
The build command will be `[custom_make] [custom_args] path/to/object.o`.
102104

103105
`custom_args` _(optional)_: Additional arguments to pass to the build command prior to the object path.
104106

105-
`target_dir` _(optional)_: Relative from the root of the project, this where the "target" or "expected" objects are located.
106-
These are the **intended result** of the match.
107-
108-
`base_dir` _(optional)_: Relative from the root of the project, this is where the "base" or "actual" objects are located.
109-
These are objects built from the **current source code**.
110-
111107
`build_target`: If true, objdiff will tell the build system to build the target objects before diffing (e.g.
112108
`make path/to/target.o`).
113109
This is useful if the target objects are not built by default or can change based on project configuration or edits
114110
to assembly files.
115111
Requires the build system to be configured properly.
116112

113+
`build_base`: If true, objdiff will tell the build system to build the base objects before diffing (e.g. `make path/to/base.o`).
114+
It's unlikely you'll want to disable this, unless you're using an external tool to rebuild the base object on source file changes.
115+
117116
`watch_patterns` _(optional)_: A list of glob patterns to watch for changes.
118117
([Supported syntax](https://docs.rs/globset/latest/globset/#syntax))
119118
If any of these files change, objdiff will automatically rebuild the objects and re-compare them.
120119
If not specified, objdiff will use the default patterns listed above.
121120

122-
`objects` _(optional)_: If specified, objdiff will display a list of objects in the sidebar for easy navigation.
121+
`units` _(optional)_: If specified, objdiff will display a list of objects in the sidebar for easy navigation.
123122

124123
> `name` _(optional)_: The name of the object in the UI. If not specified, the object's `path` will be used.
125124
>
126-
> `path`: Relative path to the object from the `target_dir` and `base_dir`.
127-
> Requires `target_dir` and `base_dir` to be specified.
125+
> `target_path`: Path to the "target" or "expected" object from the project root.
126+
> This object is the **intended result** of the match.
128127
>
129-
> `target_path`: Path to the target object from the project root.
130-
> Required if `path` is not specified.
128+
> `base_path`: Path to the "base" or "actual" object from the project root.
129+
> This object is built from the **current source code**.
131130
>
132-
> `base_path`: Path to the base object from the project root.
133-
> Required if `path` is not specified.
131+
> `metadata.auto_generated` _(optional)_: Hides the object from the object list, but still includes it in reports.
134132
>
135-
> `reverse_fn_order` _(optional)_: Displays function symbols in reversed order.
136-
Used to support MWCC's `-inline deferred` option, which reverses the order of functions in the object file.
133+
> `metadata.complete` _(optional)_: Marks the object as "complete" (or "linked") in the object list.
134+
> This is useful for marking objects that are fully decompiled. A value of `false` will mark the object as "incomplete".
137135
138136
## Building
139137

‎config.schema.json

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
{
2+
"$schema": "https://json-schema.org/draft-07/schema",
3+
"$id": "https://raw.githubusercontent.com/encounter/objdiff/main/config.schema.json",
4+
"title": "objdiff configuration",
5+
"description": "Configuration file for objdiff",
6+
"type": "object",
7+
"properties": {
8+
"min_version": {
9+
"type": "string",
10+
"description": "Minimum version of objdiff required to load this configuration file.",
11+
"examples": [
12+
"1.0.0",
13+
"2.0.0-beta.1"
14+
]
15+
},
16+
"custom_make": {
17+
"type": "string",
18+
"description": "By default, objdiff will use make to build the project.\nIf the project uses a different build system (e.g. ninja), specify it here.\nThe build command will be `[custom_make] [custom_args] path/to/object.o`.",
19+
"examples": [
20+
"make",
21+
"ninja"
22+
],
23+
"default": "make"
24+
},
25+
"custom_args": {
26+
"type": "array",
27+
"description": "Additional arguments to pass to the build command prior to the object path.",
28+
"items": {
29+
"type": "string"
30+
}
31+
},
32+
"target_dir": {
33+
"type": "string",
34+
"description": "Relative from the root of the project, this where the \"target\" or \"expected\" objects are located.\nThese are the intended result of the match.",
35+
"deprecated": true
36+
},
37+
"base_dir": {
38+
"type": "string",
39+
"description": "Relative from the root of the project, this is where the \"base\" or \"actual\" objects are located.\nThese are objects built from the current source code.",
40+
"deprecated": true
41+
},
42+
"build_target": {
43+
"type": "boolean",
44+
"description": "If true, objdiff will tell the build system to build the target objects before diffing (e.g. `make path/to/target.o`).\nThis is useful if the target objects are not built by default or can change based on project configuration or edits to assembly files.\nRequires the build system to be configured properly.",
45+
"default": false
46+
},
47+
"build_base": {
48+
"type": "boolean",
49+
"description": "If true, objdiff will tell the build system to build the base objects before diffing (e.g. `make path/to/base.o`).\nIt's unlikely you'll want to disable this, unless you're using an external tool to rebuild the base object on source file changes.",
50+
"default": true
51+
},
52+
"watch_patterns": {
53+
"type": "array",
54+
"description": "List of glob patterns to watch for changes in the project.\nIf any of these files change, objdiff will automatically rebuild the objects and re-compare them.\nSupported syntax: https://docs.rs/globset/latest/globset/#syntax",
55+
"items": {
56+
"type": "string"
57+
},
58+
"default": [
59+
"*.c",
60+
"*.cp",
61+
"*.cpp",
62+
"*.cxx",
63+
"*.h",
64+
"*.hp",
65+
"*.hpp",
66+
"*.hxx",
67+
"*.s",
68+
"*.S",
69+
"*.asm",
70+
"*.inc",
71+
"*.py",
72+
"*.yml",
73+
"*.txt",
74+
"*.json"
75+
]
76+
},
77+
"objects": {
78+
"type": "array",
79+
"description": "Use units instead.",
80+
"deprecated": true,
81+
"items": {
82+
"$ref": "#/$defs/unit"
83+
}
84+
},
85+
"units": {
86+
"type": "array",
87+
"description": "If specified, objdiff will display a list of objects in the sidebar for easy navigation.",
88+
"items": {
89+
"$ref": "#/$defs/unit"
90+
}
91+
},
92+
"progress_categories": {
93+
"type": "array",
94+
"description": "Progress categories used for objdiff-cli report.",
95+
"items": {
96+
"$ref": "#/$defs/progress_category"
97+
}
98+
}
99+
},
100+
"$defs": {
101+
"unit": {
102+
"type": "object",
103+
"properties": {
104+
"name": {
105+
"type": "string",
106+
"description": "The name of the object in the UI. If not specified, the object's path will be used."
107+
},
108+
"path": {
109+
"type": "string",
110+
"description": "Relative path to the object from the target_dir and base_dir.\nRequires target_dir and base_dir to be specified.",
111+
"deprecated": true
112+
},
113+
"target_path": {
114+
"type": "string",
115+
"description": "Path to the target object from the project root.\nRequired if path is not specified."
116+
},
117+
"base_path": {
118+
"type": "string",
119+
"description": "Path to the base object from the project root.\nRequired if path is not specified."
120+
},
121+
"reverse_fn_order": {
122+
"type": "boolean",
123+
"description": "Displays function symbols in reversed order.\nUsed to support MWCC's -inline deferred option, which reverses the order of functions in the object file.",
124+
"deprecated": true
125+
},
126+
"complete": {
127+
"type": "boolean",
128+
"description": "Marks the object as \"complete\" (or \"linked\") in the object list.\nThis is useful for marking objects that are fully decompiled. A value of `false` will mark the object as \"incomplete\".",
129+
"deprecated": true
130+
},
131+
"scratch": {
132+
"ref": "#/$defs/scratch"
133+
},
134+
"metadata": {
135+
"ref": "#/$defs/metadata"
136+
}
137+
}
138+
},
139+
"scratch": {
140+
"type": "object",
141+
"description": "If present, objdiff will display a button to create a decomp.me scratch.",
142+
"properties": {
143+
"platform": {
144+
"type": "string",
145+
"description": "The decomp.me platform ID to use for the scratch.",
146+
"examples": [
147+
"gc_wii",
148+
"n64"
149+
]
150+
},
151+
"compiler": {
152+
"type": "string",
153+
"description": "The decomp.me compiler ID to use for the scratch.",
154+
"examples": [
155+
"mwcc_242_81",
156+
"ido7.1"
157+
]
158+
},
159+
"c_flags": {
160+
"type": "string",
161+
"description": "C flags to use for the scratch. Exclude any include paths."
162+
},
163+
"ctx_path": {
164+
"type": "string",
165+
"description": "Path to the context file to use for the scratch."
166+
},
167+
"build_ctx": {
168+
"type": "boolean",
169+
"description": "If true, objdiff will run the build command with the context file as an argument to generate it.",
170+
"default": false
171+
}
172+
},
173+
"required": [
174+
"platform",
175+
"compiler"
176+
]
177+
},
178+
"metadata": {
179+
"type": "object",
180+
"properties": {
181+
"complete": {
182+
"type": "boolean",
183+
"description": "Marks the object as \"complete\" (or \"linked\") in the object list.\nThis is useful for marking objects that are fully decompiled. A value of `false` will mark the object as \"incomplete\"."
184+
},
185+
"reverse_fn_order": {
186+
"type": "boolean",
187+
"description": "Displays function symbols in reversed order.\nUsed to support MWCC's -inline deferred option, which reverses the order of functions in the object file."
188+
},
189+
"source_path": {
190+
"type": "string",
191+
"description": "Path to the source file that generated the object."
192+
},
193+
"progress_categories": {
194+
"type": "array",
195+
"description": "Progress categories used for objdiff-cli report.",
196+
"items": {
197+
"type": "string",
198+
"description": "Unique identifier for the category. (See progress_categories)"
199+
}
200+
},
201+
"auto_generated": {
202+
"type": "boolean",
203+
"description": "Hides the object from the object list by default, but still includes it in reports."
204+
}
205+
}
206+
},
207+
"progress_category": {
208+
"type": "object",
209+
"properties": {
210+
"id": {
211+
"type": "string",
212+
"description": "Unique identifier for the category."
213+
},
214+
"name": {
215+
"type": "string",
216+
"description": "Human-readable name of the category."
217+
}
218+
}
219+
}
220+
}
221+
}

0 commit comments

Comments
 (0)