Merge branch 'main' into update-project-reference-docs

Author: DmitriyShepelev

.github/ISSUE_TEMPLATE/03_mybuildisbroken.md

@@ -10,9 +10,9 @@ labels: needs-triage
 
 <!--
 * Here are some useful links to help you figure out what's wrong.
-* Our wiki: https://github.com/microsoft/msbuild/blob/master/documentation/wiki/Home.md
-* General Help: https://github.com/microsoft/msbuild/blob/master/documentation/wiki/Something's-wrong-in-my-build.md
-* Tips & Tricks: https://github.com/microsoft/msbuild/blob/master/documentation/wiki/MSBuild-Tips-%26-Tricks.md
+* Our documentation: https://github.com/dotnet/msbuild/blob/main/documentation/README.md
+* General Help: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Something's-wrong-in-my-build.md
+* Tips & Tricks: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/MSBuild-Tips-%26-Tricks.md
 -->
 
 ### Issue Description
@@ -50,4 +50,4 @@ If you want to share one just with Microsoft, you can [report a problem through
 <!--
 * We ask that you first browse the above links, as your question may already have been answered.
 * Be as detailed as you can with these questions.
--->
+-->

documentation/specs/project-cache.md

@@ -1,10 +1,10 @@
 # Summary
 
-Project cache is a new assembly-based plugin extension point in MSBuild which determines whether a build request (a project) can be skipped during build. The main expected benefit is reduced build times via [caching and/or distribution](https://github.com/dotnet/msbuild/blob/master/documentation/specs/static-graph.md#weakness-of-the-old-model-caching-and-distributability).
+Project cache is a new assembly-based plugin extension point in MSBuild which determines whether a build request (a project) can be skipped during build. The main expected benefit is reduced build times via [caching and/or distribution](https://github.com/dotnet/msbuild/blob/main/documentation/specs/static-graph.md#weakness-of-the-old-model-caching-and-distributability).
 
 # Motivation
 
-As the introduction to [static graph](https://github.com/dotnet/msbuild/blob/master/documentation/specs/static-graph.md#what-is-static-graph-for) suggests, large and complex repos expose the weaknesses in MSBuild's scheduling and incrementality models as build times elongate. This project cache plugin lets MSBuild natively communicate with existing tools that enable build caching and/or distribution, enabling true scalability.
+As the introduction to [static graph](https://github.com/dotnet/msbuild/blob/main/documentation/specs/static-graph.md#what-is-static-graph-for) suggests, large and complex repos expose the weaknesses in MSBuild's scheduling and incrementality models as build times elongate. This project cache plugin lets MSBuild natively communicate with existing tools that enable build caching and/or distribution, enabling true scalability.
 
 Visual Studio is one beneficiary. This plugin inverts dependencies among build systems: instead of higher level build engines ([Cloudbuild](https://www.microsoft.com/research/publication/cloudbuild-microsofts-distributed-and-caching-build-service/), [Anybuild](https://github.com/AnyBuild/AnyBuild), [BuildXL](https://github.com/microsoft/BuildXL), etc) calling into MSBuild, MSBuild calls into them, keeping MSBuild's external APIs and command line arguments largely unchanged and thus reusable by Visual Studio.
 
@@ -78,7 +78,7 @@ This change also simplifies and unifies user experiences. MSBuild works the same
   - On cache hits, MSBuild skips the project, but needs a BuildResult with target results to send back to the [Scheduler](https://github.com/dotnet/msbuild/blob/d39f2e4f5f3d461bc456f9abed9adec4a2f0f542/src/Build/BackEnd/Components/Scheduler/Scheduler.cs#L25).
   - Plugins have three options:
     - Worst: plugins fake the build results for each target. We consider this brittle since the plugins will have to be updated whenever the build logic changes.
-    - Better: plugins tell MSBuild to run a proxy target as a replacement for the expensive target (e.g. it tells MSBuild to run `GetTargetPath` and use those results for the Build target). See the [ProjectReference protocol](https://github.com/dotnet/msbuild/blob/master/documentation/ProjectReference-Protocol.md) for more details.
+    - Better: plugins tell MSBuild to run a proxy target as a replacement for the expensive target (e.g. it tells MSBuild to run `GetTargetPath` and use those results for the Build target). See the [ProjectReference protocol](https://github.com/dotnet/msbuild/blob/main/documentation/ProjectReference-Protocol.md) for more details.
       - Proxy target assumptions:
         - They are very fast and only retrieve items and properties from the evaluated state (like `GetTargetPath`).
         - They do not mutate state (file system, environment variables, etc).
@@ -105,7 +105,7 @@ This change also simplifies and unifies user experiences. MSBuild works the same
   - Absolute paths will likely break the build, since they'd be captured on the machine that writes to the cache.
 - Slow connections. In a coffee shop it might be faster to build everything instead of downloading from the cache. Consider racing plugin checks and building: if the bottom up build traversal reaches a node that's still querying the cache, cancel the cache query and build the node instead.
 - Inferring what targets to run on each node when using /graph
-  - Msbuild /graph requires that the [target inference protocol](https://github.com/dotnet/msbuild/blob/master/documentation/specs/static-graph.md#inferring-which-targets-to-run-for-a-project-within-the-graph) is good enough.
+  - Msbuild /graph requires that the [target inference protocol](https://github.com/dotnet/msbuild/blob/main/documentation/specs/static-graph.md#inferring-which-targets-to-run-for-a-project-within-the-graph) is good enough.
 - Small repos will probably be slower with plugin implementations that access the network. Remote distribution and caching will only be worth it for repos that are large enough.
 
 # Future work

documentation/specs/single-project-isolated-builds.md

@@ -11,7 +11,7 @@ The presence of either input or output caches turns on [isolated build constrain
 
 ## Input / Output Cache Implementation
 <!-- cache structure -->
-The cache files contain the serialized state of MSBuild's [`ConfigCache`](https://github.com/dotnet/msbuild/blob/main/src/Build/BackEnd/Components/Caching/ConfigCache.cs) and [`ResultsCache`](https://github.com/dotnet/msbuild/blob/master/src/Build/BackEnd/Components/Caching/ResultsCache.cs), which have been traditionally used by the engine to cache build results. They ensure that a target is only built once per build submission. `ConfigCache` entries are instances of [`BuildRequestConfiguration`](https://github.com/dotnet/msbuild/blob/37c5a9fec416b403212a63f95f15b03dbd5e8b5d/src/Build/BackEnd/Shared/BuildRequestConfiguration.cs#L25)s (a `(project path, global properties)` tuple), and `ResultsCache` entries are instances of [`BuildResult`](https://github.com/dotnet/msbuild/blob/37c5a9fec416b403212a63f95f15b03dbd5e8b5d/src/Build/BackEnd/Shared/BuildResult.cs#L34)s, which contain [`TargetResult`](https://github.com/dotnet/msbuild/blob/37c5a9fec416b403212a63f95f15b03dbd5e8b5d/src/Build/BackEnd/Shared/TargetResult.cs#L22)s. The `ConfigCache` entries and `ResultsCache` entries form a [bijection](https://en.wikipedia.org/wiki/Bijection).
+The cache files contain the serialized state of MSBuild's [`ConfigCache`](https://github.com/dotnet/msbuild/blob/main/src/Build/BackEnd/Components/Caching/ConfigCache.cs) and [`ResultsCache`](https://github.com/dotnet/msbuild/blob/main/src/Build/BackEnd/Components/Caching/ResultsCache.cs), which have been traditionally used by the engine to cache build results. They ensure that a target is only built once per build submission. `ConfigCache` entries are instances of [`BuildRequestConfiguration`](https://github.com/dotnet/msbuild/blob/37c5a9fec416b403212a63f95f15b03dbd5e8b5d/src/Build/BackEnd/Shared/BuildRequestConfiguration.cs#L25)s (a `(project path, global properties)` tuple), and `ResultsCache` entries are instances of [`BuildResult`](https://github.com/dotnet/msbuild/blob/37c5a9fec416b403212a63f95f15b03dbd5e8b5d/src/Build/BackEnd/Shared/BuildResult.cs#L34)s, which contain [`TargetResult`](https://github.com/dotnet/msbuild/blob/37c5a9fec416b403212a63f95f15b03dbd5e8b5d/src/Build/BackEnd/Shared/TargetResult.cs#L22)s. The `ConfigCache` entries and `ResultsCache` entries form a [bijection](https://en.wikipedia.org/wiki/Bijection).
 
 <!-- cache lifetime -->
 In a build, the input and output cache files have the same lifetime as the `ConfigCache` and  `ResultsCache`. The `ConfigCache` and  `ResultsCache` are owned by the [`BuildManager`](https://github.com/dotnet/msbuild/blob/main/src/Build/BackEnd/BuildManager/BuildManager.cs), and their lifetimes are one `BuildManager.BeginBuild` / `BuildManager.EndBuild` session. On command-line builds, the cache lifetime is the same as the entire process lifetime since `MSBuild.exe` uses one `BuildManager` with one `BeginBuild` / `EndBuild` session. When other processes (e.g. Visual Studio's `devenv.exe`) perform MSBuild builds via the `BuildManager` APIs, there can be multiple build sessions in the same process.
@@ -27,7 +27,7 @@ When loading input cache files, MSBuild merges incoming instances of `ConfigCach
 Note that the output cache file contains a single `BuildResult` with the `TargetResult`s from the project specified to be built in the `BeginBuild` / `EndBuild` session, as any `BuildResult`s obtained through isolation exemption are excluded to prevent potential duplicate input cache entries; Entries from input caches are not transferred to the output cache.
 
 <!-- How input / output cache entries are separated with the override caches -->
-Input cache entries are separated from output cache entries with the composite caches [`ConfigCacheWithOverride`](https://github.com/dotnet/msbuild/blob/main/src/Build/BackEnd/Components/Caching/ConfigCacheWithOverride.cs) and [`ResultsCacheWithOverride`](https://github.com/dotnet/msbuild/blob/master/src/Build/BackEnd/Components/Caching/ResultsCacheWithOverride.cs). Each composite cache contains two underlying caches: a cache where input caches files are loaded into (the override cache), and a cache where new results are written into (the current cache).* In the `ConfigCacheWithOverride`, these caches are instances of `ConfigCache`s and, in the `ResultsCacheWithOverride`, these caches are instances of `ResultsCache`s. A query for a cache entry is first attempted from the override cache and, if unsatisfied, a second attempt is made from the current cache. Writes are only written to the current cache, never into the override cache.* It is illegal for both the current cache and override cache to contain entries for the same project configuration, a constraint that is checked by the two override caches on each cache query.
+Input cache entries are separated from output cache entries with the composite caches [`ConfigCacheWithOverride`](https://github.com/dotnet/msbuild/blob/main/src/Build/BackEnd/Components/Caching/ConfigCacheWithOverride.cs) and [`ResultsCacheWithOverride`](https://github.com/dotnet/msbuild/blob/main/src/Build/BackEnd/Components/Caching/ResultsCacheWithOverride.cs). Each composite cache contains two underlying caches: a cache where input caches files are loaded into (the override cache), and a cache where new results are written into (the current cache).* In the `ConfigCacheWithOverride`, these caches are instances of `ConfigCache`s and, in the `ResultsCacheWithOverride`, these caches are instances of `ResultsCache`s. A query for a cache entry is first attempted from the override cache and, if unsatisfied, a second attempt is made from the current cache. Writes are only written to the current cache, never into the override cache.* It is illegal for both the current cache and override cache to contain entries for the same project configuration, a constraint that is checked by the two override caches on each cache query.
 
 ## Isolation Implementation
 

documentation/specs/task-isolation-and-dependencies.md

@@ -23,7 +23,7 @@ We also want to load groups of tasks which belong together into the same ALC (fo
 
 # Task dependency resolution
 ## Problem definition
-Tasks with complex and specifically platform specific dependencies don't work out of the box. For example if a task uses [`LibGit2Sharp`](https://www.nuget.org/packages/LibGit2Sharp) package it will not work as is. `LibGit2Sharp` has native dependencies which are platform specific. While the package carries all of them, there's no built in support for the task to load the right ones. For example [source link](https://github.com/dotnet/sourcelink/blob/master/src/Microsoft.Build.Tasks.Git/GitLoaderContext.cs) runs into this problem.
+Tasks with complex and specifically platform specific dependencies don't work out of the box. For example if a task uses [`LibGit2Sharp`](https://www.nuget.org/packages/LibGit2Sharp) package it will not work as is. `LibGit2Sharp` has native dependencies which are platform specific. While the package carries all of them, there's no built in support for the task to load the right ones. For example [source link](https://github.com/dotnet/sourcelink/blob/29b3197e824c05d03427c05d56700e4c704233e4/src/Microsoft.Build.Tasks.Git/GitLoaderContext.cs) runs into this problem.
 
 ## Solution
 .NET Core uses `.deps.json` files to describe dependencies of components. It would be natural to treat task assemblies as components and use associated .deps.json file to determine their dependencies. This would make the system work nicely end to end with the .NET Core CLI/SDK and VS integration.

documentation/wiki/Building-Testing-and-Debugging-on-Full-Framework-MSBuild.md

@@ -1,6 +1,6 @@
 # Building MSBuild for the .NET Framework
 
-These instructions refer to working with the `master` branch.
+These instructions refer to working with the `main` branch.
 
 ## Required Software
 

documentation/wiki/Contributing-Code.md

@@ -5,7 +5,7 @@ Because our focus right now is on maintaining backwards compatibility, the team
 
 - Contributions must be discussed with the team first, or they will likely be declined. As our process matures and our experience grows, the team expects to take larger contributions.
 - Only contributions referencing an approved Issue will be accepted.
-- Pull requests that do not merge easily with the tip of the master branch will be declined. The author will be asked to merge with tip and submit a new pull request.
+- Pull requests that do not merge easily with the tip of the main branch will be declined. The author will be asked to merge with tip and submit a new pull request.
 - Submissions must meet functional and performance expectations, including scenarios for which the team doesn't yet have open source tests. This means you may be asked to fix and resubmit your pull request against a new open test case if it fails one of these tests.
 - Submissions must follow the [.NET Runtime Coding Guidelines](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/coding-style.md)
 

documentation/wiki/Localization.md

@@ -21,8 +21,8 @@
 
 ## Process for interacting with the localization team
 
-- 3 weeks cadence for master, initiated by loc team
-- on demand for master / release branches, initiated by msbuild team
+- 3 weeks cadence for main, initiated by loc team
+- on demand for main / release branches, initiated by msbuild team
 
 ## Contributing a better translation
 

src/Build.UnitTests/BackEnd/DebugUtils_tests.cs

@@ -16,7 +16,7 @@ namespace Microsoft.Build.UnitTests
     public class DebugUtils_Tests
     {
         [Fact]
-        public void DumpExceptionToFileShouldWriteInTempPathByDefault()
+        public void DumpExceptionToFileShouldWriteInDebugDumpPath()
         {
             var exceptionFilesBefore = Directory.GetFiles(ExceptionHandling.DebugDumpPath, "MSBuild_*failure.txt");
 

src/Build.UnitTests/BinaryLogger_Tests.cs

@@ -216,7 +216,7 @@ public void BinaryLoggerShouldEmbedFilesViaTaskOutput()
             zipArchive.Entries.ShouldContain(zE => zE.Name.EndsWith("testtaskoutputfile.txt"));
         }
 
-        [Fact]
+        [RequiresSymbolicLinksFact]
         public void BinaryLoggerShouldEmbedSymlinkFilesViaTaskOutput()
         {
             string testFileName = "foobar.txt";

src/Build.UnitTests/Microsoft.Build.Engine.UnitTests.csproj

@@ -122,6 +122,9 @@
     <Compile Include="..\Shared\UnitTests\LongPathSupportDisabledFactAttribute.cs">
       <Link>Shared\LongPathSupportDisabledFactAttribute.cs</Link>
     </Compile>
+    <Compile Include="..\UnitTests.Shared\RequiresSymbolicLinksFactAttribute.cs">
+      <Link>RequiresSymbolicLinksFactAttribute.cs</Link>
+    </Compile>
 
     <None Include="..\Shared\UnitTests\App.config">
       <Link>App.config</Link>

src/Framework/ChangeWaves.cs

@@ -20,8 +20,8 @@ internal enum ChangeWaveConversionState
     /// Coupled together with the MSBUILDDISABLEFEATURESFROMVERSION environment variable,
     /// this class acts as a way to make risky changes while giving customers an opt-out.
     /// </summary>
-    /// See docs here: https://github.com/dotnet/msbuild/blob/master/documentation/wiki/ChangeWaves.md
-    /// For dev docs: https://github.com/dotnet/msbuild/blob/master/documentation/wiki/ChangeWaves-Dev.md
+    /// See docs here: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/ChangeWaves.md
+    /// For dev docs: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/ChangeWaves-Dev.md
     internal class ChangeWaves
     {
         internal static readonly Version Wave17_2 = new Version(17, 2);

src/Framework/NativeMethods.cs

@@ -1017,7 +1017,7 @@ internal static MemoryStatus GetMemoryStatus()
         return null;
     }
 
-    internal static bool MakeSymbolicLink(string newFileName, string exitingFileName, ref string errorMessage)
+    internal static bool MakeSymbolicLink(string newFileName, string existingFileName, ref string errorMessage)
     {
         bool symbolicLinkCreated;
         if (IsWindows)
@@ -1029,12 +1029,12 @@ internal static bool MakeSymbolicLink(string newFileName, string exitingFileName
                 flags |= SymbolicLink.AllowUnprivilegedCreate;
             }
 
-            symbolicLinkCreated = CreateSymbolicLink(newFileName, exitingFileName, flags);
+            symbolicLinkCreated = CreateSymbolicLink(newFileName, existingFileName, flags);
             errorMessage = symbolicLinkCreated ? null : Marshal.GetExceptionForHR(Marshal.GetHRForLastWin32Error()).Message;
         }
         else
         {
-            symbolicLinkCreated = symlink(exitingFileName, newFileName) == 0;
+            symbolicLinkCreated = symlink(existingFileName, newFileName) == 0;
             errorMessage = symbolicLinkCreated ? null : Marshal.GetLastWin32Error().ToString();
         }
 

src/MSBuild/LiveLogger/ANSIBuilder.cs

@@ -427,16 +427,7 @@ public static string Spinner(int n)
 
             public static string ProgressBar(float percentage, int width = 10, char completedChar = '█', char remainingChar = '░')
             {
-                string result = String.Empty;
-                for (int i = 0; i < (int)Math.Floor(width * percentage); i++)
-                {
-                    result += completedChar;
-                }
-                for (int i = (int)Math.Floor(width * percentage); i < width; i++)
-                {
-                    result += remainingChar;
-                }
-                return result;
+                return new string(completedChar, (int)Math.Floor(width * percentage)) + new string(remainingChar, width - (int)Math.Floor(width * percentage));
             }
 
             public static string Bell()