Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update package guidelines for .NET Core 3.0 #13196

Merged
merged 29 commits into from
Sep 5, 2019
Merged

Update package guidelines for .NET Core 3.0 #13196

Changes from 19 commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
7ac8513
Update package guidelines for .NET Core 3.0
tmds Jul 1, 2019
dfa9f10
Add separate packages for netcoreapp and aspnet, and update names
tmds Jul 2, 2019
101634e
Rename dotnet-netcoreapp-targeting-pack to dotnet-targeting-pack
tmds Jul 9, 2019
b9963ff
Align with Microsoft packages
tmds Jul 9, 2019
d73b28a
Remove section on preview versions
tmds Jul 9, 2019
0352d9c
Format table into list
tmds Jul 10, 2019
632a09a
Add /etc/dotnet/install_location
tmds Jul 10, 2019
22ad323
Add dotnet-runtime-deps package
tmds Jul 11, 2019
12baa27
Update docs/core/build/distribution-packaging.md
tmds Jul 12, 2019
52b02ee
Update docs/core/build/distribution-packaging.md
tmds Jul 12, 2019
74af8cd
Update docs/core/build/distribution-packaging.md
tmds Jul 12, 2019
073d8ba
Update docs/core/build/distribution-packaging.md
tmds Jul 12, 2019
f6f0e93
Update docs/core/build/distribution-packaging.md
tmds Jul 12, 2019
e2877b4
Update docs/core/build/distribution-packaging.md
tmds Jul 12, 2019
7aa74f7
Update docs/core/build/distribution-packaging.md
tmds Jul 12, 2019
feac66a
Update docs/core/build/distribution-packaging.md
tmds Jul 12, 2019
c1f78d0
Update docs/core/build/distribution-packaging.md
tmds Jul 12, 2019
bb9a77d
Update docs/core/build/distribution-packaging.md
tmds Aug 23, 2019
a84c102
Declare dotnet-runtime-deps optional
tmds Aug 23, 2019
3a2e226
Remove dotnet- prefix from {netstandard,aspnetcore}-targetting-pack
tmds Aug 26, 2019
875e8a9
Remove dotnet-sdk-[major] package
tmds Aug 26, 2019
17e8cb2
Add templates package
tmds Aug 28, 2019
4122e67
Explain package name [major].[minor]
tmds Aug 28, 2019
66ea7bb
Add recommendation to use >= for version requirements
tmds Aug 28, 2019
29291ce
Use sdk version for packages used by the sdk (packs/templates)
tmds Aug 28, 2019
51e87e8
Fix sdk version number
tmds Aug 28, 2019
b8c3e47
Tweak some package versions
tmds Aug 30, 2019
e8f9126
Apply suggestions from code review
tmds Sep 3, 2019
33b4c5d
Include Microsoft.WindowsDesktop.App
tmds Sep 5, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 86 additions & 41 deletions docs/core/build/distribution-packaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,17 +27,30 @@ When installed, .NET Core consists of several components that are laid out as fo
├── sdk
tmds marked this conversation as resolved.
Show resolved Hide resolved
│ ├── <sdk version> (3)
│ └── NuGetFallbackFolder (4)
├── packs
│ ├── Microsoft.AspNetCore.App.Ref
│ │ └── <aspnetcore ref version> (11)
│ ├── Microsoft.NETCore.App.Ref
│ │ └── <netcore ref version> (12)
│ ├── Microsoft.NETCore.App.Host.<rid>
│ │ └── <apphost version> (13)
│ ├── Microsoft.WindowsDesktop.App.Ref
│ │ └── <desktop ref version> (14)
│ └── NETStandard.Library.Ref
│ └── <netstandard version> (15)
└── shared
├── Microsoft.NETCore.App
│ └── <runtime version> (5)
└── Microsoft.AspNetCore.App
└── <aspnetcore version> (6)
├── Microsoft.AspNetCore.App
│ └── <aspnetcore version> (6)
└── Microsoft.AspNetCore.All
└── <aspnetcore version> (7)
/
├─usr/share/man/man1
├── etc/dotnet
│ └── install_location (16)
├── usr/share/man/man1
│ └── dotnet.1.gz (9)
└─usr/bin
└── usr/bin
└── dotnet (10)
```

Expand All @@ -49,7 +62,7 @@ While there's a single host, most of the other components are in versioned direc

- (3) **sdk/\<sdk version>** The SDK (also known as "the tooling") is a set of managed tools that are used to write and build .NET Core libraries and applications. The SDK includes the .NET Core Command-line interface (CLI), the managed languages compilers, MSBuild, and associated build tasks and targets, NuGet, new project templates, and so on.

- (4) **sdk/NuGetFallbackFolder** contains a cache of NuGet packages used by an SDK during the restore operation, such as when running `dotnet restore` or `dotnet build /t:Restore`.
- (4) **sdk/NuGetFallbackFolder** contains a cache of NuGet packages used by an SDK during the restore operation, such as when running `dotnet restore` or `dotnet build /t:Restore`. This folder is only used prior to .NET Core 3.0. It can't be built from source, because it contains prebuilt binary assets from `nuget.org`.

The **shared** folder contains frameworks. A shared framework provides a set of libraries at a central location so they can be used by different applications.

Expand All @@ -61,6 +74,16 @@ The **shared** folder contains frameworks. A shared framework provides a set of

- (9,10) **dotnet.1.gz, dotnet** `dotnet.1.gz` is the dotnet manual page. `dotnet` is a symlink to the dotnet host(1). These files are installed at well known locations for system integration.

- (11,12) **Microsoft.NETCore.App.Ref,Microsoft.AspNetCore.App.Ref** describe the API of an `x.y` version of .NET Core and ASP.NET Core respectively. These packs are used when compiling for those target versions.

- (13) **Microsoft.NETCore.App.Host.\<rid>** contains a native binary for platform `rid`. This binary as a template when compiling a .NET Core application into a native binary for that platform.
tmds marked this conversation as resolved.
Show resolved Hide resolved

- (14) **Microsoft.WindowsDesktop.App.Ref** describes the API of `x.y` version of Windows Desktop applications. These files are used when compiling for that target. This isn't provided on non-Windows platforms.
tmds marked this conversation as resolved.
Show resolved Hide resolved

- (15) **NETStandard.Library.Ref** describes the netstandard `x.y` API. These files are used when compiling for that target.

- (16) **/etc/dotnet/install_location** file that contains the full path to the folder that contains the `dotnet` host binary. The path may be terminated with a newline. It's not necessary to add this file when the root is `/usr/share/dotnet`.
tmds marked this conversation as resolved.
Show resolved Hide resolved

## Recommended packages

.NET Core versioning is based on the runtime component `[major].[minor]` version numbers.
Expand All @@ -70,17 +93,64 @@ For example: SDK version 2.2.302 is the second patch release of the third featur
Some of the packages include part of the version number in their name. This allows you to install a specific version.
The rest of the version isn't included in the version name. This allows the OS package manager to update the packages (for example, automatically installing security fixes). Supported package managers are Linux specific.

The following table shows the recommended packages:

| Name | Example | Use case: Install ... | Contains | Dependencies | Version |
|-----------------------------------------|------------------------|---------------------------------|--------------------|------------------------------------------------|--------------------|
| dotnet-sdk-[major] | dotnet-sdk-2 | Latest sdk for runtime major | | dotnet-sdk-[major].[latestminor] | \<sdk version> |
| dotnet-sdk-[major].[minor] | dotnet-sdk-2.1 | Latest sdk for specific runtime | | dotnet-sdk-[major].[minor].[latest sdk feat]xx | \<sdk version> |
| dotnet-sdk-[major].[minor].[sdk feat]xx | dotnet-sdk-2.1.3xx | Specific sdk feature release | (3),(4) | aspnetcore-runtime-[major].[minor] | \<sdk version> |
| aspnetcore-runtime-[major].[minor] | aspnetcore-runtime-2.1 | Specific ASP.NET Core runtime | (6),[(7)] | dotnet-runtime-[major].[minor] | \<runtime version> |
| dotnet-runtime-[major].[minor] | dotnet-runtime-2.1 | Specific runtime | (5) | host-fxr:\<runtime version>+ | \<runtime version> |
| dotnet-host-fxr | dotnet-host-fxr | _dependency_ | (2) | host:\<runtime version>+ | \<runtime version> |
| dotnet-host | dotnet-host | _dependency_ | (1),(8),(9),(10) | | \<runtime version> |
The following lists the recommended packages:

* `dotnet-sdk-[major]` - Installs the latest sdk for runtime major
* **Version:** \<sdk version>
* **Example:** dotnet-sdk-2
* **Dependencies:** `dotnet-sdk-[major].[latestminor]`

* `dotnet-sdk-[major].[minor]` - Installs the latest sdk for specific runtime
* **Version:** \<runtime version>
* **Example:** dotnet-sdk-2.1
* **Contains:** (3),(4)
* **Dependencies:** `aspnetcore-runtime-[major].[minor]`, `dotnet-netcoreapp-targeting-pack[major].[minor]`, `dotnet-aspnetcore-targeting-pack[major].[minor]`, `dotnet-netstandard-targeting-pack-[netstandard_major].[netstandard_minor]`, `dotnet-apphost-pack-[major].[minor]`

* `aspnetcore-runtime-[major].[minor]` - Installs specific ASP.NET Core runtime
tmds marked this conversation as resolved.
Show resolved Hide resolved
* **Version:** \<aspnetcore runtime version>
* **Example:** aspnetcore-runtime-2.1
* **Contains:** (6),(7)
* **Dependencies:** `dotnet-runtime-[major].[minor]`

* `dotnet-runtime-deps-[major].[minor]` _(Optional)_ - Installs the dependencies for running self-contained applications
* **Version:** \<runtime version>
* **Example:** dotnet-runtime-deps-2.1
* **Dependencies:** _distro specific dependencies_

* `dotnet-runtime-[major].[minor]` - Installs a specific runtime
* **Version:** \<runtime version>
* **Example:** dotnet-runtime-2.1
* **Contains:** (5)
* **Dependencies:** `dotnet-hostfxr:<runtime version>+`, `dotnet-runtime-deps-[major].[minor]`

* `dotnet-hostfxr` - dependency
* **Version:** \<runtime version>
* **Example:** dotnet-hostfxr
* **Contains:** (2)
* **Dependencies:** `host:<runtime version>+`

* `dotnet-host` - dependency
* **Version:** \<runtime version>
* **Example:** dotnet-host
* **Contains:** (1),(8),(9),(10),(16)

* `dotnet-apphost-pack-[major].[minor]` - dependency
* **Version:** \<runtime version>
* **Contains:** (13)

* `dotnet-targeting-pack-[major].[minor]` - Allows targeting a non-latest runtime
* **Version:** \<runtime version>
* **Contains:** (12)

* `aspnetcore-targeting-pack-[major].[minor]` - Allows targeting a non-latest runtime
* **Version:** \<aspnetcore runtime version>
* **Contains:** (11)

* `netstandard-targeting-pack-[major].[minor]` - Allows targeting a netstandard version
* **Version:** \<netstandard version>
* **Contains:** (15)

The `dotnet-runtime-deps-[major].[minor]` requires understanding the _distro specific dependencies_. Because the distro build system may be able to derive this automatically, the package is optional, in which case these dependencies are added directly to the `dotnet-runtime-[major].[minor]` package.

Most distributions require all artifacts to be built from source. This has some impact on the packages:

Expand All @@ -90,31 +160,6 @@ Most distributions require all artifacts to be built from source. This has some

Multiple `dotnet-sdk` packages may provide the same files for the `NuGetFallbackFolder`. To avoid issues with the package manager, these files should be identical (checksum, modification date, and so on).

### Preview versions

Package maintainers may decide to provide preview versions of the shared framework and SDK. Preview releases may be provided using the `dotnet-sdk-[major].[minor].[sdk feat]xx`, `aspnetcore-runtime-[major].[minor]`, or `dotnet-runtime-[major].[minor]` packages. For preview releases, the package version major must be set to zero. This way, the final release is installed as an upgrade of the package.

### Patch packages

Since a patch version of a package may cause a breaking change, a package maintainer may want to provide _patch packages_. These packages allow you to install a specific patch version that isn't automatically upgraded. Only use patch packages in rare circumstances as they aren't upgraded with (security) fixes.

The following table shows the recommended packages and **patch packages**:

| Name | Example | Contains | Dependencies |
|------------------------------------------------|--------------------------|------------------|-----------------------------------------------------------|
| dotnet-sdk-[major] | dotnet-sdk-2 | | dotnet-sdk-[major].[latest sdk minor] |
| dotnet-sdk-[major].[minor] | dotnet-sdk-2.1 | | dotnet-sdk-[major].[minor].[latest sdk feat]xx |
| dotnet-sdk-[major].[minor].[sdk feat]xx | dotnet-sdk-2.1.3xx | | dotnet-sdk-[major].[minor].[latest sdk patch] |
| **dotnet-sdk-[major].[minor].[patch]** | dotnet-sdk-2.1.300 | (3),(4) | aspnetcore-runtime-[major].[minor].[sdk runtime patch] |
| aspnetcore-runtime-[major].[minor] | aspnetcore-runtime-2.1 | | aspnetcore-runtime-[major].[minor].[latest runtime patch] |
| **aspnetcore-runtime-[major].[minor].[patch]** | aspnetcore-runtime-2.1.0 | (6),[(7)] | dotnet-runtime-[major].[minor].[patch] |
| dotnet-runtime-[major].[minor] | dotnet-runtime-2.1 | | dotnet-runtime-[major].[minor].[latest runtime patch] |
| **dotnet-runtime-[major].[minor].[patch]** | dotnet-runtime-2.1.0 | (5) | host-fxr:\<runtime version>+ |
| dotnet-host-fxr | dotnet-host-fxr | (2) | host:\<runtime version>+ |
| dotnet-host | dotnet-host | (1),(8),(9),(10) | |

An alternative to using patch packages is _pinning_ the packages to a specific version using the package manager. To avoid affecting other applications/users, such applications can be built and deployed in a container.

## Building packages

The [dotnet/source-build](https://github.com/dotnet/source-build) repository provides instructions on how to build a source tarball of the .NET Core SDK and all its components. The output of the source-build repository matches the layout described in the first section of this article.