.NET Source-build Reference Packages

This repository contains tools, source and build scripts for source-buildable reference versions of historical .NET Core packages that are referenced by .NET source build. These are used only when source building .NET.

This repo supports three package types:

1. Reference - A package that contains API signatures, no implementation. It enables developers to build, targeting a specific library version without having the full implementation assembly for that version.
2. Targeting - A bundle of reference packages that target a specific .NET TFM.
3. Text only - Packages that contain text-only assets.

This repo and it's reference packages are often referred to as SBRPs. This acronym is used from time to time in issues and some documentation.

Supported Platforms

.NET source build currently only supports Linux but generating a source-build reference or text-only package is supported on both Windows and Unix based operating systems.

Building

./build.sh -sb

Adding new Packages

New packages are needed from time to time as existing dependency versions are upgraded and new dependencies are added to .NET. The generate script supports generating new packages. Run generate.sh --help for usage details.

When generating a package(s), the tooling will detect and generate all dependent packages.

Reference

./generate.sh --package system.buffers,4.5.1

After generating new reference packages, all new projects must be referenced as a DependencyPackageProjects. These must be defined in dependency order. There is a tracking issue to address this manual step.

The tooling does not handle all situations and sometimes the generated code will need manual tweeks to get it to compile. If this occurs when generating a newer version of an existing package, it can be helpful to regenerate the older version to see what changes were made.

The tooling has evolved over time and therefore when generating new packages, you may see edits made to existing packages. This is because the new package has a dependency on an existing package, it was regenerated and changes were detected from when it was originally generated.

Workflow

• Generate reference package and its depencencies running the ./generate.sh --package <package>,<version> script.
• Revert changes for packages that were already existed in the repository.
• Run build with the ./build.sh -sb command.
• If the compilation produces numerous compilation issue - run the ./build.sh --projects <path to .csproj file> command for each generated reference package separately. It may be necessary to manually tweak the code to address compilation issues. When this occurs, please ensure there is an tracking issue to address the underlying problem with the generator.

You can search for known issues in the Known Generator Issues Markdown file.

Targeting

Generating new targeting packages is not supported. No new targeting packs should be needed/added. If you feel a new targeting pack is needed, please open a new issue to discuss.

Text Only

./generate.sh --type text --package microsoft.build.traversal,3.1.6

Vulnerable Packages

CVEs may exist for reference packages included in this repo. If they are mitigated by a newer version, the newer version should be added, the vulnerable version should be removed, and references to the vulnerable package within other reference packages should be upgraded. A comment should be added to indicate when packages were manually upgraded.

    <!-- Manually updated version from 4.3.0 to address CVE-2017-0247 -->
    <PackageReference Include="System.Net.Security" Version="4.3.1" />

Filing Issues

This repo does not accept issues. Please file issues in the source-build repository.

Cleanup

Periodically, a query is ran in a source-built environment to detect unused reference packages. These unreferenced packages will be deleted.

License

This repo is licensed with MIT.