| area-ILTools | @BruceForstall @dotnet/jit-contrib | |
| area-Infrastructure-coreclr | @jeffschwMSFT @jashook @trylek | |
| area-Infrastructure-installer | @dleeapho @wtgodbe @dagood | |
-| area-Infrastructure-libraries | @ViktorHofer @ericstj @wtgodbe @safern @Anipik | Covers:<ul><li>Packaging</li><li>Build and test infra for CoreFX repo</li><li>VS integration</li></ul><br/> |
+| area-Infrastructure-libraries | @ViktorHofer @ericstj @wtgodbe @safern @Anipik | Covers:<ul><li>Packaging</li><li>Build and test infra for libraries in dotnet/runtime repo</li><li>VS integration</li></ul><br/> |
| area-Infrastructure | @ViktorHofer @jeffschwMSFT @dleeapho | |
| area-Interop | @jeffschwMSFT @AaronRobinsonMSFT | |
| area-Meta | @joperezr | Issues without clear association to any specific API/contract, e.g. <ul><li>new contract proposals</li><li>cross-cutting code/test pattern changes (e.g. FxCop failures)</li><li>project-wide docs</li></ul><br/> |
## Making the changes in repo
**If changing the library version**
- - Update the `AssemblyVersion` property in `<Library>\Directory.Build.props` (ex: [System.Runtime\Directory.Build.props](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/Directory.Build.props#L4)) to the version determined above.
+- The `AssemblyVersion` property isn't always in `<Library>\Directory.Build.props` file unless we want to override the default for some reason. For more information on how the original version is calculated, see [Arcade documentation](https://github.com/dotnet/arcade/blob/master/Documentation/CorePackages/Versioning.md).
+- If the `AssemblyVersion` property exists (for example, [Microsoft.CSharp\Directory.Build.props](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.CSharp/Directory.Build.props#L4)), you can change it.
+- If the `AssemblyVersion` property doesn't exist (for example, [System.Runtime\Directory.Build.props](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Runtime/Directory.Build.props)), you can add it.
**If changing the target group**
- Update both the `Configurations` property in the library's csproj file and the `BuildConfigurations` property in the library's Configurations.props file.
Cross-Platform Guidelines
=========================
-This page provides a FAQ for how we handle cross-platform code in CoreFX. (For structuring of interop code, see [interop guidelines](interop-guidelines.md).)
+This page provides a FAQ for how we handle cross-platform code in dotnet/runtime. (For structuring of interop code, see [interop guidelines](interop-guidelines.md).)
#### Should assemblies be binary-compatible across platforms (e.g. exact same System.IO.dll on Windows, Linux, and Mac)?
-Our expectation is that the majority (estimating around 70%) of CoreFX assemblies will have no platform-specific code. These assemblies should be binary-compatible across platforms.
+Our expectation is that the majority (estimating around 70%) of dotnet/runtime assemblies will have no platform-specific code. These assemblies should be binary-compatible across platforms.
In some cases, the managed binary will be used across all platforms, but it'll come with its own native library that'll be compiled once per platform.
==================
## Goals
-We have the following goals related to interop code being used in CoreFX:
+We have the following goals related to interop code being used in dotnet/runtime:
- Minimize code duplication for interop.
- We should only define a given interop signature in a single place. This stuff is tricky, and we shouldn't be copy-and-pasting it.
```
### Build System
-When building CoreFx, we use the "OSGroup" property to control what target platform we are building for. The valid values for this property are Windows_NT (which is the default value from MSBuild when running on Windows), Linux and OSX.
+When building dotnet/runtime, we use the "OSGroup" property to control what target platform we are building for. The valid values for this property are Windows_NT (which is the default value from MSBuild when running on Windows), Linux and OSX.
The build system sets a few MSBuild properties, depending on the OSGroup setting:
This leaves us with a situation where we can't write portable P/Invoke declarations that will work on all flavors, and writing separate declarations per flavor is quite fragile and won't scale.
-To address this, we're moving to a model where all UNIX interop from corefx starts with a P/Invoke to a C++ lib written specifically for corefx. These libs -- System.*.Native.so (aka "shims") -- are intended to be very thin layers over underlying platform libraries. Generally, they are not there to add any significant abstraction, but to create a stable ABI such that the same IL assembly can work across UNIX flavors.
+To address this, we're moving to a model where all UNIX interop from dotnet/runtime starts with a P/Invoke to a C++ lib written specifically for dotnet/runtime. These libs -- System.*.Native.so (aka "shims") -- are intended to be very thin layers over underlying platform libraries. Generally, they are not there to add any significant abstraction, but to create a stable ABI such that the same IL assembly can work across UNIX flavors.
Guidelines for shim C++ API:
- Don't cheat and take advantage of coincidental agreement between one flavor's ABI and the shim's ABI.
- Use PascalCase in a style closer to Win32 than libc.
- If an export point has a 1:1 correspondence to the platform API, then name it after the platform API in PascalCase (e.g. stat -> Stat, fstat -> FStat).
- - If an export is not 1:1, then spell things out as we typically would in CoreFX code (i.e. don't use abbreviations unless they come from the underlying API.
+ - If an export is not 1:1, then spell things out as we typically would in dotnet/runtime code (i.e. don't use abbreviations unless they come from the underlying API.
- At first, it seemed that we'd want to use 1:1 names throughout, but it turns out there are many cases where being strictly 1:1 isn't practical.
- In order to reduce the chance of collisions when linking with CoreRT, all exports should have a prefix that corresponds to the Libraries' name, e.g. "SystemNative_" or "CryptoNative_" to make the method name more unique. See https://github.com/dotnet/corefx/issues/4818.
- Stick to data types which are guaranteed not to vary in size across flavors.
-## dotnet/CoreFx
+## dotnet/runtime
+
### Libraries in NETStandard
+
- ref
- Default targetgroup should be NETCoreApp build
- P2P references to other reference assembly CSProjs.
### End goal
-- CoreFx does not build any reference assemblies for NETStandard.
-- For every library in NETStandard.Library, the only configurations in CoreFx are framework-specific. EG: netcoreapp3.0, net472
+- dotnet/runtime does not build any reference assemblies for NETStandard.
+- For every library in NETStandard.Library, the only configurations in dotnet/runtime are framework-specific. EG: netcoreapp3.0, net472
- For every library in NETCore.App but not in NETStandard.Library there must be a framework-specific configuration for NETCoreApp1.2. Other configurations may exist to ship in a package, but those will not be built by folks building just NETCore.App.
Libraries should select a version of DotNet/NETStandard that supports the most frameworks. This means the library should choose the lowest version that provides all the API needed to implement their functionality. Eventually this will be the same moniker used for package resolution in the library project, AKA in `frameworks` section for the libraries project.json.
-In CoreFx we don't always use the package resolution for dependencies, sometimes we must use project references. Additionally we aren't building all projects with the NETStandard/DotNet identifier. This issue is tracked with https://github.com/dotnet/corefx/issues/2427. As a result we calculate the version as an added safeguard based on seeds. These seeds are listed in [Generations.json](https://github.com/dotnet/buildtools/blob/master/src/Microsoft.DotNet.Build.Tasks.Packaging/src/PackageFiles/Generations.json) and rarely change. They are a record of what libraries shipped in-box and are unchangeable for a particular framework supporting a generation. Occasionally an API change can be made even to these in-box libraries and shipped out-of-band, for example by adding a new type and putting that type in a hybrid facade. This is the only case when it is permitted to update Generations.json.
+In dotnet/runtime we don't always use the package resolution for dependencies, sometimes we must use project references. Additionally we aren't building all projects with the NETStandard/DotNet identifier. This issue is tracked with https://github.com/dotnet/corefx/issues/2427. As a result we calculate the version as an added safeguard based on seeds. These seeds are listed in [Generations.json](https://github.com/dotnet/buildtools/blob/master/src/Microsoft.DotNet.Build.Tasks.Packaging/src/PackageFiles/Generations.json) and rarely change. They are a record of what libraries shipped in-box and are unchangeable for a particular framework supporting a generation. Occasionally an API change can be made even to these in-box libraries and shipped out-of-band, for example by adding a new type and putting that type in a hybrid facade. This is the only case when it is permitted to update Generations.json.
In addition to the minimum API version required by implementation, reference assemblies should only claim the NETStandard/DotNet version of the minimum implementation assembly. Just because a reference assembly only depends on API in NETStandard1.0, if its implementations only apply to frameworks supporting NETStandard1.4, it should use NETStandard1.4.
Managed Code Performance Guidelines
===================================
-Different applications have different needs when it comes to performance. For libraries that may be used in any of them and potentially on critical paths, however, it is of the utmost importance that code is as efficient as possible. The code in CoreFX should strive to be high-performing, including minimizing the number and size of allocations, minimizing the number of branches involved in code, and overall minimizing the amount of work that must be done to perform any given operation.
+Different applications have different needs when it comes to performance. For libraries that may be used in any of them and potentially on critical paths, however, it is of the utmost importance that code is as efficient as possible. The code in dotnet/runtime should strive to be high-performing, including minimizing the number and size of allocations, minimizing the number of branches involved in code, and overall minimizing the amount of work that must be done to perform any given operation.
Much has been written about writing high-performance code in C#. This page provides links to some of that material and will expand over time as additional resources are found and identified as being relevant and useful.
# PInvoke Analyzer
-During the build of any product library in CoreFX we use a Roslyn code analyzer to look for disallowed native calls (PInvokes). When there is a violation, it will fail the build. To fix the build, either find an alternative to the PInvoke or baseline the failure temporarily. To baseline it, add the function name in the format `module!entrypoint` to a file named PInvokeAnalyzerExceptionList.analyzerdata in the same folder as the project. [Here](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Process/src/PInvokeAnalyzerExceptionList.analyzerdata) is an example.
+During the build of any product library in dotnet/runtime, we use a Roslyn code analyzer to look for disallowed native calls (PInvokes). When there is a violation, it will fail the build. To fix the build, either find an alternative to the PInvoke or baseline the failure temporarily. To baseline it, add the function name in the format `module!entrypoint` to a file named PInvokeAnalyzerExceptionList.analyzerdata in the same folder as the project. [Here](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.Process/src/PinvokeAnalyzerExceptionList.analyzerdata.netcoreapp) is an example.
If you baseline a violation, please open an issue to fix it because the library likely cannot ship in this situation. It is better to not introduce the violation. We want to clean out any baselines. There are situations where a violation may be acceptable. One situation is where we are shipping the native implementation of the API. An example of this situation is `sni.dll` which is used by SqlClient.
# Build Project Guidelines
-In order to work in corefx repo you must first run build.cmd/sh from the root of the repo at least
+In order to work in dotnet/runtime repo you must first run build.cmd/sh from the root of the repo at least
once before you can iterate and work on a given library project.
## Behind the scenes with build.cmd/sh
projects / platform / upstream / dotnet / runtime.git / commitdiff