Refresh BuildFromSource docs #37362

captainsafia · 2021-10-07T18:49:27Z

Clean up build from source docs
Add engine information to package.json files

docs/BuildFromSource.md

adityamandaleeka · 2021-10-12T07:13:16Z

docs/BuildFromSource.md


-#### Java Development Kit on Windows
+## Visual Studio Code on Windows, Linux, Mac


There isn't much here that's specific to VSCode... pretty much just the part where you open the folder using code? I'd argue that's not really important to call out, in which case this section can just become the terminal-oriented workflow (use the editor of your choice). The important things are the bits about using restore/activate/build.

davidfowl · 2021-10-17T04:23:32Z

We also need a true .vsconfig file that works. InstallVS.ps1 is jank

captainsafia · 2021-10-19T03:45:57Z

docs/BuildFromSource.md

-> origin    https://github.com/YOUR_USERNAME/aspnetcore (push)
-> upstream  https://github.com/dotnet/aspnetcore.git (fetch)
-> upstream  https://github.com/dotnet/aspnetcore.git (push)
+./eng/scripts/InstallVisualStudio.ps1


I believe the VS install will install web tools like Node by default?

If the web workload is installed than I think yes.

Pilchie

Looks good except for a few nits.

docs/BuildFromSource.md

Pilchie · 2021-10-19T15:36:00Z

docs/BuildFromSource.md

-> origin    https://github.com/YOUR_USERNAME/aspnetcore (push)
-> upstream  https://github.com/dotnet/aspnetcore.git (fetch)
-> upstream  https://github.com/dotnet/aspnetcore.git (push)
+./eng/scripts/InstallVisualStudio.ps1


If the web workload is installed than I think yes.

Pilchie · 2021-10-19T15:39:03Z

docs/BuildFromSource.md


