70 lines
3.8 KiB
Markdown
70 lines
3.8 KiB
Markdown
# The WinRT Go language projection
|
|
|
|
WinRT Go is an autogenerated language projection for Windows Runtime (WinRT) APIs.
|
|
|
|
The project was originally intended to assist in the development of the Windows implementation of the [tinygo-org/bluetooth](https://github.com/tinygo-org/bluetooth) library.
|
|
That's why it currently only contains WinRT APIs related to Bluetooth, but we are open to include new APIs if requested.
|
|
|
|
> [!IMPORTANT]
|
|
> Due to the nature of this project we decided not to tag any releases.
|
|
> All commits to the `main` branch are considered stable, and we encourage you to use the latest commit available.
|
|
>
|
|
> Breaking changes in the `main` branch should be an exception, but we may include them in favor of the simplicity of the project.
|
|
|
|
The project also contains the `winrt-go-gen` code generator and the source Windows Metadata (WinMD) files (located in `/internal/winmd/metadata`) that describe the WinRT APIs.
|
|
|
|
Notice that the code generator is not capable of generating any WinRT types.
|
|
It will work with most of them, but we've added the functionalities we exclusively needed to generate the BLE APIs.
|
|
So some things may still be missing.
|
|
Check out the [known missing features](#known-missing-features) section below for more information.
|
|
|
|
## Generated code
|
|
|
|
All the generated code is stored in the `windows` folder, and is divided in folders that match the namespace of each class.
|
|
|
|
Since our goal was to only use a subset of the WinRT APIs, the generated classes may only contain a subset of their methods.
|
|
This helps us generate less code, because we can remove dependencies between classes and completely skip their generation.
|
|
|
|
Also notice that the generated method names may differ from the ones defined in the WinRT API.
|
|
This is because Go does not support method overloading, so we are using the overload name defined in the WinMD files.
|
|
The [`GetGattServicesAsync` method](https://docs.microsoft.com/en-us/uwp/api/windows.devices.bluetooth.bluetoothledevice.getgattservicesasync?view=winrt-22621), for example, has an attribute defining the following overload name: `GetGattServicesWithCacheModeAsync`.
|
|
|
|
This also affects static methods, which include their class name as prefix to avoid collisions between classes inside the same package.
|
|
|
|
## Generating the code
|
|
|
|
The code is generated using `go generate`. But the Makefile includes a target (`make gen-files`) that removes all generated code and executes the `go generate` command.
|
|
|
|
You can also call the code generator manually.
|
|
|
|
```
|
|
Usage of winrt-go-gen:
|
|
-class string
|
|
The class to generate. This should include the namespace and the class name, e.g. 'System.Runtime.InteropServices.WindowsRuntime.EventRegistrationToken'.
|
|
-config string
|
|
config file (optional)
|
|
-debug
|
|
Enables the debug logging.
|
|
-method-filter value
|
|
The filter to use when generating the methods. This option can be set several times,
|
|
the given filters will be applied in order, and the first that matches will determine the result. The generator
|
|
will allow any method by default. The filter uses the overloaded method name to discriminate between overloaded
|
|
methods.
|
|
|
|
You can use the '!' character to negate a filter. For example, to generate all methods except the 'Add' method:
|
|
-method-filter !Add
|
|
|
|
You can also use the '*' character to match any method, so if you want to generate only the 'Add' method, you can do:
|
|
-method-filter Add -method-filter !*
|
|
```
|
|
|
|
## Known missing features
|
|
|
|
- If an interface extends another one, the methods of the parent interface are not generated.
|
|
- There are still some unsupported data types:
|
|
- Multi-dimensional arrays (`ELEMENT_TYPE_ARRAY`)
|
|
- References (`ELEMENT_TYPE_BYREF`)
|
|
- Pointer to functions (`ELEMENT_TYPE_FNPTR`)
|
|
- Pointer types (`ELEMENT_TYPE_PTR`)
|
|
- Typed references (`ELEMENT_TYPE_TYPEDBYREF`)
|