Nate McMaster
Родитель
399221e645
Коммит
d6b8907eea
74
README.md
74
README.md
|
|
@ -9,78 +9,24 @@ Utilities used in the build system for projects that are used with ASP.NET Core
|
|||
|
||||
This project is part of ASP.NET Core. You can find samples, documentation and getting started instructions for ASP.NET Core at the [Home](https://github.com/aspnet/home) repo.
|
||||
|
||||
## Utilities
|
||||
## Docs
|
||||
|
||||
### KoreBuild
|
||||
See [docs/Intro.md](./docs/Intro.md).
|
||||
|
||||
Channel | Latest Build
|
||||
-------------|----------------
|
||||
dev | ![badge][dev-badge]
|
||||
rel/2.0.2 | ![badge][rel-2.0.2-badge]
|
||||
rel/2.0.0 | ![badge][rel-2.0.0-badge]
|
||||
## Latest build
|
||||
|
||||
Channel | Latest Build
|
||||
---------------|:---------------
|
||||
dev | ![badge][dev-badge]
|
||||
release/2.0.0 | ![badge][rel-2.0.0-badge]
|
||||
|
||||
[dev-badge]: https://aspnetcore.blob.core.windows.net/buildtools/korebuild/channels/dev/badge.svg
|
||||
[rel-2.0.2-badge]: https://aspnetcore.blob.core.windows.net/buildtools/korebuild/channels/rel/2.0.2/badge.svg
|
||||
[rel-2.0.0-badge]: https://aspnetcore.blob.core.windows.net/buildtools/korebuild/channels/rel/2.0.0/badge.svg
|
||||
[rel-2.0.0-badge]: https://aspnetcore.blob.core.windows.net/buildtools/korebuild/channels/release/2.0.0/badge.svg
|
||||
|
||||
This tool contains build scripts, console tools, MSBuild targets, and other settings required to build ASP.NET Core.
|
||||
|
||||
#### KoreBuild commands
|
||||
|
||||
Previously repositories were runable in only one way, by doing `.\build.cmd`. KoreBuild commands allow you to take wider and more granular actions.
|
||||
|
||||
Command | Purpose | Example
|
||||
-------------|------------------------------------------------------------------|----------
|
||||
install-tools| Installs dotnet, CLI and Shared runtimes. | .\run.ps1 install-tools
|
||||
docker-build | Runs the build inside docker. | .\run.ps1 docker-build {jessie\|winservercore} /t:SomeTarget /p:Parameters
|
||||
default-build| Runs install-tools followed by msbuild (like build.cmd used to). | .\run.ps1 default-build /t:SomeTarget /p:Parameters
|
||||
msbuild | Runs the build normally. | .\run.ps1 msbuild /t:SomeTarget /p:Parameters
|
||||
upgrade deps | Upgrade the dependencies.props of this project. | .\run.ps1 upgrade deps
|
||||
generate deps| Generate a dependencies.props for this project. | .\run.ps1 generate deps
|
||||
|
||||
### KoreBuild config
|
||||
|
||||
KoreBuild can be configured by adding a 'korebuild.json' file into the root folder of your repository.
|
||||
|
||||
Example:
|
||||
```js
|
||||
// NB: Don't actually use comments in JSON files. PowerShell's ConvertFrom-Json will throw an error.
|
||||
|
||||
{
|
||||
// add this for editor auto-completion :)
|
||||
"$schema": "https://raw.githubusercontent.com/aspnet/BuildTools/dev/tools/korebuild.schema.json",
|
||||
|
||||
// specifies the channel used to update KoreBuild to new versions when you attempt to upgrade KoreBuild
|
||||
"channel": "dev",
|
||||
|
||||
"toolsets": {
|
||||
// All toolsets listed in this section are treated as required toolsets
|
||||
|
||||
"visualstudio": {
|
||||
// defaults to `true`
|
||||
"includePrerelease": false,
|
||||
|
||||
// see https://aka.ms/vs/workloads
|
||||
"requiredWorkloads": [
|
||||
"Microsoft.VisualStudio.Component.VSSDK"
|
||||
],
|
||||
|
||||
// Default = no minimum version
|
||||
"minVersion": "15.4",
|
||||
|
||||
// This tool is only required on Windows.
|
||||
"required": [ "windows" ]
|
||||
},
|
||||
|
||||
"nodejs": {
|
||||
"required": true,
|
||||
"minVersion": "8.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Local testing
|
||||
## Local testing
|
||||
To test changes to this project locally we recomend you do:
|
||||
|
||||
```ps1
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
Intro to BuildTools
|
||||
------------------
|
||||
-------------------
|
||||
|
||||
This repo contains console tools, MSBuild tasks, and targets used to build ASP.NET Core.
|
||||
This document is a high-level overview of how these build tools work.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,73 @@
|
|||
KoreBuild
|
||||
=========
|
||||
---------
|
||||
|
||||
KoreBuild is a set of MSBuild targets and tasks used to define a common set of build and test tasks. The entry point for KoreBuild is defined in [KoreBuild.proj][korebuild-proj].
|
||||
KoreBuild is a set of MSBuild targets, tasks, and console commands used to define a common set of build and test tasks.
|
||||
|
||||
## KoreBuild Lifecycle
|
||||
## Usage
|
||||
|
||||
The KoreBuild chains together these targets in this order. Custom targets can chain off these.
|
||||
### KoreBuild commands
|
||||
|
||||
KoreBuild commands allow you to take wider and more granular actions.
|
||||
Previously repositories were runable in only one way, by doing `.\build.cmd`. But now, you can run multiple options.
|
||||
|
||||
Command | Purpose | Example
|
||||
-------------|------------------------------------------------------------------|----------
|
||||
install-tools| Installs dotnet, CLI and Shared runtimes. | .\run.ps1 install-tools
|
||||
docker-build | Runs the build inside docker. | .\run.ps1 docker-build {jessie\|winservercore} /t:SomeTarget /p:Parameters
|
||||
default-build| Runs install-tools followed by msbuild (like build.cmd used to). | .\run.ps1 default-build /t:SomeTarget /p:Parameters
|
||||
msbuild | Runs the build normally. | .\run.ps1 msbuild /t:SomeTarget /p:Parameters
|
||||
upgrade deps | Upgrade the dependencies.props of this project. | .\run.ps1 upgrade deps
|
||||
generate deps| Generate a dependencies.props for this project. | .\run.ps1 generate deps
|
||||
|
||||
### KoreBuild config
|
||||
|
||||
KoreBuild can be configured by adding a 'korebuild.json' file into the root folder of your repository.
|
||||
|
||||
Example:
|
||||
```js
|
||||
// NB: Don't actually use comments in JSON files. PowerShell's ConvertFrom-Json will throw an error.
|
||||
|
||||
{
|
||||
// add this for editor auto-completion :)
|
||||
"$schema": "https://raw.githubusercontent.com/aspnet/BuildTools/dev/tools/korebuild.schema.json",
|
||||
|
||||
// specifies the channel used to update KoreBuild to new versions when you attempt to upgrade KoreBuild
|
||||
"channel": "dev",
|
||||
|
||||
"toolsets": {
|
||||
// All toolsets listed in this section are treated as required toolsets
|
||||
|
||||
"visualstudio": {
|
||||
// defaults to `true`
|
||||
"includePrerelease": false,
|
||||
|
||||
// see https://aka.ms/vs/workloads
|
||||
"requiredWorkloads": [
|
||||
"Microsoft.VisualStudio.Component.VSSDK"
|
||||
],
|
||||
|
||||
// Default = no minimum version
|
||||
"minVersion": "15.4",
|
||||
|
||||
// This tool is only required on Windows.
|
||||
"required": [ "windows" ]
|
||||
},
|
||||
|
||||
"nodejs": {
|
||||
"required": true,
|
||||
"minVersion": "8.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## MSBuild
|
||||
|
||||
The `msbuild` command runs an MSBuild process that executes a series of targets against the entire repository. The entry point for this MSBuild process is defined in [KoreBuild.proj][korebuild-proj].
|
||||
|
||||
### KoreBuild Lifecycle
|
||||
|
||||
The KoreBuild lifecycle chains together these targets in this order. Custom targets can chain off these.
|
||||
|
||||
1. Prepare - pre-build actions like making directories
|
||||
1. Restore - NuGet restore
|
||||
|
|
@ -16,7 +78,7 @@ The KoreBuild chains together these targets in this order. Custom targets can ch
|
|||
|
||||
When not specified, the default target is `/t:Build`, which runs all of these lifecycle targets.
|
||||
|
||||
## Other common targets
|
||||
### Other common targets
|
||||
|
||||
These targets are also available, but are not run in the default lifecycle.
|
||||
|
||||
|
|
@ -26,9 +88,10 @@ These targets are also available, but are not run in the default lifecycle.
|
|||
- Noop - a target that does nothing
|
||||
- Publish - pushes artifacts to NuGet feeds and blob stores
|
||||
|
||||
## Extensibility points
|
||||
|
||||
### Modules
|
||||
### Extensibility points
|
||||
|
||||
#### Modules
|
||||
|
||||
KoreBuild is designed to be a modular system. It is written as a backbone of default lifecycle targets and imports.
|
||||
Default functionality, such as building solutions and testing with VSTest, are written as modules in `files/KoreBuild/modules`.
|
||||
|
|
@ -39,7 +102,7 @@ These include tasks for downloading NuGet packages, creating Zip files, retrievi
|
|||
Additional KoreBuild modules can be imported by setting `CustomKoreBuildModulesPath` as a property or environment variable.
|
||||
Anything matching `$(CustomKoreBuildModulesPath)/*/module.props` and `$(CustomKoreBuildModulesPath)/*/modules.targets` will be imported into KoreBuild.
|
||||
|
||||
### RepoTasks
|
||||
#### RepoTasks
|
||||
|
||||
RepoTasks is a C# project that can be used to define MSBuild tasks that apply only to a specific repository.
|
||||
|
||||
|
|
@ -65,36 +128,36 @@ Sample contents:
|
|||
```
|
||||
|
||||
|
||||
### repo.props
|
||||
#### repo.props
|
||||
```
|
||||
<root>/build/repo.props
|
||||
```
|
||||
|
||||
If this file exists, it is imported shortly after [KoreBuild.Common.props][../files/KoreBUild/KoreBuild.Common.props].
|
||||
If this file exists, it is imported shortly after [KoreBuild.Common.props][../files/KoreBuild/KoreBuild.Common.props].
|
||||
|
||||
>**Best practies**: Only define properties and settings in \*.props files.
|
||||
>**Best practices**: Only define properties and settings in \*.props files.
|
||||
|
||||
### repo.targets
|
||||
#### repo.targets
|
||||
|
||||
```
|
||||
<root>/build/repo.targets
|
||||
```
|
||||
|
||||
If this file exists, it is imported shortly after [KoreBuild.Common.targets][../files/KoreBUild/KoreBuild.Common.targets].
|
||||
If this file exists, it is imported shortly after [KoreBuild.Common.targets][../files/KoreBuild/KoreBuild.Common.targets].
|
||||
|
||||
>**Best practies**: Define custom build steps in \*.targets files.
|
||||
>**Best practices**: Define custom build steps in \*.targets files.
|
||||
|
||||
|
||||
### version.props
|
||||
#### version.props
|
||||
|
||||
```
|
||||
<root>/version.props
|
||||
```
|
||||
|
||||
If this file exists, it is imported shortly after [KoreBuild.Common.props][../files/KoreBUild/KoreBuild.Common.props]. It should contain settings like VerisonPrefix, PackageVersion, VerisonSuffix, and others.
|
||||
If this file exists, it is imported shortly after [KoreBuild.Common.props][../files/KoreBuild/KoreBuild.Common.props]. It should contain settings like VerisonPrefix, PackageVersion, VerisonSuffix, and others.
|
||||
|
||||
These values can be used to ensure that all NuGet packages produced have the same version.
|
||||
|
||||
>**Best practies**: This file should contain all settings related to asset versions.
|
||||
>**Best practices**: This file should contain all settings related to asset versions.
|
||||
|
||||
[korebuild-proj]: ../files/KoreBuild/KoreBuild.proj
|
||||
|
|
|
|||
|
|
@ -96,8 +96,7 @@
|
|||
"default": "dev",
|
||||
"enum": [
|
||||
"dev",
|
||||
"rel/2.0.0",
|
||||
"rel/2.0.2"
|
||||
"release/2.0.0"
|
||||
]
|
||||
},
|
||||
"toolsets": {
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче