- PDF for offline use:
The Xamarin.Android build process is responsible for gluing everything
Resource.designer.cs, supporting the
AndroidResource, and other build actions,
generating Android-callable wrappers, and generating a
execution on Android devices.
In broad terms, there are two types of Android application packages
.apk files) which the Xamarin.Android build system can generate:
- Release builds, which are fully self-contained and don't require additional packages in order to execute. These are the packages which would be provided to an App store.
- Debug builds, which are not.
Not coincidentally, these match the MSBuild
produces the package. ;-)
The shared runtime is a pair of additional Android packages which
provide the Base Class Library (
mscorlib.dll, etc.) and the
Android binding library (
Mono.Android.dll, etc.). Debug builds
rely upon the shared runtime in lieu of including the Base Class Library and
Binding assemblies within the Android application package, allowing the
Debug package to be smaller.
The shared runtime may be disabled in Debug builds by setting the
$(AndroidUseSharedRuntime) property to
Fast deployment works in concert with the shared runtime to
further shrink the Android application package size. This is done by
not bundling the app's assemblies within the package. Instead, they are
copied onto the target via
adb push. This process speeds up the
build/deploy/debug cycle because if only assemblies are changed, the
package is not reinstalled. Instead, only the updated assemblies are
re-synchronized to the target device.
Fast deployment is known to fail on devices which block
from synchronizing to the directory
Fast deployment is enabled by default, and may be disabled in Debug builds
by setting the
$(EmbedAssembliesIntoApk) property to
The Xamarin.Android build process is based on MSBuild, which is also the project file format used by Xamarin Studio and Visual Studio. * Ordinarily users will not need to edit the MSBuild files by hand* - the IDE creates fully functional projects and updates them with any changes made, and automatically invoke build targets as needed.
Advanced users may wish to do things not supported by the IDE's GUI, so the build process is customisable by editing the project file directly. This page documents only the Xamarin.Android-specific features and customizations - many more things are possible with the normal MSBuild items, properties and targets.
The following build targets are defined for Xamarin.Android projects:
|Build||Builds the package.|
|Clean||Removes all files generated by the build process.|
|Install||Installs the package onto the default device or virtual device.|
|Uninstall||Uninstalls the package from the default device or virtual device.|
|SignAndroidPackage||Creates and signs the package (
MSBuild properties control the behavior of the targets. They are specified
within the project file, e.g.
<em>MyApp</em>.csproj, within an MSBuild
Specifies the build configuration to use, such as "Debug" or "Release".
The Configuration property is used to determine default values for
other properties which determine target behavior.
Additional configurations may be created within your IDE.
By default, the
A boolean value which determines whether the Android package is
debuggable, in combination with the
debug symbols to generate as part of the build,
which also impacts whether the Application is debuggable.
Possible values include:
Install properties control the behavior of the
Specifies the Android target device the Android package may be
installed to or removed from. The value of this property is the same as the
Packaging properties control the creation of the Android package, and are
used by the
The Signing Properties are also relevant
when packaing Release applications.
A boolean value that indicates whether the project is for an
Android Application (
Only one project with
Specifies which type of
linking should be
performed on assemblies contained within the Android package.
Only used in Android Application projects. The default value is
SdkOnly. Valid values are:
Note: Using an
Specifies a semicolon-delimited (
Specifies a filename to use as the template for the app's
The Android SDK build-tools package provides the `aapt` and `zipalign`
tools, among others. Multiple different versions of the build-tools
package may be installed simultaneously. The build-tools package
chosen for packaging is done by checking for and using a "preferred"
build-tools version if it is present; if the "preferred" version is
*not* present, then the highested versioned installed build-tools
package is used.
The `$(AndroidSdkBuildToolsVersion)` MSBuild property contains the prefered build-tools version. The Xamarin.Android build system provides a default value in `Xamarin.Android.Common.targets`, and the default value may be overridden within youur project file to choose an alternate build-tools version, if (for example) the latest aapt is crashing out while a previous aapt version is known to work.
A boolean property that is determines whether the shared runtime
packages are required in order to run the Application on the
target device. Relying on the shared runtime packages allows the
Application package to be smaller, speeding up the package creation
and deployment process, resulting in a faster build/deploy/debug
This property should be
A boolean property that determines whether or not the app's assemblies
should be embedded into the Application package.
This property should be
Specifies the value of the java
Specifying this property is necessary if the
Specifies additional command-line options to pass to java
when building the
Specifies the internationalization support included with the
Application, such as collation and sorting tables. The value is
a comma- or semicolon-separated list of one or more of the following
Resource properties control the generation of the
Resource.designer.cs file, which provides access to Android
|AndroidResgenExtraArgs||Specifies additional command-line options to pass to the aapt command when processing Android assets and resources.|
Specifies the name of the Resource file to generate.
The default template sets this to
Specifies a path prefix that is removed from the start
of filenames with a Build action of
The default value is
Signing properties control how the Application package is signed so that
it may be installed onto an Android device. In order to
allow quicker build iteration, the Xamarin.Android tasks do not sign packages
during the build process, because signing is quite slow. Instead, they are
signed (if necessary) before installation or during export, by the IDE or the
Install build target. Invoking the SignAndroidPackage target
will produce a package with the
-Signed.apk suffix in the output
By default, the signing target generates a new debug-signing key if necessary. If you wish to use a specific key, for example on a build server, the following MSBuild properties can be used:
|AndroidKeyStore||A boolean value which indicates whether custom signing information should be used. The default value is `False`, meaning that the default debug-signing key will be used to sign packages.|
|AndroidSigningKeyAlias||Specifies the alias for the key in the keystore. This is the keytool -alias value used when creating the keystore.|
Specifies the password of the key within the keystore file.
This is the value entered when
Specifies the filename of the keystore file created by
Specifies the password to
For example, consider the following
$ keytool -genkey -v -keystore filename.keystore -alias keystore.alias -keyalg RSA -keysize 2048 -validity 10000 Enter keystore password: keystore.filename password Re-enter new password: keystore.filename password ... Is CN=... correct? [no]: yes Generating 2,048 bit RSA key pair and self-signed certificate (SHA1withRSA) with a validity of 10,000 days for: ... Enter key password for keystore.alias (RETURN if same as keystore password): keystore.alias password [Storing filename.keystore]
To use the keystore generated above, use the property group:
<PropertyGroup> <AndroidKeyStore>True</AndroidKeyStore> <AndroidSigningKeyStore>filename.keystore</AndroidSigningKeyStore> <AndroidSigningStorePass>keystore.filename password</AndroidSigningStorePass> <AndroidSigningKeyAlias>keystore.alias</AndroidSigningKeyAlias> <AndroidSigningKeyPass>keystore.alias password</AndroidSigningKeyPass> </PropertyGroup>
Build actions are applied to files within the project and control how the file is processed.
Files with a Build action of
AndroidEnvironment are used
to initialize environment variables and system properties during process startup.
AndroidEnvironment Build action may be applied to
multiple files, and they will be evaluated in no particular order (so don't
specify the same environment variable or system property in multiple
Files with a Build action of
AndroidJavaSource are Java source code which
will be included in the final Android package.
Files with a Build action of
AndroidJavaLibrary are Java
.jar files) which will be included in the final Android
All files with an AndroidResource build action are compiled into
Android resources during the build process and made accessible via
<ItemGroup> <AndroidResource Include="Resources\values\strings.xml" /> </ItemGroup>
More advanced users might perhaps wish to have different resources used in different configurations but with the same effective path. This can be achieved by having multiple resource directories and having files with the same relative paths within these different directories, and using MSBuild conditions to conditionally include different files in different configurations. For example:
<ItemGroup Condition="'$(Configuration)'!='Debug'"> <AndroidResource Include="Resources\values\strings.xml" /> </ItemGroup> <ItemGroup Condition="'$(Configuration)'=='Debug'"> <AndroidResource Include="Resources-Debug\values\strings.xml"/> </ItemGroup> <PropertyGroup> <MonoAndroidResourcePrefix>Resources;Resources-Debug<MonoAndroidResourcePrefix> </PropertyGroup>
|Item Attribute Name||Description|
Specifies the resource path explicitly. Allows "aliasing" files so
that they will be available as multiple distinct resource names.
Native libraries are added to the build by setting their Build action
Note that since Android supports multiple Application Binary Interfaces (ABIs), the build system must know which ABI the native library is built for. There are two ways this can be done:
- Path "sniffing".
- Using the
With path sniffing, the parent directory name of the native library is used
to specify the ABI that the library targets. Thus, if you add
lib/armeabi/libfoo.so to the build, then the ABI will be "sniffed"
|Item Attribute Name||Description|
Specifies the ABI of the native library.
Content Build action is not supported (as we
haven't figured out how to support it without a possibly costly first-run
Files with a LinkDescription build action are used to control linker behavior.
The Xamarin.Android-specific parts of the build process are defined in
but normal language-specific targets such as Microsoft.CSharp.targets
are also required to build the assembly.
The following build properties must be set before importing any language targets:
<PropertyGroup> <TargetFrameworkIdentifier>MonoDroid</TargetFrameworkIdentifier> <MonoDroidVersion>v1.0</MonoDroidVersion> <TargetFrameworkVersion>v2.2</TargetFrameworkVersion> </PropertyGroup>
All these these targets and properties can be included for C# by importing Xamarin.Android.CSharp.targets:
<Import Project="$(MSBuildExtensionsPath)\Xamarin\Android\Xamarin.Android.CSharp.targets" />
and this file can easily be adapted for other languages.