This project is read-only.

Building, Testing, and Debugging

Required Software

Visual Studio "14" Professional
The Roslyn source code currently targets prerelease builds of Visual Studio "14". Because parts of the source code extend Visual Studio using the VS SDK, a Professional or higher version of Visual Studio is required.

Visual Studio "14" SDK
The Visual Studio SDK is used to extend Visual Studio "14". The SDK is a free download and a quick install that works with Visual Studio "14" Professional (or higher).

.NET Compiler Platform ("Roslyn") End User Preview
In order to test your changes inside Visual Studio, you’ll need the End User Preview installed to configure an experimental instance of Visual Studio (see below). Also, the Roslyn source code makes use of several new language features. The End User Preview must be installed for the Visual Studio IDE experience to understand the new language features. Without the End User Preview, spurious errors will appear in the Error List.

NuGet package manager
We use NuGet with package restore for our dependencies. We have seen some issues with package restore in some versions of the NuGet Package Manager, so we recommend making sure you have at least NuGet 2.8.1 installed. Go to Tools\Extensions and Updates and click on the Updates tab to see if you are up to date.

Latest Visual Studio 2015 Preview is recommended
We are not aware of any issues using earlier builds of Visual Studio 2015 Preview, but we have done the majority of our testing using the current CTPs and Preview builds and recommend its use. When using a CTP other than the latest ensure that you checkout the git branch that matches your preview, E.g:

git checkout remotes/origin/releases/Dev14Preview 

Getting the code

  1. In your browser, navigate to http://roslyn.codeplex.com/SourceControl/latest
  2. Click the "Clone" link and copy the URL
  3. Open the Visual Studio Team Explorer Windows (View\Team Explorer)
  4. Select the "Connect to Team Projects" option if you are already connected to a different project
  5. Under “Local Git Repositories” click the “Clone” link
  6. Enter the URL from step 2 in the top box
  7. Pick a location on your local machine to store the code
  8. Click the Clone button
  9. Switch to the "releases/Dev14Preview" branch
    1. In Team Explorer, select the "Branches" view
    2. Click the "New Branch" link
    3. Name your branch: releases/Dev14Preview
    4. Select: origin/releases/Dev14Preview from the dropdown
    5. Ensure "Checkout branch" is checked
    6. Click "Create Branch"

Using Visual Studio Preview releases

There are API differences between "master" and "releases/build-preview". If you build "master" you will not be able to test your changes in Visual Studio.
  • Use git branch --list from the command line to see the possible branches, E.g:
git branch --list --all
  master
  remotes/origin/DeclarationExpressions
  remotes/origin/HEAD -> origin/master
  remotes/origin/PrimaryConstructors
  remotes/origin/autoprop-initializers
  remotes/origin/master
  remotes/origin/pattern-matching
  remotes/origin/releases/Dev14CTP1
  remotes/origin/releases/Dev14CTP2
  remotes/origin/releases/Dev14CTP3
  remotes/origin/releases/Dev14CTP4
  remotes/origin/releases/Dev14Preview
  remotes/origin/releases/build-preview 
  • Select the branch that matches your CTP, E.g:
git checkout remotes/origin/releases/Dev14Preview 

Strong Name Verification

Roslyn binaries are configured to be delay signed using the Microsoft strong name key. We are using a new technique to allow these assemblies to be loaded - currently 'fakesign' - these assemblies do not need to have strong name signing disabled to be loaded. However, they cannot be installed in the GAC neither can they be loaded from a partially trusted AppDomain.

In order to test changes in Visual Studio without affecting the normal development environment, Visual Studio can be run using an isolated registry hive and AppData directories via the /rootSuffix Roslyn command line option. When Roslyn is built it creates and populates this hive with the necessary packages.
"%devenvdir%"\devenv.exe /rootSuffix Roslyn

Download NuGet Packages

From the command prompt, change directory to <clone dir> and run Src\.nuget\nuget restore Src\Roslyn.sln

This ensures that all of the references and tools needed to build Roslyn are present on the computer. Because we use toolset packages, it's important to do this before opening the solution.

Building the command line compilers

In order to build the command line compilers, you can simply open “Src\Roslyn.sln” from the directory where you created your git clone. Alternatively, you can build from the command line using msbuild Src\Roslyn.sln. If you want to debug the C# compiler, you should set the “Compilers\CSharp\csc” project as the startup project. For the Visual Basic compiler, it’s the “Compilers\VisualBasic\vbc” project.

Note that in most situations the compilers will NOT be invoked through csc and vbc for performance reasons, but they are the simplest way to debug. Other entry points include:
  1. csc2.exe and vbc2.exe. These are extremely small native executables that simply start or connect to a VBCSCompiler.exe process and send command line arguments to it. This allows the VBCSCompiler.exe process to reuse loaded assemblies for multiple projects.
  2. MSBuild tasks. In the Compilers\Core\MSBuildTasks project there are MSBuild tasks that also connect to VBCSCompiler.exe and send the arguments across.
  3. Custom hosts of the API. This includes the Visual Studio IDE experience calling into the compiler, as well as any other application written using the SDK. Debugging the binaries used by Visual Studio is covered below.

NOTE: By default VBCSCompiler.exe will run for 3 hours after starting. If you are making changes and rebuilding it often, you can change the timeout by editing Src\Compilers\Core\VBCSCompiler\App.config

Deploying changes to Visual Studio

