From 8cca28219ee220dd949b15b6052e75979f31be74 Mon Sep 17 00:00:00 2001 From: Jonathan Peppers Date: Fri, 4 Dec 2020 10:10:10 -0600 Subject: [PATCH] [Xamarin.Android.Build.Tasks] @(AndroidLibrary) for all project types Fixes: https://github.com/xamarin/xamarin-android/issues/5357 The new `@(AndroidLibrary)` item group can now be used in "legacy" Xamarin.Android: * Application and class library projects: * `foo.jar` maps to `AndroidJavaLibrary` * `bar.aar` maps to `AndroidAarLibrary` * Java binding projects: * `foo.jar` maps to `EmbeddedJar` * `foo.jar` maps to `EmbeddedReferenceJar` if `Bind="false"` metadata is added * `bar.aar` maps to `LibraryProjectZip` * Additionally: * `@(AndroidNativeLibrary)` now will be used for native libraries. You can use `@(AndroidNativeLibrary)` instead of `@(EmbeddedNativeLibrary)`. All `@(AvailableItemNames)` are now defined in a single `Xamarin.Android.AndroidItems.targets` that is imported by all project types: both legacy apps, libraries, and bindings and .NET 6. I documented the changes to the item groups, some of which didn't have documentation at all. I updated a few binding tests to use `@(AndroidLibrary)`. There are still several more tests using the old item names. --- .../guides/OneDotNetEmbeddedResources.md | 15 ++- .../guides/building-apps/build-items.md | 99 +++++++++++++++++ Documentation/release-notes/5372.md | 61 +++++++++++ .../installers/create-installers.targets | 1 + .../Xamarin.Android.AvailableItems.targets | 103 ++++++++++++++++++ .../Xamarin.Android.Bindings.Core.targets | 15 --- ...osoft.Android.Sdk.AndroidLibraries.targets | 25 ----- .../BindingBuildTest.cs | 4 +- .../Xamarin.Android.Build.Tests/XASdkTests.cs | 6 +- .../Android/AndroidItem.cs | 3 - .../Common/XamarinProject.cs | 2 +- .../Xamarin.Android.Bindings.targets | 19 ++-- .../Xamarin.Android.Build.Tasks.targets | 5 + .../Xamarin.Android.Common.props.in | 10 -- .../Xamarin.Android.Common.targets | 26 +---- .../Xamarin.Android.Legacy.targets | 3 + 16 files changed, 302 insertions(+), 95 deletions(-) create mode 100644 Documentation/release-notes/5372.md create mode 100644 src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.AvailableItems.targets diff --git a/Documentation/guides/OneDotNetEmbeddedResources.md b/Documentation/guides/OneDotNetEmbeddedResources.md index 8d9a2343863..ba980ed7444 100644 --- a/Documentation/guides/OneDotNetEmbeddedResources.md +++ b/Documentation/guides/OneDotNetEmbeddedResources.md @@ -174,8 +174,9 @@ Right now we have a confusing collection of MSBuild item groups: * `@(AndroidNativeLibrary)` - `.so` file to include in an application project. -Let's simplify this, we could support all of the above with a new -`@(AndroidLibrary)` item group: +We could simplify much of the above with a new `@(AndroidLibrary)` +item group. `@(AndroidNativeLibrary)` can be used for +`@(EmbeddedNativeLibrary)` as well: ```xml @@ -188,11 +189,15 @@ Let's simplify this, we could support all of the above with a new %(Pack) is built into NuGet MSBuild targets. --> - - - + + + ``` +`@(AndroidNativeLibrary)` should remain distinct from +`@(AndroidLibrary)` because the `%(Bind)` and `%(Abi)` metadata do not +really make sense for both native libraries and Java/Kotlin libraries. + The new `@(AndroidLibrary)` item group will simply translate to the old ones for backwards compatibility. The extension of the file can be used to determine what kind of library each item is. `%(Bind)` and diff --git a/Documentation/guides/building-apps/build-items.md b/Documentation/guides/building-apps/build-items.md index 5090f8048bf..64d4a1adc1f 100644 --- a/Documentation/guides/building-apps/build-items.md +++ b/Documentation/guides/building-apps/build-items.md @@ -75,6 +75,36 @@ package. Files with a Build action of `AndroidJavaSource` are Java source code which will be included in the final Android package. +## AndroidLibrary + +**AndroidLibrary** is a new build action for simplifying how +`.jar` and `.aar` files are included in projects. + +Any project can specify: + +```xml + + + + +``` + +The result of the above code snippet has a different effect for each +Xamarin.Android project type: + +* Application and class library projects: + * `foo.jar` maps to [**AndroidJavaLibrary**](#androidjavalibrary) + * `bar.aar` maps to [**AndroidAarLibrary**](#androidaarlibrary) +* Java binding projects: + * `foo.jar` maps to [**EmbeddedJar**](#embeddedjar) + * `foo.jar` maps to [**EmbeddedReferenceJar**](#embeddedreferencejar) + if `Bind="false"` metadata is added + * `bar.aar` maps to [**LibraryProjectZip**](#libraryprojectzip) + +This simplification means you can use **AndroidLibrary** everywhere. + +Added in Xamarin.Android 11.2. + ## AndroidLintConfig The Build action 'AndroidLintConfig' should be used in conjunction with the @@ -213,6 +243,75 @@ step). Starting in Xamarin.Android 5.1, attempting to use the `@(Content)` Build action will result in a `XA0101` warning. +## EmbeddedJar + +In a Xamarin.Android binding project, the **EmbeddedJar** build action +binds the Java/Kotlin library and embeds the `.jar` file into the +library. When a Xamarin.Android application project consumes the +library, it will have access to the Java/Kotlin APIs from C# as well +as include the Java/Kotlin code in the final Android application. + +Since Xamarin.Android 11.2, you can use the +[**AndroidLibrary**](#androidlibrary) build action as an alternative +such as: + +```xml + + + + + +``` + +## EmbeddedNativeLibrary + +In a Xamarin.Android class library or Java binding project, the +**EmbeddedNativeLibrary** build action bundles a native library such +as `lib/armeabi-v7a/libfoo.so` into the library. When a +Xamarin.Android application consumes the library, the `libfoo.so` file +will be included in the final Android application. + +Since Xamarin.Android 11.2, you can use the +[**AndroidNativeLibrary**](#androidnativelibrary) build action as an +alternative. + +## EmbeddedReferenceJar + +In a Xamarin.Android binding project, the **EmbeddedReferenceJar** +build action embeds the `.jar` file into the library but does not +create a C# binding as [**EmbeddedJar**](#embeddedjar) does. When a +Xamarin.Android application project consumes the library, it will +include the Java/Kotlin code in the final Android application. + +Since Xamarin.Android 11.2, you can use the +[**AndroidLibrary**](#androidlibrary) build action as an alternative +such as ``: + +```xml + + + + + + + + +``` + +## LibraryProjectZip + +In a Xamarin.Android binding project, the **LibraryProjectZip** build +action binds the Java/Kotlin library and embeds the `.zip` or `.aar` +file into the library. When a Xamarin.Android application project +consumes the library, it will have access to the Java/Kotlin APIs from +C# as well as include the Java/Kotlin code in the final Android +application. + +> [!NOTE] +> Only a single **LibraryProjectZip** can be included in a +> Xamarin.Android binding project. This limitation will be removed +> going forward in .NET 6. + ## LinkDescription Files with a *LinkDescription* build action are used to diff --git a/Documentation/release-notes/5372.md b/Documentation/release-notes/5372.md new file mode 100644 index 00000000000..639c9115519 --- /dev/null +++ b/Documentation/release-notes/5372.md @@ -0,0 +1,61 @@ +#### Application and library build and deployment + + * [GitHub PR 5372](https://github.com/xamarin/xamarin-android/pull/5372): + Introduces the **AndroidLibrary** Build Action for Java or Kotlin libraries. + +**AndroidLibrary** is a new Build Action can be used as an alternative +to **AndroidAarLibrary**, **AndroidJavaLibrary**, **EmbeddedJar**, +**EmbeddedReferenceJar**, and **LibraryProjectZip**. + +For example, in an Android application or class library project: + +```xml + + + + + + + + + + +``` + +In a Java binding project: + +```xml + + + + + + + + + + + + +``` + +Using the **AndroidLibrary** Build Action is optional, as the old item +names are still supported. + +The **AndroidNativeLibrary** Build Action will continue to be used for +native libraries (`.so` files). However one improvement has been +introduced for Xamarin.Android class library or Java binding projects: + +```xml + + + + + + + + +``` + +The **AndroidNativeLibrary** Build Action can now be used in all +project types. It previously was only used in application projects. diff --git a/build-tools/installers/create-installers.targets b/build-tools/installers/create-installers.targets index eda42c0f35f..1f09b221454 100644 --- a/build-tools/installers/create-installers.targets +++ b/build-tools/installers/create-installers.targets @@ -283,6 +283,7 @@ <_MSBuildFiles Include="$(MSBuildSrcDir)\K4os.Compression.LZ4.dll" /> + <_MSBuildTargetsSrcFiles Include="$(MSBuildTargetsSrcDir)\Xamarin.Android.AvailableItems.targets" /> <_MSBuildTargetsSrcFiles Include="$(MSBuildTargetsSrcDir)\Xamarin.Android.Bindings.After.targets" /> <_MSBuildTargetsSrcFiles Include="$(MSBuildTargetsSrcDir)\Xamarin.Android.Bindings.Before.targets" /> <_MSBuildTargetsSrcFiles Include="$(MSBuildTargetsSrcDir)\Xamarin.Android.Common\ImportAfter\Microsoft.Cpp.Android.targets" /> diff --git a/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.AvailableItems.targets b/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.AvailableItems.targets new file mode 100644 index 00000000000..2da2cf6f6c9 --- /dev/null +++ b/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.AvailableItems.targets @@ -0,0 +1,103 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Designer + MSBuild:UpdateGeneratedFiles + + + true + true + + + + true + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets b/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets index 9b462320531..39e0400c9b3 100644 --- a/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets +++ b/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets @@ -21,21 +21,6 @@ It is shared between "legacy" binding projects and .NET 5 projects. <_GeneratorStampFile>$(IntermediateOutputPath)generator.stamp - - - - - - - - - - - - - - - diff --git a/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.AndroidLibraries.targets b/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.AndroidLibraries.targets index 7b72962351b..b0a8d850eac 100644 --- a/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.AndroidLibraries.targets +++ b/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.AndroidLibraries.targets @@ -13,36 +13,11 @@ projects. - - - - - - true - true - - <_AarCacheFile>$(IntermediateOutputPath)$(TargetName).aar.cache <_AarOutputPath>$(OutputPath)$(TargetName).aar - - - - - - - - - - - - - - - - <_AarSearchDirectory Include="@(_ReferencePath->'%(RootDir)%(Directory)')" /> diff --git a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs index 3a1442d4ad9..fb638b52ef2 100644 --- a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs +++ b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs @@ -42,7 +42,7 @@ public void BuildBasicBindingLibrary (string classParser) var proj = new XamarinAndroidBindingProject () { IsRelease = true, }; - proj.Jars.Add (new AndroidItem.EmbeddedJar ("Jars\\svg-android.jar") { + proj.Jars.Add (new AndroidItem.AndroidLibrary ("Jars\\svg-android.jar") { WebContent = "https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/svg-android/svg-android.jar" }); proj.AndroidClassParser = classParser; @@ -106,7 +106,7 @@ public void BuildAarBindingLibraryStandalone (string classParser) UseLatestPlatformSdk = true, IsRelease = true, }; - proj.Jars.Add (new AndroidItem.LibraryProjectZip ("Jars\\material-menu-1.1.0.aar") { + proj.Jars.Add (new AndroidItem.AndroidLibrary ("Jars\\material-menu-1.1.0.aar") { WebContent = "https://repo.jfrog.org/artifactory/libs-release-bintray/com/balysv/material-menu/1.1.0/material-menu-1.1.0.aar" }); proj.AndroidClassParser = classParser; diff --git a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/XASdkTests.cs b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/XASdkTests.cs index 2dcf47e78db..c69821c5e00 100644 --- a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/XASdkTests.cs +++ b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/XASdkTests.cs @@ -94,7 +94,8 @@ public void DotNetBuildLibrary (bool isRelease, bool duplicateAar) libB.OtherBuildItems.Add (new AndroidItem.AndroidLibrary ("sub\\directory\\arm64-v8a\\libfoo.so") { BinaryContent = () => Array.Empty (), }); - libB.OtherBuildItems.Add (new AndroidItem.AndroidLibrary ("libfoo.so") { + libB.OtherBuildItems.Add (new AndroidItem.AndroidNativeLibrary (default (Func)) { + Update = () => "libfoo.so", MetadataValues = "Link=x86\\libfoo.so", BinaryContent = () => Array.Empty (), }); @@ -208,7 +209,8 @@ public void DotNetPack ([Values ("net6.0-android", "net6.0-android30")] string t proj.OtherBuildItems.Add (new AndroidItem.AndroidLibrary ("sub\\directory\\arm64-v8a\\libfoo.so") { BinaryContent = () => Array.Empty (), }); - proj.OtherBuildItems.Add (new AndroidItem.AndroidLibrary ("libfoo.so") { + proj.OtherBuildItems.Add (new AndroidItem.AndroidNativeLibrary (default (Func)) { + Update = () => "libfoo.so", MetadataValues = "Link=x86\\libfoo.so", BinaryContent = () => Array.Empty (), }); diff --git a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Android/AndroidItem.cs b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Android/AndroidItem.cs index 15f5d0096e3..a375ebc4cea 100644 --- a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Android/AndroidItem.cs +++ b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Android/AndroidItem.cs @@ -37,9 +37,6 @@ public AndroidEnvironment (Func include) { } } - /// - /// Only supported in .NET 5+ - /// public class AndroidLibrary : BuildItem { public AndroidLibrary (string include) diff --git a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Common/XamarinProject.cs b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Common/XamarinProject.cs index ab03dd44163..4f49af74ca0 100644 --- a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Common/XamarinProject.cs +++ b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Common/XamarinProject.cs @@ -252,7 +252,7 @@ public virtual List Save (bool saveProject = true) foreach (var ig in ItemGroupList) list.AddRange (ig.Select (s => new ProjectResource () { Timestamp = s.Timestamp, - Path = s.Include?.Invoke (), + Path = s.Include?.Invoke () ?? s.Update?.Invoke (), Content = s.TextContent == null ? null : s.TextContent (), BinaryContent = s.BinaryContent == null ? null : s.BinaryContent (), Encoding = s.Encoding, diff --git a/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Bindings.targets b/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Bindings.targets index 9c6ca59ad51..fe895d11e03 100755 --- a/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Bindings.targets +++ b/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Bindings.targets @@ -139,15 +139,16 @@ Copyright (C) 2012 Xamarin Inc. All rights reserved. - - - - - - - - - + + + + + + + + + + true - - - Designer - MSBuild:UpdateGeneratedFiles - - - - true - - @NDK_ARMEABI_V7_API@ diff --git a/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets b/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets index 0d974447cdc..e5b6637f914 100644 --- a/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets +++ b/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets @@ -134,6 +134,9 @@ Copyright (C) 2011-2012 Xamarin. All rights reserved. + + + - - - - - - - - - - - - - - - - - - - - - - <_XAMajorVersionNumber>1 diff --git a/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Legacy.targets b/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Legacy.targets index 5bafceed771..0d1cbf630c0 100644 --- a/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Legacy.targets +++ b/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Legacy.targets @@ -29,6 +29,7 @@ projects. .NET 5 projects will not import this file. _CheckNonIdealConfigurations; _SetupMSBuildAllProjects; _SetupDesignTimeBuildForBuild; + _CategorizeAndroidLibraries; _CreatePropertiesCache; _CleanIntermediateIfNeeded; _CheckProjectItems; @@ -61,6 +62,7 @@ projects. .NET 5 projects will not import this file. _ValidateLinkMode; _SetupMSBuildAllProjects; _SetupDesignTimeBuildForBuild; + _CategorizeAndroidLibraries; _CreatePropertiesCache; _CleanIntermediateIfNeeded; _AddAndroidDefines; @@ -167,6 +169,7 @@ projects. .NET 5 projects will not import this file. _SetupMSBuildAllProjects; _SetupDesignTimeBuildForBuild; + _CategorizeAndroidLibraries; AddLibraryJarsToBind; $(BuildDependsOn); BuildDocumentation;