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/code-coverage.md b/Documentation/building/code-coverage.md index b38be058c8bc..7bcf06087ef1 100644 --- a/Documentation/building/code-coverage.md +++ b/Documentation/building/code-coverage.md @@ -56,16 +56,16 @@ This will do the build and testing as with the normal ```build```, but it will r You can also build and test with code coverage for a particular test project rather than for the whole repo. Normally to build and test a particular test suite, from the same directory as that test suite's .csproj, you'd run: - msbuild /t:BuildAndTest + dotnet msbuild /t:BuildAndTest To do so with code coverage, append the ```/p:Coverage=true``` argument: - msbuild /t:BuildAndTest /p:Coverage=true + dotnet msbuild /t:BuildAndTest /p:Coverage=true The results for this one library will then show up in the aforementioned index.htm file. For example, to build, test, and get code coverage results for the System.Diagnostics.Debug library, from the root of the repo one can do: cd src\System.Diagnostics.Debug\tests\ - msbuild /t:BuildAndTest /p:Coverage=true + dotnet msbuild /t:BuildAndTest /p:Coverage=true And then once the run completes: @@ -76,11 +76,11 @@ And then once the run completes: Some of the libraries for which contracts and tests live in the corefx repo are actually fully or partially implemented in the core runtime library in another repo, e.g. the implementation that backs the System.Runtime contract is in System.Private.CoreLib.dll in either the coreclr or corert repo. To run coverage reports for these projects, you need to build System.Private.CoreLib locally from the coreclr repo. To get coverage of System.Private.CoreLib while running the tests for a particular library: 1. Follow the steps outlined at [Testing with Private CoreClr Bits](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/developer-guide.md#testing-with-private-coreclr-bits). Make sure to include the optional steps listed as being required for code coverage. -2. Add /p:CodeCoverageAssemblies="System.Private.CoreLib" to the previously discussed msbuild command, e.g. msbuild /t:BuildAndTest /p:Coverage=true /p:CodeCoverageAssemblies="System.Private.CoreLib" +2. Add /p:CodeCoverageAssemblies="System.Private.CoreLib" to the previously discussed dotnet msbuild command, e.g. dotnet msbuild /t:BuildAndTest /p:Coverage=true /p:CodeCoverageAssemblies="System.Private.CoreLib" The build and test projects take care of copying assemblies and PDBs as needed for coverage runs. The resulting code coverage report should now also include details for System.Private.CoreLib. -Note: as of 10/2017 OpenCover, the default coverage tool, requires PDBs to be Windows PDBs - the needed conversions are automatically performed by coverage runs. You can determine if it is a Windows PDB by doing 'more System.Private.CoreLib.pdb', if it begins with 'Microsoft C/C++ MSF 7.00' it is a Windows PDB. If you need a Windows PDB the Pdb2Pdb tool will convert (or you can do a msbuild /t:rebuild /p:DebugType=full). +Note: as of 10/2017 OpenCover, the default coverage tool, requires PDBs to be Windows PDBs - the needed conversions are automatically performed by coverage runs. You can determine if it is a Windows PDB by doing 'more System.Private.CoreLib.pdb', if it begins with 'Microsoft C/C++ MSF 7.00' it is a Windows PDB. If you need a Windows PDB the Pdb2Pdb tool will convert (or you can do a dotnet msbuild /t:rebuild /p:DebugType=full). ## Cross-platform Coverage As of 07/2018 CoreFx is only able to get coverage information on Windows. To correct this we are experimenting with [coverlet](https://github.com/tonerdo/coverlet). @@ -103,7 +103,7 @@ On Unix just specifying `/p:Coverage=True` triggers the usage of coverlet. Howev 1. Install the [dotnet/cli global tool reportgenerator](https://www.nuget.org/packages/dotnet-reportgenerator-globaltool), add it to the PATH if not automatically added by dotnet/cli (it can be only for the current session) 2. On Linux install the Arial font required for report generation: `sudo apt-get install ttf-mscorefonts-installer` -After that you request a coverage run using either `dotnet msbuild` or the `msbuild.sh` from a test folder, e.g.: +After that you request a coverage run from a test folder, e.g.: ``` dotnet msbuild /t:RebuildAndTest /p:Coverage=True diff --git a/Documentation/building/windows-instructions.md b/Documentation/building/windows-instructions.md index b696c74b19a1..19a9dc0c8ec9 100644 --- a/Documentation/building/windows-instructions.md +++ b/Documentation/building/windows-instructions.md @@ -1,19 +1,11 @@ Building CoreFX on Windows ========================== -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). +1. **[Visual Studio 2017](https://www.visualstudio.com/downloads/)** (Community, Professional, Enterprise) with the latest update must be installed. The Community version is completely free. +2. **[.NET Core SDK](https://www.microsoft.com/net/download/windows)** >= v2.1.401 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 @@ -42,7 +34,6 @@ The following are the minimum requirements: * Windows 10 SDK or Windows 8.1 SDK * Visual Studio C++ Core Features * VC++ 2017 v141 Toolset (x86, x64) - * MSBuild * .NET Framework 4.6 Targeting Pack * Windows Universal CRT SDK * VC++ 2015.3 v140 Toolset (x86, x64) @@ -57,11 +48,11 @@ This will install all the components needed. Note that you will need to adjust the install path to reflect your version, "Community", "Professional", "Enterprise" or "Preview" -## 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. @@ -70,8 +61,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. @@ -91,17 +81,16 @@ 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 Once you've built the source code for netfx from the root (`build.cmd -framework:netfx`) follow these steps: -1. Build test project with the following parameters `msbuild /t:buildandtest /p:targetgroup=netfx /p:testdebugger=devenv.exe`. This will open Visual Studio with the runner as startup project and its corresponding arguments. +1. Build test project with the following parameters `dotnet msbuild /t:buildandtest /p:targetgroup=netfx /p:testdebugger=devenv.exe`. This will open Visual Studio with the runner as startup project and its corresponding arguments. 2. Open project properties and fill in the next information: * Debugger Type -> Managed (v4.6, v4.5, v4.0) * Environment -> you need to add an environment variable as follows: @@ -112,16 +101,11 @@ Once you've built the source code for netfx from the root (`build.cmd -framework For advanced debugging using WinDBG see [Debugging CoreFX on Windows](https://github.com/dotnet/corefx/blob/master/Documentation/debugging/windows-instructions.md) ### 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 +* 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. - -* 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. +show up as red squiggles while writing code. Such errors should, however, not affect the actual compilation. -* 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. +* 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/20627) but we don't have an ETA yet. In the meantime, use the steps above to launch/debug the tests using the console runner. -* If your build fails with "[...].dll - Access is denied" errors, it might be because Visual Studio/MSBuild is locking these files. Try shutting down `VBCSCompiler.exe`, `devenv.exe` and `MSBuild.exe` from the task manager before building again. +* If your build fails with "[...].dll - Access is denied" errors, it might be because Visual Studio/MSBuild is locking these files. Try shutting down `VBCSCompiler.exe` and `dotnet.exe` from the task manager before building again. diff --git a/Documentation/coding-guidelines/adding-api-guidelines.md b/Documentation/coding-guidelines/adding-api-guidelines.md index 6db1ad090990..84ca46fd977b 100644 --- a/Documentation/coding-guidelines/adding-api-guidelines.md +++ b/Documentation/coding-guidelines/adding-api-guidelines.md @@ -82,7 +82,7 @@ the implementation without compat concerns in future releases. - Update the ProjectReferences in the respective pkgproj's to align with the build configurations in the `\src\.builds` file. This may entail adding new references or removing references according to whatever changes were made to the .builds file. - If assembly or package version is updated the package index needs to be updated by running - `msbuild /pkg/.pkgproj /t:UpdatePackageIndex` + `dotnet msbuild /pkg/.pkgproj /t:UpdatePackageIndex` **Update tests** - If changing target framework @@ -93,7 +93,7 @@ the implementation without compat concerns in future releases. - Set `TestTFMs` metadata to a list of target frameworks to run on, will generally match the `SupportedFramework` metadata in the pkgproj (ex: [tests\System.Runtime.builds](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/tests/System.Runtime.Tests.builds#L8)) - If `TestTFMs` is empty it defaults to [netcoreapp1.0](https://github.com/dotnet/corefx/commit/57af41ef1439ad2e443e42d03d55d41613e4c02e#diff-cd0fc5e0bad8102e1a45aa7575bdd102R155) - Add new test code following [conventions](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/project-guidelines.md#code-file-naming-conventions) for new files to that are specific to the new target framework. - - To run just the new test configuration run `msbuild .csproj /t:RebuildAndTest /p:TargetGroup=` + - To run just the new test configuration run `dotnet msbuild .csproj /t:RebuildAndTest /p:TargetGroup=` ## FAQ _**Is your API part of netstandard?**_ diff --git a/Documentation/coding-guidelines/interop-guidelines.md b/Documentation/coding-guidelines/interop-guidelines.md index cb16b6ef0e27..eaca895c9408 100644 --- a/Documentation/coding-guidelines/interop-guidelines.md +++ b/Documentation/coding-guidelines/interop-guidelines.md @@ -134,7 +134,7 @@ TargetsUnix is true for both OSX and Linux builds and can be used to include cod You should not test the value of the OSGroup property directly, instead use one of the values above. #### Project Files -Whenever possible, a single .csproj should be used per assembly, spanning all target platforms, e.g. System.Console.csproj includes conditional entries for when targeting Windows vs when targeting Linux. A property can be passed to msbuild to control which flavor is built, e.g. msbuild /p:OSGroup=OSX System.Console.csproj. +Whenever possible, a single .csproj should be used per assembly, spanning all target platforms, e.g. System.Console.csproj includes conditional entries for when targeting Windows vs when targeting Linux. A property can be passed to dotnet msbuild to control which flavor is built, e.g. `dotnet msbuild /p:OSGroup=OSX System.Console.csproj`. ### Constants - Wherever possible, constants should be defined as "const". Only if the data type doesn't support this (e.g. IntPtr) should they instead be static readonly fields. diff --git a/Documentation/coding-guidelines/project-guidelines.md b/Documentation/coding-guidelines/project-guidelines.md index 905be32d72f5..df67559bbb84 100644 --- a/Documentation/coding-guidelines/project-guidelines.md +++ b/Documentation/coding-guidelines/project-guidelines.md @@ -131,33 +131,21 @@ Temporary versions are at https://github.com/dotnet/corefx/blob/dev/eng/src/Tool - UAP F5 -> `uap-Windows_NT` ## Project configurations for VS -For each unique configuration needed for a given library project a configuration property group should be added to the project so it can be selected and built in VS and also clearly identify the various configurations.
- -`` +For each unique configuration needed for a given library project a configuration entry separated by a ';' should be added to the project so it can be selected and built in VS and also clearly identify the various configurations.
+`$(TargetGroup)-$(OSGroup)-$(ConfigurationGroup)|$(Platform` - Note that the majority of managed projects, currently all in corefx, $(Platform) is overridden to be AnyCPU. +`netcoreapp-Unix-Debug;netcoreapp-Unix-Release;netcoreapp-Windows_NT-Debug;netcoreapp-Windows_NT-Release;uap-Windows_NT-Debug;uap-Windows_NT-Release;uapaot-Windows_NT-Debug;uapaot-Windows_NT-Release` + ####*Examples* -Project configurations for a pure IL library project which targets the defaults. -```xml - - -``` Project configurations with a unique implementation on Unix and Windows ```xml - - - - +netcoreapp-Unix-Debug;netcoreapp-Unix-Release;netcoreapp-Windows_NT-Debug;netcoreapp-Windows_NT-Release ``` Project configurations that are unique for a few different target frameworks and runtimes ```xml - - - - - - +netcoreapp-Windows_NT-Debug;netcoreapp-Windows_NT-Release;uap-Windows_NT-Debug;uap-Windows_NT-Release;uapaot-Windows_NT-Debug;uapaot-Windows_NT-Release ``` ## Updating Configurations @@ -165,7 +153,7 @@ Project configurations that are unique for a few different target frameworks and We have a build task that you can run to automatically update all the projects with the above boilerplate as well as updating all the solution files for the libraries. Whenever you change the list of configurations for a project you can regenerate all these for the entire repo by running: ``` -msbuild build.proj /t:UpdateVSConfigurations +dotnet msbuild build.proj /t:UpdateVSConfigurations ``` If you want to scope the geneneration you can either undo changes that you don't need or you can temporally limit the set of projects or directories by updating the item set in the UpdateVSConfigurations target in https://github.com/dotnet/corefx/blob/master/build.proj diff --git a/Documentation/debugging/debugging-packages.md b/Documentation/debugging/debugging-packages.md index 1fd0d38aa192..d8ff10bd1639 100644 --- a/Documentation/debugging/debugging-packages.md +++ b/Documentation/debugging/debugging-packages.md @@ -4,9 +4,11 @@ Debugging CoreFX build issues ## MSBuild debug options * Enable MSBuild diagnostics log (msbuild.log): -`msbuild my.csproj /flp:v=diag /t:rebuild` +`dotnet msbuild my.csproj /flp:v=diag /t:rebuild` * Generate a flat project file (out.pp): -`msbuild my.csproj /pp:out.pp` +`dotnet msbuild my.csproj /pp:out.pp` +* Generate a binary log usable by the [MSBuild Binary and Structured Log Viewer](http://msbuildlog.com/): +`dotnet msbuild my.csproj /bl` ## Steps to debug packaging build issues @@ -14,11 +16,11 @@ Debugging CoreFX build issues I found the following process to help when investigating some of the build issues caused by incorrect packaging. -In general, always build the .builds file instead of any of the csproj to ensure that all [Build Pivots](../coding-guidelines/project-guidelines.md#build-pivots) are generated. This applies for running tests as well. For more information, see [Build individual CoreFX DLLs](../project-docs/developer-guide.md#building-individual-corefx-dlls) +To quickly validate if a given project compiles on all supported configurations use `dotnet msbuild /t:RebuildAll`. This applies for running tests as well. For more information, see [Building individual libraries](../project-docs/developer-guide.md#building-individual-libraries) Assuming the current directory is `\src\contractname\`: -1. Build the `\ref` folder: `msbuild /t:rebuild contractname.builds` +1. Build the `\ref` folder: `dotnet msbuild /t:rebuild` Check the logs for output such as: @@ -48,11 +50,11 @@ CopyFilesToOutputDirectory: Using your favourite IL disassembler, ensure that each platform contains the correct APIs. Missing APIs from the contracts is likely caused by not having the right `DefineConstants` tags in the csproj files. -2. Build the `\src` folder: `msbuild /t:rebuild contractname.builds` +2. Build the `\src` folder: `dotnet msbuild /t:rebuild` Use the same technique above to ensure that the binaries include the correct implementations. -3. Build the `\pkg` folder: `msbuild /t:rebuild contractname.builds` +3. Build the `\pkg` folder: `dotnet msbuild /t:rebuild` Ensure that all Build Pivots are actually being built. This should build all .\ref and .\src variations as well as actually creating the NuGet packages. @@ -70,7 +72,7 @@ Build: To validate the content of the nupkg, change the extension to .zip. As before, use an IL disassembler to verify that the right APIs are present within `ref\\contractname.dll` and the right implementations within the `lib\\contractname.dll`. -4. Run the tests from `\tests`: `msbuild /t:rebuild,test contractname.Tests.builds` +4. Run the tests from `\tests`: `dotnet msbuild /t:rebuildandtest` Ensure that the test is referencing the correct pkg. For example: ``` @@ -82,7 +84,7 @@ Ensure that the test is referencing the correct pkg. For example: ``` -Ensure that the right `TargetGroup` (what we're testing) and `TestTFM` (the Target Framework of the test code) are correctly set in the .builds file. +Ensure that the right `TargetGroup` (what we're testing) is set. To identify which of the combinations failed, search for the following pattern in the output: @@ -90,18 +92,17 @@ To identify which of the combinations failed, search for the following pattern i Project "S:\c1\src\System.Net.ServicePoint\tests\System.Net.ServicePoint.Tests.builds" (1) is building "S:\c1\src\System.Net.ServicePoint\tests\System.Net.ServicePoint.Tests.csproj" (2:5) on node 1 (Build target(s)). ResolvePkgProjReferences: - Resolved compile assets from .NETStandard,Version=v1.7: S:\c1\bin\ref\System.Net.ServicePoint\4.0.0.0\System.Net.ServicePoint.dll - Resolved runtime assets from .NETCoreApp,Version=v1.1: S:\c1\bin\AnyOS.AnyCPU.Debug\System.Net.ServicePoint\System.Net.ServicePoint.dll + Resolved compile assets from .NETStandard,Version=v2.0: S:\c1\bin\ref\System.Net.ServicePoint\4.0.0.0\System.Net.ServicePoint.dll + Resolved runtime assets from .NETCoreApp,Version=v2.0: S:\c1\bin\AnyOS.AnyCPU.Debug\System.Net.ServicePoint\System.Net.ServicePoint.dll ``` -To run a test from a single Build Pivot combination, specify all properties and build the `csproj` instead of the `builds` file: +To run a test from a single Build Pivot combination, specify all properties and build the `csproj`: ``` -msbuild /t:rebuild,test /p:Outerloop=true "/p:XunitOptions=-showprogress" /p:Configuration=Windows_Debug /p:TargetGroup=netstandard1.7 /p:TestTFM=netcoreapp1.1 .\System.Net.ServicePoint.Tests.csproj +dotnet msbuild System.Net.ServicePoint.Tests.csproj /t:rebuildandtest /p:TargetGroup=netcoreapp2.0 /p:Outerloop=true /p:xunitoptions=-showprogress /p:ConfigurationGroup=Debug ``` Will run the test using the following pivot values: * Architecture: AnyCPU * Flavor: Debug * OS: Windows_NT -* Platform Runtime: netcoreapp1.1 -* Target: netstandard1.7 +* Target: netstandard2.0 diff --git a/Documentation/debugging/windows-instructions.md b/Documentation/debugging/windows-instructions.md index f96f5620d8e4..cb1566761023 100644 --- a/Documentation/debugging/windows-instructions.md +++ b/Documentation/debugging/windows-instructions.md @@ -173,4 +173,4 @@ Helper scripts are available at https://github.com/dotnet/corefx/tree/master/src * `*System.Threading.Tasks.Dataflow.DataflowEventSource {16F53577-E41D-43D4-B47E-C17025BF4025}`: Provides an event source for tracing Dataflow information. ## Notes -* You can find the test invocation command-line by looking at the logs generated after the `msbuild /t:rebuild,test` within the test folder. +* You can find the test invocation command-line by looking at the logs generated after the `dotnet msbuild /t:rebuild,test` within the test folder. diff --git a/Documentation/project-docs/developer-guide.md b/Documentation/project-docs/developer-guide.md index 085d1d9cb40e..6d5fb79dc095 100644 --- a/Documentation/project-docs/developer-guide.md +++ b/Documentation/project-docs/developer-guide.md @@ -99,11 +99,7 @@ For more information about extra parameters take a look at the scripts `build-na ### Build Managed Since the managed build uses the .NET Core CLI (which the build will download), managed components can only be built on a subset of distros. -There are some additional prerequisites from the CLI which need to be installed. Both libicu and -libunwind are used by CoreCLR to execute managed code, so they must be -installed. Since CoreFX does not actually link against these packages, runtime -versions are sufficient. We also require curl to be present, which we use to -download the .NET Core CLI. +There are some additional prerequisites from the CLI which need to be installed. Both libicu and libunwind are used by CoreCLR to execute managed code, so they must be installed. Since CoreFX does not actually link against these packages, runtime versions are sufficient. We also require curl to be present, which we use to download the .NET Core CLI. **Examples** @@ -172,18 +168,20 @@ build System.Collections -framework:netfx -release ### Building individual projects +You can either ues `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 Libary 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 `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,20 +189,24 @@ 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`. +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 @@ -216,11 +218,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 +240,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 +257,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 +266,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 +278,7 @@ The tests can also be filtered based on xunit trait attributes defined in [`Micr ```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 +286,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 +303,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 +423,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 +445,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,21 +453,20 @@ 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 +dotnet msbuild /t:BuildAndTest /p:TargetGroup=uapaot ``` -If native compilation succeeds, the test will build and run as a native executable named "xunit.console.dll" 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.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 :: To run a single project with the .NET Native toolchain, set the appropriate build flags: cd src\Microsoft.CSharp\tests -msbuild /t:BuildAndTest /p:TargetGroup=uap +dotnet msbuild /t:BuildAndTest /p:TargetGroup=uap ``` In this case, your test will get executed within the context of a wrapper UWP application, targeting the Managed uap as opposed to the .NET Native version. @@ -486,7 +486,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. @@ -497,6 +497,6 @@ 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 /t:rebuildandtest /p:Coverage=true /p:CodeCoverageAssemblies="System.Private.CoreLib"` +`dotnet msbuild /t:rebuildandtest /p:Coverage=true /p:CodeCoverageAssemblies="System.Private.CoreLib"` In order to facilitate coverage tools that perform IL rewrite a dedicated shared framework directory is created by default for coverage runs. This shared runtime is copied from the default shared test runtime (the one with version 9.9.9, e.g.: `\corefx\bin\testhost\netcoreapp-Windows_NT-Debug-x64\shared\Microsoft.NETCore.App\9.9.9`). This behavior can be overriden by adding `/p:UseCoverageDedicatedRuntime=false` to the build command used to capture code coverage, which will cause the coverage run to use the same shared runtime as a test run using the native image of System.Private.CoreLib.dll, causing loss of source coverage information for it. 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: diff --git a/Documentation/project-docs/performance-tests.md b/Documentation/project-docs/performance-tests.md index 02ce6a9ff5d8..69e306c16b82 100644 --- a/Documentation/project-docs/performance-tests.md +++ b/Documentation/project-docs/performance-tests.md @@ -12,8 +12,8 @@ Performance test files (if present) are stored within a library's ```tests/Perfo **Step # 2:** Change directory to the performance tests directory: ```cd path/to/library/tests/Performance``` **Step # 3:** Build and run the tests: - - Windows (using admin command shell): ```msbuild /t:BuildAndTest /p:ConfigurationGroup=Release``` - - Linux: ```/Tools/msbuild.sh /t:BuildAndTest /p:ConfigurationGroup=Release``` + - Windows ```dotnet msbuild /t:BuildAndTest /p:ConfigurationGroup=Release``` + - Linux: ```dotnet msbuild /t:BuildAndTest /p:ConfigurationGroup=Release``` **Note: Because build-tests.cmd/sh runs tests concurrently, do not use it for executing performance tests. If you still want to run them concurrently you need to pass the flag `/p:Performance=true` to it: `build-tests -release -- /p:Performance=true`.** diff --git a/Documentation/project-docs/target-dotnetcore-with-msbuild.md b/Documentation/project-docs/target-dotnetcore-with-msbuild.md deleted file mode 100644 index e7692793fa22..000000000000 --- a/Documentation/project-docs/target-dotnetcore-with-msbuild.md +++ /dev/null @@ -1,118 +0,0 @@ -Using MSBuild to build .NET Core projects -========================================= - -The .NET Core tooling is going to [move from project.json to MSBuild based projects](https://blogs.msdn.microsoft.com/dotnet/2016/05/23/changes-to-project-json/). -We expect the first version of the .NET Core tools that use MSBuild to ship along with Visual Studio "15". However, it is possible to use MSBuild for .NET Core -projects today, and this page shows how. - -We recommend that most people targeting .NET Core with *new* projects today use the default tooling experience with project.json. This is because we haven't yet added -support to MSBuild for a lot of the benefits that project.json has, because a lot of the ASP.NET based tooling will not work with MSBuild today, and because when we -do release .NET Core tooling which uses MSBuild, it will be able to automatically convert from project.json to MSBuild based projects. - -You may want to use MSBuild to target .NET Core for existing projects that already use MSBuild that you want to port to .NET Core, or if you are using -MSBuild's extensibility in your build for scenarios that are not well supported for project.json projects. - -Prerequisites -============= - -- [Visual Studio 2015 Update 3 RC](https://www.visualstudio.com/downloads/visual-studio-prerelease-downloads#sec1) or higher -- [.NET Core tools for Visual Studio](https://www.visualstudio.com/downloads/download-visual-studio-vs) -- NuGet Visual Studio extension [v3.5.0-beta](https://dist.nuget.org/visualstudio-2015-vsix/v3.5.0-beta/NuGet.Tools.vsix) or later - -Creating a library targeting .NET Core -====================================== - -- File > New > Project > Class Library (Portable) - - ![New Project](https://dotnetdocs.blob.core.windows.net/getting-started/new-project.png) - -- Select ".NET Framework 4.6" and "ASP.NET Core 1.0" - - ![Portable targets dialog](pcl-targets-dialog-net46-aspnetcore10.png) - -- In the "Library" tab of the project properties, click on the "Target .NET Platform Standard" link, and click "Yes" in the dialog that is shown -- In the `project.json` file: - - Change the version number of the `NETStandard.Library` package to `1.5.0-rc2-24027` (this is the .NET Core RC2 version of the package). - - Add the below `imports` definition inside the `netstandard1.5` framework definition. This will allow your project to reference .NET Core compatible - NuGet packages that haven't been updated to target .NET Standard - - ```json - "netstandard1.5": { - "imports": [ "dnxcore50", "portable-net452" ] - } - ``` - -Creating a .NET Core console application -======================================== -Building a console application for .NET Core requires some customization of the MSBuild build process. A sample project for a .NET Core console application -is [CoreApp](https://github.com/dotnet/corefxlab/tree/master/samples/NetCoreSample/CoreApp) in the [corefxlab](https://github.com/dotnet/corefxlab) repo. -Another good option is to start with [coretemplate](https://github.com/mellinoe/coretemplate), which uses separate MSBuild targets files to target .NET Core -instead of putting the changes directly in the project file. - -It is also possible to start by creating a project in Visual Studio and modify it to target .NET Core. The instructions below show the minimal steps to get this working. -In contrast to CoreApp or coretemplate, a project created this way won't include configurations for targeting Linux and Mac OS. - -Creating a .NET Core console application from Visual Studio -=========================================================== - -- File > New > Project > Console Application -- In "Build" tab of the project properties, select "All Configurations" and change the "Platform Target" to "x64" -- Delete the `app.config` file from the project -- Add the following project.json file to the project: - - ```json - { - "dependencies": { - "Microsoft.NETCore.App": "1.0.0-rc2-3002702" - }, - "runtimes": { - "win7-x64": { }, - "ubuntu.14.04-x64": { }, - "osx.10.10-x64": { } - }, - "frameworks": { - "netcoreapp1.0": { - "imports": [ "dnxcore50", "portable-net452" ] - } - } - } - ``` - -- Open the project's XML for editing (in Visual Studio, right click on the project -> Unload Project, right click again -> Edit MyProj.csproj) - - Remove all the default `Reference` items (to `System`, `System.Core`, etc.) - - Add the following properties to the first `PropertyGroup` in the project: - - ```xml - .NETCoreApp - v1.0 - win7 - true - $(NoWarn);1701 - ``` - - - Add the following at the end of the file (after the import of `Microsoft.Portable.CSharp.Targets`: - - ```xml - - - <_TargetFrameworkDirectories>$(MSBuildThisFileDirectory) - <_FullFrameworkReferenceAssemblyPaths>$(MSBuildThisFileDirectory) - - - true - false - - - Program - $(TargetDir)dotnet.exe - $(TargetPath) - {2E36F1D4-B23C-435D-AB41-18E608940038} - - ``` - - - Close the .csproj file, and reload the project in Visual Studio - -- You should be able to run your program with F5 in Visual Studio, or from the command line in the output folder with `dotnet MyApp.exe` \ No newline at end of file