Skip to content

Commit 2132199

Browse files
gnidangnidan
committed
[wip]
1 parent 0cbc2a2 commit 2132199

24 files changed

Lines changed: 315 additions & 127 deletions

‎packages/web/sidebars.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,9 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
1212
*/
1313
const sidebars: SidebarsConfig = {
1414
// By default, Docusaurus generates a sidebar from the docs folder structure
15-
docsSidebar: [{type: 'autogenerated', dirName: '.'}],
15+
docsSidebar: [
16+
{type: 'autogenerated', dirName: '.'},
17+
],
1618

1719
// But you can create a sidebar manually
1820
/*

‎packages/web/spec/context/_category_.json‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎packages/web/spec/info/_category_.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"label": "ethdebug/format/info",
3+
"position": 7,
4+
"link": null
5+
}

‎packages/web/spec/info/info.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
import SchemaViewer from "@site/src/components/SchemaViewer";
6+
7+
# Schema
8+
9+
<SchemaViewer
10+
schema={{ id: "schema:ethdebug/format/info" }}
11+
/>

‎packages/web/spec/info/overview.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
import SchemaViewer from "@site/src/components/SchemaViewer";
6+
7+
# Overview
8+
9+
:::tip[Summary]
10+
11+
Objects in the **ethdebug/format/info** schema organize debugging data
12+
associated with a particular compilation. This includes lookup tables of
13+
types and pointers by their unique name identifiers, as well as optionally may
14+
include additional information such as complete program listings and compiled
15+
source contents.
16+
17+
:::
18+
19+
This schema serves as a root schema, in that it (a) aggregates
20+
all other schemas in this format (either directly or indirectly), and (b) in
21+
that no other schema aggregates it.
22+
23+
This schema serves as a suitable target for
24+
[JSON Schema bundling](https://json-schema.org/understanding-json-schema/structuring#bundling),
25+
e.g., for implementations that want to reduce complexity around validating
26+
**ethdebug/format** records and don't want to handle reference resolution
27+
across schema YAML files.
28+
29+
:::warning
30+
31+
**Note**, however, that "root schema" does not imply "objects in the schema
32+
always contain all relevant debugging data". Due to widespread practice among
33+
EVM language compilers to produce their own structured JSON output, objects in
34+
this schema are not necessarily complete records of debug information.
35+
36+
Compilers may choose to divide **distinct portions of debugging data** into
37+
**distinct sections of compiler JSON output**. For instance, it likely makes
38+
sense for a compiler to produce debugging data about a particular contract's
39+
bytecode alongside that contract bytecode's other output information.
40+
41+
At least until tooling accommodates this concern, debugging implementers
42+
**must** be aware that they will likely need to aggregate debugging data from
43+
multiple sections of each supported compiler's own output format.
44+
45+
:::
46+
47+
**However**, this schema _is suitable_ for representing a complete and
48+
standalone debugging data record for a particular compilation, but
49+
note the optionality of fields such as `compilation` and `programs`.
50+
Implementations looking to produce such self-contained debugging data objects
51+
should study the structure of these (and any other optional fields) and ensure
52+
that such fields are fully populated.

packages/web/spec/bytecode/_category_.json renamed to packages/web/spec/program/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"label": "ethdebug/format/bytecode",
2+
"label": "ethdebug/format/program",
33
"position": 5,
44
"link": {
55
"type": "generated-index",

‎packages/web/spec/program/context/_category_.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"label": "Program contexts",
3+
"position": 6,
4+
"link": null
5+
}

packages/web/spec/context/code.mdx renamed to packages/web/spec/program/context/code.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
77
# Code contexts
88

99
<SchemaViewer
10-
schema={{ id: "schema:ethdebug/format/context/code" }}
10+
schema={{ id: "schema:ethdebug/format/program/context/code" }}
1111
/>

packages/web/spec/bytecode/bytecode.mdx renamed to packages/web/spec/program/context/context.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
77
# Schema
88

99
<SchemaViewer
10-
schema={{ id: "schema:ethdebug/format/bytecode" }}
10+
schema={{ id: "schema:ethdebug/format/program/context" }}
1111
/>

packages/web/spec/context/variables.mdx renamed to packages/web/spec/program/context/variables.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
77
# Variables contexts
88

99
<SchemaViewer
10-
schema={{ id: "schema:ethdebug/format/context/variables" }}
10+
schema={{ id: "schema:ethdebug/format/program/context/variables" }}
1111
/>

0 commit comments

Comments
 (0)