Document .NET cross-building and the CrossBuild=true requirement for foreign-ROOTFS builds

[Copilot]

Adds documentation covering .NET cross-building scenarios and clarifies when /p:CrossBuild=true must be explicitly provided.

Changes

• Documentation/cross-building.md (new): Dedicated cross-building document covering:

  • General definition of cross-building across all .NET platforms (Android, WASM, Windows arm64, macOS, Linux, etc.)
  • Explanation of ROOTFS_DIR-based cross-builds used for certain Linux/Unix targets, including what a sysroot is
  • A scenarios table showing which builds are ROOTFS_DIR-based and whether CrossBuild=true is inferred automatically
  • Focused section on the one case requiring explicit /p:CrossBuild=true: building for the same OS/architecture as the host but using a foreign sysroot (e.g. linux-x64 inside an azurelinux-3.0-net10.0-cross-amd64 container)

• Documentation/README.md (new): Table of contents for all documents in the Documentation/ directory, organized into "Building .NET from Source" and "Maintaining Source-Build" sections.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[mthalman]

@copilot - This doesn't belong in the system requirements doc. Make a new doc file for cross building. Add a new readme to the documentation directory to use as a table of contents for all the docs.

[Copilot]

@copilot - This doesn't belong in the system requirements doc. Make a new doc file for cross building. Add a new readme to the documentation directory to use as a table of contents f...

Done in 2bdbf2d. Created Documentation/cross-building.md for the cross-building content and Documentation/README.md as a table of contents for all docs in the directory. Reverted the changes to system-requirements.md.

[am11]

In the current state, it is not capturing the reality, but rather confusing the reader.

There are several types of cross-building in .NET:

• Cross-building on Android/Linux is different from WASM/Linux, which is different than WASM/Windows
• Windows-arm64 on Windows-x64 is different from OSX-arm64 on OSX-x64.

Separately, there is the ROOTFS_DIR-based class of cross builds used for certain Linux and Unix targets.
All ROOTFS_DIR builds require /p:CrossBuild=true. In most cases this is inferred automatically when target and host OS and architectures are not same. The only exception is when target and host are same but user still wants to perform a ROOTFS_DIR-style cross build. In that case, user must explicitly provide -p:CrossBuild=true.

@akoeplinger, @mthalman, please ping copilot so it reads this comment (I'm not in the group of copilot instructors so it will ignore the comment by default). In the sea of "cross build related documentation", the last sentence of previous paragraph is a tiny gotcha, so it's better if document represents it as such and not make it a centerpiece.

[am11]

Supported .NET Cross-Build Scenarios:

Host → Target	ROOTFS_DIR-based?	Uses CrossBuild=true?	CrossBuild inferred automatically?
linux-x64 → android-arm64	No	No	No
linux-x64 → browser-wasm	No	No	No
windows-x64 → browser-wasm	No	No	No
windows-x64 → windows-arm64	No	No	No
osx-x64 → osx-arm64	No	No	No
osx-arm64 → osx-x64	No	No	No
osx-arm64 → ios-arm64	No	No	No
osx-arm64 → ios-x64	No	No	No
osx-arm64 → tvos-arm64	No	No	No
osx-arm64 → tvos-x64	No	No	No
android-x64 → android-arm64	No	No	No
linux-x64 → freebsd-x64	Yes	Yes	Yes
linux-x64 → freebsd-arm64	Yes	Yes	Yes
linux-arm64 → freebsd-x64	Yes	Yes	Yes
linux-arm64 → freebsd-arm64	Yes	Yes	Yes
linux-x64 → linux-arm64	Yes	Yes	Yes
linux-x64 → linux-x64 (foreign ROOTFS)	Yes	Yes	No
linux-arm64 → linux-arm64 (foreign ROOTFS)	Yes	Yes	No
linux-x64 → haiku-x64	Yes	Yes	Yes
linux-arm64 → haiku-arm64	Yes	Yes	Yes

[mthalman]

@copilot - Incorporate comments from #5501 (comment) and #5501 (comment)

[Copilot]

@copilot - Incorporate comments from #5501 (comment) and #5501 (comment)...

Done in b247112. The doc now:

• Opens with a broad intro acknowledging the many .NET cross-build scenarios (Android, WASM, Windows arm64, macOS, etc.)
• Has a dedicated section on ROOTFS_DIR-based cross-builds and explains that CrossBuild=true is automatically inferred when host and target differ
• Includes the scenarios table from @am11's comment showing which builds are ROOTFS_DIR-based and when inference works
• Frames the "same arch with foreign ROOTFS" case (where explicit /p:CrossBuild=true is needed) as the minor gotcha it is, at the end of the doc

[mthalman]

@am11 - Can you take another look with these updates?

[am11]

One nit, otherwise looks good. Thanks! 🤖