RFC: rgen transformer

[haritha-mohan]

Objective

The rgen transformer tool is a key component in the transition from using reflection-based code generation as currently used in bgen to the new Roslyn based approach.

The objective of the transformer is to convert the old bindings to a format compatible with the new Roslyn-based code generator. For example, this will include converting interfaces to classes and updating outdated attributes.

Since this will be a 1:1 mapping, this allows for these transformations to be automated- significantly reducing manual intervention, helps to mitigate errors, and will expedite the transition process.

Workflow

rgen transformer will be a .NET command line tool that will load syntax trees from existing files containing the old bindings and perform transformations on the encountered nodes.

The tool will accept the following arguments:

• Input directory/file path containing outdated bindings
• Output directory path to write the transformed files out to

The workflow will be as follows:

• Load the C# files and their corresponding syntax tree representations
• Parse the syntax trees and categorize the members as interfaces, classes, enums, delegates, etc.
• Extract the old binding data into an internal model. This leverages some of the work that has already been done by Manuel for the code generator.
• Convert the old bindings into a format required by the new Roslyn code generator
  • Detailed examples of transformations handled by the tool are outlined in the original RFC: RFC: Migrate bgen to use roslyn instead of the reflection API. #21308 (comment), but at a high level will involve updating several attributes regarding platform availability and nullability, converting interfaces to classes, etc.
  • The transformed data will be stored in a data model representing the new binding format
• C# files with the new bindings will be written out to the specified output directory

Testing

Throughout the development workflow, thorough unit tests will be added to ensure the tool works as expected, integrates well with the existing codebase, and is effective is providing a smooth transition to the new code generator.

Distribution

The tool will be available to download as a .NET global tool via NuGet as dotnet-rgen-transform (or something along those lines, name is subject to change). This ensures the tool will be accessible for both internal developers and external customers.

[mcumming]

The tool will accept the following arguments:

Are the arguments positional or named?

[haritha-mohan]

The tool will accept the following arguments:

Are the arguments positional or named?

named

[filipnavara]

Could this be a Roslyn analyzer and code-fix? Wouldn't that make the usage from IDE more intuitive?

[mandel-macaque]

@filipnavara we can move it too a code-fix too but we need to update all our bindings, which is going t be faster with a specific tool. Doing it in a code-fix or analyzer won't be manageable for our team, might be a good idea to provide it as a code-fix for smaller SDKs sharing the code with out tool.

[filipnavara]

Code fixes can be applied to a whole file/project at once. There are even ways to run them automatically, dotnet/upgrade-assistant used to do that.

[filipnavara]

To expand on the previous comment, the Roslynator CLI can apply analyzer code fixes project wide:

dotnet tool install -g roslynator.dotnet.cli
roslynator fix [<PROJECT|SOLUTION>] --analyzer-assemblies <PATH>