Update documentation for Update 1 #7024

jasonmalinowski · 2015-11-25T06:25:44Z

This updates our building and testing instructions for Update 1. I'm moving the content to the main repository so it can be more easily updated as code changes update it, and since it's "reasonable" that different branches might have different instructions. This is no different than the Linux instructions that are already in the repository.

Reviewers: @dotnet/roslyn-infrastructure

jasonmalinowski · 2015-11-25T06:35:23Z

Annoyingly there is no way to do a pull request for the wiki, so I've made a PR at jasonmalinowski/roslyn-wiki#1 which you can comment on there.

Pilchie · 2015-11-25T17:18:23Z

docs/contributing/Building, Debugging, and Testing on Windows.md

+
+To debug through tests, you can right click the test project that contains your
+tests and choose **Set as Startup Project**. Then press F5. This will run the
+tests under the command line runner.  Some members of the team have been


In my experience this doesn't work right now, because the path to the nuget package directory isn't rooted. Can we fix that?

Fixed in #7063.

Pilchie · 2015-11-25T17:21:39Z

👍, though @dotnet/roslyn-infrastructure should look at the linux test failure to make sure it's tracked.

dpoeschl · 2015-11-25T18:57:30Z

retest prtest/lin/dbg/unit32 please

Pilchie · 2015-11-26T01:19:03Z

Thanks for fixing. LGTM

pawchen · 2015-11-30T09:28:42Z

docs/contributing/Building, Debugging, and Testing on Windows.md

