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

Documentation/README.md

@@ -0,0 +1,29 @@
+# Source-Build Documentation
+
+## Building .NET from Source
+
+| Document | Description |
+|---|---|
+| [System Requirements](system-requirements.md) | Hardware, OS, and architecture requirements |
+| [Bootstrapping Guidelines](bootstrapping-guidelines.md) | How to acquire or build a bootstrapping SDK |
+| [Cross-Building](cross-building.md) | How to build .NET for a target platform using a cross-build container |
+| [How to Run a Stage 2 Build](how-to-stage2-build.md) | How to perform a stage 2 source build for validation |
+| [Adding Support for a New OS](boostrap-new-os.md) | Steps to bring up .NET on a new operating system |
+
+## Maintaining Source-Build
+
+| Document | Description |
+|---|---|
+| [CI Platform Coverage Guidelines](ci-platform-coverage-guidelines.md) | Guidelines for which platforms to test in CI |
+| [Feature Band Source Building](feature-band-source-building.md) | Guide for Linux distro maintainers on building feature band branches |
+| [Packaging and Installation](packaging-installation.md) | How to install or package a source-built .NET SDK |
+| [Patching Guidelines](patching-guidelines.md) | How to address build errors and other issues via patches |
+| [Package Dependency Flow](package-dependency-flow.md) | How package dependencies are managed within source-build |
+| [Eliminating Pre-builts](eliminating-pre-builts.md) | How to eliminate pre-built binaries in .NET repositories |
+| [Leak Detection](leak-detection.md) | How the poisoning mechanism works to detect pre-built leaks |
+| [Poison Report Format](poison-report-format.md) | How to interpret the poison report |
+
+## Repo Owner's Handbook
+
+See [sourcebuild-in-repos/README.md](sourcebuild-in-repos/README.md) for documentation
+aimed at repository owners who participate in source-build.

Documentation/cross-building.md

@@ -0,0 +1,43 @@
+# Cross-Building
+
+Cross-building is the process of building .NET for a target platform on a
+different host platform. For example, building for `linux-x64` on a host that
+uses the `azurelinux-3.0-net10.0-cross-amd64` container image with a
+dedicated sysroot.
+
+## When is Cross-Building Required?
+
+Cross-building is required when:
+
+- The build environment uses a cross-build container image (e.g.
+  `mcr.microsoft.com/dotnet-buildtools/prereqs:azurelinux-3.0-net10.0-cross-amd64`)
+  that provides a sysroot via the `ROOTFS_DIR` environment variable, even when
+  building for the same architecture as the host (e.g. `linux-x64`).
+
+## Enabling Cross-Building
+
+When building in a cross-build container with `ROOTFS_DIR` set, you must pass
+`/p:CrossBuild=true` to the build command. Without this flag, the runtime build
+will not use the sysroot when searching for native dependencies such as OpenSSL,
+causing the build to fail.
+
+## Example
+
+```bash
+docker run \
+  --rm \
+  --volume /path/to/dotnet:/dotnet \
+  --workdir /dotnet \
+  --env ROOTFS_DIR=/crossrootfs/x64 \
+  mcr.microsoft.com/dotnet-buildtools/prereqs:azurelinux-3.0-net10.0-cross-amd64 \
+  ./build.sh \
+    --clean-while-building \
+    --source-only \
+    --arch x64 \
+    --os linux \
+    /p:CrossBuild=true
+```
+
+> **Note:** `/p:CrossBuild=true` is only required when using a cross-build
+> container with `ROOTFS_DIR` set. It is not needed when building natively on
+> the target platform.