-#The Book of the Runtime
+# The Book of the Runtime
Welcome to the Book of the Runtime (BOTR) for the .NET Runtime. This contains
a collection of articles about the non-trivial internals of the .NET Runtime. Its
HistObjFind (histobjfind)
HistClear (histclear)
-###Aliases###
+### Aliases ###
By default you can reach all the SOS commands by using: _sos [command\_name]_
However the common commands have been aliased so that you don't need the SOS prefix:
These instructions will lead you through building CoreCLR.
----------------
-#Environment
+# Environment
You must install several components to build the CoreCLR and CoreFX repos. These instructions were tested on Windows 7+.
Visual Studio Express is not supported.
-##CMake
+## CMake
The CoreCLR repo build has been validated using CMake 3.7.2
following the instructions at [Adding to the Default PATH variable](#adding-to-the-default-path-variable)
-##Python
+## Python
Python is used in the build system. We are currently using python 2.7.9, although
any recent (2.4+) version of Python should work, including Python 3.
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
+## Git
For actual user operations, it is often more convinient to use the GIT features built into Visual Studio 2015.
However the CoreCLR and the tests use the GIT command line utilities directly so you need to install them
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
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).
-##DotNet Core SDK
+## DotNet Core SDK
While not strictly needed to build or tests 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](Documentation/workflow/UsingYourBuild.md) instructions. Visual Studio 2015 (update 3) 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://www.microsoft.com/net/core) page.
-##Adding to the default PATH variable
+## 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.
to change it for the currnet user). Simply edit the PATH variable's value and add the directory (with a semicolon separator).
-------------------------------------
-#Building
+# 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.
# CoreClr Event Logging Design
-##Introduction
+## Introduction
Event Logging is a mechanism by which CoreClr can provide a variety of information on it's state. This Logging works by inserting explicit logging calls by the developer within the VM . The Event Logging mechanism is largely based on [ETW- Event Tracing For Windows](https://msdn.microsoft.com/en-us/library/windows/desktop/bb968803(v=vs.85).aspx)
# .NET Cross-Plat Performance and Eventing Design
-##Introduction
+## Introduction
As we bring up CoreCLR on the Linux and OS X platforms, it’s important that we determine how we’ll measure and analyze performance on these platforms. On Windows we use an event based model that depends on ETW, and we have a good amount of tooling that builds on this approach. Ideally, we can extend this model to Linux and OS X and re-use much of the Windows tooling.
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.
> 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.
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.
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.
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
> 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**.
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
-#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`
\* 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)
* 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`
* `COR_PRF_USE_PROFILE_IMAGES`
* `COR_PRF_REQUIRE_PROFILE_IMAGE`
-###OS X
+### OS X
* ICorProfilerInfo:
* `SetEnterLeaveFunctionHooks`
If you want to ask a question, or want wider discussion (to see if others share you issue), we encourage you to start a thread
in the [.NET Foundation forums](http://forums.dotnetfoundation.org/).
-###Chat with the CoreCLR Community
+### Chat with the CoreCLR Community
For more real-time feedback you can also start a chat session by clicking on the icons below.
-#Running .NET Core Tests
+# Running .NET Core Tests
TODO - Incomplete.
projects / platform / upstream / dotnet / runtime.git / commitdiff