+1. Clone https://github.com/dotnet/roslyn
+2. Run the "Developer Command Prompt for VS2015" from your start menu.
+3. Run `Restore.cmd` in the command prompt to restore NuGet packages.
+4. Due to [Issue #5876](https://github.com/dotnet/roslyn/issues/5876), you should build on the command line before opening in Visual Studio. Run `msbuild /v:m /m Roslyn.sln`


It is unclear that whether this command does bootstrap, if someone want to make language changes to the compiler and want to use them in projects like Features.

It doesn't; it's just working around a bug where we might get some spurious errors in the IDE if we don't do this. Make sense now, or should I reword it?

OK, so will building inside IDE use the bootstraped compiler? Please consider adding this info when the workaround can be removed, or one have to read cibuild scripts to find out.

The compiler used to build Roslyn is the "toolset compiler" which comes from a NuGet package. If you F5 within VS (or run the dev hive) then that builds with the compiler that you just built. Makes sense?

It makes sense to build the compiler projects of Roslyn using the toolset compiler, then the newly built compiler should take over and build everything. This is what I observed from cibuild output, I think building inside IDE ideally should do the same, but I doubt if it's possible.

I'm not sure if you interpreted "everything" in my last comment:

then the newly built compiler should take over and build everything

as everything including projects outside of Roslyn, no, I meant just everything inside Roslyn(solution/folder) within that particular build session. Does not affect other projects outside.

The problem with switching the compiler version is there's no good way to do that inside Visual Studio. We want to have a reasonable expectation that if I open Roslyn.sln and hit build that it does the same thing as MSBuild on the command line.

Talking with @agocke, his response was if you do want to build the compiler with the compiler like cibuild, then you can just run cibuild.cmd and get that same experience. I agree that's not discoverable; @agocke or @jaredpar do we have better documents somewhere?

Another option is to just use the same hook we use in cibuild.cmd to take over the compiler. CIBuild essentially does the following:

Build toolset.sln

Copy Binaries\Debug to a new directory Binaries\Bootstrap

Run msbuild with /p:BootstrapBuildPath=Binaries\Bootstrap

The BootstrapBuildPath hook isn't specific to any path. You could point it to any directory on your machine so long as it had csc and vbc inside it.

I agree that's not discoverable

It's not discoverable because it generally isn't deemed valuable to individual developers. Even on the compiler team we use the toolset compiler for the vast majority of our development. The reason for cibuild using the freshly built compiler is just a sanity check that we can always compile our repo with our repo.

This is a valuable test to have but the breaks it catches are rather rare. Typically we get about 1 per month on the compiler team. The decreased throughput of the compiler when using bootstrap builds isn't worth catching a bug that you'd introduce on average once a year. Hence we do it only in our build lab.

Again let me clarify, I'm suggesting documenting.

@jasonmalinowski 1. Yes, I agree; 2. Yes, that's what I've been doing

@jaredpar 1. I remember this BootrapBuildPath property was documented in a section like "Using the OSS built compiler", but not sure if it also mentioned toolset.sln; 2. Yes, but worth doing locally before submitting pr with compiler changes, or would probably cause unnecessary trouble to the infrastructure team like I did in #6508

Well, thanks for all these info of the discussion, I think it's pretty clear to me, maybe I can try putting this into a new section tomorrow.

As far as the trouble for the infrastructure team; eh, it happens. Right now we're being very strict about filing bugs in PR failures if it's not immediately apparent that the PR is related to that. It looks like we were a bit over-aggressive in that case, but don't worry about that.

dpoeschl · 2015-11-30T18:12:10Z

docs/contributing/Building, Debugging, and Testing on Windows.md

+
+# Getting the Code
+
+1. Clone https://github.com/dotnet/roslyn


Fork and clone? Do we discuss the proper process for this somewhere?

Perhaps? I'm not sure I want to include "how to use GitHub" in our instructions, versus assuming that as a base.

jasonmalinowski · 2015-11-30T18:27:21Z

My deadline to get this merged in is in three minutes, so I'm going to merge this now, and address the (excellent) feedback from today this afternoon.

dpoeschl · 2015-11-30T18:27:24Z

docs/contributing/Building, Debugging, and Testing on Windows.md

+project as your startup project to ensure the right things are built and
+deployed.
+
+- **VisualStudioSetup**: this project builds Roslyn.VisualStudio.Setup.vsix. It


Are there dependencies between these? Does building VisualStudioSetup guarantee the CompilerExtension is redeployed if it has changes?

It does not. That's why I'm hedging with "you should do a full build to make sure everything is primed." I'm undecided whether this is good or bad -- it means we're only redeploying on what you want, but at the same time it might cause problems.

…r-update-1 Update documentation for Update 1

dpoeschl · 2015-11-30T18:28:18Z

docs/contributing/Building, Debugging, and Testing on Windows.md

+  live analysis are synchronized.
+- **ExpressionEvaluatorPackage**: this deploys the expression evaluator and
+  result providers, the components that are used by the debugger to parse and
+  evaluate C# and VB expressions in the watch window, immediate window, and


Consider: "Watch window", "Immediate window"

dpoeschl · 2015-11-30T18:28:46Z

docs/contributing/Building, Debugging, and Testing on Windows.md

+  language features, you may wish to consider building both the
+  CompilerExtension and VisualStudioSetup projects to ensure the real build and
+  live analysis are synchronized.
+- **ExpressionEvaluatorPackage**: this deploys the expression evaluator and


Should we name the .vsix files for the following three as well?

dpoeschl · 2015-11-30T18:34:29Z

Missed the inevitable merge, but 👍 and great job getting all this updated!

jasonmalinowski · 2015-11-30T22:55:13Z

I've made PR #7127 for the feedback I missed the first time around.

dnfclas added the cla-already-signed label Nov 25, 2015

Pilchie reviewed Nov 25, 2015
View reviewed changes

dpoeschl mentioned this pull request Nov 25, 2015

[Test Failure] No identified problem in prtest/lin/dbg/unit32 on PR #7024 #7042

Closed

jasonmalinowski force-pushed the update-documentation-for-update-1 branch from b78e909 to 68d4a96 Compare November 25, 2015 20:36

jasonmalinowski added 4 commits November 25, 2015 14:18

Initial porting of existing wiki content that is still accurate

f7c42ff

Add a link to where the Update 1 download will ultimately be

f9b15a7

Add instructions about building and deploying into Visual Studio

94ba429

Bring back the testing instructions

8afb70c

jasonmalinowski force-pushed the update-documentation-for-update-1 branch from 68d4a96 to 8afb70c Compare November 25, 2015 22:18

pawchen reviewed Nov 30, 2015
View reviewed changes

Pilchie added the Area-Infrastructure label Nov 30, 2015

dpoeschl reviewed Nov 30, 2015
View reviewed changes

jasonmalinowski added a commit that referenced this pull request Nov 30, 2015

Merge pull request #7024 from jasonmalinowski/update-documentation-fo…

4e8694d

…r-update-1 Update documentation for Update 1

jasonmalinowski merged commit 4e8694d into dotnet:master Nov 30, 2015

jasonmalinowski deleted the update-documentation-for-update-1 branch November 30, 2015 18:27

dpoeschl reviewed Nov 30, 2015
View reviewed changes

pawchen mentioned this pull request Dec 2, 2015

Improve document for building. #7176

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update documentation for Update 1 #7024

Update documentation for Update 1 #7024

jasonmalinowski commented Nov 25, 2015

jasonmalinowski commented Nov 25, 2015

Pilchie Nov 25, 2015

jasonmalinowski Nov 25, 2015

Pilchie commented Nov 25, 2015

dpoeschl commented Nov 25, 2015

Pilchie commented Nov 26, 2015

pawchen Nov 30, 2015

jasonmalinowski Nov 30, 2015

pawchen Nov 30, 2015

jasonmalinowski Dec 1, 2015

pawchen Dec 1, 2015

pawchen Dec 1, 2015

jasonmalinowski Dec 1, 2015

jaredpar Dec 1, 2015

pawchen Dec 1, 2015

jasonmalinowski Dec 2, 2015

dpoeschl Nov 30, 2015

jasonmalinowski Nov 30, 2015

jasonmalinowski commented Nov 30, 2015

dpoeschl Nov 30, 2015

jasonmalinowski Nov 30, 2015

dpoeschl Nov 30, 2015

dpoeschl Nov 30, 2015

jasonmalinowski Nov 30, 2015

dpoeschl commented Nov 30, 2015

jasonmalinowski commented Nov 30, 2015


		# Getting the Code

		1. Clone https://github.com/dotnet/roslyn

Update documentation for Update 1 #7024

Update documentation for Update 1 #7024

Conversation

jasonmalinowski commented Nov 25, 2015

jasonmalinowski commented Nov 25, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Pilchie commented Nov 25, 2015

dpoeschl commented Nov 25, 2015

Pilchie commented Nov 26, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasonmalinowski commented Nov 30, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dpoeschl commented Nov 30, 2015

jasonmalinowski commented Nov 30, 2015