Make it more clear that installation script use is optional (#18277)
Also address Markdown warnings in BuildFromSource.md - surround bare URLs with angle brackets - add languages to code blocks - fix missing blank lines and style inconsistencies
This commit is contained in:
Doug Bunting
GitHub
parent
df712cc4a9
commit
d6796bda6c
|
|
@ -1,9 +1,8 @@
|
|||
Build ASP.NET Core from Source
|
||||
==============================
|
||||
# Build ASP.NET Core from Source
|
||||
|
||||
Building ASP.NET Core from source allows you to tweak and customize ASP.NET Core, and to contribute your improvements back to the project.
|
||||
|
||||
See https://github.com/dotnet/aspnetcore/labels/area-infrastructure for known issues and to track ongoing work.
|
||||
See <https://github.com/dotnet/aspnetcore/labels/area-infrastructure> for known issues and to track ongoing work.
|
||||
|
||||
## Install pre-requisites
|
||||
|
||||
|
|
@ -14,20 +13,27 @@ Building ASP.NET Core on Windows requires:
|
|||
* Windows 10, version 1803 or newer
|
||||
* At least 10 GB of disk space and a good internet connection (our build scripts download a lot of tools and dependencies)
|
||||
* Visual Studio 2019. <https://visualstudio.com>
|
||||
* To install the exact required components, run [eng/scripts/InstallVisualStudio.ps1](/eng/scripts/InstallVisualStudio.ps1).
|
||||
```ps1
|
||||
PS> ./eng/scripts/InstallVisualStudio.ps1
|
||||
```
|
||||
* To install the exact required components, run [eng/scripts/InstallVisualStudio.ps1](/eng/scripts/InstallVisualStudio.ps1).
|
||||
|
||||
```ps1
|
||||
PS> ./eng/scripts/InstallVisualStudio.ps1
|
||||
```
|
||||
|
||||
However, any Visual Studio 2019 instance that meets the requirements should be fine. See [global.json](/global.json)
|
||||
and [eng/scripts/vs.json](/eng/scripts/vs.json) for those requirements.
|
||||
* Git. <https://git-scm.org>
|
||||
* NodeJS. LTS version of 10.14.2 or newer <https://nodejs.org>
|
||||
* Java Development Kit 11 or newer. Either:
|
||||
* OpenJDK <https://jdk.java.net/>
|
||||
* Oracle's JDK <https://www.oracle.com/technetwork/java/javase/downloads/index.html>
|
||||
* To install a version of the JDK that will only be used by this repo, run [eng/scripts/InstallJdk.ps1](/eng/scripts/InstallJdk.ps1)
|
||||
```ps1
|
||||
PS> ./eng/scripts/InstallJdk.ps1
|
||||
```
|
||||
* Chrome - Selenium-based tests require a version of Chrome to be installed. Download and install it from [https://www.google.com/chrome]
|
||||
* OpenJDK <https://jdk.java.net/>
|
||||
* Oracle's JDK <https://www.oracle.com/technetwork/java/javase/downloads/index.html>
|
||||
* To install a version of the JDK that will only be used by this repo, run [eng/scripts/InstallJdk.ps1](/eng/scripts/InstallJdk.ps1)
|
||||
|
||||
```ps1
|
||||
PS> ./eng/scripts/InstallJdk.ps1
|
||||
```
|
||||
|
||||
However, the build should find any JDK 11 or newer installation on the machine.
|
||||
* Chrome - Selenium-based tests require a version of Chrome to be installed. Download and install it from <https://www.google.com/chrome>
|
||||
|
||||
### macOS/Linux
|
||||
|
||||
|
|
@ -39,20 +45,22 @@ Building ASP.NET Core on macOS or Linux requires:
|
|||
* Git <https://git-scm.org>
|
||||
* NodeJS. LTS version of 10.14.2 or newer <https://nodejs.org>
|
||||
* Java Development Kit 11 or newer. Either:
|
||||
* OpenJDK <https://jdk.java.net/>
|
||||
* Oracle's JDK <https://www.oracle.com/technetwork/java/javase/downloads/index.html>
|
||||
* OpenJDK <https://jdk.java.net/>
|
||||
* Oracle's JDK <https://www.oracle.com/technetwork/java/javase/downloads/index.html>
|
||||
|
||||
## Clone the source code
|
||||
|
||||
ASP.NET Core uses git submodules to include the source from a few other projects.
|
||||
|
||||
For a new copy of the project, run:
|
||||
```
|
||||
|
||||
```ps1
|
||||
git clone --recursive https://github.com/dotnet/aspnetcore
|
||||
```
|
||||
|
||||
To update an existing copy, run:
|
||||
```
|
||||
|
||||
```ps1
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
|
|
@ -61,9 +69,11 @@ git submodule update --init --recursive
|
|||
Before opening our .sln files in Visual Studio or VS Code, you need to perform the following actions.
|
||||
|
||||
1. Executing the following on command-line:
|
||||
```
|
||||
|
||||
```ps1
|
||||
.\restore.cmd
|
||||
```
|
||||
|
||||
This will download the required tools and build the entire repository once. At that point, you should be able to open .sln files to work on the projects you care about.
|
||||
|
||||
> :bulb: Pro tip: you will also want to run this command after pulling large sets of changes. On the master branch, we regularly update the versions of .NET Core SDK required to build the repo.
|
||||
|
|
@ -74,7 +84,7 @@ Before opening our .sln files in Visual Studio or VS Code, you need to perform t
|
|||
### Solution files
|
||||
|
||||
We don't have a single .sln file for all of ASP.NET Core because Visual Studio doesn't currently handle projects of this scale.
|
||||
Instead, we have many .sln files which include a sub-set of projects. These principles guide how we create and manage .slns:
|
||||
Instead, we have many .sln files which include a sub-set of projects. These principles guide how we create and manage .sln files:
|
||||
|
||||
1. Solution files are not used by CI or command line build scripts. They are meant for use by developers only.
|
||||
2. Solution files group together projects which are frequently edited at the same time.
|
||||
|
|
@ -90,10 +100,12 @@ Opening solution files and building may produce an error code CS0006 with a mess
|
|||
|
||||
The cause of this problem is that the solution you are using does not include the project that produces this .dll. This most often occurs after we have added new projects to the repo, but failed to update our .sln files to include the new project. In some cases, it is sometimes the intended behavior of the .sln which has been crafted to only include a subset of projects.
|
||||
|
||||
**You can fix this in one of two ways**
|
||||
#### You can fix this in one of two ways
|
||||
|
||||
1. Build the project on command line. In most cases, running `build.cmd` on command line solves this problem.
|
||||
2. Update the solution to include the missing project. You can either do this one by one using `dotnet sln`
|
||||
```
|
||||
|
||||
```ps1
|
||||
dotnet sln add C:\src\AspNetCore\src\Hosting\Abstractions\src\Microsoft.AspNetCore.Hosting.Abstractions.csproj
|
||||
```
|
||||
|
||||
|
|
@ -112,6 +124,7 @@ Using Visual Studio Code with this repo requires setting environment variables o
|
|||
Use these command to launch VS Code with the right settings.
|
||||
|
||||
On Windows (requires PowerShell):
|
||||
|
||||
```ps1
|
||||
# The extra dot at the beginning is required to 'dot source' this file into the right scope.
|
||||
|
||||
|
|
@ -120,7 +133,8 @@ code .
|
|||
```
|
||||
|
||||
On macOS/Linux:
|
||||
```
|
||||
|
||||
```bash
|
||||
source activate.sh
|
||||
code .
|
||||
```
|
||||
|
|
@ -130,12 +144,14 @@ code .
|
|||
You can also build the entire project on command line with the `build.cmd`/`.sh` scripts.
|
||||
|
||||
On Windows:
|
||||
```
|
||||
|
||||
```ps1
|
||||
.\build.cmd
|
||||
```
|
||||
|
||||
On macOS/Linux:
|
||||
```
|
||||
|
||||
```bash
|
||||
./build.sh
|
||||
```
|
||||
|
||||
|
|
@ -155,6 +171,7 @@ On Windows (requires PowerShell):
|
|||
```
|
||||
|
||||
On macOS/Linux:
|
||||
|
||||
```bash
|
||||
source ./activate.sh
|
||||
```
|
||||
|
|
@ -164,12 +181,14 @@ source ./activate.sh
|
|||
Tests are not run by default. Use the `-test` option to run tests in addition to building.
|
||||
|
||||
On Windows:
|
||||
```
|
||||
|
||||
```ps1
|
||||
.\build.cmd -test
|
||||
```
|
||||
|
||||
On macOS/Linux:
|
||||
```
|
||||
|
||||
```bash
|
||||
./build.sh --test
|
||||
```
|
||||
|
||||
|
|
@ -182,7 +201,8 @@ Furthermore, you can use flags on `build.cmd`/`.sh` to build subsets based on la
|
|||
## Build properties
|
||||
|
||||
Additional properties can be added as an argument in the form `/property:$name=$value`, or `/p:$name=$value` for short. For example:
|
||||
```
|
||||
|
||||
```ps1
|
||||
.\build.cmd /p:Configuration=Release
|
||||
```
|
||||
|
||||
|
|
@ -199,8 +219,8 @@ TargetOsName | The base runtime identifier to build for (win, linux,
|
|||
After building ASP.NET Core from source, you will need to install and use your local version of ASP.NET Core.
|
||||
See ["Artifacts"](./Artifacts.md) for more explanation of the different folders produced by a build.
|
||||
|
||||
- Run the installers produced in `artifacts/installers/{Debug, Release}/` for your platform.
|
||||
- Add a NuGet.Config to your project directory with the following content:
|
||||
* Run the installers produced in `artifacts/installers/{Debug, Release}/` for your platform.
|
||||
* Add a NuGet.Config to your project directory with the following content:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
|
|
@ -215,7 +235,8 @@ See ["Artifacts"](./Artifacts.md) for more explanation of the different folders
|
|||
|
||||
*NOTE: This NuGet.Config should be with your application unless you want nightly packages to potentially start being restored for other apps on the machine.*
|
||||
|
||||
- Update the versions on `PackageReference` items in your .csproj project file to point to the version from your local build.
|
||||
* Update the versions on `PackageReference` items in your .csproj project file to point to the version from your local build.
|
||||
|
||||
```xml
|
||||
<ItemGroup>
|
||||
<PackageReference Include="Microsoft.AspNetCore.SpaServices" Version="3.0.0-dev" />
|
||||
|
|
|
|||
Loading…
Reference in New Issue