Document `--with-system-libs` semantics and packaging responsibilities
- 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