Xamarin.Android provides open-source bindings of the Android SDK for use with .NET managed languages such as C#.
|Commercial Xamarin.Android 7.0 (Cycle 8) for macOS|
|Commercial Xamarin.Android 7.1 (Cycle 9) for macOS|
|Commercial Xamarin.Android 7.1.99 (master) for macOS|
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
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, and edit the file as appropriate.
and will override any default values specified in
Overridable MSBuild properties include:
$(AndroidApiLevel): The Android API level to bind in
src/Mono.Android. This is an integer value, e.g.
15for 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 leading
$(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 Windows
libmonosgen-2.0.dllfrom OS X. Supported host values include:
mxe-Win64: Cross-compile Windows 64-bit binaries from Unix.
The default value is
$(HostOS)is based on probing various environment variables and filesystem locations. On OS X, the default would be
$(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:
$(AndroidToolchainCacheDirectory): The directory to cache the downloaded Android NDK and SDK files. This value defaults to
$(AndroidToolchainDirectory): The directory to install the downloaded Android NDK and SDK files. This value defaults to
$(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 is
external/Java.Interopdirectory, maintained by
git 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
COUNTis obtained from
$(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.
Building Xamarin.Android requires:
- Mono 4.4 or later
- The Java Development Kit (JDK)
- Autotools (
- The Android SDK and NDK
(This is because the build system uses the XmlPeek task, which was first added in Mono 4.4.)
Java Development Kit
Autotools -- including
automake -- are required to build
the Mono runtimes.
If you run into issues regarding
automake try to install it with
brew install automake
Android NDK, SDK
To 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
The files that will be downloaded and installed are controlled by
@(AndroidSdkItem) item groups, and the
URL to download files from is controlled by the
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:
This will perform
git submodule update, and any other pre-build tasks
that need to be performed. After this process is completed, ensure there
is no existing git changes in the
On the main repo, you can use
git status to ensure a clean slate.
Then, you may do one of the following:
Xamarin.Android.slninto Xamarin Studio and Build the project.
Mono.Androidproject 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-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.
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
macOS Build Notes
monodroid.projitems project files, among
others, use the
@(RequiredProgram) build action to check for the existence
of a program within
$PATH during the build. If a required program doesn't
exist, then the build will fail and a suggested
brew install command line
will be provided to install the missing commands.
brew install commands:
brew install cmake brew install libtool brew install p7zip brew install gdk-pixbuf brew install gettext brew install coreutils brew install findutils brew install gnu-tar brew install gnu-sed brew install gawk brew install gnutls brew install gnu-indent brew install gnu-getopt brew install intltool brew install scons brew install wget brew install xz
If any program is still not found, try to ensure it's linked via:
brew link <package name>
Build Output Directory Structure
There are two configurations,
Release, controlled by the
$(Configuration) MSBuild property.
bin\Build$(Configuration) directory, e.g.
artifacts needed for building the repository. They should not be needed
for later execution.
bin\$(Configuration) directory, e.g.
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 as
Mono.Android.dllfor a given Xamarin.Android
Xamarin.Android uses the MSBuild
to provide a separate
Mono.Android.dll binding assembly for each API
This means there is no single
Mono.Android.dll, there is instead a set
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
To control which API level is bound, set the
$(AndroidApiLevel) is the
Android API level, usually a number, while
is the Xamarin.Android
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
$ 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 samples/HelloWorld/bin/Debug/com.xamarin.android.helloworld-Signed.apk
HelloWorld may be launched manually through the Android app launcher,
adb shell am:
$ adb shell am start com.xamarin.android.helloworld/example.MainActivity
To discuss this project, and participate in the design, we use the email@example.com mailing list.
We use Mono's Coding Guidelines.
We use Bugzilla to track issues.