From 5b346412ae47b859ef933e27d6dcf6a5ed106ae7 Mon Sep 17 00:00:00 2001 From: Michael Simons Date: Wed, 9 Jul 2025 22:11:23 +0000 Subject: [PATCH 1/3] Add how to documentation for stage 2 builds --- Documentation/how-to-stage2-build.md | 45 ++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 Documentation/how-to-stage2-build.md diff --git a/Documentation/how-to-stage2-build.md b/Documentation/how-to-stage2-build.md new file mode 100644 index 0000000000..fe9ee6e581 --- /dev/null +++ b/Documentation/how-to-stage2-build.md @@ -0,0 +1,45 @@ +# How to run a stage 2 build + +This document describes how to perform a stage 2 source build. + +## What is a stage 2 build + +A **stage 2 build** is when you run a source build, then take the SDK and packages produced by that build and use them to rebuild the product. +Stage 2 builds are essential for validating a source‑built product. + +It’s common for stage 2 builds to surface issues. +For example, if a new Roslyn analyzer is included in the SDK, it can introduce new build errors during the stage 2 build. +These issues must be resolved for the product to be considered **source‑buildable**. + +The process of using built SDK and artifacts to rebuild the product is often called **bootstrapping**. +Distribution maintainers use it to initiate the build process: build once using the Microsoft SDK and artifacts, then rebuild using the resulting SDK and artifacts. + + +## Steps to run a stage 2 build + +1. Run a stage 1 build + + ```bash + git clone https://github.com/dotnet/dotnet.git dotnet1 + pushd dotnet1 + ./prep-source-build.sh + ./build.sh -sb + popd + ``` + +2. Run a stage 2 build + + ``` bash + mkdir -p stage1/sdk stage1/packages + + tar -xf dotnet1/artifacts/assets/Release/Private.SourceBuilt.Artifacts.*.tar.gz -C stage1/packages + + tar -xf dotnet1/artifacts/assets/Release/Sdk/*/dotnet-sdk-*.tar.gz -C stage1/sdk + + git clone https://github.com/dotnet/dotnet.git dotnet2 + pushd dotnet2 + ./build.sh -sb --with-packages stage1/packages --with-sdk stage1/sdk + popd + ``` + + > **Note:** `prep-source-build.sh` is optional for stage 2. It is only needed if you want to remove checked‑in binaries before building. From 6e75c27311a19b35f9052d51332f5b13adf9dc14 Mon Sep 17 00:00:00 2001 From: MichaelSimons Date: Thu, 10 Jul 2025 09:38:28 -0500 Subject: [PATCH 2/3] Address linter --- .github/linters/.markdown-lint.yml | 2 +- Documentation/how-to-stage2-build.md | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/linters/.markdown-lint.yml b/.github/linters/.markdown-lint.yml index dcbc943f0d..3e6b32b870 100644 --- a/.github/linters/.markdown-lint.yml +++ b/.github/linters/.markdown-lint.yml @@ -2,5 +2,5 @@ default: true MD013: # line length code_block_line_length: 256 heading_line_length: 96 - line_length: 96 + line_length: 256 MD033: false # no inline HTML diff --git a/Documentation/how-to-stage2-build.md b/Documentation/how-to-stage2-build.md index fe9ee6e581..32b68c122b 100644 --- a/Documentation/how-to-stage2-build.md +++ b/Documentation/how-to-stage2-build.md @@ -4,7 +4,7 @@ This document describes how to perform a stage 2 source build. ## What is a stage 2 build -A **stage 2 build** is when you run a source build, then take the SDK and packages produced by that build and use them to rebuild the product. +A **stage 2 build** is when you run a source build, then take the SDK and packages produced by that build and use them to rebuild the product. Stage 2 builds are essential for validating a source‑built product. It’s common for stage 2 builds to surface issues. @@ -14,7 +14,6 @@ These issues must be resolved for the product to be considered **source‑builda The process of using built SDK and artifacts to rebuild the product is often called **bootstrapping**. Distribution maintainers use it to initiate the build process: build once using the Microsoft SDK and artifacts, then rebuild using the resulting SDK and artifacts. - ## Steps to run a stage 2 build 1. Run a stage 1 build From 1f4226524b83f7727b5a021cb83eea8002b81fe6 Mon Sep 17 00:00:00 2001 From: MichaelSimons Date: Thu, 10 Jul 2025 12:51:05 -0500 Subject: [PATCH 3/3] Updates per code review --- Documentation/how-to-stage2-build.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/how-to-stage2-build.md b/Documentation/how-to-stage2-build.md index 32b68c122b..8b96dd5422 100644 --- a/Documentation/how-to-stage2-build.md +++ b/Documentation/how-to-stage2-build.md @@ -12,7 +12,8 @@ For example, if a new Roslyn analyzer is included in the SDK, it can introduce n These issues must be resolved for the product to be considered **source‑buildable**. The process of using built SDK and artifacts to rebuild the product is often called **bootstrapping**. -Distribution maintainers use it to initiate the build process: build once using the Microsoft SDK and artifacts, then rebuild using the resulting SDK and artifacts. +This helps to ensure that the second build was produced using only sources on disk without any external inputs. +Distribution maintainers use this process to initiate the build process: build once using the Microsoft SDK and artifacts, then rebuild using the resulting SDK and artifacts. ## Steps to run a stage 2 build