Skip to content

Commit 05085c5

Browse files
HurricanKaiHurricanKai
authored
Update for-contrib Docs (#1012)
1 parent 21169f6 commit 05085c5

File tree

14 files changed

+139
-91
lines changed

14 files changed

+139
-91
lines changed

‎documentation/for-contributors/generators/README.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22

33
SilkTouch is the Silk.NET project's C# native interoperability code generation stack. It contains useful generators which together generate the majority of the library's codebase.
44

5-
It does this by splitting the generation process into multiple phases, all anchored around the concept of a "shared infrastructure" - abstractions for SilkTouch generators which are agnostic of where they're running. Currently the only places SilkTouch can run is in a Roslyn Source Generator and using a `dotnet tool` Command Line Interface, but the idea is so long as no incompatibilities are introduced by each individual phase (such as being locked to .NET 6 instead of .NET Standard 2.0) the generator should be able to run in whatever form factor is desirable - the Shared Infrastructure will provide everything a generator could need for consuming a JSON configuration with C# input code and producing additional generated C# code as a result.
5+
It does this by centering all parts around a [common symbol layer](./symbol-layer/README.md), which allows other parts to be used in any configuration deemed useful, parts don't have a way other then the symbol layer to exchange data, enforcing interoperability.
66

77
Learn more about each individual cornerstone of the SilkTouch Stack:
8-
- [Shared Infrastructure](shared-infrastructure.md)
9-
- [Emitter](emitter.md)
10-
- [Overloader](overloader.md)
11-
- [Scraper](scraper.md)
8+
9+
- [Symbol Layer](./symbol-layer/README.md)
10+
- [Emitter](emitter.md)
11+
- [Scraper](scraper.md)
1212

1313
TODO: Add a link to the original proposal once the proposals folder has been reorganised according to the Software Development Plan.

‎documentation/for-contributors/generators/emitter.md

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

‎documentation/for-contributors/generators/emitter/README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Emitter
2+
3+
The emitter is responsible for creating Roslyn C# Code Symbols from our symbol layer.
4+
5+
See [here](./about%20formatting.md) for how formatting works, and [here](./visitor.md) for details on the visitor implementation.
6+
7+
In general the emitter tries it's best to be very basic doing only the job of 1:1 translating shared symbol layer into C# roslyn symbols.

‎documentation/for-contributors/generators/emitter/visitor.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Visitor
22

3+
See [here](../symbol-layer/symbol-visitor.md) for details on how the base symbol visitor works.
4+
35
To Transform our internal symbol layer to C# code a visitor (`CSharpEmitter.Visitor`) is used.
46

57
## State

‎documentation/for-contributors/generators/overloader.md

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

‎documentation/for-contributors/generators/scraper.md

Lines changed: 7 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,13 @@
11
# Scraper
22

3-
The SilkTouch Scraper is responsible for walking through the abstract syntax tree (AST) of a C/C++ header and all the referenced headers therein to generate C# bindings to as much of this as possible where the configuration indicates this is desirable. Only certain headers will have bindings generated for them, which can be specified by providing the paths to the headers to "traverse" in the JSON configuration.
3+
The scraper calls into clang to generate XML and can scrape this XML for Symbols of the [Symbol Layer](./symbol-layer/README.md)
44

5-
## ClangSharp
5+
## Scraping XML
66

7-
To walk through the C/C++ AST, ClangSharp's P/Invoke Generator is used, which is a proven tool for generating C# bindings to C/C++ APIs published by Microsoft. It does this by using the clang compiler to walk through the AST.
7+
To scrape XML there is a visitor that visits each XML node and outputs several symbols per node.
8+
This is what happens in `XmlVisitor.cs`
89

9-
ClangSharp's P/Invoke Generator is capable of producing C# bindings on its own, however these are raw bindings that use DllImport and don't aim to lift the bindings to be more C#-friendly. However, as part of Scraper development work was done to add an "XML output mode" to ClangSharp which instead of producing pure C# code, it outputs XML which roughly represents what the C# code would've looked like.
10+
## Generating XML using clang
1011

11-
## The Subagent
12-
13-
ClangSharp uses libclang, which has funny rules over multithreading. To maintain a degree of parallelism during generation, the invocation of ClangSharp was moved to be done in a separate process. The original intention was to invoke the `ClangSharpPInvokeGenerator` tool as shipped publicly, but unfortunately `dotnet tool`s cannot be referenced by other libraries or `dotnet tool`s. As such, we created our own shim which mimics the behaviour of and duplicates a lot of code from the `ClangSharpPInvokeGenerator` tool, but within the same CLI executable.
14-
15-
### The `ISubagent` abstraction
16-
17-
`ISubagent` is responsible for launching the ClangSharp tool with certain parameters, inputs, and configuration. This is an abstraction such that the main Scraper assembly remains easily portable to another form factor should we enable the Scraper to run in another form factor in the future, as well as to prevent the library assembly knowing too much about the assembly in which its executing.
18-
19-
The only implementation of this interface is the `ClangSharpSubagent` class in the `SilkTouch` assembly (CLI implementation of the Shared Infrastructure) which gathers information on the currently executing assembly, and relaunches it with `clangsharp` as the first argument and a JSON-encoded record as the second.
20-
21-
### The `silktouch clangsharp` command
22-
23-
This is the command that invokes ClangSharp as described in the previous section. This deserializes the JSON-encoded record and passes the data held therein to the `PInvokeGenerator` class within ClangSharp. This will generate the XML dump and then quit, possibly with some ClangSharp-generated diagnostics and a non-zero error code if those diagnostics are severe. The implementation of this is in the `ClangSharpHandoff` class.
24-
25-
## XML Mods
26-
27-
Once an initial XML dump has been generated by The Subagent, the XML dump will be parsed by the `Silk.NET.SilkTouch.ClangSharp.Xml` library and produce a tree of records. This is done in the `ScraperGenerator` ahead of the XML mods stage.
28-
29-
The purpose of the XML mods stage is to walk this tree of records, and modify it depending on the project configuration (for example changing all names to be PascalCase, or adding custom attributes to cause the Overloader to generate certain overloads). Each mod must be specifically enabled, and has free range over the XML. As such, they execute in the order in which they were specified in the project configuration.
30-
31-
Each XML mod has access to the `ScraperJobConfiguration.ModOptions` and the full XML tree. It does not have any access to resources beyond that, such as the SilkTouch Context.
32-
33-
TODO: Write words here about each XML mod once XML mods have been implemented
34-
35-
## Transformation
36-
37-
After the XML mods have been applied, the transformation stage is responsible for converting the bindings represented by the XML tree back into C# code that can be output via the SilkTouch Context (and added to the project compilation). Unlike ClangSharp, this stage will output bindings which are compatible with/invoke the Emitter and Overloader instead of using DllImport directly.
38-
39-
TODO: Write more words here once this stage is implemented.
12+
This is what happens in `ClangScraper.cs`, which is configured using `ClangScraperConfiguration.cs`
13+
Check XML docs for details on what methods do.

‎documentation/for-contributors/generators/shared-infrastructure.md

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

‎documentation/for-contributors/generators/symbol-layer/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Symbol Layer
2+
3+
The symbol layer is a set of types in the Silk.NET.SilkTouch.Symbols, all inheriting from the central Silk.NET.SilkTouch.Symbols.Symbol type.
4+
5+
The symbol layer is intended as a way to represent data passed between components of SilkTouch and is entirely immutable, with the only exception being the [Type Store](./type-store.md).
6+
7+
The way to update & iterate symbols is using a [Symbol Visitor](./symbol-visitor.md).
8+
9+
See [symbols](./symbols/README.md) for a list of all symbols, their visitor method, test details, etc.
10+
11+
See [type references](./type-references.md) for an explanation of type references.

‎documentation/for-contributors/generators/symbol-layer/symbol-visitor.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Symbol Visitor
2+
3+
A symbol visitor visits each symbol and then calls the appropriate methods to recursively visit all parts.
4+
Each symbol visitor has access to a [type store](./type-store.md). It has to be provided in the constructor of every symbol visitor.
5+
It's generally adviced to simply bubble up this constructor parameter to users of your type.
6+
7+
## Updating Symbols
8+
9+
Each method returns the same type it gets as parameter, so prefer to override the most specific method possible.
10+
For example, if you wish to rename all `TypeSymbol`s, override `VisitTypeSymbol`. But if you want to add a field to every struct, override `VisitStructSymbol`. If you want to rewrite the type of a symbol, for example generate a class for every struct, again, override the most specific method that is compatible with both (in this case `VisitTypeSymbol`) and do type checks as necessary.
11+
12+
### Type IDs
13+
14+
See [type store](./type-store.md) for details on what type Ids are.
15+
**Do not change type IDs when visiting symbols. This breaks all references to that type.**
16+
17+
## Managing State
18+
19+
While the base `SymbolVisitor` is stateless, derived types are free to introduce (mutable) state. This allow propagating state other then the new symbol up the tree.

‎documentation/for-contributors/generators/symbol-layer/symbols/README.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Symbols
2+
3+
This document / folder is for tracking all the available symbols, and documenting what creation of one entails.
4+
5+
## Relation to SymbolVisitor
6+
7+
In general each symbol listed below should have a corresponding method `VisitMySymbol` the only exception being `UnresolvedTypeReference` as only few visitors should ever interact with it.
8+
9+
## List
10+
11+
(Order alphabetically please!)
12+
13+
Parent Symbols (Unlisted, abstract):
14+
| Name | See Also |
15+
| ---- | -------- |
16+
| MemberSymbol | |
17+
| Symbol | |
18+
| TypeReference | [here](../type-references.md) |
19+
| TypeSymbol | |
20+
21+
| Name | Symbol Layer File | Symbol Layer Tests | Emitter Tests |
22+
| ----------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
23+
| ExternalTypeReference | [here](../../../../../src/generators/Silk.NET.SilkTouch.Symbols/ExternalTypeReference.cs) | [here](../../../../../tests/Silk.NET.SilkTouch.Symbols.Tests/SymbolVisitorTests/ExternalTypeReferenceTests.cs) | TODO!!! |
24+
| FieldSymbol | [here](../../../../../src/generators/Silk.NET.SilkTouch.Symbols/FieldSymbol.cs) | [here](../../../../../tests/Silk.NET.SilkTouch.Symbols.Tests/SymbolVisitorTests/FieldTests.cs) | [here](../../../../../tests/Silk.NET.SilkTouch.Emitter.Tests/EmitterFieldTests.cs) |
25+
| IdentifierSymbol | [here](../../../../../src/generators/Silk.NET.SilkTouch.Symbols/IdentifierSymbol.cs) | [here](../../../../../tests/Silk.NET.SilkTouch.Symbols.Tests/SymbolVisitorTests/IdentifierTests.cs) | TODO!!! |
26+
| InternalTypeReference | [here](../../../../../src/generators/Silk.NET.SilkTouch.Symbols/InternalTypeReference.cs) | TODO!!! | TODO!!! |
27+
| NamespaceSymbol | [here](../../../../../src/generators/Silk.NET.SilkTouch.Symbols/NamespaceSymbol.cs) | [here](../../../../../tests/Silk.NET.SilkTouch.Symbols.Tests/SymbolVisitorTests/NamespaceTests.cs) | [here](../../../../../tests/Silk.NET.SilkTouch.Emitter.Tests/EmitterNamespaceTests.cs) |
28+
| PointerTypeReference | [here](../../../../../src/generators/Silk.NET.SilkTouch.Symbols/PointerTypeReference.cs) | [here](../../../../../tests/Silk.NET.SilkTouch.Symbols.Tests/SymbolVisitorTests/PointerTypeReferenceTests.cs) | TODO!!! |
29+
| StructSymbol | [here](../../../../../src/generators/Silk.NET.SilkTouch.Symbols/StructSymbol.cs) | [here](../../../../../tests/Silk.NET.SilkTouch.Symbols.Tests/SymbolVisitorTests/StructTests.cs) | [here](../../../../../tests/Silk.NET.SilkTouch.Emitter.Tests/EmitterStructTests.cs) |
30+
| UnresolvedTypeReference | [here](src/generators/Silk.NET.SilkTouch.Symbols/UnresolvedTypeReference.cs) | [here](tests/Silk.NET.SilkTouch.Symbols.Tests/SymbolVisitorTests/UnresolvedTypeReferenceTests.cs) | - |
31+
32+
## How to create a symbol
33+
34+
Checklist:
35+
36+
- [ ] Write a short description of what this symbol does in the above list.
37+
- [ ] Add the symbol to Silk.NET.SilkTouch.Symbols
38+
- [ ] Add a partial of SymbolVisitor to below the definition, and add visiting method in there.
39+
- [ ] Call the new visiting method either from
40+
- The root Visit(Symbol) method, this should rarely be needed
41+
- The parent's visit method
42+
- [ ] Add Tests to Silk.NET.SilkTouch.Symbols.Tests for
43+
- [ ] The type being visited with it's own visiting method
44+
- [ ] The type being visited with it's parent (not needed if this is a new root type, with no parent)
45+
- [ ] Each part being visited correctly. Only shallowly check this, don't check parts of parts.
46+
- [ ] Handle symbol in Silk.NET.SilkTouch.Emitter
47+
- [ ] Add Tests to Silk.NET.SilkTouch.Emitter.Tests
48+
- [ ] Transforming a sample Symbol matching a specific string
49+
- [ ] Other tests, this is highly dependend on how complex the C# output looks like
50+
- [ ] More is better!
51+
- [ ] You're done. Feel free to use the symbol wherever needed. Prefer to add usages in a separate PR.

‎documentation/for-contributors/generators/symbol-layer/type-references.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Type References
2+
3+
Type references are a special kind of symbol used to reference types.
4+
5+
There are several kinds of type references.
6+
During scraping (see [scraper](../scraper.md)) `UnresolvedTypeReference`s are created.
7+
These should be resolved right after, in a process called [type resolution](../type-resolution.md).
8+
9+
Type resolution leads to a variety of more specialized type references, with the two base ones being
10+
11+
- `InternalTypeReference`, referencing another newly defined type somewhere in the tree. (Note that it's generally not adviced to define types this way, they should already occur somewhere higher up in the tree)
12+
- `ExternalTypeReference`, referencing some external type, usually well known types from the standard library
13+
14+
There are several other type reference types, but they are wrappers around other references, for example `PointerTypeReference`.

0 commit comments

Comments
 (0)