From f6b577a036eec9fdca52362440e97cf44e1ac5ee Mon Sep 17 00:00:00 2001 From: Richard Lander Date: Tue, 14 Apr 2015 14:02:50 -0700 Subject: [PATCH] Correct test instructions - Correct running test instructions - Add links for Linux and Mac OS X builds. --- ...ng-CoreCLR-on-Linux.md => Linux-instructions.md | 0 Mac-OS-X-instructions.md | 4 + Testing-across-repos.md | 20 ---- Windows-instructions.md | 125 +++++++++++++++++++++ 4 files changed, 129 insertions(+), 20 deletions(-) rename Building-and-Running-CoreCLR-on-Linux.md => Linux-instructions.md (100%) create mode 100644 Mac-OS-X-instructions.md delete mode 100644 Testing-across-repos.md create mode 100644 Windows-instructions.md diff --git a/Building-and-Running-CoreCLR-on-Linux.md b/Linux-instructions.md similarity index 100% rename from Building-and-Running-CoreCLR-on-Linux.md rename to Linux-instructions.md diff --git a/Mac-OS-X-instructions.md b/Mac-OS-X-instructions.md new file mode 100644 index 0000000..ce06974 --- /dev/null +++ b/Mac-OS-X-instructions.md @@ -0,0 +1,4 @@ +Mac OS X Instructions +================== + +Nothing here yet. \ No newline at end of file diff --git a/Testing-across-repos.md b/Testing-across-repos.md deleted file mode 100644 index f6ccdea..0000000 --- a/Testing-across-repos.md +++ /dev/null @@ -1,20 +0,0 @@ -#How to run CoreFx tests on top of CoreCLR binaries -If you want to validate the changes you have made to the CoreCLR repo you can do that by running the CoreFx tests on top of the newly build binaries (from the CoreCLR repo) - -In order to do this you need to create a file called `localpublish.props` under the `\packages` folder. -The contents of the file should look like this (make sure to update the version to the current version of the CoreCLR package used by CoreFx): - - - - - Microsoft.DotNet.CoreCLR - 1.0.2-prerelease - \packages - - - - -Once this file is there, subsequent builds of the CoreCLR repo are going to install the CoreCLR package into the location specified by `InstallLocation`. - -To run tests, follow the procedure for running tests in CoreFx \ No newline at end of file diff --git a/Windows-instructions.md b/Windows-instructions.md new file mode 100644 index 0000000..3c61fb2 --- /dev/null +++ b/Windows-instructions.md @@ -0,0 +1,125 @@ +Prerequisites +============= + +- Visual Studio must be installed. Supported versions: + - [Visual Studio Community 2013](http://go.microsoft.com/fwlink/?LinkId=517284) - **Free** for Open Source development! + - [Visual Studio 2013](http://www.visualstudio.com/downloads/download-visual-studio-vs) (Pro, Premium, Ultimate) + - Visual Studio Express isn't supported. + - Visual Studio 2015 is not yet support. +- Install [Cmake](http://www.cmake.org/download/ "CMake") 3.0.2 for Windows and make sure it is present in PATH environment variable for the system. +- Powershell should be installed. +- Tools required to work with Git are installed (e.g. [Git for Windows](http://msysgit.github.io/), [GitHub for Windows](https://windows.github.com/)) + +**Known Issues** + +If you installed VS 2013 after VS 2012, then DIA SDK gets incorrectly installed to the VS 2012 install folder instead of VS 2013 install folder. This will result in a build break. To workaround this [issue](https://connect.microsoft.com/VisualStudio/feedback/details/814147/dia-sdk-installed-into-wrong-directory), copy `%program files (x86)%\Microsoft Visual Studio 11.0\DIA SDK` to `%program files (x86)%\Microsoft Visual Studio 12.0\DIA SDK` and restart the build. More details are [here](http://support.microsoft.com/kb/3035999). + +**Git Configuration** + +The repository is configured to allow Git to make the right decision about handling CRLF. Specifically, if you are working on **Windows**, please ensure that **core.autocrlf** is set to **true**. On **non-Windows** platforms, please set it to **input**. + +Building the repository +======================= + +1. Clone CoreCLR. + - `git clone https://github.com/dotnet/coreclr` + - Alternatitely, clone a fork. This is the best approach if you plan to contribute to the repo. +3. Open a new command prompt and navigate to the root of the cloned repo. +4. Invoke "build.cmd clean" + +This will do a clean x64/Debug build of CoreCLR, its native components, Mscorlib and the tests. + + +- Product Binaries will be dropped in `\Binaries\Product\\` folder. +- A Nuget package, Microsoft.Dotnet.CoreCLR, will also be created under `\Binaries\Product\\\.nuget` folder. +- Test binaries will be dropped under `\Binaries\Tests\\` folder + +**build /?** will list supported parameters. + +## Building and running tests ## + +**Building Tests**        + +In a clean command prompt, issue the following command: + + \tests\buildtest.cmd clean + +**buildtest /?** will list supported parameters. + +**Note:** The above command (or building from the repo_root) must be done once, at the least, to ensure that all test dependencies are initialized correctly. + +In Visual Studio, open `\tests\src\AllTestProjects.sln`, build all the test projects or the one required. + +**Running Tests** + +In a clean command prompt: `\tests\runtest.cmd` + +**runtest /?** will list supported parameters. + +This will generate the report named as `TestRun__.html` (e.g. `TestRun_x64__release.html`) in the current folder. It will also copy all the test dependencies to the folder passed at the command line. + +**Investigating Test Failures** + +Upon completing a test run, you may find one or more tests have failed. + +The output of the Test will be available in Test reports directory, but the default the directory would be something like is `\binaries\tests\x64\debug\Reports\Exceptions\Finalization`. + +There are 2 files of interest: + +- `Finalizer.output.txt` - Contains all the information logged by the test. +- `Finalizer.error.txt` - Contains the information reported by CoreRun.exe (which executed the test) when the test process crashes. + +**Rerunning a failed test** + +If you wish to re-run a failed test, please follow the following steps: + +1. Set an environment variable, `CORE_ROOT`, pointing to the path to product binaries that was passed to runtest.cmd. The command to set this environment variable is also specified in the test report for a failed test. +2. Next, run the failed test, the command to which is also present in the test report for a failed test. It will be something like `\binaries\tests\x64\debug\Exceptions\Finalization\Finalizer.cmd`. + +If you wish to run the test under a debugger (e.g. [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx)), append `-debug ` to the test command. For example: + + + \binaries\tests\x64\debug\Exceptions\Finalization\Finalizer.cmd -debug + +**Modifying a test** + +If test changes are needed, make the change and build the test project. This will binplace the binaries in test binaries folder (e.g. `\binaries\tests\x64\debug\Exceptions\Finalization`). At this point, follow the steps to re-run a failed test to re-run the modified test. + +**Authoring Tests (in VS)** + +1. Use an existing test such as `\tests\src\Exceptions\Finalization\Finalizer.csproj` as a template and copy it to a new folder under `\tests\src`. +2. Add the project of the new test to `\tests\src\AllTestProjects.sln` in VS +3. Add source files to this newly added project. +4. Indicate the success of the test by returning `100`. +5. Add the .NET CoreFX contract references, as required, via the Nuget Package Manager in Visual Studio. *Make sure this does not change the csproj. If it does, then undo the change in the csproj.* +6. Add any other projects as a dependency, if needed. +7. Build the test. +8. Follow the steps to re-run a failed test to validate the new test. + + +## Debugging ## + +**Debugging CoreCLR** + + + +1. Perform a build of the repo. +2. Open \binaries\Cmake\CoreCLR.sln in VS. +3. Right click the INSTALL project and choose ‘Set as StartUp Project’ +4. Bring up the properties page for the INSTALL project +5. Select Configuration Properties->Debugging from the left side tree control +6. Set Command=`$(SolutionDir)..\product\$(Platform)\$(Configuration)\corerun.exe` + 1. This points to the folder where the built runtime binaries are present. +7. Set Command Arguments=`` (e.g. HelloWorld.exe) +8. Set Working Directory=`$(SolutionDir)..\product\$(Platform)\$(Configuration)` + 1. This points to the folder containing CoreCLR binaries. +9. Press F11 to start debugging at wmain in corerun (or set a breakpoint in source and press F5 to run to it) + 1. As an example, set a breakpoint for the EEStartup function in ceemain.cpp to break into CoreCLR startup. + +Steps 1-8 only need to be done once, and then (9) can be repeated whenever you want to start debugging. The above can be done with Visual Studio 2013. + +**Debugging Mscorlib and/or managed application** + +To step into and debug managed code of Mscorlib.dll (or the managed application being executed by the runtime you built), using Visual Studio, is something that will be supported with Visual Studio 2015. We are actively working to enable this support. + +Until then, you can use [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and [SOS](https://msdn.microsoft.com/en-us/library/bb190764(v=vs.110).aspx) (an extension to WinDbg to support managed debugging) to step in and debug the generated managed code. This is what we do on the .NET Runtime team as well :) \ No newline at end of file -- 2.7.4