53bcf69f91
* Tasks/BuildApk.cs: Add 'TlsProvider' parameter. * Xamarin.Android.Common.targets: Add <AndroidTlsProvider> property and pass it to BuildApk. Add this to your .csproj file to select the TLS Provider. Valid values are "legacy" and "btls". We now add a new 'XA_TLS_PROVIDER' environment variable to the .apk, which is read by System/Mono.Net.Security/MonoTlsProviderFactory.Droid.cs to select the TLS Provider. Linker support (to eliminate the unused provider, similar to how it's already done in xamarin-macios) is coming shortly. |
||
---|---|---|
Documentation | ||
build-tools | ||
external | ||
samples/HelloWorld | ||
src | ||
tools | ||
.gitattributes | ||
.gitignore | ||
.gitmodules | ||
Configuration.Java.Interop.Override.props | ||
Configuration.Override.props.in | ||
Configuration.props | ||
Dockerfile | ||
LICENSE | ||
Makefile | ||
README.md | ||
Xamarin.Android-Tests.sln | ||
Xamarin.Android.sln | ||
product.snk |
README.md
Xamarin.Android
Xamarin.Android provides open-source bindings of the Android SDK for use with .NET managed languages such as C#.
Build Status
Platform | Status |
---|---|
OSS macOS | |
OSS Ubuntu |
Downloads
Platform | Status |
---|---|
Commercial Xamarin.Android 6.2 (Cycle 8) for macOS | |
Commercial Xamarin.Android 7.0.99 (master) for macOS |
Configuration.Override.props
The Xamarin.Android build is heavily dependent on MSBuild, with the intention
that it should (eventually?) be possible to build the project simply by
checking out the repo, loading Xamarin.Android.sln
into an IDE, and Building
the solution. (This isn't currently possible, and may never be, but it's
the vision.)
However, some properties may need to be altered in order to suit your requirements, such as the location of a cache directory to store the Android SDK and NDK.
To modify the build process, copy
Configuration.Override.props.in
to Configuration.Override.props
, and edit the file as appropriate.
Configuration.Override.props
is <Import/>
ed by Configuration.props
and will override any default values specified in Configuration.props
.
Overridable MSBuild properties include:
-
$(AndroidApiLevel)
: The Android API level to bind insrc/Mono.Android
. This is an integer value, e.g.15
for API-15 (Android 4.0.3). -
$(AndroidFrameworkVersion)
: The Xamarin.Android$(TargetFrameworkVersion)
version which corresponds to$(AndroidApiLevel)
. This is usually the Android version number with a leadingv
, e.g.v4.0.3
for API-15. -
$(AndroidSupportedHostJitAbis)
: The Android ABIs for which to build a host JIT and Xamarin.Android base class libraries (mscorlib.dll
/etc.). The "host JIT" is used e.g. with the Xamarin Studio Designer, to render Xamarin.Android apps on the developer's machine. There can also be support for cross-compiling mono for a different host, e.g. to build Windowslibmonosgen-2.0.dll
from OS X. Supported host values include:Darwin
Linux
mxe-Win64
: Cross-compile Windows 64-bit binaries from Unix.
The default value is
$(HostOS)
, where$(HostOS)
is based on probing various environment variables and filesystem locations. On OS X, the default would beDarwin
. -
$(AndroidSupportedTargetJitAbis)
: The Android ABIs for which to build the the Mono JIT for inclusion within apps. This is a:
-separated list of ABIs to build. Supported values are:armeabi
armeabi-v7a
arm64-v8a
x86
x86_64
-
$(AndroidToolchainCacheDirectory)
: The directory to cache the downloaded Android NDK and SDK files. This value defaults to$(HOME)\android-archives
. -
$(AndroidToolchainDirectory)
: The directory to install the downloaded Android NDK and SDK files. This value defaults to$(HOME)\android-toolchain
. -
$(HostCc)
,$(HostCxx)
: The C and C++ compilers to use to generate host-native binaries. -
$(JavaInteropSourceDirectory)
: The Java.Interop source directory to build and reference projects from. By default, this isexternal/Java.Interop
directory, maintained bygit submodule update
. -
$(MakeConcurrency)
: make(1) parameters to use intended to influence the number of CPU cores used when make(1) executes. By default this uses-jCOUNT
, whereCOUNT
is obtained fromsysctl hw.ncpu
. -
$(MonoSgenBridgeVersion)
: The Mono SGEN Bridge version to support. Valid values include:4
: Mono 4.6 support.5
: Mono 4.8 support. This is the default.
Build Requirements
Building Xamarin.Android requires:
- Mono 4.4 or later
- The Java Development Kit (JDK)
- Autotools (
autoconf
,automake
, etc.) xxd
- The Android SDK and NDK
Mono 4.4 or later is required to build on OS X and Linux.
(This is because the build system uses the XmlPeek task, which was first added in Mono 4.4.)
## Java Development KitThe Java Development Kit may be downloaded from the Oracle Java SE Downloads page.
## AutotoolsAutotools -- including autoconf
and automake
-- are required to build
the Mono runtimes.
On OS X, autotools are distributed with Mono.framework.
## `xxd`The xxd utility is used to build src/monodroid. It is installed by default on OS X. Linux users may need to separately install it; it may be part of the vim-common package.
## Android NDK, SDKTo simplify building Xamarin.Android, important pieces of the Android SDK
and Android NDK will be automatically downloaded and installed from
Google's website. Downloaded files are cached locally, by default into
$(AndroidToolchainCacheDirectory)
. The Android NDK and SDK will be installed by
default into $(AndroidToolchainDirectory)
.
The files that will be downloaded and installed are controlled by
build-tools/android-toolchain/android-toolchain.projitems
via the @(AndroidNdkItem)
and @(AndroidSdkItem)
item groups, and the
URL to download files from is controlled by the $(AndroidUri)
property.
Build
At this point in time, building Xamarin.Android is only supported on OS X. We will work to improve this.
To build Xamarin.Android, first prepare the project:
make prepare
This will perform git submodule update
, and any other pre-build tasks
that need to be performed.
Then, you may do one of the following:
-
Run make:
make
-
Load
Xamarin.Android.sln
into Xamarin Studio and Build the project.Note: The
Mono.Android
project may fail on the first build because it generates sources, and those sources won't exist on the initial project load. Rebuild the project should this happen.
Linux build notes
If you have the binfmt_misc
module enabled with any of Mono or Wine installed and
you plan to cross-build the Windows compilers and tools (by enabling the mxe-Win32
or mxe-Win64
host targets) as well as LLVM+AOT targets, you will need to disable
binfmt_misc
for the duration of the build or the Mono/LLVM configure scripts will
fail to detect they are cross-compiling and they will produce Windows PE executables
for tools required by the build.
To disable binfmt_misc
you need to issue the following command as root:
echo 0 > /proc/sys/fs/binfmt_misc/status
and to enable it again, issue the following command:
echo 1 > /proc/sys/fs/binfmt_misc/status
Build Output Directory Structure
There are two configurations, Debug
and Release
, controlled by the
$(Configuration)
MSBuild property.
The bin\Build$(Configuration)
directory, e.g. bin\BuildDebug
, contains
artifacts needed for building the repository. They should not be needed
for later execution.
The bin\$(Configuration)
directory, e.g. bin\Debug
, contains
redistributable artifacts, such as tooling and runtimes. This directory
acts as a local installation prefix, in which the directory structure
mirrors that of the OS X Xamarin.Android.framework directory structure:
bin\$(Configuration)\lib\xbuild\Xamarin\Android
: MSBuild-related support files and required runtimes used by the MSBuild tooling.bin\$(Configuration)\lib\xbuild-frameworks\MonoAndroid
: Xamarin.Android profiles.bin\$(Configuration)\lib\xbuild-frameworks\MonoAndroid\v1.0
: Xamarin.Android Base Class Library assemblies such asmscorlib.dll
.bin\$(Configuration)\lib\xbuild-frameworks\MonoAndroid\*
: ContainsMono.Android.dll
for a given Xamarin.Android$(TargetFrameworkVersion)
.
Xamarin.Android $(TargetFrameworkVersion)
s
Xamarin.Android uses the MSBuild $(TargetFrameworkVersion)
mechanism
to provide a separate Mono.Android.dll
binding assembly for each API
level.
This means there is no single Mono.Android.dll
, there is instead a set
of them.
This complicates the "mental model" for the Mono.Android
project, as
a project can have only one output, not many (...within reason...).
As such, building the Mono.Android
project will only generate a single
Mono.Android.dll
.
To control which API level is bound, set the $(AndroidApiLevel)
and
$(AndroidFrameworkVersion)
properties. $(AndroidApiLevel)
is the
Android API level, usually a number, while $(AndroidFrameworkVersion)
is the Xamarin.Android $(TargetFrameworkVersion)
.
The default values will target Android API-24, Android 7.0.
For example, to generate Mono.Android.dll
for API-19 (Android 4.4):
cd src/Mono.Android
xbuild /p:AndroidApiLevel=19 /p:AndroidFrameworkVersion=v4.4
# creates bin\Debug\lib\xbuild-frameworks\MonoAndroid\v4.4\Mono.Android.dll
Samples
The HelloWorld sample may be built with the xabuild script:
$ tools/scripts/xabuild /t:SignAndroidPackage samples/HelloWorld/HelloWorld.csproj
xabuild /t:SignAndroidPackage
will generate an .apk
file, which may be
installed onto an Android device with the adb install
command:
$ adb install samples/HelloWorld/bin/Debug/com.xamarin.android.helloworld-Signed.apk
HelloWorld may be launched manually through the Android app launcher,
or via adb shell am
:
$ adb shell am start com.xamarin.android.helloworld/example.MainActivity
Contributing
Mailing Lists
To discuss this project, and participate in the design, we use the android-devel@lists.xamarin.com mailing list.
Coding Guidelines
We use Mono's Coding Guidelines.
Reporting Bugs
We use Bugzilla to track issues.
Maintainer FAQ
How do I rebuild the Mono Runtime and Native Binaries?
The various Mono runtimes -- over 20 of them (!) -- all store object code
within build-tools/mono-runtimes/obj/$(Configuration)/TARGET
.
If you change sources within external/mono
, a top-level make
/xbuild
invocation may not rebuild those mono native binaries. To explicitly rebuild
all Mono runtimes, use the ForceBuild
target:
# Build and install all runtimes
$ xbuild /t:ForceBuild build-tools/mono-runtimes/mono-runtimes.mdproj
To build Mono for a specific target, run make
from the relevant directory
and invoke the _InstallRuntimes
target. For example, to rebuild
Mono for armeabi-v7a:
$ cd build-tools/mono-runtimes
$ make -C obj/Debug/armeabi-v7a
# This updates bin/$(Configuration)/lib/xbuild/Xamarin/Android/lib/armeabi-v7a/libmonosgen-2.0.so
$ xbuild /t:_InstallRuntimes
How do I rebuild BCL assemblies?
The Xamarin.Android Base Class Library assemblies, such as mscorlib.dll
,
are built within external/mono
, using Mono's normal build system:
# This updates external/mono/mcs/class/lib/monodroid/ASSEMBLY.dll
$ make -C external/mono/mcs/class/ASSEMBLY PROFILE=monodroid
Alternatively, if you want to rebuild all the assemblies, the "host" Mono needs to be rebuilt. Note that the name of the "host" directory varies based on the operating system you're building from:
$ make -C build-tools/mono-runtimes/obj/Debug/host-Darwin
Once the assemblies have been rebuilt, they can be copied into the appropriate
Xamarin.Android SDK directory by using the _InstallBcl
target:
# This updates bin/$(Configuration)/lib/xbuild-frameworks/MonoAndroid/v1.0/ASSEMBLY.dll
$ xbuild build-tools/mono-runtimes/mono-runtimes.mdproj /t:_InstallBcl