diff options
Diffstat (limited to 'Documentation/project-docs')
| -rw-r--r-- | Documentation/project-docs/adding_new_public_apis.md | 1 | ||||
| -rw-r--r-- | Documentation/project-docs/ci-trigger-phrases.md | 11 | ||||
| -rw-r--r-- | Documentation/project-docs/contributing-workflow.md | 2 | ||||
| -rw-r--r-- | Documentation/project-docs/contributing.md | 2 | ||||
| -rw-r--r-- | Documentation/project-docs/glossary.md | 67 | ||||
| -rw-r--r-- | Documentation/project-docs/linux-performance-tracing.md | 20 | ||||
| -rw-r--r-- | Documentation/project-docs/profiling-api-status.md | 26 |
7 files changed, 71 insertions, 58 deletions
diff --git a/Documentation/project-docs/adding_new_public_apis.md b/Documentation/project-docs/adding_new_public_apis.md index 289ba7de77..cca5095078 100644 --- a/Documentation/project-docs/adding_new_public_apis.md +++ b/Documentation/project-docs/adding_new_public_apis.md @@ -9,7 +9,6 @@ Many of the CoreFX libraries type-forward their public APIs to the implementatio **Staging the changes** Make the changes to CoreCLR, including System.Private.CoreLib -- Update `coreclr/src/mscorlib/model.xml` with the new APIs. APIs that are not listed in this file will be stripped out prior to publishing. - Merge the changes - Wait for a new System.Private.CoreLib to be published. Check the latest published version [here](https://dotnet.myget.org/feed/dotnet-core/package/nuget/Microsoft.TargetingPack.Private.CoreCLR). diff --git a/Documentation/project-docs/ci-trigger-phrases.md b/Documentation/project-docs/ci-trigger-phrases.md index 03e071d79d..dd0e981ead 100644 --- a/Documentation/project-docs/ci-trigger-phrases.md +++ b/Documentation/project-docs/ci-trigger-phrases.md @@ -235,8 +235,16 @@ To trigger a job, post a comment on your PR with "@dotnet-bot {trigger-phrase}". - **Ubuntu x64 Checked CoreFX JitStressRegs=8 Build & Test:** "test Ubuntu corefx_jitstressregs8" - **Ubuntu x64 Checked CoreFX JitStressRegs=0x10 Build & Test:** "test Ubuntu corefx_jitstressregs0x10" - **Ubuntu x64 Checked CoreFX JitStressRegs=0x80 Build & Test:** "test Ubuntu corefx_jitstressregs0x80" +- **Ubuntu x86 Debug Build:** "test Ubuntu x86 Debug" +- **Ubuntu x86 Checked Build:** "test Ubuntu x86 Checked" +- **Ubuntu x86 Release Build:** "test Ubuntu x86 Release" +- **Ubuntu arm Cross Debug Build & Small Test:** "test Ubuntu arm Cross Debug Build" +- **Ubuntu arm Cross Checked Build & Small Test:** "test Ubuntu arm Cross Checked Build" - **Ubuntu arm64 Release Cross Build:** "test Ubuntu arm64" -- **Ubuntu15.10 x64 Release Priority 0 Build:** "test Ubuntu15.10" +- **Ubuntu16.04 x64 Release Priority 0 Build:** "test Ubuntu16.04 x64" +- **Ubuntu16.04 arm Cross Checked Build & Small Test:** "test Ubuntu16.04 arm Cross Checked Build" +- **Ubuntu16.04 arm Cross Release Build & Small Test:** "test Ubuntu16.04 arm Cross Release Build" +- **Ubuntu16.10 x64 Release Priority 0 Build:** "test Ubuntu16.10" - **OSX x64 Release Priority 1 Build & Test:** "test OSX pri1" - **OSX x64 Release IL RoundTrip Build & Test:** "test OSX ilrt" - **OSX x64 Release Long-Running GC Build & Test:**: "test OSX Release longgc" @@ -343,3 +351,4 @@ To trigger a job, post a comment on your PR with "@dotnet-bot {trigger-phrase}". - **Debian x64 Release Priority 1 Build & Test:** "test Debian8.2 pri1" - **RedHat x64 Release Priority 0 Build:** "test RHEL7.2" - **RedHat x64 Release Priority 1 Build & Test:** "test RHEL7.2 pri1" +- **Tizen arm Cross Checked Build & Small Test:** "test Tizen armel Cross Checked Build" diff --git a/Documentation/project-docs/contributing-workflow.md b/Documentation/project-docs/contributing-workflow.md index 70423e573b..d88e098ebf 100644 --- a/Documentation/project-docs/contributing-workflow.md +++ b/Documentation/project-docs/contributing-workflow.md @@ -6,7 +6,7 @@ You can contribute to .NET Core with issues and PRs. Simply filing issues for pr Getting Started =============== -If you are looking at getting your feet wet with some simple (but still beneficial) changes, check out _up for grabs_ issues on the [CoreCLR](https://github.com/dotnet/coreclr/labels/up-for-grabs) and [CoreFX](https://github.com/dotnet/corefx/labels/up%20for%20grabs) repos. +If you are looking at getting your feet wet with some simple (but still beneficial) changes, check out _up for grabs_ issues on the [CoreCLR](https://github.com/dotnet/coreclr/labels/up-for-grabs) and [CoreFX](https://github.com/dotnet/corefx/labels/up-for-grabs) repos. For new ideas, please always start with an issue before starting development of an implementation. See [project priorities](project-priorities.md) to understand the Microsoft team's approach to engagement on general improvements to the product. Use [CODE_OWNERS.TXT](https://github.com/dotnet/coreclr/blob/master/CODE_OWNERS.TXT) to find relevant maintainers and @ mention them to ask for feedback on your issue. diff --git a/Documentation/project-docs/contributing.md b/Documentation/project-docs/contributing.md index f099bf93bf..3bedc82b07 100644 --- a/Documentation/project-docs/contributing.md +++ b/Documentation/project-docs/contributing.md @@ -129,7 +129,7 @@ The following file header is the used for .NET Core. Please use it for new files ``` - See [class.cpp](../../src/vm/class.cpp) for an example of the header in a C++ file. -- See [List.cs](https://github.com/dotnet/corefx/blob/master/src/System.Collections/src/System/Collections/Generic/List.cs) for an example of the header in a C# file. +- See [List.cs](../../src/mscorlib/src/System/Collections/Generic/List.cs) for an example of the header in a C# file. Copying Files from Other Projects --------------------------------- diff --git a/Documentation/project-docs/glossary.md b/Documentation/project-docs/glossary.md index f4ae1c5127..2a4e912cf3 100644 --- a/Documentation/project-docs/glossary.md +++ b/Documentation/project-docs/glossary.md @@ -1,37 +1,42 @@ .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 contributers when conversing on GitHub (issues, PRs), on twitter and other sites. +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. -* 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 Communicaton -* 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/mscorlib/src/System/Reflection/Emit/DynamicMethod.cs). -* MD: MetaData -* 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). -* ReadyToRun: 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. -* 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 +| 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 Communicaton. | +| 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/mscorlib/src/System/Reflection/Emit/DynamicMethod.cs). | +| MD | MetaData. | +| 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. | diff --git a/Documentation/project-docs/linux-performance-tracing.md b/Documentation/project-docs/linux-performance-tracing.md index 93d63b42aa..c9d66fa8dd 100644 --- a/Documentation/project-docs/linux-performance-tracing.md +++ b/Documentation/project-docs/linux-performance-tracing.md @@ -3,13 +3,13 @@ Performance Tracing on Linux When a performance problem is encountered on Linux, these instructions can be used to gather detailed information about what was happening on the machine at the time of the performance problem. -#Required Tools# +# Required Tools # - **perfcollect**: Bash script that automates data collection. - Available at <http://aka.ms/perfcollect>. - **PerfView**: Windows-based performance tool that can also analyze trace files collected with Perfcollect. - Available at <http://aka.ms/perfview>. -#Preparing Your Machine# +# Preparing Your Machine # Follow these steps to prepare your machine to collect a performance trace. 1. Download Perfcollect. @@ -30,7 +30,7 @@ Follow these steps to prepare your machine to collect a performance trace. > sudo ./perfcollect install > ``` -#Collecting a Trace# +# Collecting a Trace # 1. Have two shell windows available - one for controlling tracing, referred to as **[Trace]**, and one for running the application, referred to as **[App]**. 2. **[App]** Setup the application shell - this enables tracing configuration inside of CoreCLR. @@ -81,7 +81,7 @@ Follow these steps to prepare your machine to collect a performance trace. The compressed trace file is now stored in the current working directory. -#Collecting in a Docker Container# +# Collecting in a Docker Container # Perfcollect can be used to collect data for an application running inside a Docker container. The main thing to know is that collecting a trace requires elevated privileges because the [default seccomp profile](https://docs.docker.com/engine/security/seccomp/) blocks a required syscall - perf_events_open. In order to use the instructions in this document to collect a trace, spawn a new shell inside the container that is privileged. @@ -94,7 +94,7 @@ Even though the application hosted in the container isn't privileged, this new s If you want to try tracing in a container, we've written a [demo Dockerfile](https://raw.githubusercontent.com/dotnet/corefx-tools/master/src/performance/perfcollect/docker-demo/Dockerfile) that installs all of the performance tracing pre-requisites, sets the environment up for tracing, and starts a sample CPU-bound app. -#Filtering# +# Filtering # Filtering is implemented on Windows through the latest mechanisms provided with the [EventSource](https://msdn.microsoft.com/en-us/library/system.diagnostics.tracing.eventsource(v=vs.110).aspx) class. On Linux those mechanisms are not available yet. Instead, there are two environment variables that exist just on linux to do some basic filtering. @@ -104,10 +104,10 @@ On Linux those mechanisms are not available yet. Instead, there are two environm Setting one or both of these variables will only enable collecting events that contain the name you specify as a substring. Strings are treated as case insensitive. -#Viewing a Trace# +# Viewing a Trace # Traces are best viewed using PerfView on Windows. Note that we're currently looking into porting the analysis pieces of PerfView to Linux so that the entire investigation can occur on Linux. -##Open the Trace File## +## Open the Trace File ## 1. Copy the trace.zip file from Linux to a Windows machine. 2. Download PerfView from <http://aka.ms/perfview>. 3. Run PerfView.exe @@ -116,7 +116,7 @@ Traces are best viewed using PerfView on Windows. Note that we're currently loo > PerfView.exe <path to trace.zip file> > ``` -##Select a View## +## Select a View ## PerfView will display the list of views that are supported based on the data contained in the trace file. - For CPU investigations, choose **CPU stacks**. @@ -126,10 +126,10 @@ PerfView will display the list of views that are supported based on the data con For more details on how to interpret views in PerfView, see help links in the view itself, or from the main window in PerfView choose **Help->Users Guide**. -#Extra Information# +# Extra Information # This information is not strictly required to collect and analyze traces, but is provided for those who are interested. -##Prerequisites## +## Prerequisites ## Perfcollect will alert users to any prerequisites that are not installed and offer to install them. Prerequisites can be installed automatically by running: >```bash diff --git a/Documentation/project-docs/profiling-api-status.md b/Documentation/project-docs/profiling-api-status.md index a1f2f17c0e..c689eaefdb 100644 --- a/Documentation/project-docs/profiling-api-status.md +++ b/Documentation/project-docs/profiling-api-status.md @@ -1,10 +1,10 @@ -#Status of CoreCLR Profiler APIs +# Status of CoreCLR Profiler APIs The notes below will help you determine what profiling APIs are safe to use. The .NET Core project started with the codebase from the desktop CoreCLR/Silverlight so all the profiler APIs present there are also present in the code here. However that doesn't automatically imply that they are all working or being actively tested right now. Our goal is to eventually have everything tested and working across all the supported OSes. As we make progress we'll document it here. If you want to use APIs that we haven't tested yet you are welcome to do so, but you need to do your own testing to determine whether they work. If you do test APIs we haven't gotten to yet, we hope you'll add a note below in the Community Tested API section so that everyone can benefit. -#Microsoft Tested APIs: +# Microsoft Tested APIs: -###Windows +### Windows * ICorProfilerCallback: * `Initialize` @@ -34,12 +34,12 @@ The notes below will help you determine what profiling APIs are safe to use. The \* Instrumentation APIs have not been tested on assemblies compiled with Ready2Run technology. Ready2Run is currently used for all Framework assemblies. -###Linux -###OS X +### Linux +### OS X -#Community Tested APIs (please include GitHub handle) +# Community Tested APIs (please include GitHub handle) -###Windows +### Windows * IProfilerCallback * ModuleLoadStarted (noahfalk on behalf of one of our vendors) * JITCompilationStarted (noahfalk on behalf of one of our vendors) @@ -51,12 +51,12 @@ The notes below will help you determine what profiling APIs are safe to use. The * IMetaDataAssemblyEmit * DefineAssemblyRef (noahfalk on behalf of one of our vendors) -###Linux -###OS X +### Linux +### OS X -#APIs definitely known not to work yet -###Windows -###Linux +# APIs definitely known not to work yet +### Windows +### Linux * ICorProfilerInfo: * `SetEnterLeaveFunctionHooks` @@ -68,7 +68,7 @@ The notes below will help you determine what profiling APIs are safe to use. The * `COR_PRF_USE_PROFILE_IMAGES` * `COR_PRF_REQUIRE_PROFILE_IMAGE` -###OS X +### OS X * ICorProfilerInfo: * `SetEnterLeaveFunctionHooks` |