[Xamarin.Android.Build.Tasks] Add Support for AndroidManifest.xml overlays

Documentation/guides/building-apps/build-items.md

@@ -83,6 +83,36 @@ which tests to enable and disable.
 See the [lint documentation](https://developer.android.com/studio/write/lint)
 for more details.
 
+## AndroidManifestOverlay
+
+The build action `AndroidManifestOverlay` can we used to provide additional
+`AndroidManifest.xml` files to the [Manifest Merger]([~/android/deploy-test/building-apps/build-properties.md#](https://developer.android.com/studio/build/manifest-merge)) tool.
+Files with this build action will be passed to the Manifest Merger along with
+the main `AndroidManifest.xml` file and any additional manifest files from
+references. These will then be merged into the final manifest.
+
+You can use this build action to provide additional changes and settings to
+your app depending on your build configuration. For example if you need to
+have a specific permission only while debugging, you can use the overlay to
+inject that permission when debugging. For example given the following
+overlay file contents
+
+```
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.CAMERA" />
+</manifest>
+```
+
+you can use the following to add this for a debug build.
+
+```
+<ItemGroup>
+  <AndroidManifestOverlay Include="DebugPermissions.xml" Condition=" '$(Configuration)' == 'Debug' " />
+</ItemGroup>
+```
+
+Introduced in Xamarin.Android 11.2
+
 ## AndroidNativeLibrary
 
 [Native libraries](~/android/platform/native-libraries.md)

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/ManifestTest.cs

@@ -150,6 +150,33 @@ public void CheckElementReOrdering ([Values (true, false)] bool useAapt2)
 			}
 		}
 
+		[Test]
+		public void OverlayManifestTest ()
+		{
+			var proj = new XamarinAndroidApplicationProject () {
+				IsRelease = true,
+				ManifestMerger = "manifestmerger.jar",
+			};
+			proj.AndroidManifest = @"<?xml version=""1.0"" encoding=""utf-8""?>
+<manifest xmlns:android=""http://schemas.android.com/apk/res/android"" xmlns:tools=""http://schemas.android.com/tools"" android:versionCode=""1"" android:versionName=""1.0"" package=""foo.foo"">
+	<application android:label=""foo"">
+	</application>
+</manifest>";
+			proj.OtherBuildItems.Add (new BuildItem ("AndroidManifestOverlay", "ManifestOverlay.xml") {
+				TextContent = () => @"<?xml version=""1.0"" encoding=""utf-8""?>
+<manifest xmlns:android=""http://schemas.android.com/apk/res/android"">
+	<uses-permission android:name=""android.permission.CAMERA"" />
+</manifest>
+"
+			});
+			using (var b = CreateApkBuilder ("temp/OverlayManifestTest", cleanupAfterSuccessfulBuild: true, cleanupOnDispose: false)) {
+				Assert.IsTrue (b.Build (proj), "Build should have succeeded.");
+				var manifestFile = Path.Combine (Root, b.ProjectDirectory, proj.IntermediateOutputPath, "android", "AndroidManifest.xml");
+				var text = File.ReadAllText (manifestFile);
+				StringAssert.Contains ("android.permission.CAMERA", text, $"{manifestFile} should contain 'android.permission.CAMERA'");
+			}
+		}
+
 		[Test]
 		public void RemovePermissionTest ()
 		{

src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets

@@ -170,6 +170,7 @@ Copyright (C) 2011-2012 Xamarin. All rights reserved.
   <AvailableItemName Include="MultiDexMainDexList" />
   <AvailableItemName Include="ProguardConfiguration" />
   <AvailableItemName Include="ProjectReference" />
+  <AvailableItemName Include="AndroidManifestOverlay" />
 </ItemGroup>
 
 <!-- Version/fx properties -->
@@ -1441,6 +1442,7 @@ because xbuild doesn't support framework reference assemblies.
       OutputManifestFile="$(IntermediateOutputPath)android\AndroidManifest.xml"
       LibraryManifestFiles="@(ExtractedManifestDocuments)"
       ManifestPlaceholders="$(AndroidManifestPlaceholders)"
+      ManifestOverlayFiles="@(AndroidManifestOverlay)"
   />
   <ItemGroup>
     <FileWrites Include="$(IntermediateOutputPath)android\AndroidManifest.xml" />