-## Step 5: Use the result of your build
+![Screen Shot 2021-10-05 at 9 05 39 AM](https://user-images.githubusercontent.com/1857993/136060792-6b4c6158-0a2c-4dd6-8639-08d83da6d2d1.png)


Suggest a better alt-text for this.

BrennanConroy · 2021-10-19T16:36:24Z

docs/BuildScript.md

+
+| Command                                                      | What does it do?                                             |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| `.\eng\build.cmd -all -pack -arch x64`                       | Build development packages for all the shipping projects in the repo. |


IMO this list should mainly contain the commands that we think users should be using, like .\build.cmd -t and have them at the top, and maybe even place the .\eng\build.cmd ... commands in a separate table for "less common" commands. Especially since a couple sentences ago we said

It is not recommended to run the top-level build script for the repo.

BrennanConroy · 2021-10-19T16:38:14Z

docs/RepoDependencies.md

+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| [Git source control](https://git-scm.org/)                   | Used for cloning, branching, and other source control-related activities in the repo. |
+| [.NET](https://dotnet.microsoft.com/)                        | A preview version of the .NET SDK is used for building projects within the repo. |
+| [NodeJS]()                                                   | Used for building JavaScript assets in the repo.             |


Unless I'm mistaken Node and Yarn are optional, used when building SignalR client or Blazor
And Yarn is installed and used automatically if you use the build script.

And Yarn is installed and used automatically if you use the build script.

I wasn't sure of this. The last time I had to build the repo from a clean set up I needed to install yarn separately. Do you have a reference to where in the scripts we install it?

Unless I'm mistaken Node and Yarn are optional, used when building SignalR client or Blazor

Correct. However, since we have users run a repo-wide restore before they activate their dotnet environment and launch the editor Node/Yarn are needed for the install phase in the restore.

aspnetcore/global.json

Line 31 in 1aa3490

"Yarn.MSBuild": "1.22.10",

https://github.com/natemcmaster/Yarn.MSBuild#usage

Guess it doesn't matter much if we move away from Yarn soon

BrennanConroy · 2021-10-19T16:44:47Z

docs/UsingBuildResults.md

+</configuration>
+```
+
+In the project files for your repo, update the package versions to target the development version. For example, if you want to validate changes to the `Microsoft.AspNetCore.Components.WebAssembly` package. You can make the following changes to the PackageReference.


Sadly, I don't think it's this easy for many projects in the repo.
a) we don't produce packages for many projects
b) you often need to reference other dlls (aspnet shared fx) and probably the same runtime shared fx that was used to build the repo

Agreed -- with this being in a separate doc we can expand on different ways to test under each scenarios.

If you were to add another set of instructions here, what would that be?

The old docs mentioned:

Run the installers produced in artifacts/installers/{Debug, Release}/ for your platform.

I've never gotten that to work, and maybe it doesn't, but if we could have something "simple" like that it would be great.

Personally I've never had a clean experience using the locally built product in an external app, I've had to do things like modify a file in the bin folder of the built app etc.

You can reference the dlls directly using <Reference Include="path to assembly" />

I've never gotten that to work, and maybe it doesn't, but if we could have something "simple" like that it would be great.

I've been in the same situation so that's why I removed reference to the installers in this doc. I've never had it work. cc: @dougbu in case there is an issue to resolve here.

Personally I've never had a clean experience using the locally built product in an external app, I've had to do things like modify a file in the bin folder of the built app etc.

@davidfowl uses HintPath in the reference to help with some of this.

In any case, I think sorting out these types of integrated validation scenarios is another issue worth tracking.

Co-authored-by: Kevin Pilch <kevinpi@microsoft.com>

Tratcher

Overall this is a cleaner approach. It needs a little more detail on the "things I need to install" section.

Tratcher · 2021-10-21T20:34:25Z

docs/RepoDependencies.md

+| Dependency                                                   | Use                                                          |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| [Git source control](https://git-scm.org/)                   | Used for cloning, branching, and other source control-related activities in the repo. |
+| [.NET](https://dotnet.microsoft.com/)                        | A preview version of the .NET SDK is used for building projects within the repo. |


They don't actually need to install this, it will be downloaded for them.

Tratcher · 2021-10-21T20:35:42Z

docs/RepoDependencies.md

+| [.NET](https://dotnet.microsoft.com/)                        | A preview version of the .NET SDK is used for building projects within the repo. |
+| [NodeJS]()                                                   | Used for building JavaScript assets in the repo.             |
+| [Yarn](https://yarnpkg.com/)                                 | Used for installing JavaScript dependencies in the repo.     |
+| [curl](https://curl.haxx.se/)/[wget](https://www.gnu.org/software/wget) | Used for downloading installation files and assets from the web. |


Preinstalled?

Tratcher · 2021-10-21T20:38:01Z

docs/RepoDependencies.md

@@ -0,0 +1,25 @@
+# Repo Dependencies


This page is not helpful from the perspective of someone trying to build the repo. Which of these do I need to install vs which are acquired automatically or come built in? What's the minimum version I need?

Visual Studio and it's many components are a required build dependencies on Windows that's not listed here.

Listing the minimum required version will likely get out of date, but we could link to the place in the repo that defines it.

dougbu

I have a nagging feeling we've lost useful text while things moved around. Is that valid❔

dougbu · 2021-10-21T23:52:01Z

docs/BuildFromSource.md

-ASP.NET Core uses git submodules to include the source from a few other projects. In order to pull the sources of the these submodules when cloning the repo, be sure to pass the `--recursive` flag to the `git clone` command.
-
-```powershell
+```


Avoid Markdown lint warnings about leaving code blocks without a type. Use bash if you don't like powershell. This is a general problem throughout this PR.

dougbu · 2021-10-21T23:53:01Z

docs/BuildFromSource.md

-
-Development is done in your own repo, not directly against the official `dotnet/aspnetcore` repo. To create your own fork, click the __Fork__ button from our GitHub repo as a signed-in user and your own fork will be created.
-
-> :bulb: All other steps below will be against your fork of the aspnetcore repo (e.g. `YOUR_USERNAME/aspnetcore`), not the official `dotnet/aspnetcore` repo.


Not sure but this note seems useful

dougbu · 2021-10-25T19:19:48Z

docs/RepoDependencies.md

+| [NodeJS]()                                                   | Used for building JavaScript assets in the repo.             |
+| [Yarn](https://yarnpkg.com/)                                 | Used for installing JavaScript dependencies in the repo.     |
+| [curl](https://curl.haxx.se/)/[wget](https://www.gnu.org/software/wget) | Used for downloading installation files and assets from the web. |
+| [tar](http://gnuwin32.sourceforge.net/packages/gtar.htm)     | Used for unzipping installation assets. Included by default on macOS, Linux, and Windows 10 and above. |


We previously mentioned gtar.htm as a fallback only. On Windows, users should stick w/ the pre-installed program or use eng/scripts/InstallTar.ps1 to place the git copy where the build will find it.

dougbu · 2021-10-25T19:27:24Z

docs/UsingBuildResults.md

+To start, build the packages with your changes locally on your repo.
+
+```
+.\build.cmd -all -pack -arch x64


Suggested change

.\build.cmd -all -pack -arch x64

.\eng\build.cmd -all -pack -arch x64

dougbu · 2021-10-25T19:30:29Z

docs/BuildFromSource.md


- Update the versions on `PackageReference` items in your .csproj project file to point to the version from your local build.
+The `build.cmd` and `build.sh` scripts contain multiple flags that can be used control the behavior of the build script. See [BuildScript](./BuildScript.md) for information about the flags available on the script and helpful invocation patterns.


Suggested change

The `build.cmd` and `build.sh` scripts contain multiple flags that can be used control the behavior of the build script. See [BuildScript](./BuildScript.md) for information about the flags available on the script and helpful invocation patterns.

The `eng\build.cmd` and `eng/build.sh` scripts contain multiple flags that can be used control the behavior of the build script. See [BuildScript](./BuildScript.md) for information about the flags available on the script and helpful invocation patterns.

dougbu · 2021-10-25T19:31:20Z

docs/BuildScript.md

+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| `.\eng\build.cmd -all -pack -arch x64`                       | Build development packages for all the shipping projects in the repo. |
+| `.\eng\build.cmd -test -projects .\src\Framework\test\Microsoft.AspNetCore.App.UnitTests.csproj` | Run all the unit tests in the `Microsoft.AspNetCore.App.UnitTests` project. |
+| `.\build.cmd -Configuration Release`                         | Build projects in a subdirectory using a `Release` configuration. |


Suggested change

| `.\build.cmd -Configuration Release` | Build projects in a subdirectory using a `Release` configuration. |

| `.\eng\build.cmd -Configuration Release` | Build projects in a subdirectory using a `Release` configuration. |

dougbu · 2021-10-25T19:32:27Z

docs/BuildFromSource.md

-```
-
-On macOS/Linux, you can run the shell script:
+4. Once you've opened the project in VS Code, you can build and test changes by running the `./build.sh` command in the terminal.


Suggested change

4. Once you've opened the project in VS Code, you can build and test changes by running the `./build.sh` command in the terminal.

4. Once you've opened the project in VS Code, you can build and test changes by running the `./eng/build.sh` command in the terminal.

dougbu · 2021-10-25T19:32:44Z

docs/BuildFromSource.md

 ./build.sh
+./build.sh -test


Suggested change

./build.sh

./build.sh -test

./eng/build.sh

./eng/build.sh -test

dougbu · 2021-10-25T19:35:52Z

src/Components/Web.JS/package.json

+  },
+  "engines": {
+    "node": "16.x"


@captainsafia how do these additions fit in w/ the doc changes❔

dougbu · 2021-10-25T19:38:00Z

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{


Unclear how this fits in

Pilchie added the area-infrastructure Includes: MSBuild projects/targets, build scripts, CI, Installers and shared framework label Oct 8, 2021

captainsafia force-pushed the safia/doc-update branch from fe59350 to bd1633d Compare October 11, 2021 17:08

adityamandaleeka reviewed Oct 11, 2021

View reviewed changes

docs/BuildFromSource.md Outdated Show resolved Hide resolved

adityamandaleeka reviewed Oct 12, 2021

View reviewed changes

docs/BuildFromSource.md Outdated Show resolved Hide resolved

adityamandaleeka reviewed Oct 12, 2021

View reviewed changes

TanayParikh mentioned this pull request Oct 13, 2021

Update build from source doc 33411 #37497

Closed

4 tasks

captainsafia added 2 commits October 16, 2021 20:48

Refresh BuildFromSource docs

4561c10

Address feedback from peer review and set Node engine version

165a466

captainsafia force-pushed the safia/doc-update branch from ca1059f to 165a466 Compare October 17, 2021 03:48

captainsafia marked this pull request as ready for review October 19, 2021 03:44

captainsafia requested review from BrennanConroy, halter73, mkArtakMSFT, Pilchie and a team as code owners October 19, 2021 03:44

captainsafia requested review from a team, rafikiassumani-msft and Tratcher October 19, 2021 03:44

captainsafia commented Oct 19, 2021

View reviewed changes

Pilchie reviewed Oct 19, 2021

View reviewed changes

BrennanConroy reviewed Oct 19, 2021

View reviewed changes

Apply suggestions from code review

fd2e24a

Co-authored-by: Kevin Pilch <kevinpi@microsoft.com>

Tratcher reviewed Oct 21, 2021

View reviewed changes

dougbu reviewed Oct 25, 2021

View reviewed changes

captainsafia closed this Jan 6, 2022

captainsafia mentioned this pull request Feb 1, 2022

Update CONTRIBUTING.md for project #27562

Closed

captainsafia mentioned this pull request Apr 28, 2022

Documentation : Guide for building the project requires some additional steps #37240

Open

captainsafia deleted the safia/doc-update branch July 20, 2022 20:35

captainsafia mentioned this pull request Sep 22, 2022

Update BuildFromSource docs to be more scenario focused #44127

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refresh BuildFromSource docs #37362

Refresh BuildFromSource docs #37362

captainsafia commented Oct 7, 2021 •

edited

Loading

adityamandaleeka Oct 12, 2021

davidfowl commented Oct 17, 2021

captainsafia Oct 19, 2021

Pilchie Oct 19, 2021

Pilchie left a comment

Pilchie Oct 19, 2021

Pilchie Oct 19, 2021

BrennanConroy Oct 19, 2021

BrennanConroy Oct 19, 2021 •

edited

Loading

captainsafia Oct 20, 2021

BrennanConroy Oct 20, 2021

BrennanConroy Oct 19, 2021

captainsafia Oct 19, 2021

BrennanConroy Oct 19, 2021

davidfowl Oct 20, 2021 •

edited

Loading

captainsafia Oct 20, 2021

Tratcher left a comment

Tratcher Oct 21, 2021

Tratcher Oct 21, 2021

Tratcher Oct 21, 2021

Tratcher Oct 21, 2021

dougbu left a comment

dougbu Oct 21, 2021

dougbu Oct 21, 2021

dougbu Oct 25, 2021

dougbu Oct 25, 2021

dougbu Oct 25, 2021

dougbu Oct 25, 2021

dougbu Oct 25, 2021

dougbu Oct 25, 2021

dougbu Oct 25, 2021

dougbu Oct 25, 2021


		#### Java Development Kit on Windows
		## Visual Studio Code on Windows, Linux, Mac


		## Step 5: Use the result of your build
		![Screen Shot 2021-10-05 at 9 05 39 AM](https://user-images.githubusercontent.com/1857993/136060792-6b4c6158-0a2c-4dd6-8639-08d83da6d2d1.png)


		Development is done in your own repo, not directly against the official `dotnet/aspnetcore` repo. To create your own fork, click the __Fork__ button from our GitHub repo as a signed-in user and your own fork will be created.

		> :bulb: All other steps below will be against your fork of the aspnetcore repo (e.g. `YOUR_USERNAME/aspnetcore`), not the official `dotnet/aspnetcore` repo.

	.\build.cmd -all -pack -arch x64
	.\eng\build.cmd -all -pack -arch x64


		- Update the versions on `PackageReference` items in your .csproj project file to point to the version from your local build.
		The `build.cmd` and `build.sh` scripts contain multiple flags that can be used control the behavior of the build script. See [BuildScript](./BuildScript.md) for information about the flags available on the script and helpful invocation patterns.

	The `build.cmd` and `build.sh` scripts contain multiple flags that can be used control the behavior of the build script. See [BuildScript](./BuildScript.md) for information about the flags available on the script and helpful invocation patterns.
	The `eng\build.cmd` and `eng/build.sh` scripts contain multiple flags that can be used control the behavior of the build script. See [BuildScript](./BuildScript.md) for information about the flags available on the script and helpful invocation patterns.

	\| `.\build.cmd -Configuration Release` \| Build projects in a subdirectory using a `Release` configuration. \|
	\| `.\eng\build.cmd -Configuration Release` \| Build projects in a subdirectory using a `Release` configuration. \|

	4. Once you've opened the project in VS Code, you can build and test changes by running the `./build.sh` command in the terminal.
	4. Once you've opened the project in VS Code, you can build and test changes by running the `./eng/build.sh` command in the terminal.

Refresh BuildFromSource docs #37362

Refresh BuildFromSource docs #37362

Conversation

captainsafia commented Oct 7, 2021 • edited Loading

Choose a reason for hiding this comment

davidfowl commented Oct 17, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Pilchie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BrennanConroy Oct 19, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidfowl Oct 20, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Tratcher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dougbu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

captainsafia commented Oct 7, 2021 •

edited

Loading

BrennanConroy Oct 19, 2021 •

edited

Loading

davidfowl Oct 20, 2021 •

edited

Loading