When you build using VS 2015 the updates will be deployed to the Roslyn Hive and ready for debugging.

Debugging Visual Studio
  1. In Solution Explorer, right click the project “OpenSourceDebug” and choose “Set as Startup Project”
  2. Choose Debug\Start Debugging (F5)
At this point, you will be able to debug the code that you changed. Note that not all aspects of the compiler are executed inside the Visual Studio process, so you may not hit all breakpoints. Visual Studio will call many of the APIs in your built binaries to power its own features, but if you invoke a build inside your target Visual Studio, that will launch a new instance of csc.exe and vbc.exe. This technique does not execute vbcscompiler.exe. csc.exe and vbc.exe are a separate process and are not retained in memory after compilation is complete.

If you have installed and built Roslyn with a previous build of Visual Studio, you may get an InvalidCast out of VS MEF, this is because the VS MEFCache is out of date, I cured this by re-creating the roslyn hive by running this command at a Dos Prompt:

"%VSSDK140Install%\VisualStudioIntegration\Tools\Bin\CreateExpInstance.exe" /Create /VSInstance=14.0 /RootSuffix=Roslyn

To Build a project using OSS built compilers

At the command line type:
set RoslynHive=VisualStudio\14.0Roslyn
MSBuild someproj.vbproj

Running Unit Tests

To run the unit tests:
  1. Close the solution in Visual Studio (to ensure files are not locked)
  2. Open a Developer Command Prompt (administrator rights are not required)
  3. Navigate to the root of your clone
  4. Run msbuild /m BuildAndTest.proj /p:DeployExtensions=false
This will first build all sources, and then run all unit tests using the msbuild runner from the xUnit 2.0 runners NuGet Package. Results will be placed in a file named <clone dir>\UnitTestResults.html. Several warnings are expected as we have a policy of adding skipped unit tests to represent bugs that are not yet fixed.

Debugging unit test failures
You can debug a unit test project using xunit.console.x86.exe which is part of the package above:
  1. Open project properties for the unit test project containing the test you want to debug
  2. Select the Debug tab
  3. Change the "Start Action" to "Debug External Program"
  4. Set the path to the program to be "<clone directory>\Src\packages\xunit.runners.2.0.0-alpha-build2576\tools\xunit.console.x86.exe"
  5. Enter the full path of the unit test assembly, followed by "-noshadow" to the "Command Line Arguments" text box
  6. Set a breakpoint in the body of the test you want to run
  7. Start Debugging (F5)

Contributing

Please see How to Contribute for details on contributing changes back to the code.

Removing the code
  1. Start Task Manager and end all "VBCSCompiler.exe" processes
  2. Delete the directory containing your local git clone

Uninstalling the End User Preview (optional)
You are welcome to continue to use the End User Preview to provide feedback on the potential new language and IDE features it contains, but if you want to uninstall it, you can do so by following these steps:
  1. Start Task Manager and end all “VBCSCompiler.exe” processes
  2. Start Visual Studio
  3. Go to Tools\Extensions and Updates
  4. Select "Roslyn Preview" and click “Uninstall”

Walkthroughs

Install and build Roslyn

1. Install the latest Visual Studio 14 preview from [url:http://www.visualstudio.com/en-us/downloads/visual-studio-14-ctp-vs.aspx]
2. Install the corresponding  VSSDK from the same page 
3. Clone the repo using: git clone  https://git01.codeplex.com/roslyn
4. Checkout the branch that matches the downloaded preview E.g: 
    Git checkout releases/Dev14Preview
5. Start VS, Load the Roslyn Solution 
6. Set the Tools\OpenSourceDebug project to the default project 
7. Use the menu to build the solution 

Build and Debug Roslyn with Visual Studio

1. Install and Configure VS as above
2. Start VS, Load the Roslyn Solution 
3. Press F5 to start debugging 
4. The solution will build and start a new instance of Visual Studio 
5. In the new instance of VS create a new C# or VB project 
6. In the VS with the Roslyn solution open, add a breakpoint to the file: Workspaces\workspace\workspace.cs at line 142 
7. Add an interface to the project created earlier and see the breakpoint hit.

Build Project with OSS compilers within Visual Studio

1. Install and Configure VS as above
2. Press F5 to start a new instance of VS
3. Create a new C# or VB project
4. Use Tools/Options/Projects and Solutions/Build and Run to set the 'Build Project Verbosity' to 'Normal' so that we can ensure the correct compiler was used
5. Build the solution you built above.
6. Look in the build 0utput window and observe the compiler used is similar to:  
%USERPROFILE%\APPDATA\LOCAL\MICROSOFT\VISUALSTUDIO\14.0ROSLYN\EXTENSIONS\MSOPENTECH\OPENSOURCEDEBUG\0.7\csc.exe

Build with OSS Roslyn compilers using MSBUILD

1.  In a Visual Studio Command Shell, type the following command:
2.  MSBUILD ConsoleApplication01.csproj /t:Rebuild /p:RoslynHive=VisualStudio\14.0Roslyn
3.  In the build output from this command observe a compiler command line similar to:
%USERPROFILE%\APPDATA\LOCAL\MICROSOFT\VISUALSTUDIO\14.0ROSLYN\EXTENSIONS\MSOPENTECH\OPENSOURCEDEBUG\0.7\csc.exe


Last edited Jan 7, 2015 at 9:14 PM by KevinRansom, version 40