dotnet / dotnet/source-build

Document `--with-system-libs` semantics and packaging responsibilities

Open
#5,631 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
287
Forks
145
Avg merge
1d 22h
Merged PRs (30d)
10

Description

The VMR `build.sh --help` output describes the syntax of `--with-system-libs`, but there is no detailed documentation explaining its behavior or the packaging implications for produced runtime packs.

In particular, it is unclear that:

- `--with-system-libs all` enables every system-library substitution recognized by the VMR build. It does not restrict substitutions to libraries included with the target operating system; required libraries may instead be supplied by the distribution or build environment.
- Enabling a system-library substitution may cause native artifacts in runtime packs to be built using a library supplied by the build environment instead of .NET's bundled implementation. If the resulting artifact links to that library dynamically, a compatible library must be available in the deployment environment.
- A subsequent `dotnet publish --self-contained` copies the selected native assets from the runtime pack but does not generally discover and bundle arbitrary libraries to which those assets dynamically link. Those dependencies therefore remain external to the published output and must be supplied by the deployment environment.

This ambiguity contributed to dotnet/source-build#5632, where a Homebrew-built macOS runtime pack retained absolute dependencies on Homebrew's Brotli libraries.

Related: dotnet/runtime#4625

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the VMR build.sh --help output and the documentation locations for runtime packs and dotnet publish. Document the stated --with-system-libs behavior, substitution and linking implications, and the Homebrew Brotli example from dotnet/source-build#5632. Done means a reader can understand which dependencies remain external after publishing.

Written by the indexing model from the issue text.

Assessment

Tech stack
shell
Domain
build-system, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.