Skip to content

README-PACKAGES.md

Latest commit

 

History

History
149 lines (108 loc) · 4.3 KB

README-PACKAGES.md

File metadata and controls

149 lines (108 loc) · 4.3 KB
Raw

AnAspect.OneOf - Package Structure

For Users (Simple Installation)

Just install ONE package:

<ItemGroup>
  <PackageReference Include="Fody" Version="6.8.0" PrivateAssets="all" />
  <PackageReference Include="AnAspect.OneOf" Version="0.1.0-alpha" />
</ItemGroup>

The AnAspect.OneOf package will automatically pull in:

  • AnAspect.OneOf.Attributes (markers for IL weaving)
  • AnAspect.OneOf.SourceGenerator (generates OneOf types)

✅ This is the recommended approach for end users.

Package Details (For Reference)

Main Package

AnAspect.OneOf (install this!)

  • Contains the Fody weaver (AnAspect.OneOf.Fody.dll)
  • Automatically includes Attributes and SourceGenerator as dependencies
  • Users only need to install this package

Supporting Packages (Installed Automatically)

AnAspect.OneOf.Attributes

  • Marker attributes for IL weaving
  • Installed automatically as a dependency

AnAspect.OneOf.SourceGenerator

  • Roslyn source generator
  • Generates OneOf<T1,T2> types at compile time
  • Installed automatically as a dependency

Current Limitation (v0.1.0-alpha)

⚠️ In the current alpha release, you may need to install all three packages manually due to how the packages are structured:

<ItemGroup>
  <PackageReference Include="Fody" Version="6.8.0" PrivateAssets="all" />
  <PackageReference Include="AnAspect.OneOf" Version="0.1.0-alpha" />
  <PackageReference Include="AnAspect.OneOf.SourceGenerator" Version="0.1.0-alpha" />
  <PackageReference Include="AnAspect.OneOf.Attributes" Version="0.1.0-alpha" />
</ItemGroup>

Why? Fody weavers have special packaging requirements that make automatic dependency resolution tricky in the first release.

Future releases will have this fixed so you only need to install AnAspect.OneOf.

For Library Developers

If you're building on top of AnAspect.OneOf, you might want to reference individual packages:

  • AnAspect.OneOf.Attributes: If you only need the marker attributes
  • AnAspect.OneOf.SourceGenerator: If you only need the code generation
  • AnAspect.OneOf: If you need the full IL weaving experience

Package Dependencies Graph

AnAspect.OneOf (main package)
├── AnAspect.OneOf.Attributes (auto-included)
├── AnAspect.OneOf.SourceGenerator (auto-included)
└── Fody 6.8.0 (user must install separately)

Installation Comparison

❌ Current (v0.1.0-alpha) - Manual

<PackageReference Include="Fody" Version="6.8.0" PrivateAssets="all" />
<PackageReference Include="AnAspect.OneOf" Version="0.1.0-alpha" />
<PackageReference Include="AnAspect.OneOf.SourceGenerator" Version="0.1.0-alpha" />
<PackageReference Include="AnAspect.OneOf.Attributes" Version="0.1.0-alpha" />

✅ Future Releases - Automatic

<PackageReference Include="Fody" Version="6.8.0" PrivateAssets="all" />
<PackageReference Include="AnAspect.OneOf" Version="0.2.0-alpha" />
<!-- Other packages installed automatically -->

Why Three Packages?

Design Reasons:

  1. Separation of Concerns

    • Attributes: Compile-time markers (no runtime dependencies)
    • SourceGenerator: Code generation (analyzer)
    • Fody: IL weaving (post-build)

  2. Modularity

    • Users who only want source generation can skip Fody
    • Users who only want attributes can skip everything else

  3. NuGet Best Practices

    • Analyzers/generators packaged separately
    • Fody weavers packaged separately
    • Keeps package sizes small

However, for most users, this complexity is unnecessary, which is why we're working to make the main package include everything automatically.

Recommended Documentation Update

Update your README.md installation section to:

## Installation

### Simple (Recommended)
```xml
<ItemGroup>
  <PackageReference Include="Fody" Version="6.8.0" PrivateAssets="all" />
  <PackageReference Include="AnAspect.OneOf" Version="0.1.0-alpha" />
  <!-- For v0.1.0-alpha, also add these temporarily: -->
  <PackageReference Include="AnAspect.OneOf.SourceGenerator" Version="0.1.0-alpha" />
  <PackageReference Include="AnAspect.OneOf.Attributes" Version="0.1.0-alpha" />
</ItemGroup>

Add FodyWeavers.xml:

<?xml version="1.0" encoding="utf-8"?>
<Weavers>
</Weavers>

Note: Future versions will only require installing AnAspect.OneOf.