-# Contributing
+Contribution to .NET Runtime
+=====================
-See [Contributing](Documentation/project-docs/contributing.md) for information about coding styles, source structure, making pull requests, and more.
+You can contribute to .NET Runtime with issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated.
-# Developers
+## Contribution "Bar"
-See the [Developer Guide](Documentation/project-docs/developer-guide.md) for details about developing in this repo.
+Project maintainers will merge changes that improve the product significantly and broadly and that align with the [.NET Core roadmap](https://github.com/dotnet/core/blob/master/roadmap.md).
+
+Maintainers will not merge changes that have narrowly-defined benefits, due to compatibility risk. The .NET Core codebase is used by several Microsoft products (for example, ASP.NET Core, .NET Framework 4.x, Windows Universal Apps) to enable execution of managed code. Other companies are building products on top of .NET, too. We may revert changes if they are found to be breaking.
+
+Contributions must also satisfy the other published guidelines defined in this document.
+
+## DOs and DON'Ts
+
+Please do:
+
+* **DO** follow our [coding style](docs/coding-guidelines/coding-style.md) (C# code-specific)
+* **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
+* **DO** include tests when adding new features. When fixing bugs, start with
+ adding a test that highlights how the current behavior is broken.
+* **DO** keep the discussions focused. When a new or related topic comes up
+ it's often better to create new issue than to side track the discussion.
+* **DO** blog and tweet (or whatever) about your contributions, frequently!
+
+Please do not:
+
+* **DON'T** make PRs for style changes.
+* **DON'T** surprise us with big pull requests. Instead, file an issue and start
+ a discussion so we can agree on a direction before you invest a large amount
+ of time.
+* **DON'T** commit code that you didn't write. If you find code that you think is a good fit to add to .NET Core, file an issue and start a discussion before proceeding.
+* **DON'T** submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it.
+* **DON'T** add API additions without filing an issue and discussing with us first. See [API Review Process](docs/project-docs/api-review-process.md).
+
+## Managed Code Compatibility
+
+Contributions must maintain [API signature](docs/coding-guidelines/breaking-changes.md#bucket-1-public-contract) and behavioral compatibility. Contributions that include [breaking changes](docs/coding-guidelines/breaking-changes.md) will be rejected. Please file an issue to discuss your idea or change if you believe that it may affect managed code compatibility.
+
+## Suggested Workflow
+
+We use and recommend the following workflow:
+
+1. Create an issue for your work.
+ - You can skip this step for trivial changes.
+ - Reuse an existing issue on the topic, if there is one.
+ - Get agreement from the team and the community that your proposed change is a good one.
+ - If your change adds a new API, follow the [API Review Process](docs/project/api-reivew-process.md).
+ - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.
+2. Create a personal fork of the repository on GitHub (if you don't already have one).
+3. Create a branch off of master (`git checkout -b mybranch`).
+ - Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue.
+ - Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
+4. Make and commit your changes.
+ - Please follow our [Commit Messages](#commit-messages) guidance.
+5. Add new tests corresponding to your change, if applicable.
+6. Build the repository with your changes.
+ - Make sure that the builds are clean.
+ - Make sure that the tests are all passing, including your new tests.
+7. Create a pull request (PR) against the upstream repository's **master** branch.
+ - Push your changes to your fork on GitHub (if you haven't already).
+
+Note: It is OK for your PR to include a large number of commits. Once your change is accepted, you will be asked to squash your commits into one or some appropriately small number of commits before your PR is merged.
+
+Note: It is OK to create your PR as "[WIP]" on the upstream repo before the implementation is done. This can be useful if you'd like to start the feedback process concurrent with your implementation. State that this is the case in the initial PR comment.
+
+## Up for Grabs
+
+The team marks the most straightforward issues as [up for grabs](https://github.com/dotnet/corefx/labels/up-for-grabs). This set of issues is the place to start if you are interested in contributing but new to the codebase.
+
+## Commit Messages
+
+Please format commit messages as follows (based on [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)):
+
+```
+Summarize change in 50 characters or less
+
+Provide more detail after the first line. Leave one blank line below the
+summary and wrap all lines at 72 characters or less.
+
+If the change fixes an issue, leave another blank line after the final
+paragraph and indicate which issue is fixed in the specific format
+below.
+
+Fix #42
+```
+
+Also do your best to factor commits appropriately, not too large with unrelated things in the same commit, and not too small with the same small change applied N times in N different commits.
+
+## Contributor License Agreement
+
+You must sign a [.NET Foundation Contribution License Agreement (CLA)](https://cla.dotnetfoundation.org) before your PR will be merged. This is a one-time requirement for projects in the .NET Foundation. You can read more about [Contribution License Agreements (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia.
+
+The agreement: [net-foundation-contribution-license-agreement.pdf](https://github.com/dotnet/home/blob/master/guidance/net-foundation-contribution-license-agreement.pdf)
+
+You don't have to do this up-front. You can simply clone, fork, and submit your pull-request as usual. When your pull-request is created, it is classified by a CLA bot. If the change is trivial (for example, you just fixed a typo), then the PR is labelled with `cla-not-required`. Otherwise it's classified as `cla-required`. Once you signed a CLA, the current and all future pull-requests will be labelled as `cla-signed`.
+
+## File Headers
+
+The following file header is the used for .NET Core. Please use it for new files.
+
+```
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+```
+
+- See [class.cpp](../../src/vm/class.cpp) for an example of the header in a C++ file.
+- See [List.cs](../../src/System.Private.CoreLib/shared/System/Collections/Generic/List.cs) for an example of the header in a C# file.
+
+## PR - CI Process
+
+The [dotnet continuous integration](https://dev.azure.com/dnceng/public/) (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean.
+
+If the CI build fails for any reason, the PR issue will be updated with a link that can be used to determine the cause of the failure.
+
+## PR Feedback
+
+Microsoft team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback.
+
+One or more Microsoft team members will review every PR prior to merge. They will often reply with "LGTM, modulo comments". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me".
+
+There are lots of thoughts and [approaches](https://github.com/antlr/antlr4-cpp/blob/master/CONTRIBUTING.md#emoji) for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback.
+
+## Contributing Ports
+
+We encourage ports of CoreCLR to other platforms. There are multiple ports ongoing at any one time. You may be interested in one of the following ports:
+
+Chips:
+
+- [ARM32](https://github.com/dotnet/coreclr/labels/arch-arm32)
+- [ARM64](https://github.com/dotnet/coreclr/labels/arch-arm64)
+- [X86](https://github.com/dotnet/coreclr/labels/arch-x86)
+
+Operating System:
+
+- [Linux](https://github.com/dotnet/coreclr/labels/os-linux)
+- [macOS](https://github.com/dotnet/coreclr/labels/os-mac-os-x)
+- [Windows Subsystem for Linux](https://github.com/dotnet/coreclr/labels/os-windows-wsl)
+- [FreeBSD](https://github.com/dotnet/coreclr/labels/os-freebsd)
+
+Note: Add links to install instructions for each of these ports.
+
+Ports have a weaker contribution bar, at least initially. A functionally correct implementation is considered an important first goal. Performance, reliability and compatibility are all important concerns after that.
+
+### Copying Files from Other Projects
+
+.NET Core uses some files from other projects, typically where a binary distribution does not exist or would be inconvenient.
+
+The following rules must be followed for PRs that include files from another project:
+
+- The license of the file is [permissive](https://en.wikipedia.org/wiki/Permissive_free_software_licence).
+- The license of the file is left in-tact.
+- The contribution is correctly attributed in the [3rd party notices](../../THIRD-PARTY-NOTICES.TXT) file in the repository, as needed.
+
+See [IdnMapping.cs](../../src/System.Private.CoreLib/shared/System/Globalization/IdnMapping.cs) for an example of a file copied from another project and attributed in the [CoreCLR 3rd party notices](../../THIRD-PARTY-NOTICES.TXT) file.
+
+### Porting Files from Other Projects
+
+There are many good algorithms implemented in other languages that would benefit the .NET Core project. The rules for porting a Java file to C# , for example, are the same as would be used for copying the same file, as described above.
+
+[Clean-room](https://en.wikipedia.org/wiki/Clean_room_design) implementations of existing algorithms that are not permissively licensed will generally not be accepted. If you want to create or nominate such an implementation, please create an issue to discuss the idea.
<InstallerProjectRoot>$([MSBuild]::NormalizeDirectory('$(RepoRoot)', 'src', 'installer'))</InstallerProjectRoot>
<DocsDir>$([MSBuild]::NormalizeDirectory('$(RepoRoot)', 'docs'))</DocsDir>
- <ManPagesDir>$([MSBuild]::NormalizeDirectory('$(DocsDir)', 'installer', 'manpages'))</ManPagesDir>
+ <ManPagesDir>$([MSBuild]::NormalizeDirectory('$(DocsDir)', 'manpages'))</ManPagesDir>
<CoreLibSharedDir>$([MSBuild]::NormalizeDirectory('$(LibrariesProjectRoot)', 'System.Private.CoreLib', 'src'))</CoreLibSharedDir>
</PropertyGroup>
-# Documentation
\ No newline at end of file
+Documents Index
+===============
+
+This repo includes several documents that explain both high-level and low-level concepts about the .NET runtime and libraries. These are very useful for contributors, to get context that can be very difficult to acquire from just reading code.
+
+Intro to .NET
+==================
+
+.NET is a self-contained .NET runtime and framework that implements ECMA 335. It can be (and has been) ported to multiple architectures and platforms. It support a variety of installation options, having no specific deployment requirements itself.
+
+Getting Started
+===============
+
+- [Installing the .NET SDK](https://dotnet.microsoft.com/download)
+- [Official .NET Docs](https://docs.microsoft.com/dotnet/core/)
+
+Software requirements
+===============
+- [Windows Requirements](workflow/windows-requirements.md)
+- [Linux Requirements](workflow/linux-requirements.md)
+- [MacOS Requirements](workflow/macos-requirements.md)
+
+Workflow (Building, testing, etc.)
+===============
+- [Workflow Instructions](workflow/README.md)
+
+Design Docs
+=================
+
+- [.NET Globalization Invariant Mode](design/features/globalization-invariant-mode.md)
+- [Cross-Platform Cryptography](design/features/cross-platform-cryptography.md)
+- Many more under [design/features](design/features/)
+
+The Book of the Runtime is a set of chapters that go in depth into various
+interesting aspects of the design of the .NET Framework.
+
+- [Book of the Runtime](design/coreclr/botr/README.md)
+
+For your convenience, here are a few quick links to popular chapters:
+
+- [Introduction to the Common Language Runtime](design/coreclr/botr/intro-to-clr.md)
+- [Garbage Collection Design](design/coreclr/botr/garbage-collection.md)
+- [Type System](design/coreclr/botr/type-system.md)
+
+For additional information, see this list of blog posts that provide a ['deep-dive' into the CoreCLR source code](deep-dive-blog-posts.md)
+
+Coding Guidelines
+=================
+
+- [CLR Coding Guide](coding-guidelines/clr-code-guide.md)
+- [CLR JIT Coding Conventions](coding-guidelines/clr-jit-coding-conventions.md)
+- [Cross Platform Performance and Eventing Design](coding-guidelines/cross-platform-performance-and-eventing.md)
+- [Adding New Events to the VM](coding-guidelines/EventLogging.md)
+- [C# coding style](coding-guidelines/coding-style.md)
+- [Framework Design Guidelines](coding-guidelines/framework-design-guidelines-digest.md)
+- [Cross-Platform Guidelines](coding-guidelines/cross-platform-guidelines.md)
+- [Performance Guidelines](coding-guidelines/performance-guidelines.md)
+- [Interop Guidelines](coding-guidelines/interop-guidelines.md)
+- [Breaking Changes](coding-guidelines/breaking-changes.md)
+- [Breaking Change Definitions](coding-guidelines/breaking-change-definitions.md)
+- [Breaking Change Rules](coding-guidelines/breaking-change-rules.md)
+- [Project Guidelines](coding-guidelines/project-guidelines.md)
+- [Adding APIs Guidelines](coding-guidelines/adding-api-guidelines.md)
+- [Legal Native calls](coding-guidelines/pinvoke-checker.md)
+
+Project Docs
+=================
+
+To be added. Visit the [project docs folder](project/) directly meanwhile.
+
+Other Information
+=================
+
+- [.NET Glossary](project/glossary.md)
+- [.NET Filename Encyclopedia](project/dotnet-filenames.md)
+- [Porting to .NET Core](project/support-dotnet-core-instructions.md)
+- [.NET Standards (Ecma)](project/dotnet-standards.md)
+- [CLR Configuration Knobs](../src/coreclr/src/inc/clrconfigvalues.h)
+- [MSDN Entry for the CLR](http://msdn.microsoft.com/library/8bs2ecf4.aspx)
+- [Wikipedia Entry for the CLR](http://en.wikipedia.org/wiki/Common_Language_Runtime)
+++ /dev/null
-Documents Index
-===============
-
-This repo includes several documents that explain both high-level and low-level concepts about the .NET runtime. These are very useful for contributors, to get context that can be very difficult to acquire from just reading code.
-
-Intro to .NET Core
-==================
-
-.NET Core is a self-contained .NET runtime and framework that implements [ECMA 335](project-docs/dotnet-standards.md). It can be (and has been) ported to multiple architectures and platforms. It supports a variety of installation options, having no specific deployment requirements itself.
-
-Getting Started
-===============
-
-- [Installing the .NET Core SDK](https://dotnet.microsoft.com/download)
-- [Official .NET Core Docs](https://docs.microsoft.com/dotnet/core/)
-
-Project Docs
-============
-
-- [Project Roadmap](https://github.com/dotnet/core/blob/master/roadmap.md)
-- [Developer Guide](project-docs/developer-guide.md)
-- [Contributing to .NET Core](project-docs/contributing.md)
-- [Contributing Workflow](project-docs/contributing-workflow.md)
-- [Performance Guidelines](project-docs/performance-guidelines.md)
-- [Garbage Collector Guidelines](project-docs/garbage-collector-guidelines.md)
-- [Public APIs in System.Private.CoreLib](project-docs/changing-corelib.md)
-- [Project NuGet Dependencies](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/project-nuget-dependencies.md)
-
-Coding Guidelines
-=================
-
-- [CLR Coding Guide](coding-guidelines/clr-code-guide.md)
-- [CLR JIT Coding Conventions](coding-guidelines/clr-jit-coding-conventions.md)
-- [Cross Platform Performance and Eventing Design](coding-guidelines/cross-platform-performance-and-eventing.md)
-- [Adding New Events to the VM](coding-guidelines/EventLogging.md)
-
-Build CoreCLR from Source
-=========================
-
-- [Building CoreCLR on FreeBSD](building/freebsd-instructions.md)
-- [Building CoreCLR on Linux](building/linux-instructions.md)
-- [Building CoreCLR on OS X](building/osx-instructions.md)
-- [Building CoreCLR on Windows](building/windows-instructions.md)
-
-Testing and Debugging CoreCLR
-=============================
-
-- [Debugging CoreCLR](building/debugging-instructions.md)
-- [Testing Changes on Windows](building/windows-test-instructions.md)
-- [Testing Changes on Linux, OS X, and FreeBSD](building/unix-test-instructions.md)
-- [Testing with CoreFX](building/testing-with-corefx.md)
-- [Performance Tracing on Windows](project-docs/windows-performance-tracing.md)
-- [Performance Tracing on Linux](project-docs/linux-performance-tracing.md)
-- [Creating native images](building/crossgen.md)
-
-Book of the Runtime
-===================
-
-The Book of the Runtime is a set of chapters that go in depth into various
-interesting aspects of the design of the .NET Framework.
-
-- [Book of the Runtime](botr/README.md)
-
-For your convenience, here are a few quick links to popular chapters:
-
-- [Introduction to the Common Language Runtime](botr/intro-to-clr.md)
-- [Garbage Collection Design](botr/garbage-collection.md)
-- [Type System](botr/type-system.md)
-
-For additional information, see this list of blog posts that provide a ['deep-dive' into the CoreCLR source code](deep-dive-blog-posts.md)
-
-Decoder Rings
-=============
-
-- [.NET Core Glossary](project-docs/glossary.md)
-- [.NET Filename Encyclopedia](project-docs/dotnet-filenames.md)
-
-Other Information
-=================
-
-- [CoreFX Repo documentation](https://github.com/dotnet/corefx/tree/master/Documentation)
-- [Porting to .NET Core](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/support-dotnet-core-instructions.md)
-- [.NET Standards (Ecma)](project-docs/dotnet-standards.md)
-- [CLR Configuration Knobs](../src/inc/clrconfigvalues.h)
-- [MSDN Entry for the CLR](http://msdn.microsoft.com/library/8bs2ecf4.aspx)
-- [Wikipedia Entry for the CLR](http://en.wikipedia.org/wiki/Common_Language_Runtime)
+++ /dev/null
-Testing with CoreFX
-===================
-
-You can use CoreFX tests to validate your changes to CoreCLR.
-The coreclr repo Azure DevOps CI system runs CoreFX tests against
-every pull request, and regularly runs the CoreFX tests under
-many different configurations (e.g., platforms, stress modes).
-
-There are two basic options:
-
-1. Build the CoreFX product and tests with a build of CoreCLR, or
-2. Use a published snapshot of the CoreFX test build with a build of CoreCLR.
-
-Mechanism #1 is the easiest. Mechanism #2 is how the CI system runs tests,
-as it is optimized for our distributed Helix test running system.
-
-# Building CoreFX against CoreCLR
-
-In all cases, first build the version of CoreCLR that you wish to test. You do not need to build the coreclr tests. Typically, this will be a Checked build (faster than Debug, but with asserts that Release builds do not have). In the examples here, coreclr is assumed to be cloned to `f:\git\runtime`.
-
-For example:
-```
-f:\git\runtime> src\coreclr\build.cmd x64 checked skiptests
-```
-
-Normally when you build CoreFX it is built against a "last known good" Release version of CoreCLR.
-
-There are two options here:
-1. Build CoreFX against your just-built CoreCLR.
-2. Build CoreFX normally, against the "last known good" version of CoreCLR, and then overwrite the "last known good" CoreCLR.
-
-Option #1 might fail to build if CoreCLR has breaking changes that have not propagated to CoreFX yet.
-Option #2 should always succeed the build, since the CoreFX CI has verified this build already.
-Option #2 is generally recommended.
-
-## Building CoreFX against just-built CoreCLR
-
-```
-f:\git\runtime> src\libraries\build.cmd -configuration Release -arch x64 -restore -build -buildtests -test /p:CoreCLROverridePath=f:\git\runtime\artifacts\bin\coreclr\Windows_NT.x64.Checked
-```
-
-Note that this will replace the coreclr used in the build, and because `-test` is passed, will also run the tests.
-
-## Replace CoreCLR after building CoreFX normally
-
-Do the following:
-
-1. Build the CoreFX repo, but don't build tests yet.
-
-```
-f:\git\runtime> src\libraries\build.cmd -configuration Release -arch x64 -restore -build
-```
-
-This creates a "testhost" directory with a subdirectory that includes the coreclr bits, e.g., `f:\git\runtime\artifacts\bin\testhost\netcoreapp-Windows_NT-Release-x64\shared\Microsoft.NETCore.App\3.0.0`.
-
-2. Copy the contents of the CoreCLR build you wish to test into the CoreFX runtime
-folder created in step #1.
-
-```
-f:\git\runtime> copy f:\git\runtime\artifacts\bin\coreclr\Windows_NT.x64.Checked\* f:\git\runtime\artifacts\bin\testhost\netcoreapp-Windows_NT-Release-x64\shared\Microsoft.NETCore.App\3.0.0
-```
-
-3. Optionally, create a script that contains any environment variables you want to set when running each CoreFX test. Disabling TieredCompilation or setting a JIT stress mode is a common case. E.g.,
-
-```
-f:\git\runtime> echo set COMPlus_TieredCompilation=0>f:\git\runtime\SetStressModes.bat
-```
-
-4. Build and run the CoreFX tests. Optionally, pass in a file that will be passed to xunit to provide extra xunit arguments. Typically, this is used to exclude known failing tests.
-
-```
-f:\git\runtime> src\libraries\build.cmd -configuration Release -arch x64 -buildtests -test /p:WithoutCategories=IgnoreForCI /p:PreExecutionTestScript=f:\git\runtime\SetStressModes.bat /p:TestRspFile=f:\git\runtime\src\coreclr\tests\CoreFX\CoreFX.issues.rsp
-```
-
-## Handling cross-compilation testing
-
-The above instructions work fine if you are building and testing on the same machine,
-but what if you are building on one machine and testing on another? This happens,
-for example, when building for Windows arm32 on a Windows x64 machine,
-or building for Linux arm64 on a Linux x64 machine (possibly in Docker).
-In these cases, build all the tests, copy them to the target machine, and run tests
-there.
-
-To do that, remove `-test` from the command-line used to build CoreFX tests. Without `-test`,
-the tests will be built but not run.
-
-If using `run-corefx-tests.py`, pass the argument `-no_run_tests`.
-
-After the tests are copied to the remote machine, you want to run them. Use one of the scripts
-[tests\scripts\run-corefx-tests.bat](https://github.com/dotnet/runtime/blob/master/src/coreclr/tests/scripts/run-corefx-tests.bat) or
-[tests\scripts\run-corefx-tests.sh](https://github.com/dotnet/runtime/blob/master/src/coreclr/tests/scripts/run-corefx-tests.sh)
-to run all the tests (consult the scripts for proper usage). Or, run a single test as described below.
-
-## Running a single CoreFX test assembly
-
-Once you've built the CoreFX tests (possibly with replaced CoreCLR bits), you can also run just a single test. E.g.,
-
-```
-f:\git\runtime> cd f:\git\runtime\artifacts\bin\System.Buffers.Tests\netcoreapp-Release
-f:\git\runtime\artifacts\bin\System.Buffers.Tests\netcoreapp-Release> RunTests.cmd -r f:\git\runtime\artifacts\bin\testhost\netcoreapp-Windows_NT-Release-x64
-```
-
-Alternatively, you can run the tests from from the test source directory, as follows:
-
-```
-f:\git\runtime> cd f:\git\runtime\src\System.Buffers\tests
-f:\git\runtime\src\System.Buffers\tests> dotnet msbuild /t:Test /p:ForceRunTests=true;ConfigurationGroup=Release
-```
-
-# Using a published snapshot of CoreFX tests
-
-The corefx official build system publishes a set of corefx test packages for consumption
-by the coreclr CI. You can use this set of published files, but it is complicated, especially
-if you wish to run more than one or a few tests.
-
-The process builds a "test host", which is a directory layout like the dotnet CLI, and uses that
-when invoking the tests. CoreFX product packages, and packages needed to run CoreFX tests,
-are restored, and the CoreCLR to test is copied in.
-
-For Windows:
-
-1. `.\src\coreclr\build.cmd <arch> <build_type> skiptests` -- build the CoreCLR you want to test
-2. `.\src\coreclr\build-test.cmd <arch> <build_type> buildtesthostonly` -- this generates the test host
-
-For Linux and macOS:
-
-1. `./src/coreclr/build.sh <arch> <build_type> skiptests`
-2. `./src/coreclr/build-test.sh <arch> <build_type> generatetesthostonly`
-
-The published tests are summarized in a `corefx-test-assets.xml` file that lives here:
-
-```
-https://dotnetfeed.blob.core.windows.net/dotnet-core/corefx-tests/$(MicrosoftPrivateCoreFxNETCoreAppVersion)/$(__BuildOS).$(__BuildArch)/$(_TargetGroup)/corefx-test-assets.xml
-```
-
-where `MicrosoftPrivateCoreFxNETCoreAppVersion` is defined in `eng\Versions.props`. For example:
-
-```
-https://dotnetfeed.blob.core.windows.net/dotnet-core/corefx-tests/4.6.0-preview8.19326.15/Linux.arm64/netcoreapp/corefx-test-assets.xml
-```
-
-This file lists all the published test assets. You can download each one, unpack it, and
-then use the generated test host to run the test.
-
-Here is an example test file:
-```
-https://dotnetfeed.blob.core.windows.net/dotnet-core/corefx-tests/4.6.0-preview8.19326.15/Linux.arm64/netcoreapp/tests/AnyOS.AnyCPU.Release/CoreFx.Private.TestUtilities.Tests.zip
-```
-
-There is no automated way to download, unpack, and run all the tests. If you wish to run all the tests, one of the methods in the "Building CoreFX against CoreCLR"
-section should be used instead, if possible.
-
-# CoreFX test exclusions
-
-The CoreCLR CI system runs CoreFX tests against a just-built CoreCLR. If tests need to be
-disabled due to transitory breaking change, for instance, update the
-[test exclusion file](https://github.com/dotnet/runtime/blob/master/src/coreclr/tests/CoreFX/CoreFX.issues.rsp).
+++ /dev/null
-Build CoreCLR on Windows
-========================
-
-These instructions will lead you through building CoreCLR.
-
-----------------
-# Environment
-
-You must install several components to build the CoreCLR and CoreFX repos. These instructions were tested on Windows 10 Pro, version 1903.
-
-## Visual Studio
-
-- Install [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/). The Community version is completely free.
-
-Visual Studio 2019 installation process:
-* Its recommended to use 'Workloads' installation approach. The following are the minimum requirements:
- * .NET Desktop Development with all default components.
- * Desktop Development with C++ with all default components.
-* To build for Arm32, Make sure that you have the Windows 10 SDK installed (or selected to be installed as part of VS installation). To explicitly install Windows SDK, download it from here: [Windows SDK for Windows 10](https://developer.microsoft.com/en-us/windows/downloads).
- * In addition, ensure you install the ARM tools. In the "Individual components" window, in the "Compilers, build tools, and runtimes" section, check the box for "Visual C++ compilers and libraries for ARM".
-* To build the tests, make sure you have a Windows 10 SDK component for at least version 10.0.17763 or newer. This component is installed by default as a part of 'Desktop Development with C++' workload.
-* **Important:** You must have the `msdia120.dll` COM Library registered in order to build the repository.
- * This binary is registered by default when installing the "VC++ Tools" with Visual Studio 2019.
- * You can also manually register the binary by launching the "Developer Command Prompt for VS2019" with Administrative privileges and running `regsvr32.exe "%VSINSTALLDIR%\Common7\IDE\msdia120.dll"`.
-
-The CoreCLR repo build has been validated using Visual Studio 2019 16.1.6.
-
-## CMake
-
-- Install [CMake](http://www.cmake.org/download) for Windows.
-- Add its location (e.g. C:\Program Files (x86)\CMake\bin) to the PATH environment variable.
- The installation script has a check box to do this, but you can do it yourself after the fact following the instructions at [Adding to the Default PATH variable](#adding-to-the-default-path-variable).
-
-The CoreCLR repo build has been validated using CMake 3.15.0.
-
-## Python
-
-- Install [Python](https://www.python.org/downloads/) for Windows.
-- Add its location (e.g. C:\Python*\) to the PATH environment variable.
- The installation script has a check box to do this, but you can do it yourself after the fact following the instructions at [Adding to the Default PATH variable](#adding-to-the-default-path-variable).
-
-The CoreCLR repo build has been validated using Python 3.7.4.
-
-## Git
-
-- Install [Git](https://git-for-windows.github.io/) for Windows.
-- Add its location (e.g. C:\Program Files\Git\cmd) to the PATH environment variable.
- The installation script has a check box to do this, but you can do it yourself after the fact following the instructions at [Adding to the Default PATH variable](#adding-to-the-default-path-variable).
-
-The CoreCLR repo build has been validated using Git 2.22.0.
-
-## PowerShell
-
-- Ensure that it is accessible via the PATH environment variable. Typically this is `%SYSTEMROOT%\System32\WindowsPowerShell\v1.0\` and its automatically set upon Windows installation.
-- Powershell version must be 3.0 or higher. Use `$PSVersionTable.PSVersion` to determine the engine version.
-
-The CoreCLR repo build has been validated using PowerShell 5.1.
-
-## DotNet Core SDK
-
-While not strictly needed to build or test the .NET Core repository, having the .NET Core SDK installed lets you use the dotnet.exe command to run .NET Core applications in the 'normal' way. We use this in the
-[Using Your Build](../workflow/UsingYourBuild.md) instructions. Visual Studio should have
-installed the .NET Core SDK, but in case it did not you can get it from the [Installing the .NET Core SDK](https://dotnet.microsoft.com/download) page.
-
-## Adding to the default PATH variable
-
-The commands above need to be on your command lookup path. Some installers will automatically add them to the path as part of the installation, but if not here is how you can do it.
-
-You can, of course, add a directory to the PATH environment variable with the syntax `set PATH=%PATH%;DIRECTORY_TO_ADD_TO_PATH`.
-
-However, the change above will only last until the command windows close. You can make your change to
-the PATH variable persistent by going to Control Panel -> System And Security -> System -> Advanced system settings -> Environment Variables,
-and select the 'Path' variable in the 'System variables' (if you want to change it for all users) or 'User variables' (if you only want
-to change it for the current user). Simply edit the PATH variable's value and add the directory (with a semicolon separator).
-
--------------------------------------
-# Building
-
-Once all the necessary tools are in place, building is trivial. Simply run build build.cmd script that lives at
-the base of the repository.
-
-```bat
- .\src\coreclr\build
-
- [Lots of build spew]
-
- Product binaries are available at C:\git\runtime\artifacts\bin\coreclr\Windows_NT.x64.debug
- Test binaries are available at C:\git\runtime\artifacts\tests\coreclr\Windows_NT.x64.debug
-```
-
-As shown above, the product will be placed in
-
-- Product binaries will be dropped in `artifacts\bin\coreclr\<OS>.<arch>.<flavor>` folder.
-- A NuGet package, Microsoft.Dotnet.CoreCLR, will be created under `artifacts\bin\coreclr\<OS>.<arch>.<flavor>\.nuget` folder.
-- Test binaries will be dropped under `artifacts\tests\coreclr\<OS>.<arch>.<flavor>` folder.
-
-By default, build generates a 'Debug' build type, that has extra checking (assert) compiled into it. You can
-also build the 'release' version which does not have these checks.
-
-The build places logs in `artifacts\log` and these are useful when the build fails.
-
-The build places all of its output in the `artifacts\obj\coreclr` directory, so if you remove that directory you can force a
-full rebuild.
-
-The build has a number of options that you can learn about using build -?. Some of the more important options are
-
- * -skiptests - don't build the tests. This can shorten build times quite a bit, but means you can't run tests.
- * -release - build the 'Release' build type that does not have extra development-time checking compiled in.
- You want this if you are going to do performance testing on your build.
-
-See [Using Your Build](../workflow/UsingYourBuild.md) for instructions on running code with your build.
-
-See [Running Tests](../workflow/RunningTests.md) for instructions on running the tests.
+++ /dev/null
-Contribution Workflow
-=====================
-
-You can contribute to .NET Core with issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated.
-
-## Suggested Workflow
-
-We use and recommend the following workflow:
-
-1. Create an issue for your work.
- - You can skip this step for trivial changes.
- - Reuse an existing issue on the topic, if there is one.
- - Get agreement from the team and the community that your proposed change is a good one.
- - If your change adds a new API, follow the [API Review Process](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/api-review-process.md).
- - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.
-2. Create a personal fork of the repository on GitHub (if you don't already have one).
-3. Create a branch off of master (`git checkout -b mybranch`).
- - Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue.
- - Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
-4. Make and commit your changes.
- - Please follow our [Commit Messages](contributing.md#commit-messages) guidance.
-5. Add new tests corresponding to your change, if applicable.
-6. Build the repository with your changes.
- - Make sure that the builds are clean.
- - Make sure that the tests are all passing, including your new tests.
-7. Create a pull request (PR) against the upstream repository's **master** branch.
- - Push your changes to your fork on GitHub (if you haven't already).
-
-Note: It is OK for your PR to include a large number of commits. Once your change is accepted, you will be asked to squash your commits into one or some appropriately small number of commits before your PR is merged.
-
-Note: It is OK to create your PR as "[WIP]" on the upstream repo before the implementation is done. This can be useful if you'd like to start the feedback process concurrent with your implementation. State that this is the case in the initial PR comment.
-
-## PR - CI Process
-
-The [dotnet continuous integration](https://dev.azure.com/dnceng/public/) (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean.
-
-If the CI build fails for any reason, the PR issue will be updated with a link that can be used to determine the cause of the failure.
-
-## PR Feedback
-
-Microsoft team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback.
-
-1 or more Microsoft team members will review every PR prior to merge. They will often reply with "LGTM, modulo comments". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me".
-
-There are lots of thoughts and [approaches](https://github.com/antlr/antlr4-cpp/blob/master/CONTRIBUTING.md#emoji) for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback.
-
-# Merging Pull Requests (for contributors with write access)
-
-Use ["Squash and Merge"](https://github.com/blog/2141-squash-your-commits) by default for individual contributions unless requested by the PR author.
- Do so, even if the PR contains only one commit. It creates a simpler history than "Create a Merge Commit".
- Reasons that PR authors may request "Merge and Commit" may include (but are not limited to):
-
- - The change is easier to understand as a series of focused commits. Each commit in the series must be buildable so as not to break `git bisect`.
- - Contributor is using an e-mail address other than the primary GitHub address and wants that preserved in the history. Contributor must be willing to squash
- the commits manually before acceptance.
-
+++ /dev/null
-Contributing to .NET Core
-=========================
-
-The .NET Core team maintains guidelines for contributing to the .NET Core repos. A .NET Core team member will be happy to explain why a guideline is defined as it is.
-
-General contribution guidance is included in this document. Additional guidance is defined in the documents linked below.
-
-- [Copyright](copyright.md) describes the licensing practices for the project.
-- [Contribution Workflow](contributing-workflow.md) describes the workflow that the team uses for considering and accepting changes.
-- [Garbage Collection Guidelines](garbage-collector-guidelines.md) for changes that affect the GC.
-- [Performance Guidelines](performance-guidelines.md) for changes in performance critical code or that otherwise affect performance.
-- [Porting the JIT](https://github.com/dotnet/coreclr/pull/2214#issuecomment-161850464) to other chip architectures.
-
-Up for Grabs
-------------
-
-The team marks the most straightforward issues as "up for grabs". This set of issues is the place to start if you are interested in contributing but new to the codebase.
-
-- [dotnet/corefx - "up for grabs"](https://github.com/dotnet/corefx/labels/up-for-grabs)
-- [dotnet/coreclr - "up for grabs"](https://github.com/dotnet/coreclr/labels/up-for-grabs)
-
-Contribution "Bar"
-------------------
-
-Project maintainers will merge changes that improve the product significantly and broadly and that align with the [.NET Core roadmap](https://github.com/dotnet/core/blob/master/roadmap.md).
-
-Maintainers will not merge changes that have narrowly-defined benefits, due to compatibility risk. The .NET Core codebase is used by several Microsoft products (for example, ASP.NET Core, .NET Framework 4.x, Windows Universal Apps) to enable execution of managed code. Other companies are building products on top of .NET Core, too. We may revert changes if they are found to be breaking.
-
-Contributions must also satisfy the other published guidelines defined in this document.
-
-Automated Code Review Assistance
-------------------
-
-CROSS is a tool developed by Microsoft that is used to highlight areas of higher risk in a code change in order to help code reviewers do a more effective job.
-
-DOs and DON'Ts
---------------
-
-Please do:
-
-* **DO** follow our [coding style](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md) (C# code-specific)
-* **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
-* **DO** include tests when adding new features. When fixing bugs, start with
- adding a test that highlights how the current behavior is broken.
-* **DO** keep the discussions focused. When a new or related topic comes up
- it's often better to create new issue than to side track the discussion.
-* **DO** blog and tweet (or whatever) about your contributions, frequently!
-
-Please do not:
-
-* **DON'T** make PRs for style changes.
-* **DON'T** surprise us with big pull requests. Instead, file an issue and start
- a discussion so we can agree on a direction before you invest a large amount
- of time.
-* **DON'T** commit code that you didn't write. If you find code that you think is a good fit to add to .NET Core, file an issue and start a discussion before proceeding.
-* **DON'T** submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it.
-* **DON'T** add API additions without filing an issue and discussing with us first. See [API Review Process](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/api-review-process.md).
-
-Managed Code Compatibility
---------------------------
-
-Contributions must maintain [API signature](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md#bucket-1-public-contract) and behavioral compatibility. Contributions that include [breaking changes](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md) will be rejected. Please file an issue to discuss your idea or change if you believe that it may affect managed code compatibility.
-
-Contributing to System.Private.CoreLib library
-----------------------------------------------
-
-Most changes in managed libraries should be made in the [CoreFX](https://github.com/dotnet/corefx) repo. The CoreCLR repo contains implementation for the [System.Private.CoreLib.dll](https://github.com/dotnet/coreclr/tree/master/src/System.Private.CoreLib) library. Publicly visible changes in this library require [staging](changing-corelib.md) over the two repos.
-
-Commit Messages
----------------
-
-Please format commit messages as follows (based on [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)):
-
-```
-Summarize change in 50 characters or less
-
-Provide more detail after the first line. Leave one blank line below the
-summary and wrap all lines at 72 characters or less.
-
-If the change fixes an issue, leave another blank line after the final
-paragraph and indicate which issue is fixed in the specific format
-below.
-
-Fix #42
-```
-
-Also do your best to factor commits appropriately, not too large with unrelated things in the same commit, and not too small with the same small change applied N times in N different commits.
-
-Contributor License Agreement
------------------------------
-
-You must sign a [.NET Foundation Contribution License Agreement (CLA)](https://cla.dotnetfoundation.org) before your PR will be merged. This is a one-time requirement for projects in the .NET Foundation. You can read more about [Contribution License Agreements (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia.
-
-The agreement: [net-foundation-contribution-license-agreement.pdf](https://github.com/dotnet/home/blob/master/guidance/net-foundation-contribution-license-agreement.pdf)
-
-You don't have to do this up-front. You can simply clone, fork, and submit your pull-request as usual. When your pull-request is created, it is classified by a CLA bot. If the change is trivial (for example, you just fixed a typo), then the PR is labelled with `cla-not-required`. Otherwise it's classified as `cla-required`. Once you signed a CLA, the current and all future pull-requests will be labelled as `cla-signed`.
-
-File Headers
-------------
-
-The following file header is the used for .NET Core. Please use it for new files.
-
-```
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-```
-
-- See [class.cpp](../../src/vm/class.cpp) for an example of the header in a C++ file.
-- See [List.cs](../../src/System.Private.CoreLib/shared/System/Collections/Generic/List.cs) for an example of the header in a C# file.
-
-Contributing Ports
-------------------
-
-We encourage ports of CoreCLR to other platforms. There are multiple ports ongoing at any one time. You may be interested in one of the following ports:
-
-Chips:
-
-- [ARM32](https://github.com/dotnet/coreclr/labels/arch-arm32)
-- [ARM64](https://github.com/dotnet/coreclr/labels/arch-arm64)
-- [X86](https://github.com/dotnet/coreclr/labels/arch-x86)
-
-Operating System:
-
-- [Linux](https://github.com/dotnet/coreclr/labels/os-linux)
-- [macOS](https://github.com/dotnet/coreclr/labels/os-mac-os-x)
-- [Windows Subsystem for Linux](https://github.com/dotnet/coreclr/labels/os-windows-wsl)
-- [FreeBSD](https://github.com/dotnet/coreclr/labels/os-freebsd)
-
-Note: Add links to install instructions for each of these ports.
-
-Ports have a weaker contribution bar, at least initially. A functionally correct implementation is considered an important first goal. Performance, reliability and compatibility are all important concerns after that.
-
-Copying Files from Other Projects
----------------------------------
-
-.NET Core uses some files from other projects, typically where a binary distribution does not exist or would be inconvenient.
-
-The following rules must be followed for PRs that include files from another project:
-
-- The license of the file is [permissive](https://en.wikipedia.org/wiki/Permissive_free_software_licence).
-- The license of the file is left in-tact.
-- The contribution is correctly attributed in the [3rd party notices](../../THIRD-PARTY-NOTICES.TXT) file in the repository, as needed.
-
-See [IdnMapping.cs](../../src/System.Private.CoreLib/shared/System/Globalization/IdnMapping.cs) for an example of a file copied from another project and attributed in the [CoreCLR 3rd party notices](../../THIRD-PARTY-NOTICES.TXT) file.
-
-Porting Files from Other Projects
----------------------------------
-
-There are many good algorithms implemented in other languages that would benefit the .NET Core project. The rules for porting a Java file to C# , for example, are the same as would be used for copying the same file, as described above.
-
-[Clean-room](https://en.wikipedia.org/wiki/Clean_room_design) implementations of existing algorithms that are not permissively licensed will generally not be accepted. If you want to create or nominate such an implementation, please create an issue to discuss the idea.
+++ /dev/null
-Developer Guide
-===============
-
-This guide provides instructions (mostly as links) on how to build the repo and implement improvements. It will expand over time.
-
-Building the repository
-=======================
-
-The CoreCLR repo can be built from a regular, non-admin command prompt. The build produces CoreCLR (multiple native binaries), the mscorlib managed library and the accompanying tests. The repo can be built for the following platforms, using the provided instructions.
-
-| Chip | Windows | Linux | OS X |
-| :---- | :-----: | :---: | :--: |
-| x64 | ●| ◒| ◒ |
-| x86 | ◯| ◯| ◯|
-| ARM32 | ◯ | ◯| ◯ |
-| | [Instructions](../building/windows-instructions.md) | [Instructions](../building/linux-instructions.md) | [Instructions](../building/osx-instructions.md) |
-
-The CoreCLR build and test suite is a work in progress, as are the [building and testing instructions](../README.md). The .NET Core team and the community are improving Linux and OS X support on a daily basis and are adding more tests for all platforms. See [CoreCLR Issues](https://github.com/dotnet/coreclr/issues) to find out about specific work items or report issues.
-
-Understanding the TFS-Git Mirror
-================================
-
-The Microsoft team maintains a Microsoft-internal TFS server of CoreCLR. An automated system is used to flow changes in/out of GitHub. The mirroring infrastructure uses the following hint files to mirror a given TFS folder into GitHub and back:
-
-1. `.gitmirror` - any folder containing this file will **only** have its contained files mirrored. Subfolders are **not** mirrored.
-2. `.gitmirrorall` - any folder containing this file will have all of its files **and** subfolders mirrored recursively. The subfolders do not need to have any hint files.
-
-Thus, if you add a new folder to be included as part of the CoreCLR build, it will also need to have one of the two hint files mentioned above.
+++ /dev/null
-.NET Core Glossary
-===
-
-This glossary defines terms, both common and more niche, that are important to understand when reading .NET Core documents and source code. They are also often used by .NET Core team members and other contributors when conversing on GitHub (issues, PRs), on twitter and other sites.
-
-As much as possible, we should link to the most authoritative and recent source of information for a term. That approach should be the most helpful for people who want to learn more about a topic.
-
-| Term | Description |
-| ----- | ------------- |
-| AOT | Ahead-of-time compiler. Converts the MSIL bytecode to native machine code for a specific target CPU architecture. |
-| BBT | Microsoft internal early version of C/C++ PGO. See https://www.microsoft.com/windows/cse/bit_projects.mspx. |
-| BOTR | Book Of The Runtime. |
-| CLR | Common Language Runtime. |
-| COMPlus | An early name for the .NET platform, back when it was envisioned as a successor to the COM platform (hence, "COM+"). Used in various places in the CLR infrastructure, most prominently as a common prefix for the names of internal configuration settings. Note that this is different from the product that eventually ended up being named [COM+](https://msdn.microsoft.com/en-us/library/windows/desktop/ms685978.aspx). |
-| COR | [Common Object Runtime](http://www.danielmoth.com/Blog/mscorlibdll.aspx). The name of .NET before it was named .NET. |
-| DAC | Data Access Component. An abstraction layer over the internal structures in the runtime. |
-| EE | Execution Engine. |
-| GC | [Garbage Collector](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/garbage-collection.md). |
-| IPC | Inter-Process Communication. |
-| JIT | [Just-in-Time](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/ryujit-overview.md) compiler. RyuJIT is the code name for the next generation Just-in-Time(aka "JIT") for the .NET runtime. |
-| LCG | Lightweight Code Generation. An early name for [dynamic methods](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Reflection/Emit/DynamicMethod.cs). |
-| MD | MetaData. |
-| MDA | Managed Debugging Assistant - see [details](https://docs.microsoft.com/en-us/dotnet/framework/debug-trace-profile/diagnosing-errors-with-managed-debugging-assistants) (Note: Not in .NET Core, equivalent diagnostic functionality is made available on a case-by-case basis, e.g. [#15465](https://github.com/dotnet/coreclr/issues/15465)) |
-| NGen | Native Image Generator. |
-| NYI | Not Yet Implemented. |
-| PAL | [Platform Adaptation Layer](http://archive.oreilly.com/pub/a/dotnet/2002/03/04/rotor.html). Provides an abstraction layer between the runtime and the operating system. |
-| PE | Portable Executable. |
-| PGO | Profile Guided Optimization - see [details](https://blogs.msdn.microsoft.com/vcblog/2008/11/12/pogo/). |
-| POGO | Profile Guided Optimization - see [details](https://blogs.msdn.microsoft.com/vcblog/2008/11/12/pogo/). |
-| ProjectN | Codename for the first version of [.NET Native for UWP](https://msdn.microsoft.com/en-us/vstudio/dotnetnative.aspx). |
-| R2R | Ready-to-Run. A flavor of native images - command line switch of [crossgen](../building/crossgen.md). |
-| Redhawk | Codename for experimental minimal managed code runtime that evolved into [CoreRT](https://github.com/dotnet/corert/). |
-| SOS | [Son of Strike](http://blogs.msdn.com/b/jasonz/archive/2003/10/21/53581.aspx). The debugging extension for DbgEng based debuggers. Uses the DAC as an abstraction layer for its operation. |
-| SuperPMI | JIT component test framework (super fast JIT testing - it mocks/replays EE in EE-JIT interface) - see [SuperPMI details](https://github.com/dotnet/coreclr/blob/master/src/ToolBox/superpmi/readme.txt). |
-| SVR | The CLR used to be built as two variants, with one called "mscorsvr.dll", to mean the "server" version. In particular, it contained the server GC implementation, which was intended for multi-threaded apps capable of taking advantage of multiple processors. In the .NET Framework 2 release, the two variants were merged into "mscorwks.dll". The WKS version was the default, however the SVR version remained available. |
-| TPA | Trusted Platform Assemblies used to be a special set of assemblies that comprised the platform assemblies, when it was originally designed. As of today, it is simply the set of assemblies known to constitute the application. |
-| URT | Universal Runtime. Ancient name for what ended up being .NET, is used in the WinError facility name FACILITY_URT. |
-| UTC | [Universal Tuple Compiler](https://blogs.msdn.microsoft.com/vcblog/2013/06/12/optimizing-c-code-overview/). The Microsoft C++ optimizer back-end that that starts by converting the information from the FrontEnd into tuples – a binary stream of instructions. |
-| UWP | [Universal Windows Platform (UWP)](https://docs.microsoft.com/en-us/windows/uwp/get-started/universal-application-platform-guide) is a platform-homogeneous application architecture available on every device that runs Windows 10. |
-| VSD | [Virtual Stub Dispatch](../botr/virtual-stub-dispatch.md). Technique of using stubs for virtual method invocations instead of the traditional virtual method table. |
-| VM | Virtual machine. |
-| WKS | The CLR used to be built as two variants, with one called "mscorwks.dll", to mean the "workstation" version. In particular, it contained the client GC implementation, which was intended for single-threaded apps, independent of how many processors were on the machine. In the .NET Framework 2 release, the two variants were merged into "mscorwks.dll". The WKS version was the default, however the SVR version remained available. |
-| ZAP | Original code name for NGen. |
An example may be helpful in understanding how marshaling works. The common debugging scenario is represented in the following block diagram:
-
+
The debugger in this figure could be Visual Studio, MDbg, WinDbg, etc. The debugger interfaces with the CLR debugger interface (DBI) APIs to get the information it needs. Information that must come from the target goes through the DAC. The debugger implements the data target, which is responsible for implementing a ReadVirtual function to read memory in the target. The dotted line in the diagram represents the process boundary.
The MethodDescs are allocated in chunks to save space. Multiple MethodDesc tend to have identical MethodTable and upper bits of metadata token. MethodDescChunk is formed by hoisting the common information in front of an array of multiple MethodDescs. The MethodDesc contains just the index of itself in the array.
-
+
Figure 1 MethodDescChunk and MethodTable
Temporary entry points are never saved into NGen images. All entry points in NGen images are stable entry points that are never changed. It is an important optimization that reduced private working set.
-
+
Figure 2 Entry Point State Diagram
A method can have both native code and precode if there is a need to do work before the actual method body is executed. This situation typically happens for NGen image fixups. Native code is an optional MethodDesc slot in this case. This is necessary to lookup the native code of the method in a cheap uniform way.
-
+
Figure 3 The most complex case of Precode, Stub and Native Code
Note that only the data-gathering part of the profiler solution should be running in-process with the profiled application—UI and data analysis should be done in a separate process.
-
+
The _ICorProfilerCallback_ and _ICorProfilerCallback2_ interfaces consists of methods with names like ClassLoadStarted, ClassLoadFinished, JITCompilationStarted. Each time the CLR loads/unloads a class, compiles a function, etc., it calls the corresponding method in the profiler's _ICorProfilerCallback/ICorProfilerCallback2_ interface. (And similarly for all of the other notifications; see later for details)
**Example:** The diagram below shows 10 objects, before garbage collection. They lie at start addresses (equivalent to _ObjectIDs_) of 08, 09, 10, 12, 13, 15, 16, 17, 18 and 19. _ObjectIDs_ 09, 13 and 19 are dead (shown shaded); their space will be reclaimed during garbage collection.
-
+
The "After" picture shows how the space occupied by dead objects has been reclaimed to hold live objects. The live objects have been moved in the heap to the new locations shown. As a result, their _ObjectIDs_ all change. The simplistic way to describe these changes is with a table of before-and-after _ObjectIDs_, like this:
Notifications of exceptions are the most difficult of all notifications to describe and to understand. This is because of the inherent complexity in exception processing. The set of exception notifications described below was designed to provide all the information required for a sophisticated profiler – so that, at every instant, it can keep track of which pass (first or second), which frame, which filter and which finally block is being executed, for every thread in the profilee process. Note that the Exception notifications do not provide any _threadID's_ but a profiler can always call _ICorProfilerInfo::GetCurrentThreadID_ to discover which managed thread throws the exception.
-
+
The figure above displays how the code profiler receives the various callbacks, when monitoring exception events. Each thread starts out in "Normal Execution." When the thread is in a state within the big gray box, the exception system has control of the thread—any non-exception-related callbacks (e.g. ObjectAllocated) that occur while the thread is in one of these states may be attributed to the exception system itself. When the thread is in a state outside of the big gray box, it is running arbitrary managed code.
In addition to HIR and LIR `BasicBlock`s, a separate representation--`insGroup` and `instrDesc`--is used during the actual instruction encoding.
-
+
## GenTree Nodes
### RyuJIT High-Level Overview
-
+
#### Notes
This is the 10,000 foot view of RyuJIT. It takes in MSIL (aka CIL) in the form of byte codes, and the Importer phase transforms these to the intermediate representation used in the JIT. The IR operations are called “GenTrees”, as in “trees for code generation”. This format is preserved across the bulk of the JIT, with some changes in form and invariants along the way. Eventually, the code generator produces a low-level intermediate called InstrDescs, which simply capture the instruction encodings while the final mappings are done to produce the actual native code and associated tables.
### RyuJIT Phases
-
+
#### Notes
This is the more detailed view, and shows all of the significant phases of RyuJIT. The ones in green are responsible for creating and normalizing the IR and associated data structures.
The phases in orange are the optimization phases, and the phases in purple are the lower-level, back-end phases.
### Initial Phases of RyuJIT
-
+
- Importer:
- initialize the local variable table and scan the MSIL to form BasicBlocks
- Create the IR from the MSIL
The initial phases of RyuJIT set up the IR in preparation for the optimization phases. This includes importing the IL, that is, producing GenTrees IR from the incoming MSIL, inlining methods when considered profitable, normalizing the representation, analyzing the flowgraph, specifying the execution order and identifying the important local variables for optimization.
### Optimization Phases of RyuJIT
-
+
- SSA and Value Numbering Optimizations
- Dataflow analysis, SSA construction and Value numbering
The optimization phases of RyuJIT are based on liveness analysis, SSA and value numbering. These are used to perform loop invariant code hoisting, copy propagation, common subexpression elimination, assertion propagation, and range check elimination. SSA is used to uniquely identify the values of lclVars, while value numbering is used to identify trees that compute the same value for a given execution.
### Back-end Phases of RyuJIT
-
+
- Rationalization: eliminate “parental context” in trees
- Not really strictly “back-end” but required by back-end)
- Historically oriented toward a small working set
### RyuJIT IR
-
+
#### Notes
The RyuJIT IR can be described at a high level as follows:
- After ordering (`fgSetBlockOrder()`):
- The execution order *within a statement* is specified by the `gtNext` and `gtPrev` links
-
+
#### Notes
This is the same diagram as before, but with additional links to indicate execution order. The statements have a link to the first node in the list, and each node has a link to its previous and next node in the linear order.
- In LIR, statements are replaced with GT_IL_OFFSET nodes to allow mapping back to the incoming IL
- All the nodes for a `BasicBlock` are in a single linked-list
-
+
## RyuJIT Front-End
```
{BinaryDir}\CoreRun.exe PopCount.exe 1122334455667788 > jitdump.out.0
-
+
#### Notes
The first thing we’re going to do is to take a look at the IR for the sample.
The following diagram illustrates a stack containing all the frames types (note that this document uses a convention where stacks grow towards the top of the page):
-
+
# Making Frames Crawlable
This performance requirement rules out any dictionary look up
approaches and leaves us with the following high-level architecture.
-
+
Figure 1 The abstract high-level object design
The most universal type designation in the CLR is the `TypeHandle`. It's an abstract entity which encapsulates a pointer to either a `MethodTable` (representing "ordinary" types like `System.Object` or `List<string>`) or a `TypeDesc` (representing byrefs, pointers, function pointers, arrays, and generic variables). It constitutes the identity of a type in that two handles are equal if and only if they represent the same type. To save space, the fact that a `TypeHandle` contains a `TypeDesc` is indicated by setting the second lowest bit of the pointer to 1 (i.e. (ptr | 2)) instead of using additional flags<sup>2</sup>. `TypeDesc` is "abstract" and has the following inheritance hierarchy.
-
+
Figure 2 The TypeDesc hierarchy
In the generics-free world, everything is nice and everyone is happy because every ordinary (not represented by a `TypeDesc`) type has one `MethodTable` pointing to its associated `EEClass` which in turn points back to the `MethodTable`. All instances of the type contain a pointer to the `MethodTable` as their first field at offset 0, i.e. at the address seen as the reference value. To conserve space, `MethodDesc`s representing methods declared by the type are organized in a linked list of chunks pointed to by the `EEClass`<sup>4</sup>.
-
+
Figure 3 Non-generic type with non-generic methods
share. This sharing has a positive impact on the memory footprint and
consequently also performance.
-
+
Figure 4 Generic type with non-generic methods - shared EEClass
The type system is generally a service provided to many parts of the CLR, and most core components have some form of dependency on the behavior of the type system. This diagram describes the general dataflow that effects the type system. It is not exhaustive, but calls out the major information flows.
-
+
### Component Dependencies
The following is a small class structure (modeled in C#), and what the resulting implementation table and slot map would be for each class.
-
+
Thus, looking at this map, we see that the first column of the sub-maps of the slot maps correspond to the slot number in the classic virtual table view (remember that System.Object contributes four virtual methods of its own, which are omitted for clarity). Searches for method implementations are always bottom-up. Thus, if I had an object of type _B_ and I wished to invoke _I.Foo_, I would look for a mapping of _I.Foo_ starting at _B_'s slot map. Not finding it there, I would look in _A_'s slot map and find it there. It states that virtual slot 0 of _I_ (corresponding to _I.Foo_) is implemented by virtual slot 0. Then I return to _B_'s slot map and search for an implementation for slot 0, and find that it is implemented by slot 1 in its own implementation table.
There are currently three types of stubs. The below diagram shows the general control flow between these stubs, and will be explained below.
-
+
### Generic Resolver
The former interface virtual table dispatch mechanism results in a code sequence similar to this:
-
+
And the typical stub dispatch sequence is:
-
+
where expectedMT, failure and target are constants encoded in the stub.
Below is the portion of the call graph the escape analysis will have to consider when proving this allocation is not escaping.
Green arrows correspond to the call sites that are inlined and red arrows correspond to the call sites that are not inlined.
-
+
## Roadmap
+++ /dev/null
-# Build Core-Setup with a Local CoreCLR or CoreFX
-
-## Testing with private CoreCLR bits
-
-Generally the Core-Setup build system gets the CoreCLR from a NuGet package which gets pulled down and correctly copied to the various output directories by building `src\pkg\projects\netcoreapp\src\netcoreapp.depproj` which gets built as part of `build.cmd/sh`. For folks that want to do builds and test runs in corefx with a local private build of coreclr you can follow these steps:
-
-1. Build CoreCLR and note your output directory. Ex: `\coreclr\bin\Product\Windows_NT.x64.Release\` Note this will vary based on your OS/Architecture/Flavor and it is generally a good idea to use Release builds for CoreCLR when building Core-Setup and the OS and Architecture should match what you are building in Core-Setup.
-2. Build Core-Setup either passing in the `CoreCLROverridePath` property or setting it as an environment variable:
-
-```batch
-build.cmd /p:CoreCLROverridePath=d:\git\coreclr\bin\Product\Windows_NT.x64.Release
-```
-
-By convention the project will look for PDBs in a directory under `$(CoreCLROverridePath)/PDB` and if found will also copy them. If not found no PDBs will be copied. If you want to explicitly set the PDB path then you can pass `CoreCLRPDBOverridePath` property to that PDB directory.
-Once you have updated your CoreCLR you can run tests however you usually do and it should be using your copy of CoreCLR.
-If you prefer, you can use a Debug build of System.Private.CoreLib, but if you do you must also use a Debug build of the native portions of the runtime, e.g. coreclr.dll. Tests with a Debug runtime will execute much more slowly than with Release runtime bits. This override is only enabled for building the NETCoreApp shared framework.
-
-## Testing with private CoreFX bits
-
-Similarly to how Core-Setup consumes CoreCLR, Core-Setup also consumes CoreFX from a NuGet package which gets pulled down and correctly copied to the various output directories by building `src\pkg\projects\netcoreapp\src\netcoreapp.depproj` which gets built as part of `build.cmd/sh`. To test with a local private build of CoreFX, you can follow these steps:
-
-1. Build CoreFX and note your configuration (Ex. Debug, Checked, Release).
-2. Build Core-Setup either passing in the `CoreFXOverridePath` property or setting it as an environment variable (assuming your CoreFX repo is located at `d:\git\corefx`):
-
-```batch
-build.cmd /p:CoreFXOverridePath=d:\git\corefx\artifacts\packages\Debug
-```
-
-The Core-Setup build will resolve the correct libraries to use to build the NETCoreApp shared framework based on the restored packages and will locate the files in the output directory based on the nuspec file of the shared-framework package in the local CoreFX build. This override does not enable using a local CoreFX build when creating the WindowsDesktop shared framework.
+++ /dev/null
-Build Core-Setup on Windows
-========================
-
-These instructions will lead you through building Core-Setup.
-
-----------------
-# Environment
-
-You must install several components to build the Core-Setup repo. These instructions were tested on Windows 10+.
-
-## Visual Studio
-
-Visual Studio must be installed. Supported versions:
-- [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/#2019) (Community, Professional, Enterprise). The community version is completely free.
-- [Visual Studio 2017](https://visualstudio.microsoft.com/vs/) (Community, Professional, Enterprise). The community version is completely free.
-
-For Visual Studio:
-* Required installer options that need to be manually enabled:
- * Universal Windows App Development Tools: Tools and Windows 10 SDK (10.0.14393) + Windows 10 SDK (10.0.10586)
- * Visual C++
-
-Visual Studio Express is not supported.
-
-## CMake
-
-The Core-Setup repo build requires at least CMake 3.14.
-
-- Install [CMake](http://www.cmake.org/download) for Windows.
-- Add its location (e.g. C:\Program Files (x86)\CMake\bin) to the PATH environment variable.
- The installation script has a check box to do this, but you can do it yourself after the fact
- following the instructions at [Adding to the Default PATH variable](#adding-to-the-default-path-variable)
-
-
-## Git
-
-For actual user operations, it is often convenient to use the Git features built
-into your editor or IDE. However, Core-Setup and the tests use the Git command
-line utilities directly, so you need to set them up for the build to work
-properly. You can get Git from:
-
-- Install [Git For Windows](https://git-for-windows.github.io/)
-- Add its location (e.g. C:\Program Files\Git\cmd) to the PATH environment variable.
- The installation script has a check box to do this, but you can do it yourself after the fact
- following the instructions at [Adding to the Default PATH variable](#adding-to-the-default-path-variable)
-
-## PowerShell
-PowerShell is used in the build system. Ensure that it is accessible via the PATH environment variable.
-Typically this is %SYSTEMROOT%\System32\WindowsPowerShell\v1.0\.
-
-Powershell version must be 3.0 or higher. This should be the case for Windows 8 and later builds.
-- Windows 7 SP1 can install Powershell version 4 [here](https://www.microsoft.com/en-us/download/details.aspx?id=40855).
-
-## Adding to the default PATH variable
-
-The commands above need to be on your command lookup path. Some installers will automatically add them to
-the path as part of installation, but if not here is how you can do it.
-
-You can of course add a directory to the PATH environment variable with the syntax
-```
- set PATH=%PATH%;DIRECTORY_TO_ADD_TO_PATH
-```
-However the change above will only last until the command windows closes. You can make your change to
-the PATH variable persistent by going to Control Panel -> System And Security -> System -> Advanced system settings -> Environment Variables,
-and select the 'Path' variable in the 'System variables' (if you want to change it for all users) or 'User variables' (if you only want
-to change it for the current user). Simply edit the PATH variable's value and add the directory (with a semicolon separator).
-
--------------------------------------
-# Building
-
-Once all the necessary tools are in place, building is trivial. Simply run the
-`build.cmd` script that lives at the base of the repository.
-
-If you want to build a subset of the build because `build.cmd` takes too long,
-try using the `Subset` property. For example, adding `/p:Subset=CoreHost` to
-your build command makes it only build the native project. Read the
-documentation in [Subsets.props](/Subsets.props) and try `/p:Subset=help` for
-more info.
+++ /dev/null
-11/30/2018 02:15:00 PM
+++ /dev/null
-Issue Guide\r
-===========\r
-\r
-Core-setup uses the [CoreFx policies](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/issue-guide.md), so use that for general information on how to create an issue, etc.\r
-\r
-### Areas\r
-Areas are tracked by labels area-* (e.g. area-Host). To view owners for each area in this repository check out the [area-owners.md](https://github.com/dotnet/runtime/blob/master/docs/area-owners.md) page.\r
+++ /dev/null
-Documents Index
-===============
-
-Intro to .NET Core
-==================
-
-.NET Core is a self-contained .NET runtime and framework that implements ECMA 335. It can be (and has been) ported to multiple architectures and platforms. It support a variety of installation options, having no specific deployment requirements itself.
-
-Learn about .NET Core
-====================
-
-- [Official .NET Core Docs](https://docs.microsoft.com/dotnet/core)
-
-Get .NET Core
-=============
-
-- [Get .NET Core SDK](https://www.microsoft.com/net/core)
-
-Architecture Docs
-=================
-
-- [.NET Core Globalization Invariant Mode](architecture/globalization-invariant-mode.md)
-- [Cross-Platform Cryptography](architecture/cross-platform-cryptography.md)
-
-Project Docs
-============
-
-- [Developer Guide](project-docs/developer-guide.md)
-- [Performance Testing](project-docs/performance-tests.md)
-- [Contributing to CoreFX](project-docs/contributing.md)
-- [Contributing to .NET Core](../coreclr/project-docs/contributing.md)
-- [Contributing Workflow](../coreclr/project-docs/contributing-workflow.md)
-- [Issue Guide](project-docs/issue-guide.md)
-- [Branching Guide](project-docs/branching-guide.md)
-- [API Review Process](project-docs/api-review-process.md)
-- [Strong Name Signing](project-docs/strong-name-signing.md)
-- [Public Signing](project-docs/public-signing.md)
-- [Repo Organization](project-docs/repo-organization.md)
-- [Project NuGet Dependencies](https://github.com/dotnet/buildtools/blob/master/Documentation/project-nuget-dependencies.md)
-- [Profiling CoreFX](https://github.com/dotnet/performance/blob/master/docs/profiling-workflow-corefx.md)
-
-Coding Guidelines
-=================
-
-- [C# coding style](coding-guidelines/coding-style.md)
-- [Framework Design Guidelines](coding-guidelines/framework-design-guidelines-digest.md)
-- [Cross-Platform Guidelines](coding-guidelines/cross-platform-guidelines.md)
-- [Performance Guidelines](coding-guidelines/performance-guidelines.md)
-- [Interop Guidelines](coding-guidelines/interop-guidelines.md)
-- [Breaking Changes](coding-guidelines/breaking-changes.md)
-- [Breaking Change Definitions](coding-guidelines/breaking-change-definitions.md)
-- [Breaking Change Rules](coding-guidelines/breaking-change-rules.md)
-- [Project Guidelines](coding-guidelines/project-guidelines.md)
-- [Adding APIs Guidelines](coding-guidelines/adding-api-guidelines.md)
-- [Legal Native calls](building/pinvoke-checker.md)
-
-Building from Source
-====================
-
-- [Building CoreFX on FreeBSD, Linux and OS X](building/unix-instructions.md)
-- [Code Coverage](building/code-coverage.md)
-- [Cross Building](building/cross-building.md)
-- [Package and Assembly File Versioning](building/versioning.md)
-
-Other Information
-=================
-
-- [CoreCLR Repo documentation](../coreclr)
-- [Porting to .NET Core](project-docs/support-dotnet-core-instructions.md)
-- [.NET Standards (Ecma)](../coreclr/project-docs/dotnet-standards.md)
-- [MSDN Entry for the CLR](http://msdn.microsoft.com/library/8bs2ecf4.aspx)
-- [Wikipedia Entry for the CLR](http://en.wikipedia.org/wiki/Common_Language_Runtime)
+++ /dev/null
-Building CoreFX on Linux and OS X
-==========================================
-
-## Building
-
-1. Install the prerequisites ([Linux](#user-content-linux), [macOS](#user-content-macos))
-2. Clone the corefx repo `git clone https://github.com/dotnet/corefx.git`
-3. Navigate to the `corefx` directory
-4. Run the build script `./build.sh`
-
-Calling the script `build.sh` builds both the native and managed code.
-
-For more information about the different options when building, run `build.sh --help` and look at examples in the [developer-guide](../project-docs/developer-guide.md).
-
-To build per project, you can use the script `.dotnet/dotnet msbuild` from the root of the repo, e.g. `.dotnet/dotnet msbuild src/System.Console/src /t:rebuild`.
-
-## Minimum Hardware Requirements
-- 2GB RAM
-
-## Prerequisites (native build)
-
-### Linux
-
-First, the package lists might need to be updated
-
-`sudo apt-get update`
-
-#### Native build
-
-For Ubuntu 14.04, the following packages should be installed to build the native
-components
-
-* git
-* clang-9
-* cmake
-* make
-* libc6-dev
-* libssl-dev
-* libkrb5-dev
-* zlib1g-dev
-
-`sudo apt-get install git clang-9 cmake make libc6-dev libssl-dev libkrb5-dev
-zlib1g-dev`
-
-#### Managed build
-
-For Ubuntu 14.04, install the following packages:
-
-* libunwind8
-* libicu52
-* curl
-
-`sudo apt-get install libunwind8 libicu52 curl`
-
-For Ubuntu 16.04 LTS / Bash on Ubuntu on Windows you may need to replace libicu52 with libicu55.
-Ubuntu 16.10 and Ubuntu 17.04 will require libicu57.
-
-`sudo apt-get install libunwind8 libicu55 curl`
-
-For Ubuntu 18.04, you will also need to replace libicu52 with libicu60 and install libssl1.0-dev_1.0.2n-1ubuntu5.1_amd64.deb with dpkg-deb.
-
-```sh
-sudo apt-get install libunwind8 libicu60 curl
-apt-get download libssl1.0-dev
-sudo dpkg-deb -X libssl1.0-dev_1.0.2n-1ubuntu5.1_amd64.deb /
-```
-
-In addition to the above packages, the runtime versions of the packages listed
-in the native section should also be installed (this happens automatically on
-most systems when you install the development packages).
-
-### Windows Subsystem For Linux
-
-Generally building and testing should work fine on Windows Subsystem for Linux (WSL) and it can be convenient if you primarily work on Windows and want to run tests sometimes on Linux.
-
-There is one caveat: you must set the LANG in your shell to something other than the default. For example,
-```sh
-export LANG=en_US.UTF-8
-```
-Otherwise you may get errors like `PackagingException: File not found: '/home/dan/git/corefx/LICENSE.TXT'`. More info in [this issue](https://github.com/dotnet/corefx/issues/38608). It is possible this may occur on other distros, if LANG is set as above.
-
-We have not tested on WSL2 yet. If you try it out, we'd welcome an update.
-
-### macOS
-
-macOS 10.12 or higher is needed to build corefx 2.x.
-
-On macOS a few components are needed which are not provided by a default developer setup:
-* CMake
-* pkgconfig
-* OpenSSL 1.0.1 or 1.0.2
-
-One way of obtaining these components is via [Homebrew](http://brew.sh):
-```sh
-$ brew install cmake pkgconfig openssl
-```
-
-As of El Capitan (OS X 10.11), Apple still has the libraries for OpenSSL 0.9.8 in `/usr/lib`,
-but the headers are no longer available since that library version is out of support.
-Some compilers get upset over new headers being in `/usr/local/include` with the old library being present at
-`/usr/lib/libcrypto.dylib` (the tools have no issue with the versioned files, e.g. `/usr/lib/libcrypto.0.9.8.dylib`),
-and so Homebrew does not allow the OpenSSL package to be installed into system default paths. A minimal installation
-is presented here to facilitate simplifying runtime requirements and compile-time requirements (for build systems using
-CMake's `find_package`, like ours):
-```sh
-# We need to make the runtime libraries discoverable, as well as make
-# pkg-config be able to find the headers and current ABI version.
-#
-# Ensure the paths we will need exist
-mkdir -p /usr/local/lib/pkgconfig
-
-# The rest of these instructions assume a default Homebrew path of
-# /usr/local/opt/<module>, with /usr/local being the answer to
-# `brew --prefix`.
-#
-# Runtime dependencies
-ln -s /usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib /usr/local/lib/
-ln -s /usr/local/opt/openssl/lib/libssl.1.0.0.dylib /usr/local/lib/
-
-# Compile-time dependencies (for pkg-config)
-ln -s /usr/local/opt/openssl/lib/pkgconfig/libcrypto.pc /usr/local/lib/pkgconfig/
-ln -s /usr/local/opt/openssl/lib/pkgconfig/libssl.pc /usr/local/lib/pkgconfig/
-ln -s /usr/local/opt/openssl/lib/pkgconfig/openssl.pc /usr/local/lib/pkgconfig/
-```
-
-### Known Issues
-If you see errors along the lines of `SendFailure (Error writing headers)` you may need to import trusted root certificates:
-
-```sh
-mozroots --import --sync
-```
-
----
-
-## FreeBSD
-
-Build instructions for FreeBSD can be found [here](freebsd-instructions.md).
+++ /dev/null
-Building CoreFX on Windows
-==========================
-
-## Required Software
-
-1. **[Visual Studio 2019](https://visualstudio.microsoft.com/vs/preview/)** (Community, Professional, Enterprise) with the latest update must be installed. The Community version is completely free.
-2. **[CMake](https://cmake.org/)** must be installed from [the CMake download page](https://cmake.org/download/#latest) and added to your path. CMake 3.15.5 or later is required.
-
-## Recommended Software
-**[.NET Core SDK](https://dotnet.microsoft.com/download/dotnet-core/3.0)** >= v3.0.100 should be installed, which will add the `dotnet` toolchain to your path.
-
-### Visual Studio 2019
-
-#### Visual Studio 2019 - 'Workloads' based install
-
-The following are the minimum requirements:
- * .NET desktop development
- * All Required Components
- * .NET Framework 4.7.2 SDK
- * Verify the required components include:
- * .NET Framework 4.7.2 targeting pack
- * Desktop development with C++
- * All Required Components
- * Windows Universal CRT SDK
- * MSVC v142 - VS 2019 C++ x64/x86 build tools (latest - for example - v14.24)
- * MSVC v141 - VS 2017 C++ x64/x86 build tools (latest - for example - v14.16)
- * Verify the required components include:
- * Windows 10 SDK (latest - for example - 10.0.18362.0)
- * .NET Core cross-platform development
- * All Required Components
-
-#### Visual Studio 2019 - 'Individual components' based install
-
-The following are the minimum requirements:
- * C# and Visual Basic Roslyn Compilers
- * .NET Portable Library Targeting Pack
- * Windows 10 SDK
- * C++ core features
- * MSVC v142 - VS 2019 C++ x64/x86 build tools (latest - for example - v14.24)
- * MSVC v141 - VS 2017 C++ x64/x86 build tools (latest - for example - v14.16)
- * MSBuild
- * .NET Framework 4.7.2 SDK
- * .NET Framework 4.7.2 Targeting Pack
- * Windows Universal CRT SDK
-
-To build binaries for ARM, you need the following additional indivdual components:
-* Visual C++ compilers and libraries for ARM
-* Visual C++ compilers and libraries for ARM64
-
-## Building From the Command Line
-
-From a (non-admin) Command Prompt window:
-
-- `build.cmd` - Will cause basic tool initialization and build the default configuration for refs, libs, and packages.
-
-For information on different configurations see [project-guidelines](../coding-guidelines/project-guidelines.md).
-
-**Note**: Before working on individual projects or test projects you **must** run `build.cmd` from the root once before beginning that work. It is also a good idea to run `build.cmd` whenever you pull a large set of unknown changes into your branch.
-
-Visual Studio Solution (.sln) files exist for related groups of libraries. These can be loaded to build, debug and test inside the Visual Studio IDE.
-
-Note that when calling the script `build.cmd` attempts to build both the native and managed code.
-
-For more information about the different options when building, run `build.cmd -help` and look at examples in the [developer-guide](../project-docs/developer-guide.md).
-
-### Running tests from the command line
-
-From the root, use `build.cmd -test`.
-For more details, or to test an individual project, see the [developer guide topic](../project-docs/developer-guide.md).
-
-### Running tests from Visual Studio
-
-1. Open solution of interest
-2. Right click test project and select 'Set as startup project'
-3. Select the corresponding launch profile (green arrow, i.e. `.NET Core xUnit Console`)
-4. Ctrl+F5 (Run)
-
-### Debugging tests in Visual Studio
-
-1. Open solution of interest
-2. Right click test project and select 'Set as startup project'
-3. Set breakpoint appropriately
-4. Select the corresponding launch profile (green arrow, i.e. `.NET Core xUnit Console`)
-5. F5 (Debug)
-
-### Using Test Explorer in Visual Studio
-
-1. Open solution from the build script: `.\build.cmd -vs Microsoft.CSharp`. Alternatively you can also pass in the relative or full path to the solution file.
-2. Navigate to the Test Explorer tab and run/debug tests.
-
-VS Test Explorer support is limited to the .NET Core. To switch between Configurations (Debug / Release), Visual Studio needs to be reopened with the command above together with the additional `--configuration/-c` option.
-
-For advanced debugging using WinDBG see [Debugging CoreFX on Windows](../debugging/windows-instructions.md)
-
-### Notes
-* At any given time, the corefx repo might be configured to use a [more recent compiler](../../../DotnetCLIVersion.txt) than
-the one used by the installed .NET Core SDK. This means the corefx codebase might
-be using language features that are not understood by the IDE, which might result in errors that
-show up as red squiggles while writing code. Such errors should, however, not affect the actual compilation.
-
-* If your build fails with "[...].dll - Access is denied" errors, it might be because Visual Studio/MSBuild is locking these files. Run `taskkill /im dotnet.exe /f` to shutdown all currently running dotnet instances.
+++ /dev/null
-# Benchmarking .NET Core applications
-
-All Benchmarks have been moved to the [dotnet/performance/](https://github.com/dotnet/performance/) repository.
-
-Please read the [Benchmarking workflow for CoreFX](https://github.com/dotnet/performance/blob/master/docs/benchmarking-workflow-corefx.md) document to find out how to build and run the Benchmarks.
\ No newline at end of file
+++ /dev/null
-Contributing to CoreFX
-======================
-
-This document describes contribution guidelines that are specific to CoreFX. Please read [.NET Core Guidelines](../../coreclr/project-docs/contributing.md) for more general .NET Core contribution guidelines.
-
-Coding Style Changes
---------------------
-
-We intend to bring dotnet/corefx into full conformance with the style guidelines described in [Coding Style](../coding-guidelines/coding-style.md). We plan to do that with tooling, in a holistic way. In the meantime, please:
-
-* **DO NOT** send PRs for style changes. For example, do not send PRs that are focused on changing usage of ```Int32``` to ```int```.
-* **DO NOT** send PRs for upgrading code to use newer language features, though it's ok to use newer language features as part of new code that's written. For example, it's ok to use expression-bodied members as part of new code you write, but do not send a PR focused on changing existing properties or methods to use the feature.
-* **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
-
-API Changes
------------
-
-* **DO NOT** submit such PRs until the APIs have been approved via the [API Review Process](api-review-process.md).
-
-Pull Requests
--------------
-
-* **DO** submit all code changes via pull requests (PRs) rather than through a direct commit. PRs will be reviewed and potentially merged by the repo maintainers after a peer review that includes at least one maintainer.
-* **DO NOT** submit "work in progress" PRs. A PR should only be submitted when it is considered ready for review and subsequent merging by the contributor.
-* **DO** give PRs short-but-descriptive names (e.g. "Improve code coverage for System.Console by 10%", not "Fix #1234")
-* **DO** refer to any relevant issues, and include [keywords](https://help.github.com/articles/closing-issues-via-commit-messages/) that automatically close issues when the PR is merged.
-* **DO** tag any users that should know about and/or review the change.
-* **DO** ensure each commit successfully builds. The entire PR must pass all tests in the Continuous Integration (CI) system before it'll be merged.
-* **DO** address PR feedback in an additional commit(s) rather than amending the existing commits, and only rebase/squash them when necessary. This makes it easier for reviewers to track changes.
-* **DO** assume that ["Squash and Merge"](https://github.com/blog/2141-squash-your-commits) will be used to merge your commit unless you request otherwise in the PR.
-* **DO NOT** fix merge conflicts using a merge commit. Prefer `git rebase`.
-* **DO NOT** mix independent, unrelated changes in one PR. Separate real product/test code changes from larger code formatting/dead code removal changes. Separate unrelated fixes into separate PRs, especially if they are in different assemblies.
-
-Merging Pull Requests (for contributors with write access)
-----------------------------------------------------------
-
-* **DO** use ["Squash and Merge"](https://github.com/blog/2141-squash-your-commits) by default for individual contributions unless requested by the PR author.
- Do so, even if the PR contains only one commit. It creates a simpler history than "Create a Merge Commit".
- Reasons that PR authors may request "Merge and Commit" may include (but are not limited to):
-
- - The change is easier to understand as a series of focused commits. Each commit in the series must be buildable so as not to break `git bisect`.
- - Contributor is using an e-mail address other than the primary GitHub address and wants that preserved in the history. Contributor must be willing to squash
- the commits manually before acceptance.
-
+++ /dev/null
-Developer Guide
-===============
-
-The repo can be built for the following platforms, using the provided setup and the following instructions.
-
-| Chip | Windows | Linux | macOS | FreeBSD |
-| :---- | :------: | :------: | :------: | :------: |
-| x64 | ✔ | ✔ | ✔ | ✔ |
-| x86 | ✔ | | | |
-| ARM | ✔ | ✔ | | |
-| ARM64 | ✔ | ✔ | | |
-| | [Instructions](../building/windows-instructions.md) | [Instructions](../building/unix-instructions.md) | [Instructions](../building/unix-instructions.md) | [Instructions](../building/unix-instructions.md) |
-
-
-Building the repository
-=======================
-
-The CoreFX repo can be built from a regular, non-admin command prompt. The build produces multiple binaries that make up the CoreFX libraries and the accompanying tests.
-
-For information about the different options that are available use the argument `-help|-h` when calling the build script:
-```
-build -h
-```
-On Unix, arguments can be passed in with a single `-` or double hyphen `--`.
-
-### Build
-The CoreFX build has two logical components, the native build which produces the "shims" (which provide a stable interface between the OS and managed code) and
-the managed build which produces the MSIL code and NuGet packages that make up CoreFX.
-
-Calling the script `build` attempts to build both the native and managed code.
-
-The build configurations are generally defaulted based on where you are building (i.e. which OS or which architecture) but we have a few shortcuts for the individual properties that can be passed to the build scripts:
-
-- `-framework|-f` identifies the target framework for the build. It defaults to `netcoreapp` but possible values include `netcoreapp` or `netfx`. (msbuild property `TargetGroup`)
-- `-os` identifies the OS for the build. It defaults to the OS you are running on but possible values include `Windows_NT`, `Unix`, `Linux`, or `OSX`. (msbuild property `OSGroup`)
-- `-configuration|-c Debug|Release` controls the optimization level the compilers use for the build. It defaults to `Debug`. (msbuild property `ConfigurationGroup`)
-- `-arch` identifies the architecture for the build. It defaults to `x64` but possible values include `x64`, `x86`, `arm`, or `arm64`. (msbuild property `ArchGroup`)
-
-For more details on the build configurations see [project-guidelines](../coding-guidelines/project-guidelines.md#build-pivots).
-
-**Note**: Before working on individual projects or test projects you **must** run `build` from the root once before beginning that work. It is also a good idea to run `build` whenever you pull a large set of unknown changes into your branch. If you invoke the build script without any actions, the default action chain `-restore -build` is executed. This means that restore and build are not implicit when invoking other actions!
-
-**Note:** You can chain multiple actions together but the order of execution is fixed and does not relate to the position of the argument in the command.
-
-The most common workflow for developers is to call `build` from the root once and then go and work on the individual library that you are trying to make changes for.
-
-By default build only builds the product libraries and none of the tests. If you want to build the tests you can call `build -buildtests`. If you want to run the tests you can call `build -test`. To build and run the tests combine both arguments: `build -buildtests -test`. To build both the product libraries and the test libraries pass `build -build -buildtests` to the command line.
-
-If you invoke the build script without any argument the default arguments will be executed `-restore -build`. Note that -restore and -build are only implicit if no actions are passed in.
-
-**Examples**
-- Building in release mode for platform x64 (restore and build are implicit here as no actions are passed in)
-```
-build -c Release -arch x64
-```
-
-- Building the src assemblies and build and run tests (running all tests takes a considerable amount of time!)
-```
-build -restore -build -buildtests -test
-```
-
-- Building for different target frameworks (restore and build are implicit again as no action is passed in)
-```
-build -framework netcoreapp
-build -framework netfx
-```
-
-- Build only managed components and skip the native build
-```
-build /p:BuildNative=false
-```
-
-- Clean the entire solution
-```
-build -clean
-```
-### Build Native
-The native build produces shims over libc, openssl, gssapi, and libz.
-The build system uses CMake to generate Makefiles using clang.
-The build also uses git for generating some version information.
-
-The native component should be buildable on any system.
-
-**Examples**
-
-- Building in debug mode for platform x64
-```
-./src/Native/build-native debug x64
-```
-
-- The following example shows how you would do an arm cross-compile build.
-```
-./src/Native/build-native debug arm cross verbose
-```
-
-For more information about extra parameters take a look at the scripts `build-native` under src/Native.
-
-### Build And Run Tests
-To build the tests and run them you can call the build script passing -tests option. The same parameters you pass to build should also be passed to ensure you are building and running the tests on the same configuration you have build the product on. However to run tests on the same machine you need to ensure the machine supports the configuration you are building.
-
-**Examples**
-- The following shows how to build only the tests but not run them
-```
-build -buildtests
-```
-
-- The following builds and runs all tests for netcoreapp in release configuration.
-```
-build -buildtests -test -c Release -f netcoreapp
-```
-
-- The following example shows how to pass extra msbuild properties to ignore tests ignored in CI.
-```
-build -test /p:WithoutCategories=IgnoreForCI
-```
-
-### Building individual libraries
-
-**Note**: Before working on individual projects or test projects you **must** run `build` from the root once before beginning that work. It is also a good idea to run `build` whenever you pull a large set of unknown changes into your branch.
-
-Similar to building the entire repo with build.cmd/sh in the root you can build projects based on our directory structure by passing in the directory. We also support
-shortcuts for libraries so you can omit the root src folder from the path. When given a directory we will build all projects that we find recursively under that directory.
-
-**Examples**
-
-- Build all projects for a given library (ex: System.Collections) including running the tests
-```
-build System.Collections
-```
-or
-```
-build src\System.Collections
-```
-or
-```
-cd src\System.Collections
-..\..\build .
-```
-
-- Build just the tests for a library project.
-```
-build src\System.Collections\tests
-```
-
-- All the options listed above like framework and configuration are also supported (note they must be after the directory)
-```
-build System.Collections -f netfx -c Release
-```
-
-### Building individual projects
-
-You can either use `dotnet msbuild` or `msbuild`, depending on which is in your path. As `dotnet msbuild` works on all supported environments (i.e. Unix) we will use it throughout this guide.
-
-**Note**: Before working on individual projects or test projects you **must** run `build` from the root once before beginning that work. It is also a good idea to run `build` whenever you pull a large set of unknown changes into your branch.
-
-Under the src directory is a set of directories, each of which represents a particular assembly in CoreFX. See Library Project Guidelines section under [project-guidelines](../coding-guidelines/project-guidelines.md) for more details about the structure.
-
-For example the src\System.Diagnostics.DiagnosticSource directory holds the source code for the System.Diagnostics.DiagnosticSource.dll assembly.
-
-You can build the DLL for System.Diagnostics.DiagnosticSource.dll by going to the `src\System.Diagnostics.DiagnosticsSource\src` directory and typing `dotnet msbuild`. The DLL ends up in `bin\AnyOS.AnyCPU.Debug\System.Diagnostics.DiagnosticSource` as well as `bin\runtime\[BuildConfiguration]`.
-
-You can build the tests for System.Diagnostics.DiagnosticSource.dll by going to
-`src\System.Diagnostics.DiagnosticSource\tests` and typing `dotnet msbuild`.
-
-Some libraries might also have a ref and/or a pkg directory and you can build them in a similar way by typing `dotnet msbuild` in that directory.
-
-For libraries that have multiple build configurations the configurations will be listed in the `<BuildConfigurations>` property group, commonly found in a configurations.props file next to the csproj. When building the csproj for a configuration the most compatible one in the list will be chosen and set for the build. For more information about `BuildConfigurations` see [project-guidelines](../coding-guidelines/project-guidelines.md).
-
-**Examples**
-
-- Build project for Linux for netcoreapp
-```
-dotnet msbuild System.Net.NetworkInformation.csproj /p:OSGroup=Linux
-```
-
-- Build release version of library
-```
-dotnet msbuild System.Net.NetworkInformation.csproj /p:ConfigurationGroup=Release
-```
-
-To build for all supported configurations you can use the `BuildAll` and `RebuildAll` tasks:
-
-```
-dotnet msbuild System.Net.NetworkInformation.csproj /t:RebuildAll
-```
-
-### Building all for other OSes
-
-By default, building from the root will only build the libraries for the OS you are running on. One can
-build for another OS by specifying `build -os [value]`.
-
-Note that you cannot generally build native components for another OS but you can for managed components so if you need to do that you can do it at the individual project level or build all via passing `/p:BuildNative=false`.
-
-### Building in Release or Debug
-
-By default, building from the root or within a project will build the libraries in Debug mode.
-One can build in Debug or Release mode from the root by doing `build -c Release` or `build -c Debug` or when building a project by specifying `/p:ConfigurationGroup=[Debug|Release]` after the `dotnet msbuild` command.
-
-### Building other Architectures
-
-One can build 32- or 64-bit binaries or for any architecture by specifying in the root `build -arch [value]` or in a project `/p:ArchGroup=[value]` after the `dotnet msbuild` command.
-
-### Benchmarks
-
-All Benchmarks have been moved to the [dotnet/performance/](https://github.com/dotnet/performance/) repository.
-
-Please read the [Benchmarking workflow for CoreFX](https://github.com/dotnet/performance/blob/master/docs/benchmarking-workflow-corefx.md) document to find out how to build and run the Benchmarks.
-
-### Tests
-
-We use the OSS testing framework [xunit](http://xunit.github.io/).
-
-#### Running tests on the command line
-
-To build tests you need to pass the `-buildtests` flag to build.cmd/sh or if you want to build both src and tests you pass `-buildtests` flag (`build -restore -build -buildtests`). Note that you need to specify -restore and -build additionally as those are only implicit if no action is passed in.
-
-For more information about cross-platform testing, please take a look [here](https://github.com/dotnet/corefx/blob/master/Documentation/building/cross-platform-testing.md).
-
-If you are interested in building and running the tests only for a specific library, then there are two different ways to do it:
-
-The easiest (and recommended) way to do it, is by simply building the test .csproj file for that library.
-
-```cmd
-cd src\System.Collections.Immutable\tests
-dotnet msbuild /t:BuildAndTest ::or /t:Test to just run the tests if the binaries are already built
-dotnet msbuild /t:RebuildAndTest ::this will cause a test project to rebuild and then run tests
-```
-
-It is possible to pass parameters to the underlying xunit runner via the `XunitOptions` parameter, e.g.:
-```cmd
-dotnet msbuild /t:Test "/p:XunitOptions=-class Test.ClassUnderTests"
-```
-
-There may be multiple projects in some directories so you may need to specify the path to a specific test project to get it to build and run the tests.
-
-Tests participate in the incremental build. This means that if tests have already been run, and inputs to the incremental build have not changed, rerunning the tests target will not execute the test runner again. To force re-executing tests in this situation, use `/p:ForceRunTests=true`.
-
-#### Running a single test on the command line
-
-To quickly run or debug a single test from the command line, set the XunitMethodName property (found in Tools\tests.targets) to the full method name (including namespace), e.g.:
-```cmd
-dotnet msbuild /t:RebuildAndTest /p:XunitMethodName={FullyQualifiedNamespace}.{ClassName}.{MethodName}
-```
-
-#### Running tests in a different target framework
-
-Each test project can potentially have multiple build configurations. There are some tests that might be OS-specific, or might be testing an API that is available only on some target frameworks, so the `BuildConfigurations` property specifies the valid configurations. By default we will build and run only the default build configuration which is `netcoreapp`. The rest of the configurations will need to be built and ran by specifying the configuration options.
-
-```cmd
-cd src\System.Runtime\tests
-dotnet msbuild System.Runtime.Tests.csproj /p:TargetGroup=netfx
-```
-
-#### Filtering tests using traits
-
-The tests can also be filtered based on xunit trait attributes defined in [`Microsoft.DotNet.XUnitExtensions`](https://github.com/dotnet/arcade/tree/master/src/Microsoft.DotNet.XUnitExtensions). These attributes are specified above the test method's definition. The available attributes are:
-
-#### OuterLoopAttribute
-
-```cs
-[OuterLoop()]
-```
-Tests marked as `OuterLoop` are for scenarios that don't need to run every build. They may take longer than normal tests, cover seldom hit code paths, or require special setup or resources to execute. These tests are excluded by default when testing through `dotnet msbuild` but can be enabled manually by adding the `-testscope outerloop` switch or `/p:TestScope=outerloop` e.g.
-
-```cmd
-build -test -testscope outerloop
-cd src/System.Text.RegularExpressions/tests && dotnet msbuild /t:RebuildAndTest /p:TestScope=outerloop
-```
-
-#### PlatformSpecificAttribute
-
-```cs
-[PlatformSpecific(TestPlatforms platforms)]
-```
-Use this attribute on test methods to specify that this test may only be run on the specified platforms. This attribute returns the following categories based on platform
-- `nonwindowstests` for tests that don't run on Windows
-- `nonlinuxtests` for tests that don't run on Linux
-- `nonosxtests` for tests that don't run on OS X
-
-**[Available Test Platforms](https://github.com/dotnet/arcade/blob/master/src/Microsoft.DotNet.XUnitExtensions/src/TestPlatforms.cs)**
-
-When running tests by building a test project, tests that don't apply to the `OSGroup` are not run. For example, to run Linux-specific tests on a Linux box, use the following command line:
-```sh
-dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=Linux
-```
-To run all Linux-compatible tests that are failing:
-```sh
-dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=Linux /p:WithCategories=failing
-```
-
-#### ActiveIssueAttribute
-This attribute is intended to be used when there is an active issue tracking the test failure and it is needed to be fixed. This is a temporary attribute to skip the test while the issue is fixed. It is important that you limit the scope of the attribute to just the platforms and target monikers where the issue applies.
-
-This attribute can be applied either to a test class (will disable all the tests in that class) or to a test method. It allows multiple usages on the same member.
-
-This attribute returns the 'failing' category, which is disabled by default.
-
-**Disable for all platforms and all target frameworks:**
-```cs
-[ActiveIssue(int issue)]
-[ActiveIssue(string issue)]
-```
-**Disable for specific platform:**
-```cs
-[ActiveIssue(int issue, TestPlatforms platforms)]
-[ActiveIssue(string issue, TestPlatforms platforms)]
-```
-**Disable for specific target frameworks:**
-```cs
-[ActiveIssue(int issue, TargetFrameworkMonikers frameworks)]
-[ActiveIssue(string issue, TargetFrameworkMonikers frameworks)]
-```
-**Disable for specific test platforms and target frameworks:**
-```cs
-[ActiveIssue(int issue, TestPlatforms platforms, TargetFrameworkMonikers frameworks)]
-[ActiveIssue(string issue, TestPlatforms platforms, TargetFrameworkMonikers frameworks)]
-```
-Use this attribute over test methods to skip failing tests only on the specific platforms and the specific target frameworks.
-
-#### SkipOnTargetFrameworkAttribute
-This attribute is intended to disable a test permanently on a framework where an API is not available or there is an intentional difference in behavior in between the tested framework and the skipped framework.
-
-This attribute can be applied either to a test class (will disable all the tests in that class) or to a test method. It allows multiple usages on the same member.
-
-```cs
-[SkipOnTargetFramework(TargetFrameworkMonikers frameworks, string reason)]
-```
-Use this attribute over test methods to skip tests only on the specific target frameworks. The reason parameter doesn't affect the traits but we rather always use it so that when we see this attribute we know why it is being skipped on that framework.
-
-If it needs to be skipped in multiple frameworks and the reasons are different please use two attributes on the same test so that you can specify different reasons for each framework.
-
-**Currently this are the [Framework Monikers](https://github.com/dotnet/arcade/blob/master/src/Microsoft.DotNet.XUnitExtensions/src/TargetFrameworkMonikers.cs#L23-L26) that we support through our test execution infrastructure**
-
-#### ConditionalFactAttribute
-Use this attribute to run the test only when a condition is `true`. This attribute is used when `ActiveIssueAttribute` or `SkipOnTargetFrameworkAttribute` are not flexible enough due to needing to run a custom logic at test time. This test behaves as a `[Fact]` test that has no test data passed in as a parameter.
-
-```cs
-[ConditionalFact(params string[] conditionMemberNames)]
-```
-
-The conditional method needs to be a static method or property on this or any ancestor type, of any visibility, accepting zero arguments, and having a return type of Boolean.
-
-**Example:**
-```cs
-public class TestClass
-{
- public static bool ConditionProperty => true;
-
- [ConditionalFact(nameof(ConditionProperty))]
- public static void TestMethod()
- {
- Assert.True(true);
- }
-}
-```
-
-#### ConditionalTheoryAttribute
-Use this attribute to run the test only when a condition is `true`. This attribute is used when `ActiveIssueAttribute` or `SkipOnTargetFrameworkAttribute` are not flexible enough due to needing to run a custom logic at test time. This test behaves as a `[Theory]` test that has no test data passed in as a parameter.
-
-```cs
-[ConditionalTheory(params string[] conditionMemberNames)]
-```
-
-This attribute must have `[MemberData(string member)]` or a `[ClassData(Type class)]` attribute, which represents an `IEnumerable<object>` containing the data that will be passed as a parameter to the test. Another option is to add multiple or one `[InlineData(object params[] parameters)]` attribute.
-
-The conditional method needs to be a static method or property on this or any ancestor type, of any visibility, accepting zero arguments, and having a return type of Boolean.
-
-**Example:**
-```cs
-public class TestClass
-{
- public static bool ConditionProperty => true;
-
- public static IEnumerable<object[]> Subtract_TestData()
- {
- yield return new object[] { new IntPtr(42), 6, (long)36 };
- yield return new object[] { new IntPtr(40), 0, (long)40 };
- yield return new object[] { new IntPtr(38), -2, (long)40 };
- }
-
- [ConditionalTheory(nameof(ConditionProperty))]
- [MemberData(nameof(Equals_TestData))]
- public static void Subtract(IntPtr ptr, int offset, long expected)
- {
- IntPtr p1 = IntPtr.Subtract(ptr, offset);
- VerifyPointer(p1, expected);
-
- IntPtr p2 = ptr - offset;
- VerifyPointer(p2, expected);
-
- IntPtr p3 = ptr;
- p3 -= offset;
- VerifyPointer(p3, expected);
- }
-}
-```
-
-**Note that all of the attributes above must include an issue number/link and/or have a comment next to them briefly justifying the reason. ActiveIssueAttribute and SkipOnTargetFrameworkAttribute should use their constructor parameters to do this**
-
-_**A few common examples with the above attributes:**_
-
-- Run all tests acceptable on Windows that are not failing:
-```cmd
-dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=Windows_NT
-```
-- Run all outer loop tests acceptable on OS X that are currently associated with active issues:
-```sh
-dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=OSX /p:WithCategories="OuterLoop;failing""
-```
-
-### Code Coverage
-
-Code coverage is built into the corefx build system. It utilizes OpenCover for generating coverage data and ReportGenerator for generating reports about that data. To run:
-
-```cmd
-:: Run full coverage (assuming sources and tests are already built)
-build -test -coverage
-
-If coverage succeeds, the full report can be found at `artifacts\coverage\index.htm`.
-
-:: To run a single project with code coverage enabled pass the /p:Coverage=true property
-cd src\System.Collections.Immutable\tests
-dotnet msbuild /t:BuildAndTest /p:Coverage=true
-```
-
-If coverage succeeds, the individual report can be found at `$(OutDir)\report\index.htm`.
-
-Code coverage reports from the continuous integration system are available from the links on the front page of the corefx repo.
-
-## Testing with private CoreCLR bits
-
-Generally the CoreFx build system gets the CoreCLR from a NuGet package which gets pulled down and correctly copied to the various output directories by building '\eng\restore\runtime\runtime.depproj' which gets built as part of `build.cmd/sh`. For folks that want to do builds and test runs in corefx with a local private build of coreclr you can follow these steps:
-
-
-1. Build CoreCLR and note your output directory. Ex: `\coreclr\bin\Product\Windows_NT.x64.Release\` Note this will vary based on your OS/Architecture/Flavor and it is generally a good idea to use Release builds for CoreCLR when running CoreFx tests and the OS and Architecture should match what you are building in CoreFx.
-2. Build CoreFx either passing in the `CoreCLROverridePath` property or setting it as an environment variable:
-```
-build.cmd /p:CoreCLROverridePath=d:\git\coreclr\bin\Product\Windows_NT.x64.Release\
-```
-
-When we copy the files to override the CoreCLR we do a hard-link copy, so in general if you rebuild CoreCLR the new binaries should be reflected in CoreFx for subsequent builds of individual projects in corefx. However if you want to force refresh or if you want to just update the CoreCLR after you already ran `build.cmd` from CoreFx you can run the following command:
-
-```
-dotnet msbuild /p:CoreCLROverridePath=d:\git\coreclr\bin\Product\Windows_NT.x64.Release\ ./external/runtime/runtime.depproj
-```
-
-By convention the project will look for PDBs in a directory under `$(CoreCLROverridePath)/PDB` and if found will also copy them. If not found no PDBs will be copied. If you want to explicitly set the PDB path then you can pass `CoreCLRPDBOverridePath` property to that PDB directory.
-
-Once you have updated your CoreCLR you can run tests however you usually do (via build.cmd -test, individual test project, in VS, etc) and it should be using your copy of CoreCLR.
-
-If you prefer, you can use a Debug build of System.Private.CoreLib, but if you do you must also use a Debug build of the native portions of the runtime, e.g. coreclr.dll. Tests with a Debug runtime will execute much more slowly than with Release runtime bits.
-
-If the test project does not set the property `TestRuntime` to `true` and you want to collect code coverage that includes types in System.Private.CoreLib.dll, you'll need to follow the above steps, then
-
-`dotnet msbuild /t:rebuildandtest /p:Coverage=true /p:TestRuntime=true`
-
-
-## Debugging with Visual Studio Code
-
-- Install [Visual Studio Code](https://code.visualstudio.com/)
-- Install the [C# Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp)
-- Open the folder containing the source you want to debug in VS Code - i.e., if you are debugging a test failure in System.Net.Sockets, open `corefx/src/System.Net.Sockets`
-- Open the debug window: `ctrl-shift-D` or click on the button on the left
-- Click the gear button at the top to create a launch configuration, select `.NET Core` from the selection dropdown
-- In the `.NET Core Launch (console)` configuration do the following
- - delete the `preLaunchTask` property
- - set `program` to the full path to `dotnet` in the artifacts/bin/testhost directory.
- - something like `corefx/artifacts/bin/testhost/netcoreapp-{OS}-{Configuration}-{Architecture}`, plus the full path to your corefx directory.
- - set `cwd` to the test bin directory.
- - using the System.Net.Sockets example, it should be something like `corefx/artifacts/bin/System.Net.Sockets.Tests/netcoreapp-{OS}-{Configuration}-{Architecture}`, plus the full path to your corefx directory.
- - set `args` to the command line arguments to pass to the test
- - something like: `[ "exec", "--runtimeconfig", "{TestProjectName}.runtimeconfig.json", "xunit.console.dll", "{TestProjectName}.dll", "-notrait", ... ]`, where TestProjectName would be `System.Net.Sockets.Tests`
- - to run a specific test, you can append something like: `[ "method", "System.Net.Sockets.Tests.{ClassName}.{TestMethodName}", ...]`
-- Set a breakpoint and launch the debugger, inspecting variables and call stacks will now work
+++ /dev/null
-Performance Tests
-======================
-
-All Performance Tests have been moved to the [dotnet/performance/](https://github.com/dotnet/performance/) repository.
-
-Please read:
-
-* the [Benchmarking workflow for CoreFX](https://github.com/dotnet/performance/blob/master/docs/benchmarking-workflow-corefx.md) document to find out how to build and run the Performance Tests.
-* the [Profiling workflow for CoreFX](https://github.com/dotnet/performance/blob/master/docs/profiling-workflow-corefx.md) document to find out how to profile CoreFX.
-
## Process
-
+
## Steps
Patents
-------
-Microsoft has issued a [Patent Promise for .NET Libraries and Runtime Components](https://github.com/dotnet/coreclr/blob/master/PATENTS.TXT).
+Microsoft has issued a [Patent Promise for .NET Libraries and Runtime Components](/PATENTS.TXT).
correct -- they are merely listed to help you find the better and less confusing
terminology.
+| Term | Description |
+| ----- | ------------- |
+| AOT | Ahead-of-time compiler. Converts the MSIL bytecode to native machine code for a specific target CPU architecture. |
+| BBT | Microsoft internal early version of C/C++ PGO. See https://www.microsoft.com/windows/cse/bit_projects.mspx. |
+| BOTR | Book Of The Runtime. |
+| CLR | Common Language Runtime. |
+| COMPlus | An early name for the .NET platform, back when it was envisioned as a successor to the COM platform (hence, "COM+"). Used in various places in the CLR infrastructure, most prominently as a common prefix for the names of internal configuration settings. Note that this is different from the product that eventually ended up being named [COM+](https://msdn.microsoft.com/en-us/library/windows/desktop/ms685978.aspx). |
+| COR | [Common Object Runtime](http://www.danielmoth.com/Blog/mscorlibdll.aspx). The name of .NET before it was named .NET. |
+| DAC | Data Access Component. An abstraction layer over the internal structures in the runtime. |
+| EE | Execution Engine. |
+| GC | [Garbage Collector](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/garbage-collection.md). |
+| IPC | Inter-Process Communication. |
+| JIT | [Just-in-Time](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/ryujit-overview.md) compiler. RyuJIT is the code name for the next generation Just-in-Time(aka "JIT") for the .NET runtime. |
+| LCG | Lightweight Code Generation. An early name for [dynamic methods](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Reflection/Emit/DynamicMethod.cs). |
+| MD | MetaData. |
+| MDA | Managed Debugging Assistant - see [details](https://docs.microsoft.com/en-us/dotnet/framework/debug-trace-profile/diagnosing-errors-with-managed-debugging-assistants) (Note: Not in .NET Core, equivalent diagnostic functionality is made available on a case-by-case basis, e.g. [#15465](https://github.com/dotnet/coreclr/issues/15465)) |
+| NGen | Native Image Generator. |
+| NYI | Not Yet Implemented. |
+| PAL | [Platform Adaptation Layer](http://archive.oreilly.com/pub/a/dotnet/2002/03/04/rotor.html). Provides an abstraction layer between the runtime and the operating system. |
+| PE | Portable Executable. |
+| PGO | Profile Guided Optimization - see [details](https://blogs.msdn.microsoft.com/vcblog/2008/11/12/pogo/). |
+| POGO | Profile Guided Optimization - see [details](https://blogs.msdn.microsoft.com/vcblog/2008/11/12/pogo/). |
+| ProjectN | Codename for the first version of [.NET Native for UWP](https://msdn.microsoft.com/en-us/vstudio/dotnetnative.aspx). |
+| R2R | Ready-to-Run. A flavor of native images - command line switch of [crossgen](../building/crossgen.md). |
+| Redhawk | Codename for experimental minimal managed code runtime that evolved into [CoreRT](https://github.com/dotnet/corert/). |
+| SOS | [Son of Strike](http://blogs.msdn.com/b/jasonz/archive/2003/10/21/53581.aspx). The debugging extension for DbgEng based debuggers. Uses the DAC as an abstraction layer for its operation. |
+| SuperPMI | JIT component test framework (super fast JIT testing - it mocks/replays EE in EE-JIT interface) - see [SuperPMI details](https://github.com/dotnet/coreclr/blob/master/src/ToolBox/superpmi/readme.txt). |
+| SVR | The CLR used to be built as two variants, with one called "mscorsvr.dll", to mean the "server" version. In particular, it contained the server GC implementation, which was intended for multi-threaded apps capable of taking advantage of multiple processors. In the .NET Framework 2 release, the two variants were merged into "mscorwks.dll". The WKS version was the default, however the SVR version remained available. |
+| TPA | Trusted Platform Assemblies used to be a special set of assemblies that comprised the platform assemblies, when it was originally designed. As of today, it is simply the set of assemblies known to constitute the application. |
+| URT | Universal Runtime. Ancient name for what ended up being .NET, is used in the WinError facility name FACILITY_URT. |
+| UTC | [Universal Tuple Compiler](https://blogs.msdn.microsoft.com/vcblog/2013/06/12/optimizing-c-code-overview/). The Microsoft C++ optimizer back-end that that starts by converting the information from the FrontEnd into tuples – a binary stream of instructions. |
+| UWP | [Universal Windows Platform (UWP)](https://docs.microsoft.com/en-us/windows/uwp/get-started/universal-application-platform-guide) is a platform-homogeneous application architecture available on every device that runs Windows 10. |
+| VSD | [Virtual Stub Dispatch](../botr/virtual-stub-dispatch.md). Technique of using stubs for virtual method invocations instead of the traditional virtual method table. |
+| VM | Virtual machine. |
+| WKS | The CLR used to be built as two variants, with one called "mscorwks.dll", to mean the "workstation" version. In particular, it contained the client GC implementation, which was intended for single-threaded apps, independent of how many processors were on the machine. In the .NET Framework 2 release, the two variants were merged into "mscorwks.dll". The WKS version was the default, however the SVR version remained available. |
+| ZAP | Original code name for NGen. |
+
## Terms
In this document, the following terms are used:
To begin using the .NET Portability Analyzer, download the extension from the Visual Studio Gallery. You can configure it in Visual Studio via *Tools* >> *Options* >> *.NET Portability Analyzer* and select your Target Platforms.
-
+
To analyze your entire project, right-click on your project in the Solution Explorer and select *Analyze* >> *Analyze Assembly Portability*. Otherwise, go to the Analyze menu and select *Analyze Assembly Portability*. From there, select your project's executable or .dll.
-
+
After running the analysis, you will see your .NET Portability Report. Only types that are unsupported by a target platform will appear in the list and you can review recommendations in the **Messages** tab in the **Error List**. You can also jump to problem areas directly from the **Messages** tab.
-
+
Don't want to use Visual Studio? You can also use the Portability Analyzer from the Command Prompt. Download the command-line analyzer [here](http://github.com/microsoft/dotnet-apiport/releases).
# Visual Studio Solutions
The repository has a number of Visual Studio Solutions files (`*.sln`) that are useful for editing parts of
-what are in the repository. In particular
+what are in the repository. In particular
- * `src\System.Private.CoreLib\System.Private.CorLib.sln` - This solution is for all managed (C#) code that is defined
+ * `src\coreclr\src\System.Private.CoreLib\System.Private.CorLib.sln` - This solution is for all managed (C#) code that is defined
in the runtime itself. This is all class library support of one form or another.
* `artifacts\obj\coreclr\Windows_NT.<Arch>.<BuildType>\CoreCLR.sln` - this solution contains most native (C++) projects
associated with the repository, including
Notice that the CoreCLR solution is under the 'bin' directory. This is because it is created as part of the build.
Thus you can only launch this solution after you have built at least once.
-* See [Debugging](../building/debugging-instructions.md)
+* See [Debugging](building/debugging-instructions.md)
# See Also
--- /dev/null
+# Workflow Guide
+
+The repo can be built for the following platforms, using the provided setup and the following instructions.
+
+| Chip | Windows | Linux | macOS | FreeBSD |
+| :---- | :------: | :------: | :------: | :------: |
+| x64 | ✔ | ✔ | ✔ | ✔ |
+| x86 | ✔ | | | |
+| ARM | ✔ | ✔ | | |
+| ARM64 | ✔ | ✔ | | |
+| | [Requirements](windows-requirements.md) | [Requirements](linux-requirements.md) | [Requirements](macos-instructions.md) |
+
+## Building the repository
+
+The runtime repo can be built from a regular, non-admin command prompt. The repository currently consists of three different partitions: the runtime (coreclr), libraries and the installer. For every partition there's a helper script available in the root (e.g. libraries.cmd/sh). The root build script (build.cmd/sh) should be used to build the entire repository.
+
+For information about the different options available, suplly the argument `-help|-h` when invoking the build script:
+```
+libraries -h
+```
+On Unix, arguments can be passed in with a single `-` or double hyphen `--`.
+
+## Workflows
+
+For instructions on how to build, debug, test, etc. please visit the instructions in the workflow sub-folders.
\ No newline at end of file
--- /dev/null
+# Building
+
+Once all the necessary tools are in place, building is trivial. Simply run coreclr.cmd/sh script that lives in the repository root.
+
+```bat
+ .\coreclr.cmd
+
+ [Lots of build spew]
+
+ Product binaries are available at C:\git\runtime\artifacts\bin\coreclr\Windows_NT.x64.debug
+ Test binaries are available at C:\git\runtime\artifacts\tests\coreclr\Windows_NT.x64.debug
+```
+
+As shown above, the product will be placed in
+
+- Product binaries will be dropped in `artifacts\bin\coreclr\<OS>.<arch>.<flavor>` folder.
+- A NuGet package, Microsoft.Dotnet.CoreCLR, will be created under `artifacts\bin\coreclr\<OS>.<arch>.<flavor>\.nuget` folder.
+- Test binaries will be dropped under `artifacts\tests\coreclr\<OS>.<arch>.<flavor>` folder.
+
+By default, build generates a 'Debug' build type, that has extra checking (assert) compiled into it. You can
+also build the 'release' version which does not have these checks.
+
+The build places logs in `artifacts\log` and these are useful when the build fails.
+
+The build places all of its output in the `artifacts\obj\coreclr` directory, so if you remove that directory you can force a
+full rebuild.
+
+The build has a number of options that you can learn about using build -?. Some of the more important options are
+
+ * -skiptests - don't build the tests. This can shorten build times quite a bit, but means you can't run tests.
+ * -release - build the 'Release' build type that does not have extra development-time checking compiled in.
+ You want this if you are going to do performance testing on your build.
+
+See [Running Tests](../../testing/coreclr-testing.md) for instructions on running the tests.
--- /dev/null
+# Build
+
+The libraries build has two logical components, the native build which produces the "shims" (which provide a stable interface between the OS and managed code) and
+the managed build which produces the MSIL code and NuGet packages that make up CoreFX.
+
+Calling the script `libraries` attempts to build both the native and managed code.
+
+The build configurations are generally defaulted based on where you are building (i.e. which OS or which architecture) but we have a few shortcuts for the individual properties that can be passed to the build scripts:
+
+- `-framework|-f` identifies the target framework for the build. It defaults to `netcoreapp` but possible values include `netcoreapp` or `netfx`. (msbuild property `TargetGroup`)
+- `-os` identifies the OS for the build. It defaults to the OS you are running on but possible values include `Windows_NT`, `Unix`, `Linux`, or `OSX`. (msbuild property `OSGroup`)
+- `-configuration|-c Debug|Release` controls the optimization level the compilers use for the build. It defaults to `Debug`. (msbuild property `ConfigurationGroup`)
+- `-arch` identifies the architecture for the build. It defaults to `x64` but possible values include `x64`, `x86`, `arm`, or `arm64`. (msbuild property `ArchGroup`)
+
+For more details on the build configurations see [project-guidelines](../../../coding-guidelines/project-guidelines.md#build-pivots).
+
+**Note**: Before working on individual projects or test projects you **must** run `build` from the root once before beginning that work. It is also a good idea to run `build` whenever you pull a large set of unknown changes into your branch. If you invoke the build script without any actions, the default action chain `-restore -build` is executed. This means that restore and build are not implicit when invoking other actions!
+
+**Note:** You can chain multiple actions together but the order of execution is fixed and does not relate to the position of the argument in the command.
+
+The most common workflow for developers is to call `libraries` from the root once and then go and work on the individual library that you are trying to make changes for.
+
+By default build only builds the product libraries and none of the tests. If you want to build the tests you can call `libraries -buildtests`. If you want to run the tests you can call `build -test`. To build and run the tests combine both arguments: `libraries -buildtests -test`. To build both the product libraries and the test libraries pass `libraries -build -buildtests` to the command line.
+
+If you invoke the build script without any argument the default arguments will be executed `-restore -build`. Note that -restore and -build are only implicit if no actions are passed in.
+
+**Examples**
+- Building in release mode for platform x64 (restore and build are implicit here as no actions are passed in)
+```
+libraries -c Release -arch x64
+```
+
+- Building the src assemblies and build and run tests (running all tests takes a considerable amount of time!)
+```
+libraries -restore -build -buildtests -test
+```
+
+- Building for different target frameworks (restore and build are implicit again as no action is passed in)
+```
+libraries -framework netcoreapp
+libraries -framework netfx
+```
+
+- Build only managed components and skip the native build
+```
+libraries /p:BuildNative=false
+```
+
+- Clean the entire solution
+```
+libraries -clean
+```
+### Build Native
+The native build produces shims over libc, openssl, gssapi, and libz.
+The build system uses CMake to generate Makefiles using clang.
+The build also uses git for generating some version information.
+
+The native component should be buildable on any system.
+
+**Examples**
+
+- Building in debug mode for platform x64
+```
+./src/libraries/Native/build-native debug x64
+```
+
+- The following example shows how you would do an arm cross-compile build.
+```
+./src/libraries/Native/build-native debug arm cross verbose
+```
+
+For more information about extra parameters take a look at the scripts `build-native` under src/Native.
+
+### Building individual libraries
+
+**Note**: Before working on individual projects or test projects you **must** run `libraries` from the root once before beginning that work. It is also a good idea to run `libraries` whenever you pull a large set of unknown changes into your branch.
+
+Similar to building the entire repo with build.cmd/sh in the root you can build projects based on our directory structure by passing in the directory. We also support
+shortcuts for libraries so you can omit the root src folder from the path. When given a directory we will build all projects that we find recursively under that directory.
+
+**Examples**
+
+- Build all projects for a given library (ex: System.Collections) including running the tests
+```
+libraries System.Collections
+```
+or
+```
+libraries src\libraries\System.Collections
+```
+or
+```
+cd src\libraries\System.Collections
+..\..\libraries .
+```
+
+- Build just the tests for a library project.
+```
+libraries src\libraries\System.Collections\tests
+```
+
+- All the options listed above like framework and configuration are also supported (note they must be after the directory)
+```
+libraries System.Collections -f netfx -c Release
+```
+
+### Building individual projects
+
+You can either use `dotnet msbuild` or `msbuild`, depending on which is in your path. As `dotnet msbuild` works on all supported environments (i.e. Unix) we will use it throughout this guide.
+
+Under the src directory is a set of directories, each of which represents a particular assembly in CoreFX. See Library Project Guidelines section under [project-guidelines](../../../coding-guidelines/project-guidelines.md) for more details about the structure.
+
+For example the src\libraries\System.Diagnostics.DiagnosticSource directory holds the source code for the System.Diagnostics.DiagnosticSource.dll assembly.
+
+You can build the DLL for System.Diagnostics.DiagnosticSource.dll by going to the `src\libraries\System.Diagnostics.DiagnosticsSource\src` directory and typing `dotnet msbuild`. The DLL ends up in `artifacts\bin\AnyOS.AnyCPU.Debug\System.Diagnostics.DiagnosticSource` as well as `artifacts\bin\runtime\[BuildConfiguration]`.
+
+You can build the tests for System.Diagnostics.DiagnosticSource.dll by going to
+`src\libraries\System.Diagnostics.DiagnosticSource\tests` and typing `dotnet msbuild`.
+
+Some libraries might also have a ref and/or a pkg directory and you can build them in a similar way by typing `dotnet msbuild` in that directory.
+
+For libraries that have multiple build configurations the configurations will be listed in the `<BuildConfigurations>` property group, commonly found in a configurations.props file next to the csproj. When building the csproj for a configuration the most compatible one in the list will be chosen and set for the build. For more information about `BuildConfigurations` see [project-guidelines](../../../coding-guidelines/project-guidelines.md).
+
+**Examples**
+
+- Build project for Linux for netcoreapp
+```
+dotnet msbuild System.Net.NetworkInformation.csproj /p:OSGroup=Linux
+```
+
+- Build release version of library
+```
+dotnet msbuild System.Net.NetworkInformation.csproj /p:ConfigurationGroup=Release
+```
+
+To build for all supported configurations you can use the `BuildAll` and `RebuildAll` tasks:
+
+```
+dotnet msbuild System.Net.NetworkInformation.csproj /t:RebuildAll
+```
+
+### Building all for other OSes
+
+By default, building from the root will only build the libraries for the OS you are running on. One can
+build for another OS by specifying `libraries -os [value]`.
+
+Note that you cannot generally build native components for another OS but you can for managed components so if you need to do that you can do it at the individual project level or build all via passing `/p:BuildNative=false`.
+
+### Building in Release or Debug
+
+By default, building from the root or within a project will build the libraries in Debug mode.
+One can build in Debug or Release mode from the root by doing `libraries -c Release` or `libraries -c Debug` or when building a project by specifying `/p:ConfigurationGroup=[Debug|Release]` after the `dotnet msbuild` command.
+
+### Building other Architectures
+
+One can build 32- or 64-bit binaries or for any architecture by specifying in the root `libraries -arch [value]` or in a project `/p:ArchGroup=[value]` after the `dotnet msbuild` command.
```
$ pwd
/usr/pkgsrc/wip/corefx-git/work/corefx
-$ ./run-test.sh \
+$ ./eng/run-test.sh \
--coreclr-bins /usr/pkg/CoreCLR/ \
--mscorlib-bins /usr/pkg/CoreCLR/ \
--corefx-tests /public/artifacts/tests/NetBSD.AnyCPU.Debug/ \
--- /dev/null
+# Debugging Libraries with Visual Studio Code
+
+- Install [Visual Studio Code](https://code.visualstudio.com/)
+- Install the [C# Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp)
+- Open the folder containing the source you want to debug in VS Code - i.e., if you are debugging a test failure in System.Net.Sockets, open `runtime/src/libraries/System.Net.Sockets`
+- Open the debug window: `ctrl-shift-D` or click on the button on the left
+- Click the gear button at the top to create a launch configuration, select `.NET Core` from the selection dropdown
+- In the `.NET Core Launch (console)` configuration do the following
+ - delete the `preLaunchTask` property
+ - set `program` to the full path to `dotnet` in the artifacts/bin/testhost directory.
+ - something like `runtime/artifacts/bin/testhost/netcoreapp-{OS}-{Configuration}-{Architecture}`, plus the full path to your corefx directory.
+ - set `cwd` to the test bin directory.
+ - using the System.Net.Sockets example, it should be something like `runtime/artifacts/bin/System.Net.Sockets.Tests/netcoreapp-{OS}-{Configuration}-{Architecture}`, plus the full path to your corefx directory.
+ - set `args` to the command line arguments to pass to the test
+ - something like: `[ "exec", "--runtimeconfig", "{TestProjectName}.runtimeconfig.json", "xunit.console.dll", "{TestProjectName}.dll", "-notrait", ... ]`, where TestProjectName would be `System.Net.Sockets.Tests`
+ - to run a specific test, you can append something like: `[ "method", "System.Net.Sockets.Tests.{ClassName}.{TestMethodName}", ...]`
+- Set a breakpoint and launch the debugger, inspecting variables and call stacks will now work
# Running .NET Core Tests
-Details on test metadata can be found in [test-configuration.md](https://github.com/dotnet/runtime/blob/master/docs/coreclr/building/test-configuration.md).
+Details on test metadata can be found in [test-configuration.md](building/test-configuration.md).
## Build All Tests
--- /dev/null
+# Filtering libraries tests using traits
+
+The tests can be filtered based on xunit trait attributes defined in [`Microsoft.DotNet.XUnitExtensions`](https://github.com/dotnet/arcade/tree/master/src/Microsoft.DotNet.XUnitExtensions). These attributes are specified above the test method's definition. The available attributes are:
+
+#### OuterLoopAttribute
+
+```cs
+[OuterLoop()]
+```
+Tests marked as `OuterLoop` are for scenarios that don't need to run every build. They may take longer than normal tests, cover seldom hit code paths, or require special setup or resources to execute. These tests are excluded by default when testing through `dotnet msbuild` but can be enabled manually by adding the `-testscope outerloop` switch or `/p:TestScope=outerloop` e.g.
+
+```cmd
+build -test -testscope outerloop
+cd src/System.Text.RegularExpressions/tests && dotnet msbuild /t:RebuildAndTest /p:TestScope=outerloop
+```
+
+#### PlatformSpecificAttribute
+
+```cs
+[PlatformSpecific(TestPlatforms platforms)]
+```
+Use this attribute on test methods to specify that this test may only be run on the specified platforms. This attribute returns the following categories based on platform
+- `nonwindowstests` for tests that don't run on Windows
+- `nonlinuxtests` for tests that don't run on Linux
+- `nonosxtests` for tests that don't run on OS X
+
+**[Available Test Platforms](https://github.com/dotnet/arcade/blob/master/src/Microsoft.DotNet.XUnitExtensions/src/TestPlatforms.cs)**
+
+When running tests by building a test project, tests that don't apply to the `OSGroup` are not run. For example, to run Linux-specific tests on a Linux box, use the following command line:
+```sh
+dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=Linux
+```
+To run all Linux-compatible tests that are failing:
+```sh
+dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=Linux /p:WithCategories=failing
+```
+
+#### ActiveIssueAttribute
+This attribute is intended to be used when there is an active issue tracking the test failure and it is needed to be fixed. This is a temporary attribute to skip the test while the issue is fixed. It is important that you limit the scope of the attribute to just the platforms and target monikers where the issue applies.
+
+This attribute can be applied either to a test class (will disable all the tests in that class) or to a test method. It allows multiple usages on the same member.
+
+This attribute returns the 'failing' category, which is disabled by default.
+
+**Disable for all platforms and all target frameworks:**
+```cs
+[ActiveIssue(int issue)]
+[ActiveIssue(string issue)]
+```
+**Disable for specific platform:**
+```cs
+[ActiveIssue(int issue, TestPlatforms platforms)]
+[ActiveIssue(string issue, TestPlatforms platforms)]
+```
+**Disable for specific target frameworks:**
+```cs
+[ActiveIssue(int issue, TargetFrameworkMonikers frameworks)]
+[ActiveIssue(string issue, TargetFrameworkMonikers frameworks)]
+```
+**Disable for specific test platforms and target frameworks:**
+```cs
+[ActiveIssue(int issue, TestPlatforms platforms, TargetFrameworkMonikers frameworks)]
+[ActiveIssue(string issue, TestPlatforms platforms, TargetFrameworkMonikers frameworks)]
+```
+Use this attribute over test methods to skip failing tests only on the specific platforms and the specific target frameworks.
+
+#### SkipOnTargetFrameworkAttribute
+This attribute is intended to disable a test permanently on a framework where an API is not available or there is an intentional difference in behavior in between the tested framework and the skipped framework.
+
+This attribute can be applied either to a test class (will disable all the tests in that class) or to a test method. It allows multiple usages on the same member.
+
+```cs
+[SkipOnTargetFramework(TargetFrameworkMonikers frameworks, string reason)]
+```
+Use this attribute over test methods to skip tests only on the specific target frameworks. The reason parameter doesn't affect the traits but we rather always use it so that when we see this attribute we know why it is being skipped on that framework.
+
+If it needs to be skipped in multiple frameworks and the reasons are different please use two attributes on the same test so that you can specify different reasons for each framework.
+
+**Currently this are the [Framework Monikers](https://github.com/dotnet/arcade/blob/master/src/Microsoft.DotNet.XUnitExtensions/src/TargetFrameworkMonikers.cs#L23-L26) that we support through our test execution infrastructure**
+
+#### ConditionalFactAttribute
+Use this attribute to run the test only when a condition is `true`. This attribute is used when `ActiveIssueAttribute` or `SkipOnTargetFrameworkAttribute` are not flexible enough due to needing to run a custom logic at test time. This test behaves as a `[Fact]` test that has no test data passed in as a parameter.
+
+```cs
+[ConditionalFact(params string[] conditionMemberNames)]
+```
+
+The conditional method needs to be a static method or property on this or any ancestor type, of any visibility, accepting zero arguments, and having a return type of Boolean.
+
+**Example:**
+```cs
+public class TestClass
+{
+ public static bool ConditionProperty => true;
+
+ [ConditionalFact(nameof(ConditionProperty))]
+ public static void TestMethod()
+ {
+ Assert.True(true);
+ }
+}
+```
+
+#### ConditionalTheoryAttribute
+Use this attribute to run the test only when a condition is `true`. This attribute is used when `ActiveIssueAttribute` or `SkipOnTargetFrameworkAttribute` are not flexible enough due to needing to run a custom logic at test time. This test behaves as a `[Theory]` test that has no test data passed in as a parameter.
+
+```cs
+[ConditionalTheory(params string[] conditionMemberNames)]
+```
+
+This attribute must have `[MemberData(string member)]` or a `[ClassData(Type class)]` attribute, which represents an `IEnumerable<object>` containing the data that will be passed as a parameter to the test. Another option is to add multiple or one `[InlineData(object params[] parameters)]` attribute.
+
+The conditional method needs to be a static method or property on this or any ancestor type, of any visibility, accepting zero arguments, and having a return type of Boolean.
+
+**Example:**
+```cs
+public class TestClass
+{
+ public static bool ConditionProperty => true;
+
+ public static IEnumerable<object[]> Subtract_TestData()
+ {
+ yield return new object[] { new IntPtr(42), 6, (long)36 };
+ yield return new object[] { new IntPtr(40), 0, (long)40 };
+ yield return new object[] { new IntPtr(38), -2, (long)40 };
+ }
+
+ [ConditionalTheory(nameof(ConditionProperty))]
+ [MemberData(nameof(Equals_TestData))]
+ public static void Subtract(IntPtr ptr, int offset, long expected)
+ {
+ IntPtr p1 = IntPtr.Subtract(ptr, offset);
+ VerifyPointer(p1, expected);
+
+ IntPtr p2 = ptr - offset;
+ VerifyPointer(p2, expected);
+
+ IntPtr p3 = ptr;
+ p3 -= offset;
+ VerifyPointer(p3, expected);
+ }
+}
+```
+
+**Note that all of the attributes above must include an issue number/link and/or have a comment next to them briefly justifying the reason. ActiveIssueAttribute and SkipOnTargetFrameworkAttribute should use their constructor parameters to do this**
+
+_**A few common examples with the above attributes:**_
+
+- Run all tests acceptable on Windows that are not failing:
+```cmd
+dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=Windows_NT
+```
+- Run all outer loop tests acceptable on OS X that are currently associated with active issues:
+```sh
+dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=OSX /p:WithCategories="OuterLoop;failing""
+```
--- /dev/null
+# Testing Libraries
+
+We use the OSS testing framework [xunit](http://xunit.github.io/).
+
+To build the tests and run them you can call the libraries build script.
+
+**Examples**
+- The following shows how to build only the tests but not run them
+```
+libraries -buildtests
+```
+
+- The following builds and runs all tests for netcoreapp in release configuration.
+```
+libraries -buildtests -test -c Release -f netcoreapp
+```
+
+- The following example shows how to pass extra msbuild properties to ignore tests ignored in CI.
+```
+libraries -test /p:WithoutCategories=IgnoreForCI
+```
+
+## Running tests on the command line
+
+To build tests you need to pass the `-buildtests` flag to build.cmd/sh or if you want to build both src and tests you pass `-buildtests` flag (`libraries -restore -build -buildtests`). Note that you need to specify -restore and -build additionally as those are only implicit if no action is passed in.
+
+If you are interested in building and running the tests only for a specific library, then there are two different ways to do it:
+
+The easiest (and recommended) way to do it, is by simply building the test .csproj file for that library.
+
+```cmd
+cd src\libraries\System.Collections.Immutable\tests
+dotnet msbuild /t:BuildAndTest ::or /t:Test to just run the tests if the binaries are already built
+dotnet msbuild /t:RebuildAndTest ::this will cause a test project to rebuild and then run tests
+```
+
+It is possible to pass parameters to the underlying xunit runner via the `XUnitOptions` parameter, e.g.:
+```cmd
+dotnet msbuild /t:Test "/p:XUnitOptions=-class Test.ClassUnderTests"
+```
+
+There may be multiple projects in some directories so you may need to specify the path to a specific test project to get it to build and run the tests.
+
+#### Running a single test on the command line
+
+To quickly run or debug a single test from the command line, set the XunitMethodName property, e.g.:
+```cmd
+dotnet msbuild /t:RebuildAndTest /p:XunitMethodName={FullyQualifiedNamespace}.{ClassName}.{MethodName}
+```
+
+#### Running tests in a different target framework
+
+Each test project can potentially have multiple build configurations. There are some tests that might be OS-specific, or might be testing an API that is available only on some target frameworks, so the `BuildConfigurations` property specifies the valid configurations. By default we will build and run only the default build configuration which is `netcoreapp`. The rest of the configurations will need to be built and ran by specifying the configuration options.
+
+```cmd
+cd src\libraries\System.Runtime\tests
+dotnet msbuild System.Runtime.Tests.csproj /p:TargetGroup=netfx
+```
\ No newline at end of file
paths:
include:
- '*'
- - docs/installer/manpages/*
+ - docs/manpages/*
exclude:
- src/coreclr/*
- src/libraries/*
paths:
include:
- '*'
- - docs/installer/manpages/*
+ - docs/manpages/*
exclude:
- src/coreclr/*
- src/libraries/*
<DebPackageVersion>$(HostPackageVersion)</DebPackageVersion>
<InputRoot>$(SharedHostPublishRoot)</InputRoot>
<DebFile>$(SharedHostInstallerFile)</DebFile>
- <ManPagesDir Condition="'$(ManPagesDir)' == ''">$(RepoRoot)Documentation/manpages</ManPagesDir>
<ConfigJsonName>dotnet-sharedhost-debian_config.json</ConfigJsonName>
<ConfigJsonFile>$(debPackaginfConfigPath)$(ConfigJsonName)</ConfigJsonFile>
<debIntermediatesDir>$(PackagesIntermediateDir)$(DebPackageName)/$(DebPackageVersion)</debIntermediatesDir>
<RpmPackageVersion>$(HostPackageVersion)</RpmPackageVersion>
<InputRoot>$(SharedHostPublishRoot)</InputRoot>
<RpmFile>$(SharedHostInstallerFile)</RpmFile>
- <ManPagesDir Condition="'$(ManPagesDir)' == ''">$(RepoRoot)Documentation/manpages</ManPagesDir>
<ConfigJsonName>dotnet-sharedhost-rpm_config.json</ConfigJsonName>
<ConfigJsonFile>$(rpmPackagingConfigPath)$(ConfigJsonName)</ConfigJsonFile>
<RpmIntermediatesDir>$(PackagesIntermediateDir)$(RpmPackageName)/$(RpmPackageVersion)</RpmIntermediatesDir>
projects / platform / upstream / dotnet / runtime.git / commitdiff
