You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/core/build/distribution-packaging.md
+99-43Lines changed: 99 additions & 43 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,17 +27,34 @@ When installed, .NET Core consists of several components that are laid out as fo
27
27
├── sdk
28
28
│ ├── <sdk version> (3)
29
29
│ └── NuGetFallbackFolder (4)
30
-
└── shared
31
-
├── Microsoft.NETCore.App
32
-
│ └── <runtime version> (5)
33
-
└── Microsoft.AspNetCore.App
34
-
└── <aspnetcore version> (6)
35
-
└── Microsoft.AspNetCore.All
36
-
└── <aspnetcore version> (7)
30
+
├── packs
31
+
│ ├── Microsoft.AspNetCore.App.Ref
32
+
│ │ └── <aspnetcore ref version> (11)
33
+
│ ├── Microsoft.NETCore.App.Ref
34
+
│ │ └── <netcore ref version> (12)
35
+
│ ├── Microsoft.NETCore.App.Host.<rid>
36
+
│ │ └── <apphost version> (13)
37
+
│ ├── Microsoft.WindowsDesktop.App.Ref
38
+
│ │ └── <desktop ref version> (14)
39
+
│ └── NETStandard.Library.Ref
40
+
│ └── <netstandard version> (15)
41
+
├── shared
42
+
│ ├── Microsoft.NETCore.App
43
+
│ │ └── <runtime version> (5)
44
+
│ ├── Microsoft.AspNetCore.App
45
+
│ │ └── <aspnetcore version> (6)
46
+
│ ├── Microsoft.AspNetCore.All
47
+
│ │ └── <aspnetcore version> (6)
48
+
│ └── Microsoft.WindowsDesktop.App
49
+
│ └── <desktop app version> (7)
50
+
└── templates
51
+
│ └── <templates version> (17)
37
52
/
38
-
├─usr/share/man/man1
53
+
├── etc/dotnet
54
+
│ └── install_location (16)
55
+
├── usr/share/man/man1
39
56
│ └── dotnet.1.gz (9)
40
-
└─usr/bin
57
+
└── usr/bin
41
58
└── dotnet (10)
42
59
```
43
60
@@ -49,18 +66,32 @@ While there's a single host, most of the other components are in versioned direc
49
66
50
67
- (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.
51
68
52
-
- (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`.
69
+
- (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`.
53
70
54
71
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.
55
72
56
73
- (5) **shared/Microsoft.NETCore.App/\<runtime version>** This framework contains the .NET Core runtime and supporting managed libraries.
57
74
58
-
- (6,7) **shared/Microsoft.AspNetCore.{App,All}/\<aspnetcore version>** contains the ASP.NET Core libraries. The libraries under `Microsoft.AspNetCore.App` are developed and supported as part of the .NET Core project. The libraries under `Microsoft.AspNetCore.All` are a superset that also contains third-party libraries.
75
+
- (6) **shared/Microsoft.AspNetCore.{App,All}/\<aspnetcore version>** contains the ASP.NET Core libraries. The libraries under `Microsoft.AspNetCore.App` are developed and supported as part of the .NET Core project. The libraries under `Microsoft.AspNetCore.All` are a superset that also contains third-party libraries.
76
+
77
+
- (7) **shared/Microsoft.Desktop.App/\<desktop app version>** contains the Windows desktop libraries. This isn't included on non-Windows platforms.
59
78
60
79
- (8) **LICENSE.txt,ThirdPartyNotices.txt** are the .NET Core license and licenses of third-party libraries used in .NET Core, respectively.
61
80
62
81
- (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.
63
82
83
+
- (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.
84
+
85
+
- (13) **Microsoft.NETCore.App.Host.\<rid>** contains a native binary for platform `rid`. This binary is a template when compiling a .NET Core application into a native binary for that platform.
86
+
87
+
- (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.
88
+
89
+
- (15) **NETStandard.Library.Ref** describes the netstandard `x.y` API. These files are used when compiling for that target.
90
+
91
+
- (16) **/etc/dotnet/install_location** is a 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`.
92
+
93
+
- (17) **templates** contains the templates used by the SDK. For example, `dotnet new` finds project templates here.
94
+
64
95
## Recommended packages
65
96
66
97
.NET Core versioning is based on the runtime component `[major].[minor]` version numbers.
@@ -70,50 +101,75 @@ For example: SDK version 2.2.302 is the second patch release of the third featur
70
101
Some of the packages include part of the version number in their name. This allows you to install a specific version.
71
102
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.
72
103
73
-
The following table shows the recommended packages:
104
+
The following lists the recommended packages:
74
105
75
-
| Name | Example | Use case: Install ... | Contains | Dependencies | Version |
- The third-party libraries under `shared/Microsoft.AspNetCore.All` can't be easily built from source. So that folder is omitted from the `aspnetcore-runtime` package.
118
+
*`dotnet-runtime-deps-[major].[minor]`_(Optional)_ - Installs the dependencies for running self-contained applications
119
+
***Version:**\<runtime version>
120
+
***Example:** dotnet-runtime-deps-2.1
121
+
***Dependencies:**_distro specific dependencies_
88
122
89
-
- The `NuGetFallbackFolder` is populated using binary artifacts from `nuget.org`. It should remain empty.
123
+
*`dotnet-runtime-[major].[minor]` - Installs a specific runtime
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).
129
+
*`dotnet-hostfxr` - dependency
130
+
***Version:**\<runtime version>
131
+
***Example:** dotnet-hostfxr
132
+
***Contains:** (2)
133
+
***Dependencies:**`host:<runtime version>+`
92
134
93
-
### Preview versions
135
+
*`dotnet-host` - dependency
136
+
***Version:**\<runtime version>
137
+
***Example:** dotnet-host
138
+
***Contains:** (1),(8),(9),(10),(16)
94
139
95
-
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.
*`dotnet-targeting-pack-[major].[minor]` - Allows targeting a non-latest runtime
145
+
***Version:**\<runtime version>
146
+
***Contains:** (12)
98
147
99
-
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.
148
+
*`aspnetcore-targeting-pack-[major].[minor]` - Allows targeting a non-latest runtime
149
+
***Version:**\<aspnetcore runtime version>
150
+
***Contains:** (11)
100
151
101
-
The following table shows the recommended packages and **patch packages**:
152
+
*`netstandard-targeting-pack-[major].[minor]` - Allows targeting a netstandard version
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.
160
+
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.
161
+
162
+
When package content is under a versioned folder, the package name `[major].[minor]` match the versioned folder name. For all packages, except the `netstandard-targeting-pack-[major].[minor]`, this also matches with the .NET Core version.
163
+
164
+
Dependencies between packages should use a _equal or greater than_ version requirement. For example, `dotnet-sdk-2.2:2.2.401` requires `aspnetcore-runtime-2.2 >= 2.2.6`. This makes it possible for the user to upgrade their installation via a root package (e.g. `dnf update dotnet-sdk-2.2`).
165
+
166
+
Most distributions require all artifacts to be built from source. This has some impact on the packages:
167
+
168
+
- The third-party libraries under `shared/Microsoft.AspNetCore.All` can't be easily built from source. So that folder is omitted from the `aspnetcore-runtime` package.
169
+
170
+
- The `NuGetFallbackFolder` is populated using binary artifacts from `nuget.org`. It should remain empty.
171
+
172
+
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).
0 commit comments