summaryrefslogtreecommitdiff
path: root/Documentation/building/windows-instructions.md
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/building/windows-instructions.md')
-rw-r--r--Documentation/building/windows-instructions.md196
1 files changed, 64 insertions, 132 deletions
diff --git a/Documentation/building/windows-instructions.md b/Documentation/building/windows-instructions.md
index f68ed2c8c7..8ba021bbf9 100644
--- a/Documentation/building/windows-instructions.md
+++ b/Documentation/building/windows-instructions.md
@@ -1,21 +1,19 @@
Build CoreCLR on Windows
========================
-These instructions will lead you through building CoreCLR and running a "Hello World" demo on Windows.
+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
--------------
+## Visual Studio
Visual Studio must be installed. Supported versions:
+- [Visual Studio 2015](https://www.visualstudio.com/downloads/visual-studio-2015-downloads-vs) (Community, Professional, Enterprise). The community version is completely free.
-- [Visual Studio 2015](https://www.visualstudio.com/downloads/visual-studio-2015-downloads-vs) (Community, Professional, Enterprise)
-
-To debug managed code, ensure you have installed atleast [Visual Studio 2015 Update 3](https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update3-vs).
+To debug managed code, ensure you have installed at least [Visual Studio 2015 Update 3](https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update3-vs).
Make sure that you install "VC++ Tools". By default, they will not be installed.
@@ -23,166 +21,100 @@ To build for Arm32, you need to have [Windows SDK for Windows 10](https://develo
Visual Studio Express is not supported.
-CMake
------
+##CMake
The CoreCLR repo build has been validated using CMake 3.5.2.
- Install [CMake](http://www.cmake.org/download) for Windows.
-- Add it to the PATH environment variable.
+- Add its location (e.g. C:\Program Files (x86)\CMake\bin) to the PATH environment variable.
+ 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)
+
+
+##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.
- Install [Python](https://www.python.org/downloads/) for Windows.
-- Add it to the PATH environment variable.
-
-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\.
+- Add its location (e.g. C:\Python*\) to the PATH environment variable.
+ 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 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).
+##Git
-Git Setup
----------
+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
+for these to work properly. You can get it from
-Clone the CoreCLR and CoreFX repositories (either upstream or a fork).
+- Install [Git For Windows](https://git-for-windows.github.io/)
+- Add its location (e.g. C:\Program Files\Git\cmd) to the PATH environment variable.
+ 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)
-```bat
-C:\git>git clone https://github.com/dotnet/coreclr
-C:\git>git clone https://github.com/dotnet/corefx
-```
+##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\.
-This guide assumes that you've cloned the CoreCLR and CoreFX repositories into C:\git using the default repo names. If your setup is different, you'll need to pay attention to the commands you run. The guide will always show you the current directory.
+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).
-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**.
+##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.
-Demo directory
---------------
+##Adding to the default PATH variable
-In order to keep everything tidy, create a new directory for the files that you will build or acquire.
+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.
-```bat
-c:\git>mkdir \coreclr-demo\runtime
-c:\git>mkdir \coreclr-demo\ref
+You can of course add a directory to the PATH environment variable with the syntax
+```
+ set PATH=%PATH%;DIRECTORY_TO_ADD_TO_PATH
```
+However the change above will only last until the command windows closes. You can make your change to
+the PATH variable persistent by going to Control Panel -> System And Security -> System -> Advanced system settings -> Environment Variables,
+and select the 'Path' variable in the 'System variables' (if you want to change it for all users) or 'User variables' (if you only want
+to change it for the currnet user). Simply edit the PATH variable's value and add the directory (with a semicolon separator).
-Build the Runtime
-=================
+-------------------------------------
+#Building
-To build CoreCLR, run `build.cmd` from the root of the coreclr repository. This will do a x64/Debug build of CoreCLR, its native components, mscorlib.dll, and the tests.
+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.
- C:\git\coreclr>build -rebuild
+```bat
+ .\build
[Lots of build spew]
- Repo successfully built.
-
Product binaries are available at C:\git\coreclr\bin\Product\Windows_NT.x64.debug
Test binaries are available at C:\git\coreclr\bin\tests\Windows_NT.x64.debug
+```
-**Note:** To avoid building the tests, pass the 'skiptestbuild' option to build.
-
-**build -?** will list supported parameters.
-
-Check the build output.
+As shown above the product will be placed in
- Product binaries will be dropped in `bin\Product\<OS>.<arch>.<flavor>` folder.
- A NuGet package, Microsoft.Dotnet.CoreCLR, will be created under `bin\Product\<OS>.<arch>.<flavor>\.nuget` folder.
- Test binaries will be dropped under `bin\Tests\<OS>.<arch>.<flavor>` folder
-You will see several files. The interesting ones are:
-
-- `corerun`: The command line host. This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it.
-- `coreclr.dll`: The CoreCLR runtime itself.
-- `mscorlib.dll`: The core managed library for CoreCLR, which contains all of the fundamental data types and functionality.
-
-Copy these files into the demo directory.
-
-```bat
-C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\clrjit.dll \coreclr-demo\runtime
-C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\CoreRun.exe \coreclr-demo\runtime
-C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\coreclr.dll \coreclr-demo\runtime
-C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\mscorlib.dll \coreclr-demo\runtime
-C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\System.Private.CoreLib.dll \coreclr-demo\runtime
-```
-
-Build the Framework
-===================
-
-Build the framework out of the corefx directory.
+By default build generates a 'Debug' build type, that has extra checking (assert) compiled into it. You can
+also build the 'release' version which does not have these checks
- c:\git\corefx>build.cmd
+The build places logs in `bin\Logs` and these are useful when the build fails.
- [Lots of build spew]
-
- 0 Warning(s)
- 0 Error(s)
- Time Elapsed 00:03:14.53
- Build Exit Code = 0
-
-It's also possible to add -rebuild to build.cmd to force it to delete the previously built assemblies.
-
-For the purposes of this demo, you need to copy a few required assemblies to the demo folder.
-
-```bat
-C:\git\corefx>copy bin\Windows_NT.AnyCPU.Debug\System.Console\System.Console.dll \coreclr-demo\runtime
-C:\git\corefx>copy bin\Windows_NT.AnyCPU.Debug\System.Diagnostics.Debug\System.Diagnostics.Debug.dll \coreclr-demo\runtime
-C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.IO\System.IO.dll \coreclr-demo\runtime
-C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.IO.FileSystem.Primitives\System.IO.FileSystem.Primitives.dll \coreclr-demo\runtime
-C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Runtime\System.Runtime.dll \coreclr-demo\runtime
-C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Runtime.InteropServices\System.Runtime.InteropServices.dll \coreclr-demo\runtime
-C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Text.Encoding\System.Text.Encoding.dll \coreclr-demo\runtime
-C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Text.Encoding.Extensions\System.Text.Encoding.Extensions.dll \coreclr-demo\runtime
-C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Threading\System.Threading.dll \coreclr-demo\runtime
-C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Threading.Tasks\System.Threading.Tasks.dll \coreclr-demo\runtime
-```
-
-You also need to copy reference assemblies, which will be used during compilation.
-
-```bat
-C:\git\corefx>copy bin\ref\System.Runtime\4.0.0.0\System.Runtime.dll \coreclr-demo\ref
-C:\git\corefx>copy bin\ref\System.Console\4.0.0.0\System.Console.dll \coreclr-demo\ref
-```
-
-Compile the Demo
-================
+The build places all of its output in the `bin` directory, so if you remove that directory you can force a
+full rebuild.
-Now you need a Hello World application to run. You can write your own, if you'd like. Here's a very simple one:
+Build has a number of options that you can learn about using build -?. Some of the more important options are
-```C#
-using System;
+ * skiptests - don't build the tests. This can shorten build times quite a bit, but means you can't run tests.
+ * release - build the 'Release' build type that does not have extra development-time checking compiled in.
+ * -rebuild - force the build not to be incremental but to recompile everything.
+ You want this if you are going to do performance testing on your build.
-public class Program
-{
- public static void Main()
- {
- Console.WriteLine("Hello, Windows");
- Console.WriteLine("Love from CoreCLR.");
- }
-}
-```
-
-Personally, I'm partial to the one on corefxlab which will print a picture for you. Download the [corefxlab demo](https://raw.githubusercontent.com/dotnet/corefxlab/master/demos/CoreClrConsoleApplications/HelloWorld/HelloWorld.cs) to `\coreclr-demo`.
-
-Then you just need to build it, with csc, the .NET Framework C# compiler. It may be easier to do this step within the "Developer Command Prompt for VS2015", if csc is not in your path. Because you need to compile the app against the .NET Core surface area, you need to pass references to the contract assemblies you restored using NuGet:
-
-```bat
-csc /nostdlib /noconfig /r:ref\System.Runtime.dll /r:ref\System.Console.dll /out:runtime\hello.exe hello.cs
-```
-
-Run the demo
-============
-
-You're ready to run Hello World! To do that, run corerun, passing the path to the managed exe, plus any arguments. In this case, no arguments are necessary.
-
-```bat
-C:\coreclr-demo>cd runtime
-C:\coreclr-demo\runtime>CoreRun.exe hello.exe
-```
+See [Using Your Build](../workflow/UsingYourBuild.md) for instructions on running code with your build.
-If `CoreRun.exe` fails for some reason, you will see an empty output. To diagnose the issue, you can use `/v` to switch verbose mode on: `CoreRun.exe /v hello.exe`.
+See [Running Tests](../workflow/RunningTests.md) for instructions on running the tests.
-Over time, this process will get easier. Thanks for trying out CoreCLR. Feel free to try a more interesting demo.