Skip to content

release.md

Latest commit

 

History

History
113 lines (79 loc) · 3.51 KB

release.md

File metadata and controls

113 lines (79 loc) · 3.51 KB
Raw

CBOR Serialization Library Release Notes

Overview

This project provides a .NET library for CBOR (Concise Binary Object Representation) serialization using source generation. It is designed to be fully AOT-compatible and leverages System.Formats.Cbor for the underlying CBOR operations.

Project Structure

  • NCbor: The main runtime library that provides the core serialization logic and base classes.
  • NCbor.Generator: A source generator project that analyzes types marked with [CborSerializable] and generates optimized serialization/deserialization code.
  • NCbor.Demo: A demo project showcasing the usage of the library.

Local Development

Building the Project

  1. Clone the Repository:

    git clone https://github.com/yourusername/cbor.git
cd cbor

  2. Build the Solution:

    dotnet build NCbor.sln

Using the Source Generator Locally

  • The source generator is included as a project reference in the demo project.
  • To use the generator in your project, add the following to your .csproj: 
    <ItemGroup>
    <ProjectReference Include="..\NCbor\NCbor.csproj" />
    <Analyzer Include="..\NCbor.Generator\bin\Debug\netstandard2.0\NCbor.Generator.dll" />
</ItemGroup>

Why Explicit Analyzer Reference is Needed

  • When developing locally, the source generator is not automatically included as an analyzer.
  • You must explicitly add the generator DLL as an analyzer to ensure it runs during the build process.
  • This is different from NuGet packages, where analyzers are automatically included.

NuGet Packaging

Preparing the Generator for NuGet

  1. Update the Generator Project File: Add the following to NCbor.Generator.csproj:

    <PropertyGroup>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <IncludeAnalyzer>true</IncludeAnalyzer>
</PropertyGroup>

  2. Pack the Generator:

    dotnet pack NCbor.Generator/NCbor.Generator.csproj

Publishing to NuGet

  1. Create a NuGet Account (if you don't have one).
  2. Get Your API Key from the NuGet website.
  3. Publish the Package: 
    dotnet nuget push NCbor.Generator/bin/Debug/NCbor.Generator.1.0.0.nupkg --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json

Using the NuGet Package

  • Once published, users can install the package: 
    dotnet add package NCbor.Generator
  • The analyzer will be automatically included, and no explicit <Analyzer> reference is needed.

Source Generator Details

How It Works

  • The source generator analyzes types marked with [CborSerializable].
  • It generates optimized serialization and deserialization methods.
  • The generated code is added to the project during the build process.

Key Components

  • CborSourceGenerator: The main generator class that implements IIncrementalGenerator.
  • SerializationCodeGenerator: Generates the serialization and deserialization code.

Troubleshooting

  • Build Errors: Ensure the generator project is built before the demo project.
  • Missing Analyzer: Verify the <Analyzer> reference is correctly added in the project file.
  • NuGet Issues: Check the package version and API key.

Future Enhancements

  • Support for more complex types.
  • Advanced error handling.
  • Comprehensive test suite.
  • Performance optimizations.

License

This project is licensed under the terms of the LICENSE file.

For more details, refer to the specification document.