Skip to content

[Xamarin.Android.Build.Tasks] @(AndroidLibrary) for all project types #5372

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonpryor merged 1 commit into from
Dec 9, 2020
Merged

[Xamarin.Android.Build.Tasks] @(AndroidLibrary) for all project types #5372

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 10 additions & 5 deletions Documentation/guides/OneDotNetEmbeddedResources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<!-- Include and bind -->
Expand All @@ -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.
-->
<AndroidLibrary Include="bar.aar" Pack="false" />
<!-- Native libraries need ABI directory -->
<AndroidLibrary Include="armeabi-v7a\libfoo.so" />
<AndroidLibrary Include="x86\libfoo.so" />
<!-- Native libraries need ABI directory or %(Abi) -->
<AndroidNativeLibrary Include="armeabi-v7a\libfoo.so" />
<AndroidNativeLibrary Include="libfoo.so" Abi="x86" />
```

`@(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
Expand Down
99 changes: 99 additions & 0 deletions Documentation/guides/building-apps/build-items.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<ItemGroup>
<AndroidLibrary Include="foo.jar" />
<AndroidLibrary Include="bar.aar" />
</ItemGroup>
```

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
Expand Down Expand Up @@ -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
<Project>
<ItemGroup>
<AndroidLibrary Include="Library.jar" />
</ItemGroup>
</Project>
```

## 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**
Copy link
Copy Markdown
Contributor

@jonpryor jonpryor Dec 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto here, etc., etc. We can link to build properties & item group docs now! Let's use it.

Copy link
Copy Markdown
Member Author

@jonathanpeppers jonathanpeppers Dec 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did this everywhere now, except for when they refer to themselves.

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 `<AndroidLibrary Include="..." Bind="false" />`:

```xml
<Project>
<ItemGroup>
<!-- A .jar file to bind & embed -->
<AndroidLibrary Include="Library.jar" />
<!-- A .jar file to only embed -->
<AndroidLibrary Include="Dependency.jar" Bind="false" />
</ItemGroup>
</Project>
```

## 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
Expand Down
61 changes: 61 additions & 0 deletions Documentation/release-notes/5372.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<Project>
<ItemGroup>
<!-- If the project was using: -->
<AndroidAarLibrary Include="foo.aar" />
<AndroidJavaLibrary Include="bar.jar" />
<!-- It can now be replaced with: -->
<AndroidLibrary Include="foo.aar" />
<AndroidLibrary Include="bar.jar" />
</ItemGroup>
</Project>
```

In a Java binding project:

```xml
<Project>
<ItemGroup>
<!-- If the project was using: -->
<LibraryProjectZip Include="foo.aar" />
<EmbeddedJar Include="bar.jar" />
<EmbeddedReferenceJar Include="dependency.jar" />
<!-- It can now be replaced with: -->
<AndroidLibrary Include="foo.aar" />
<AndroidLibrary Include="bar.jar" />
<AndroidLibrary Include="dependency.jar" Bind="false" />
</ItemGroup>
</Project>
```

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
<Project>
<ItemGroup>
<!-- If the project was using: -->
<EmbeddedNativeLibrary Include="lib/armeabi-v7a/libfoo.so" />
<!-- It can now be replaced with: -->
<AndroidNativeLibrary Include="lib/armeabi-v7a/libfoo.so" />
</ItemGroup>
</Project>
```

The **AndroidNativeLibrary** Build Action can now be used in all
project types. It previously was only used in application projects.
1 change: 1 addition & 0 deletions build-tools/installers/create-installers.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,7 @@
<_MSBuildFiles Include="$(MSBuildSrcDir)\K4os.Compression.LZ4.dll" />
</ItemGroup>
<ItemGroup>
<_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" />
Expand Down
103 changes: 103 additions & 0 deletions ...amarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.AvailableItems.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
<!--
***********************************************************************************************
Xamarin.Android.AvailableItems.targets

This file is imported by every project type to setup @(AvailableItemName).
This item group populates the Build Action drop-down in IDEs.

***********************************************************************************************
-->
<Project>

<!-- Not legacy binding projects -->
<ItemGroup Condition=" '$(_AndroidIsBindingProject)' != 'true' ">
<AvailableItemName Include="AndroidAotProfile" />
<AvailableItemName Include="AndroidAsset" />
<AvailableItemName Include="AndroidEnvironment" />
<AvailableItemName Include="AndroidExternalJavaLibrary" />
<AvailableItemName Include="AndroidInterfaceDescription" />
<AvailableItemName Include="AndroidJavaSource" />
<AvailableItemName Include="AndroidLibrary" />
<AvailableItemName Include="AndroidLintConfig" />
<AvailableItemName Include="AndroidResourceAnalysisConfig" />
<AvailableItemName Include="AndroidNativeLibrary" />
<AvailableItemName Include="AndroidResource" />
<AvailableItemName Include="AndroidBoundLayout" />
<AvailableItemName Include="LinkDescription" />
<AvailableItemName Include="MultiDexMainDexList" />
<AvailableItemName Include="ProguardConfiguration" />
<AvailableItemName Include="ProjectReference" />
<AvailableItemName Include="AndroidManifestOverlay" />
</ItemGroup>
<!-- Legacy, non-binding projects -->
<ItemGroup Condition=" '$(_AndroidIsBindingProject)' != 'true' and '$(UsingAndroidNETSdk)' != 'true' ">
<AvailableItemName Include="AndroidAarLibrary" />
<AvailableItemName Include="AndroidJavaLibrary" />
</ItemGroup>
<!-- Legacy, non-application projects -->
<ItemGroup Condition=" '$(AndroidApplication)' != 'true' and '$(UsingAndroidNETSdk)' != 'true' ">
<AvailableItemName Include="EmbeddedNativeLibrary" />
</ItemGroup>
<!-- Legacy binding projects or .NET 6 -->
<ItemGroup Condition=" '$(_AndroidIsBindingProject)' == 'true' or '$(UsingAndroidNETSdk)' == 'true' ">
<AvailableItemName Include="TransformFile" />
<AvailableItemName Include="LibraryProjectProperties" />
<AvailableItemName Include="JavaDocIndex" />
<AvailableItemName Include="JavaDocJar" />
<AvailableItemName Include="JavaSourceJar" />
</ItemGroup>
<!-- Legacy binding projects -->
<ItemGroup Condition=" '$(_AndroidIsBindingProject)' == 'true' and '$(UsingAndroidNETSdk)' != 'true' ">
<AvailableItemName Include="EmbeddedJar" />
<AvailableItemName Include="EmbeddedNativeLibrary" />
<AvailableItemName Include="EmbeddedReferenceJar" />
<AvailableItemName Include="InputJar" />
<AvailableItemName Include="ReferenceJar" />
<AvailableItemName Include="LibraryProjectZip" />
</ItemGroup>

<!-- Default item metadata -->
<ItemDefinitionGroup>
<AndroidResource>
<SubType>Designer</SubType>
<Generator>MSBuild:UpdateGeneratedFiles</Generator>
</AndroidResource>
<AndroidLibrary>
<Bind>true</Bind>
<Pack Condition=" '$(UsingAndroidNETSdk)' == 'true' ">true</Pack>
</AndroidLibrary>
<AndroidAarLibrary>
<!-- NOTE: .aar items should skip %(AndroidSkipResourceProcessing) by default -->
<AndroidSkipResourceProcessing>true</AndroidSkipResourceProcessing>
</AndroidAarLibrary>
</ItemDefinitionGroup>

<!-- Convert @(AndroidLibrary) to the legacy item group names -->
<Target Name="_CategorizeAndroidLibraries">
<!-- Applications, or legacy class libraries -->
<ItemGroup Condition=" '$(AndroidApplication)' == 'true' or ('$(_AndroidIsBindingProject)' != 'true' and '$(UsingAndroidNETSdk)' != 'true') ">
<AndroidAarLibrary Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.aar' " />
<AndroidJavaLibrary Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.jar' " />
</ItemGroup>
<!-- Any library that is not an app -->
<ItemGroup Condition=" '$(AndroidApplication)' != 'true' ">
<EmbeddedNativeLibrary Include="@(AndroidNativeLibrary)" />
</ItemGroup>
<!-- .NET 6 class libraries-->
<ItemGroup Condition=" '$(AndroidApplication)' != 'true' and '$(UsingAndroidNETSdk)' == 'true' ">
<AndroidAarLibrary Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.aar' and '%(AndroidLibrary.Bind)' != 'true' " />
<LibraryProjectZip Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.aar' and '%(AndroidLibrary.Bind)' == 'true' " />
<AndroidJavaLibrary Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.jar' and '%(AndroidLibrary.Bind)' != 'true' " />
<EmbeddedJar Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.jar' and '%(AndroidLibrary.Bind)' == 'true' " />
<!-- .aar files should be copied to $(OutputPath) in .NET 6-->
<None Include="@(LibraryProjectZip)" CopyToOutputDirectory="PreserveNewest" Link="%(Filename)%(Extension)" />
</ItemGroup>
<!-- Legacy binding projects -->
<ItemGroup Condition=" '$(_AndroidIsBindingProject)' == 'true' and '$(UsingAndroidNETSdk)' != 'true' ">
<LibraryProjectZip Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.aar' and '%(AndroidLibrary.Bind)' == 'true' " />
<EmbeddedJar Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.jar' and '%(AndroidLibrary.Bind)' != 'true' " />
<EmbeddedReferenceJar Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.jar' and '%(AndroidLibrary.Bind)' == 'true' " />
</ItemGroup>
</Target>

</Project>
15 changes: 0 additions & 15 deletions ...Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,21 +21,6 @@ It is shared between "legacy" binding projects and .NET 5 projects.
<_GeneratorStampFile>$(IntermediateOutputPath)generator.stamp</_GeneratorStampFile>
</PropertyGroup>

<!-- Get our Build Actions to show up in VS -->
<ItemGroup>
<AvailableItemName Include="EmbeddedJar" />
<AvailableItemName Include="EmbeddedNativeLibrary" />
<AvailableItemName Include="EmbeddedReferenceJar" />
<AvailableItemName Include="InputJar" />
<AvailableItemName Include="ReferenceJar" />
<AvailableItemName Include="TransformFile" />
<AvailableItemName Include="LibraryProjectProperties" />
<AvailableItemName Include="LibraryProjectZip" />
<AvailableItemName Include="JavaDocIndex" />
<AvailableItemName Include="JavaDocJar" />
<AvailableItemName Include="JavaSourceJar" />
</ItemGroup>

<Target Name="ExportJarToXml"
DependsOnTargets="$(ExportJarToXmlDependsOnTargets)"
Condition=" '$(UsingAndroidNETSdk)' != 'true' Or '@(InputJar->Count())' != '0' Or '@(EmbeddedJar->Count())' != '0' Or '@(LibraryProjectZip->Count())' != '0' ">
Expand Down
25 changes: 0 additions & 25 deletions ....Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.AndroidLibraries.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,36 +13,11 @@ projects.
<UsingTask TaskName="Xamarin.Android.Tasks.CreateAar" AssemblyFile="$(_XamarinAndroidBuildTasksAssembly)" />
<UsingTask TaskName="Xamarin.Android.Tasks.ExtractJarsFromAar" AssemblyFile="$(_XamarinAndroidBuildTasksAssembly)" />

<ItemGroup>
<AvailableItemName Include="AndroidLibrary" />
</ItemGroup>
<ItemDefinitionGroup>
<AndroidLibrary>
<Bind>true</Bind>
<Pack>true</Pack>
</AndroidLibrary>
</ItemDefinitionGroup>
<PropertyGroup>
<_AarCacheFile>$(IntermediateOutputPath)$(TargetName).aar.cache</_AarCacheFile>
<_AarOutputPath>$(OutputPath)$(TargetName).aar</_AarOutputPath>
</PropertyGroup>

<Target Name="_CategorizeAndroidLibraries">
<ItemGroup Condition=" '$(AndroidApplication)' == 'true' ">
<AndroidAarLibrary Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.aar' " />
<AndroidJavaLibrary Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.jar' " />
<AndroidNativeLibrary Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.so' " />
</ItemGroup>
<ItemGroup Condition=" '$(AndroidApplication)' != 'true' ">
<AndroidAarLibrary Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.aar' and '%(AndroidLibrary.Bind)' != 'true' " />
<LibraryProjectZip Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.aar' and '%(AndroidLibrary.Bind)' == 'true' " />
<AndroidJavaLibrary Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.jar' and '%(AndroidLibrary.Bind)' != 'true' " />
<EmbeddedJar Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.jar' and '%(AndroidLibrary.Bind)' == 'true' " />
<EmbeddedNativeLibrary Include="@(AndroidLibrary)" Condition=" '%(AndroidLibrary.Extension)' == '.so' " />
<None Include="@(LibraryProjectZip)" CopyToOutputDirectory="PreserveNewest" Link="%(Filename)%(Extension)" />
</ItemGroup>
</Target>

<Target Name="_ResolveAars" Condition=" '$(AndroidApplication)' == 'true' ">
<ItemGroup>
<_AarSearchDirectory Include="@(_ReferencePath->'%(RootDir)%(Directory)')" />
Expand Down
4 changes: 2 additions & 2 deletions src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down
Loading