Skip to content

Latest commit

 

History

History
55 lines (38 loc) · 7.95 KB

README.md

File metadata and controls

55 lines (38 loc) · 7.95 KB
Raw

SourceGeneratorUtils Quality Gate Status Coverage Dotnet Version

An essential library equipped with utility functions and helpers to aid in writing source files for source generators or for general purposes.

Context and goals

In my journey of implementing source generators, I noticed recurrent similarities in each project. Handling source generation on nested types, for example, appeared frequently. Rewriting this logic on every source generator felt redundant and time-consuming, prompting me to abstract and manage most of these routine writing tasks. Hence, SourceGeneratorUtils was created.

The main objective is to enable developers to dive straight into writing the code necessary for their source generators, instead of handling the boilerplate writing logic for namespaces, containing types etc.. With SourceGeneratorUtils, developers can supply a populated implementation of AbstractGenerationSpec (or AbstractTypeGenerationSpec) that could be mapped from Roslyn's ISymbol (for source generators) or some parsed files with type definitions (for general purpose). They can then focus on implementing SourceCodeEmitter<TSpec>s components (used by SourceFileEmitter<TSpec>) with logic specific to the target code to generate.

Installation

In order to import the library in your source generators, some small tweaks are required. Full details can be found on this repository's detailed documentation. Alternatively, you can also use the source generator version that'll emit the library as well as all the polyfills required to use it directly into your source generator project.

NuGet Releases NuGet Badge NuGet Badge

Two packages can be found on nuget.org:

> dotnet add package SourceGeneratorUtils
> dotnet add package SourceGeneratorUtils.SourceGeneration

CI Builds CI status

For those who want to utilize builds from this repository's main branch, install them from the NuGet Github Package Registry using this repo's package feed. You'll need your own Github Personal Access Token (PAT) in order to access the registry. For information on obtaining your PAT, see the Working with the NuGet registry article.

  1. At the command line, navigate to your user profile directory and run the following command to add the package feed to your NuGet configuration, replacing the <GITHUB_USER_NAME> and <PERSONAL_ACCESS_TOKEN> placeholders with the relevant values: 
    > dotnet nuget add source -n GitHub -u <GITHUB_USER_NAME> -p <PERSONAL_ACCESS_TOKEN> https://nuget.pkg.github.com/thenameless314159/index.json
  2. You should now be able to add a reference to the package specifying a version from the repository packages feed

Getting started

An article explaining the default implementation usage is available on this repository's detailed documentation.

Comprehensive documentation, along with illustrative examples (for the provided abstractions), is currently in progress and will be available soon.

What's Included?

This library provides a variety of types that help the conception of source generation logic :

  • SourceWriter - A minimal wrapper over StringBuilder, it handles indentation in a straightforward manner.
  • SourceBuilder - Another thin wrapper, this time over a dictionary, to store generated source files and export them to disk. The following type can populate it:
  • SourceFileEmitterBase<TSpec> - Base abstraction to encapsulate all the necessary logic to write a C# source file ready for compilation. This abstraction should be used if you don't need target types declaration as well as SourceCodeEmitter<TSpec> components.
  • SourceFileEmitterBaseOptions - A simple record that holds options for source file generation within a SourceFileEmitterBase<TSpec>.
  • SourceCodeEmitter<TSpec> - An abstraction that allows developers to break down their source generation logic into smaller reusable components. This type is used by the following:
  • SourceFileEmitter<TSpec> An abstraction encapsulating all the logic necessary to generate ready-to-compile source files for the given target.
  • SourceFileEmitterOptions - A simple record that holds options for source file generation within a SourceFileEmitter<TSpec>.

Acknowledgements

  • I would like to thank Damian Edwards for the inspiration I drew from his CI workflows.
  • Gratitude is also extended to the individual who wrote SourceWriter at Microsoft and all the team behind the System.Text.Json source generator.