Skip to content

Commit ceb883a

Browse files
ExaniteExanite
committed
Merge branch 'feature/generator-usage-docs' into feature/generator-docs
2 parents 133c257 + 2af78a6 commit ceb883a

1 file changed

Lines changed: 183 additions & 0 deletions

File tree

‎docs/for-contributors/using-the-generator.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
(This needs clean up before merging. This was originally meant to be a Discord message, but I figured it's a good start to having proper docs.)
2+
3+
Okay, so short guide (by Exanite):
4+
5+
Note that this is from my perspective as a new contributor/maintainer. I'm guessing at how some of this stuff works. :sweat_smile:
6+
7+
The way that Silk 3 works is by taking the output of ClangSharpPInvokeGenerator and modifying the output with a set of mods.
8+
These mods do things such as renaming identifiers, creating types such as handle structs or enums, and adding method overloads.
9+
10+
**Do note that Silk 3 is in heavy development and things can change without warning.**
11+
This is probably the case until we're a few previews in.
12+
13+
**Also note that only C bindings are supported right now. COM will be available later.**
14+
15+
## Generator overview
16+
17+
There are two main things to configure:
18+
1. Silk 3 - This is the [`generator.json`](https://github.com/dotnet/Silk.NET/blob/develop/3.0/generator.json) file.
19+
2. ClangSharpPInvokeGenerator - This is the [`eng/silktouch`](https://github.com/dotnet/Silk.NET/tree/develop/3.0/eng/silktouch) folder.
20+
21+
Both are organized by library.
22+
23+
I suggest referencing the SDL configuration since it best represents your average C library.
24+
Most options there should be applicable after you replace the SDL specific types/paths/etc.
25+
26+
### `generator.json`
27+
28+
This defines which mods to run.
29+
- `AddIncludes` adds system header files. You want this.
30+
- `ClangScraper` runs ClangSharpPInvokeGenerator. Only including this is equivalent to running ClangSharpPInvokeGenerator directly.
31+
- The rest do a bunch of other transformations that I won't cover here. Ask if you're interested please.
32+
33+
One way to learn about the mods and debug them is to add them one by one.
34+
Mods run in the order you define them and work off the output of each other.
35+
36+
However, you can probably get by just copying the mod order from SDL verbatim.
37+
38+
Things to note:
39+
- I'm unfamiliar with the test project config. You probably can ignore it.
40+
- Bool types are only transformed for functions. Bool types in structs will likely be left as`int` or similar.
41+
42+
### `eng/silktouch`
43+
44+
This folder contains a bunch of `.rsp` files, which hold command line arguments for ClangSharpPInvokeGenerator.
45+
46+
> To read more about ClangSharpPInvokeGenerator's command line arguments, I recommend installing the tool and using its help options.
47+
>
48+
> ```sh
49+
> dotnet tool install --global ClangSharpPInvokeGenerator
50+
> ClangSharpPInvokeGenerator --help
51+
> ClangSharpPInvokeGenerator -c help
52+
> ```
53+
54+
These rsp files can import other rsp files using the `@path` syntax.
55+
Eg: `@../settings.rsp`
56+
57+
Note that these paths are relative to the `generate.rsp` file (I think... or at least the folder containing that file).
58+
59+
`@../../remap-stdint.rsp` is my addition that ensures that stdint types behave consistently between Windows and Linux.
60+
61+
This is the general structure of the `eng/silktouch` folder:
62+
63+
```
64+
eng
65+
- silktouch
66+
- opengl <-- This level contains folders per library
67+
- glcompat <-- This level contains folders for each "profile" (I think that's the term) for each variant of the library
68+
- glcore
69+
- gles1
70+
- gles2
71+
- sdl
72+
- SDL3
73+
```
74+
75+
You likely don't need to worry about profiles, so we'll just keep focusing on the SDL case.
76+
77+
This is the structure of the SDL rsps.
78+
Note that you don't necessarily have to structure it this way.
79+
80+
```
81+
eng
82+
- silktouch
83+
- sdl
84+
- SDL3
85+
- generate.rsp <-- The main settings file
86+
- header.txt
87+
- sdl-SDL.h <-- Hand written header file that includes the relevant headers of the library you want to bind
88+
- remap.rsp
89+
- settings.rsp <-- Shared settings for all profiles. Technically can be merged into generate.rsp.
90+
```
91+
92+
Let's take a look at the `sdl-SDL.h` file and the `generate.rsp` and `settings.rsp` files.
93+
I'll only include the important parts of the config here.
94+
95+
`sdl-SDL.h`:
96+
```h
97+
#include <SDL3/SDL.h>
98+
#include <SDL3/SDL_main.h>
99+
#include <SDL3/SDL_vulkan.h>
100+
```
101+
102+
`generate.rsp`:
103+
```rsp
104+
@../settings.rsp
105+
@../remap.rsp
106+
--exclude
107+
SDL_SetX11EventHook
108+
SDL_SetWindowsMessageHook
109+
SDL_FILE
110+
SDL_LINE
111+
--file
112+
sdl-SDL.h
113+
--methodClassName
114+
Sdl
115+
--namespace
116+
Silk.NET.SDL
117+
--output
118+
../../../../sources/SDL/SDL3
119+
--traverse
120+
../../../submodules/sdl/include/SDL3/SDL_assert.h
121+
../../../submodules/sdl/include/SDL3/SDL_atomic.h
122+
../../../submodules/sdl/include/SDL3/SDL_audio.h
123+
```
124+
125+
`settings.rsp`:
126+
```rsp
127+
@../../common.rsp
128+
--define-macro
129+
TODO_DEFINE_MACROS=HERE
130+
--headerFile
131+
header.txt
132+
--include-directory
133+
../../../submodules/sdl/include
134+
--with-callconv
135+
*=Winapi
136+
--with-librarypath
137+
*=SDL3
138+
```
139+
140+
#### Relevant options from `generate.rsp`:
141+
142+
`--file` specifies the header file that we first look through.
143+
`--traverse` specifies which header files actually contribute towards the output. (Not sure if you can glob or similar here)
144+
145+
This separation is because while we need certain header files such as the system headers to compile the library, we don't want to include the system headers as part of our generated bindings.
146+
147+
`--output` should point to the same `Jobs.JOB_NAME.SourceProject` path you defined in `generator.json`.
148+
149+
`--methodClassName` specifies which C# class contains the generated methods/constants.
150+
`--namespace` specifies the C# namespace of the generated files.
151+
152+
`--exclude` allows you exclude types/functions/constants from the output. Usually these are things that aren't useful, don't generate correctly, or are platform-specific.
153+
154+
#### Relevant options from `settings.rsp`:
155+
156+
`--headerFile` specifies the header file appended to the top of every generated file.
157+
158+
`--include-directory` specifies the include directories. This affects all of the headers included, such as in `sdl-SDL.h`.
159+
160+
`--with-librarypath` is the name of the native library without prefixes/suffixes. If the library name differs outside of the usual `lib` prefix or `.dll`/`.so`/`.dylib` suffixes, the way to handle this is to add `UseAlternativeName` in the generated bindings. An example with Vulkan can be found at `sources/Vulkan/Vulkan/Vk.cs`.
161+
162+
```cs
163+
static Vk()
164+
{
165+
LoaderInterface.RegisterHook(Assembly.GetExecutingAssembly());
166+
LoaderInterface.RegisterAlternativeName("vulkan", "vulkan-1");
167+
LoaderInterface.RegisterAlternativeName("vulkan", "MoltenVK");
168+
}
169+
```
170+
171+
### Generated bindings output
172+
173+
All generated binding will be output to the `Jobs.JOB_NAME.SourceProject` path you defined in `generator.json`.
174+
175+
These generated files all have the `.gen.cs` suffix and most of them are partial type declarations.
176+
This means by creating a similarly named `.cs` file and using the `partial` C# keyword, you can add to the type.
177+
178+
Do not modify the `.gen.cs` files manually since rerunning the generator will overwrite those changes.
179+
180+
### Packing the generated bindings
181+
182+
Haven't done this myself so I'll leave this section as WIP.
183+
I imagine that `dotnet pack` or similar will just work though.

0 commit comments

Comments
 (0)