Binding Libraries with Binderator

In order to maintain so many packages, this repository uses a custom tool called binderator.

This tool provides many functions, such as:

• Downloading needed Java files from Maven
• Ensuring all Java dependencies are met
• Generating needed .csproj files for each package

Configuring binderator

binderator is configured with the config.json file located in the repository root.

The most common elements to modify are:

• artifacts - Specifies a Java artifact to bind and create a NuGet package for. There is one of these for each package we create.
• licenses - Specifies additional information about license(s) found in a Java .pom file needed for generating correctly licensed NuGet packages.

artifacts

The minimum information necessary to bind a Java artifact is:

{
  "groupId": "androidx.activity",
  "artifactId": "activity",
  "version": "1.9.2",
  "nugetId": "Xamarin.AndroidX.Activity",
  "nugetVersion": "1.9.2.1"
}

Required Field	Type	Description
groupId	string	The group id of the Java library to bind.
artifactId	string	The artifact id of the Java library to bind.
version	string	The version of the Java library to bind.
nugetId	string	The package name to give the NuGet package.
nugetVersion	string	The version to give the NuGet version.

Additionally, there are many optional fields that can be used to configure various aspects of the artifact binding process.

Optional Field	Type	Default	Description
dependencyOnly	bool	false	When true, specifies that this isn't a Java artifact that should be bound. Instead, it provides a Java package -> NuGet package mapping that the binderator dependency resolution process will use to add a <PackageReference> to fulfill the dependency.
frozen	bool	false	When true, specifies that this artifact is currently "frozen" at the specified version. That is, we will not try to automatically update this artifact when new versions are published to Maven. This is often used when there is an issue with a newer version that we don't want to deal with yet.
allowPrereleaseDependencies	bool	false	By default, we prohibit a stable NuGet package from depending on an unstable NuGet package. However, sometimes the state of the Java ecosystem doesn't give us a choice. When true, we will not throw an error if the package has an unstable dependency.
assemblyName	string	null	By default, the binding assembly filename is the same as the NuGet package id. When specified, this allows the binding assembly name to be changed.
excludedRuntimeDependencies	string	null	A comma delimited list of dependencies specified in the artifact's .pom file that should be ignored. This can be used to bypass problematic dependencies. However it must be used carefully, as the NuGet package will not specify the dependency, but if Java requires it at runtime the application will crash. The format is {groupid}.{artifactid}.
extraDependencies	string	null	A comma delimited list of additional dependencies that the artifact NuGet package should depend on. This is used when additional Java or .NET dependencies are needed that aren't specified in the .pom file. The format is {groupid}.{artifactid}:{version}. Version is optional.
type	string	targets	Specifies the binding "style" of the package. Valid values: - androidlibrary - A normal .NET for Android binding package using <AndroidLibrary>. The .jar/.aar will be placed next to the binding .dll. - targets - The legacy AndroidX style where the .jar/.aar is manually placed in the NuGet package and a .targets file is added which add the library using AndroidJavaLibrary or AndroidAarLibrary. - xbd - The style generally used by GPS/FB/MLKit/etc. This style is for proprietary libraries where we cannot include the .jar/.aar in the NuGet package. Instead, a .targets file is added which uses Xamarin.Build.Download to download the artifact when the user compiles their application. - no-bindings - A style that only adds the Java artifact to the user's application. No C# bindings are generated for this style.
mavenRepositoryType	string	Google	By default, binderator looks for Java artifacts in Google's Maven. If the artifact exists in another Maven, this specifies the Maven type. Valid values: - Google - Google's Maven - MavenCentral - Maven Central - Url - Another Maven repository, specified with the mavenRepositoryLocation field.
mavenRepositoryLocation	string	null	When using mavenRepositoryType = Url, this specifies the URL of the Maven repository.
documentationType	string	none	Any additional source to use to add documentation and method parameter information to the binding. Valid values: - none - No additional source, parameter names will be pulled from Java bytecode when available - javadoc - Additional documentation will be pulled from a -javadoc.jar package using <JavaDocJar>. - javasource - Additional documentation will be pulled from a -sources.jar package using <JavaSourceJar>.
skipExtendedTests	bool	false	When true, specifies that "extended" package tests should not be run on this package. Used when there are known issues that prevent this package from passing tests.
overrideLicenses	json	null	By default, licensing information is pulled from the artifact's .pom file. If this information is missing, manually specify license(s) with the following JSON: "overrideLicenses": [ "Apache 2.0|http://www.apache.org/licenses/LICENSE-2.0.txt" ] The format is {license_name}|{license_url}. (The license URL is optional.)
comments	string	null	Allows additional comment(s) about the artifact to be specified. This is highly recommended when using some of the rarer optional fields to explain why they are needed.