Skip to content

Commit 22a6f4a

Browse files
Add how to documentation for stage 2 builds (#5277)
* Add how to documentation for stage 2 builds * Address linter * Updates per code review
1 parent 8346475 commit 22a6f4a

File tree

2 files changed

+46
-1
lines changed

2 files changed

+46
-1
lines changed

.github/linters/.markdown-lint.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,5 @@ default: true
22
MD013: # line length
33
code_block_line_length: 256
44
heading_line_length: 96
5-
line_length: 96
5+
line_length: 256
66
MD033: false # no inline HTML
Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# How to run a stage 2 build
2+
3+
This document describes how to perform a stage 2 source build.
4+
5+
## What is a stage 2 build
6+
7+
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.
8+
Stage 2 builds are essential for validating a source‑built product.
9+
10+
It’s common for stage 2 builds to surface issues.
11+
For example, if a new Roslyn analyzer is included in the SDK, it can introduce new build errors during the stage 2 build.
12+
These issues must be resolved for the product to be considered **source‑buildable**.
13+
14+
The process of using built SDK and artifacts to rebuild the product is often called **bootstrapping**.
15+
This helps to ensure that the second build was produced using only sources on disk without any external inputs.
16+
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.
17+
18+
## Steps to run a stage 2 build
19+
20+
1. Run a stage 1 build
21+
22+
```bash
23+
git clone https://github.com/dotnet/dotnet.git dotnet1
24+
pushd dotnet1
25+
./prep-source-build.sh
26+
./build.sh -sb
27+
popd
28+
```
29+
30+
2. Run a stage 2 build
31+
32+
``` bash
33+
mkdir -p stage1/sdk stage1/packages
34+
35+
tar -xf dotnet1/artifacts/assets/Release/Private.SourceBuilt.Artifacts.*.tar.gz -C stage1/packages
36+
37+
tar -xf dotnet1/artifacts/assets/Release/Sdk/*/dotnet-sdk-*.tar.gz -C stage1/sdk
38+
39+
git clone https://github.com/dotnet/dotnet.git dotnet2
40+
pushd dotnet2
41+
./build.sh -sb --with-packages stage1/packages --with-sdk stage1/sdk
42+
popd
43+
```
44+
45+
> **Note:** `prep-source-build.sh` is optional for stage 2. It is only needed if you want to remove checked‑in binaries before building.

0 commit comments

Comments
 (0)