diff --git a/Documentation/building/advanced-inner-loop-testing.md b/Documentation/building/advanced-inner-loop-testing.md index a503f1e13576..e5e08ed2fb60 100644 --- a/Documentation/building/advanced-inner-loop-testing.md +++ b/Documentation/building/advanced-inner-loop-testing.md @@ -4,7 +4,7 @@ This tutorial describes how to build and run application code that targets self-compiled .NET Core binaries without using Visual Studio, the .NET Core SDK Host (`dotnet.exe`) or a project file (e.g. `csproj`). Follow these steps to quickly validate changes you've made in the product e.g. by running benchmarks or tests on it. -If you are on Windows you currently need to use the `Developer Command Prompt for VS 2017` to build corefx/coreclr! For the sake of completeness, we have placed our repositories under `d:\git\`. +For the sake of completeness, we have placed our repositories under `d:\git\`. ## Compile corefx with self-compiled coreclr binaries If you've made changes to coreclr make sure to also build it and pass its binaries to corefx. diff --git a/Documentation/building/windows-instructions.md b/Documentation/building/windows-instructions.md index 7e77f8fc7f36..1aa390e271fb 100644 --- a/Documentation/building/windows-instructions.md +++ b/Documentation/building/windows-instructions.md @@ -6,14 +6,9 @@ You can build .NET Core either via the command line or by using Visual Studio. ## Required Software 1. **Visual Studio** must be installed. Supported versions: - * [Visual Studio 2015](https://www.visualstudio.com/vs/older-downloads/) (Community, Professional, Enterprise). The Community version is completely free. - * [Visual Studio 2017](https://www.visualstudio.com/downloads/) (Community, Professional, Enterprise). 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. - -### Visual Studio 2015 - -* [Visual Studio 2015 Update 1](https://www.visualstudio.com/en-us/news/vs2015-update1-vs.aspx) is required. -* You must select **Programming Languages | Visual C++ | Common Tools for Visual C++ 2015** while installing VS 2015 (or modify your install to include it). + * [Visual Studio 2017](https://www.visualstudio.com/downloads/) (Community, Professional, Enterprise). The Community version is completely free. +2. **[.NET Core SDK](https://www.microsoft.com/net/download/windows)** must be installed which will add the `dotnet` CLI to your path. +3. **[CMake](https://cmake.org/)** must be installed from [the CMake download page](https://cmake.org/download/#latest) and added to your path. ### Visual Studio 2017 @@ -47,11 +42,11 @@ The following are the minimum requirements: * Windows Universal CRT SDK * VC++ 2015.3 v140 Toolset (x86, x64) -## Building From the Command Line +For the best possible experience make sure to have the latest version of Visual Studio 2017 installed. -You must use the Developer Command Prompt. It will have a name like "Developer Command Prompt for VS 2017" or similar in your start menu. +## Building From the Command Line -From a (non-admin) Developer Command Prompt window: +From a (non-admin) Command Prompt window: - `build.cmd` - Will cause basic tool initialization and build the default configuration for refs, libs, and packages. - `build-tests.cmd` - Will build and run tests for the default configuration. @@ -60,8 +55,7 @@ For information on different configurations see [project-guidelines](../coding-g **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. +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. Only use it when the parameters that you are passing to the script apply for both components. Otherwise, use the scripts `build-native.cmd` and `build-managed.cmd` respectively. @@ -81,11 +75,10 @@ For more details, or to test an individual project, see the [developer guide top ### Debugging tests in Visual Studio -1. Install VS 2015 Preview or later including Web Developer Tools -2. Open solution of interest in VS 2015 -3. Right click test project and select 'Set as startup project' -4. Set breakpoint appropriately -5. F5 (Debug) +1. Open solution of interest +2. Right click test project and select 'Set as startup project' +3. Set breakpoint appropriately +4. F5 (Debug) ### Debugging NETFX tests in Visual Studio @@ -103,13 +96,8 @@ For advanced debugging using WinDBG see [Debugging CoreFX on Windows](https://gi ### Notes * At any given time, the corefx repo might be configured to use a more recent compiler than -the one used by the most recent Visual Studio IDE release. This means the corefx codebase might +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. +show up as red squiggles while writing code. Such errors should, however, not affect the actual compilation. * Running tests from using the VS test explorer does not currently work after we switched to running on CoreCLR. [We will be working on enabling full VS test integration](https://github.com/dotnet/corefx/issues/1318) but we don't have an ETA yet. In the meantime, use the steps above to launch/debug the tests using the console runner. - -* VS 2015 is required to debug tests running on CoreCLR as the CoreCLR -debug engine is a VS 2015 component. - -* If the Xamarin PCL profiles are installed, the build will fail due to [issue #449](https://github.com/dotnet/corefx/issues/449). A possible workaround is listed [in the issue](https://github.com/dotnet/corefx/issues/449#issuecomment-95117040) itself. diff --git a/Documentation/project-docs/developer-guide.md b/Documentation/project-docs/developer-guide.md index 64ba711eea56..0c0c877e46f8 100644 --- a/Documentation/project-docs/developer-guide.md +++ b/Documentation/project-docs/developer-guide.md @@ -178,12 +178,12 @@ Under the src directory is a set of directories, each of which represents a part 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 `msbuild`. The DLL ends up in `bin\AnyOS.AnyCPU.Debug\System.Diagnostics.DiagnosticSource` as well as `bin\runtime\[BuildConfiguration]`. +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 `msbuild`. +`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 `msbuild` in that directory. +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 `` 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 choosen and set for the build. For more information about `BuildConfigurations` see [project-guidelines](../coding-guidelines/project-guidelines.md). @@ -191,21 +191,19 @@ For libraries that have multiple build configurations the configurations will be - Build project for Linux for netcoreapp ``` -msbuild System.Net.NetworkInformation.csproj /p:OSGroup=Linux +dotnet msbuild System.Net.NetworkInformation.csproj /p:OSGroup=Linux ``` - Build project for uap (not if trying to build on non-windows you also need to specify OSGroup=Windows_NT) ``` -msbuild System.Net.NetworkInformation.csproj /p:TargetGroup=uap +dotnet msbuild System.Net.NetworkInformation.csproj /p:TargetGroup=uap ``` - Build release version of library ``` -msbuild System.Net.NetworkInformation.csproj /p:ConfigurationGroup=Release +dotnet msbuild System.Net.NetworkInformation.csproj /p:ConfigurationGroup=Release ``` -**Note:** If building in a non-Windows environment, call `/Tools/msbuild.sh` instead of just `msbuild`. - ### 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 @@ -216,11 +214,11 @@ Note that you cannot generally build native components for another OS but you ca ### 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 -release` or `build -debug` or when building a project by specifying `/p:ConfigurationGroup=[Debug|Release]` after the `msbuild` command. +One can build in Debug or Release mode from the root by doing `build -release` or `build -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 -buildArch=[value]` or in a project `/p:ArchGroup=[value]` after the `msbuild` command. +One can build 32- or 64-bit binaries or for any architecture by specifying in the root `build -buildArch=[value]` or in a project `/p:ArchGroup=[value]` after the `dotnet msbuild` command. ### Tests @@ -238,15 +236,14 @@ The easiest (and recommended) way to do it, is by simply building the test .cspr ```cmd cd src\System.Collections.Immutable\tests -msbuild /t:BuildAndTest ::or /t:Test to just run the tests if the binaries are already built -msbuild /t:RebuildAndTest ::this will cause a test project to rebuild and then run 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 -msbuild /t:Test "/p:XunitOptions=-class Test.ClassUnderTests" +dotnet msbuild /t:Test "/p:XunitOptions=-class Test.ClassUnderTests" ``` -**Note:** If building in a non-Windows environment, call `./Tools/msbuild.sh` instead of just `msbuild`. 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. @@ -256,7 +253,7 @@ Tests participate in the incremental build. This means that if tests have alrea 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 -msbuild /t:RebuildAndTest /p:XunitMethodName={FullyQualifiedNamespace}.{ClassName}.{MethodName} +dotnet msbuild /t:RebuildAndTest /p:XunitMethodName={FullyQualifiedNamespace}.{ClassName}.{MethodName} ``` #### Running tests in a different target framework @@ -265,7 +262,7 @@ Each test project can potentially have multiple build configurations. There are ```cmd cd src\System.Runtime\tests -msbuild System.Runtime.Tests.csproj /p:TargetGroup=netfx +dotnet msbuild System.Runtime.Tests.csproj /p:TargetGroup=netfx ``` #### Filtering tests using traits @@ -277,7 +274,7 @@ The tests can also be filtered based on xunit trait attributes defined in [`xuni ```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 msbuild but can be enabled manually by adding the `Outerloop` property e.g. +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 `Outerloop` property e.g. ```cmd build-managed -Outerloop @@ -285,7 +282,7 @@ build-managed -Outerloop To run only the Outerloop tests, use the following command: ```cmd -msbuild /t:BuildAndTest /p:WithCategories=OuterLoop +dotnet msbuild /t:BuildAndTest /p:WithCategories=OuterLoop ``` #### PlatformSpecificAttribute @@ -302,11 +299,11 @@ Use this attribute on test methods to specify that this test may only be run on 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 -/Tools/msbuild.sh /t:BuildAndTest /p:OSGroup=Linux +dotnet msbuild /t:BuildAndTest /p:OSGroup=Linux ``` To run all Linux-compatible tests that are failing: ```sh -/Tools/msbuild.sh /t:BuildAndTest /p:OSGroup=Linux /p:WithCategories=failing +dotnet msbuild /t:BuildAndTest /p:OSGroup=Linux /p:WithCategories=failing ``` #### ActiveIssueAttribute @@ -422,11 +419,11 @@ _**A few common examples with the above attributes:**_ - Run all tests acceptable on Windows that are not failing: ```cmd -msbuild /t:BuildAndTest /p:OSGroup=Windows_NT +dotnet msbuild /t:BuildAndTest /p:OSGroup=Windows_NT ``` - Run all outer loop tests acceptable on OS X that are currently associated with active issues: ```sh -/Tools/msbuild.sh /t:BuildAndTest /p:OSGroup=OSX /p:WithCategories="OuterLoop;failing"" +dotnet msbuild /t:BuildAndTest /p:OSGroup=OSX /p:WithCategories="OuterLoop;failing"" ``` Alternatively, you can directly invoke the XUnit executable by changing your working directory to the test execution directory at `bin\tests\{OSPlatformConfig)\{Project}.Tests\{TargetGroup}.{TestTFM}\` which is created when the test project is built. For example, the following command runs all Linux-supported inner-loop tests: @@ -444,7 +441,7 @@ build-tests -Coverage :: To run a single project with code coverage enabled pass the /p:Coverage=true property cd src\System.Collections.Immutable\tests -msbuild /t:BuildAndTest /p:Coverage=true +dotnet msbuild /t:BuildAndTest /p:Coverage=true ``` If coverage succeeds, the code coverage report will be generated automatically and placed in the bin\tests\coverage directory. You can view the full report by opening index.htm @@ -452,15 +449,14 @@ Code coverage reports from the continuous integration system are available from ### Building tests with .NET Native (Windows only) -.NET Native is a technology that allows compiling IL applications down into a native executable and minimal set of native DLLs, containing all needed functionality from the .NET Framework in native format. For CoreFX tests, .NET Native support in CoreFX is relatively early, but supported. +.NET Native is a technology that allows compiling IL applications down into a native executable and minimal set of native DLLs, containing all needed functionality from the .NET Framework in native format. ```cmd :: To run a single project with the .NET Native toolchain, set the appropriate build flags: cd src\Microsoft.CSharp\tests -::TODO: The exact properties needed for .NET Native tests runs after engineering work is TBD -msbuild /t:BuildAndTest /p:TargetGroup=uap /p:UseDotNetNativeToolchain=true +msbuild /t:BuildAndTest /p:TargetGroup=uapaot ``` -If native compilation succeeds, the test will build and run as a native executable named "xunit.console.netcore.exe" in a folder named "native" in the test execution folder. Note many tests in CoreFX are not ready to run though native compilation yet. +If native compilation succeeds, the test will build and run as a native executable named "xunit.console.netcore.exe" in a folder named "uapaot" in the test execution folder. The .NET Native toolchain, required to build with TargetGroup `uapaot` is currently not available for external contributors. A slight variation on these arguments will allow you to build and run against `uap`, the managed version of the UWP Framework subset, used when debugging UWP applications in Visual Studio: ```cmd @@ -486,7 +482,7 @@ build.cmd -- /p:CoreCLROverridePath=d:\git\coreclr\bin\Product\Windows_NT.x64.Re 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: ``` -msbuild /p:CoreCLROverridePath=d:\git\coreclr\bin\Product\Windows_NT.x64.Release\ ./external/runtime/runtime.depproj +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. @@ -499,4 +495,4 @@ If you prefer, you can use a Debug build of System.Private.CoreLib, but if you d To collect code coverage that includes types in System.Private.CoreLib.dll, you'll need to follow the above steps, then -`msbuild /p:CoreCLROverridePath=d:\git\coreclr\bin\Product\Windows_NT.x64.Release\ /t:rebuildandtest /p:Coverage=true /p:CodeCoverageAssemblies="System.Private.CoreLib"` +`dotnet msbuild /p:CoreCLROverridePath="d:\git\coreclr\bin\Product\Windows_NT.x64.Release\" /t:RebuildAndTest /p:Coverage=true /p:CodeCoverageAssemblies="System.Private.CoreLib"` diff --git a/Documentation/project-docs/dogfooding.md b/Documentation/project-docs/dogfooding.md index 60e1f1f8bf07..76bcdd6eb5b5 100644 --- a/Documentation/project-docs/dogfooding.md +++ b/Documentation/project-docs/dogfooding.md @@ -12,28 +12,36 @@ this experience. Make sure to consult this document often. 2. By default, the dotnet CLI will use the globally installed SDK if it matches the major/minor version you request and has a higher revision. To force it to use the locally installed SDK, you must set an environment variable `DOTNET_MULTILEVEL_LOOKUP=0` in your shell. You can use `dotnet --info` to verify what version of the Shared Framework it is using. -3. Reminder: if you are using a local copy of the dotnet CLI, take care that when you type `dotnet` you do not inadvertently pick up a different copy that you may have in your path. On Windows, for example, if you use a Developer Command Prompt, a global copy may be in the path, so use the fully qualified path to your local `dotnet`. If you receive an error "The current .NET SDK does not support targeting .NET Core 2.1." then you may be executing an older `dotnet`. +3. Reminder: if you are using a local copy of the dotnet CLI, take care that when you type `dotnet` you do not inadvertently pick up a different copy that you may have in your path. On Windows, for example, if you use a Command Prompt, a global copy may be in the path, so use the fully qualified path to your local `dotnet`. If you receive an error "The current .NET SDK does not support targeting .NET Core 2.1." then you may be executing an older `dotnet`. After setting up dotnet you can verify you are using the newer version by executing `dotnet --info` -- the version should be greater than `2.1.300-*` (dotnet CLI for .NET Core 2.1 is currently numbered `2.1.300-*`). Here is an example output at the time of writing: ``` ->dotnet.exe --info -.NET Command Line Tools (2.1.300-preview2-008171) - -Product Information: - Version: 2.1.300-preview2-008171 - Commit SHA-1 hash: fbc76ea5f6 +>dotnet --info +.NET Core SDK (reflecting any global.json): + Version: 2.1.301 + Commit: 59524873d6 Runtime Environment: OS Name: Windows - OS Version: 10.0.16299 + OS Version: 10.0.17711 OS Platform: Windows RID: win10-x64 - Base Path: F:\dotnet\sdk\2.1.300-preview2-008171\ + Base Path: C:\Program Files\dotnet\sdk\2.1.301\ + +Host (useful for support): + Version: 2.1.1 + Commit: 6985b9f684 + +.NET Core SDKs installed: + 2.1.301 [C:\Program Files\dotnet\sdk] -Microsoft .NET Core Shared Framework Host +.NET Core runtimes installed: + Microsoft.AspNetCore.All 2.1.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All] + Microsoft.AspNetCore.App 2.1.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App] + Microsoft.NETCore.App 2.1.1 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App] - Version : 2.1.0-preview2-26209-04 - Build : 5df6e9b7ab674a461b2a7f01ac87fb6e0ca06666 +To install additional .NET Core runtimes or SDKs: + https://aka.ms/dotnet-download ``` 4. Our nightly builds are uploaded to MyGet, not NuGet - so ensure the .NET Core MyGet feed is in your nuget configuration in case you need other packages from .NET Core that aren't included in the download. For example, on Windows you could edit `%userprofile%\appdata\roaming\nuget\nuget.config` or on Linux edit `~/.nuget/NuGet/NuGet.Config` to add this line: