Build Process
- PDF for offline use:
Let us know how you feel about this.
0/250
Overview
The Xamarin.Android build process is responsible for gluing everything
together: generating Resource.designer.cs, supporting the AndroidAsset, AndroidResource, and other build actions,
generating Android-callable wrappers, and generating a .apk for
execution on Android devices.
Application Packages
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 Configuration which
produces the package. ;-)
Shared Runtime
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 False.
Fast Deployment
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 adb
from synchronizing to the directory /data/data/@PACKAGE_NAME@/files/.__override__.
Fast deployment is enabled by default, and may be disabled in Debug builds
by setting the $(EmbedAssembliesIntoApk) property to True.
MSBuild Projects
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.
Build Targets
The following build targets are defined for Xamarin.Android projects:
| Target Name | Description |
|---|---|
| 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 (.apk). Use with
/p:Configuration=Release to
generate self-contained "Release" packages.
|
| UpdateAndroidResources | Updates the Resource.designer.cs file. This target is
usually called by the IDE when new resources are added to the project.
|
Build Properties
MSBuild properties control the behavior of the targets. They are specified
within the project file, e.g. <em>MyApp</em>.csproj, within an MSBuild PropertyGroupelement.
| Property Name | Description |
|---|---|
| Configuration |
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 The default |
| DebugSymbols |
A boolean value which determines whether the Android package is
debuggable, in combination with the $(DebugType)
property. A debuggable package contains debug symbols,
sets the //application/@android:debuggable attribute
to true, and automatically adds the INTERNET
permission so that a debugger can attach to the process.
An application is debuggable if DebugSymbols is
True and DebugType is either the
empty string or Full.
|
| DebugType |
Specifies the
type of
debug symbols to generate as part of the build,
which also impacts whether the Application is debuggable.
Possible values include:
DebugType is not set or is the empty string, then the
DebugSymbols property controls whether or not th
Application is debuggable.
|
Install Properties
Install properties control the behavior of the Install and Uninstall targets.
| Property Name | Description |
|---|---|
| AdbTarget |
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
adb Target Device option:
|
Packaging Properties
Packaging properties control the creation of the Android package, and are
used by the Install and SignAndroidPackage targets.
The Signing Properties are also relevant
when packaing Release applications.
| Property Name | Description |
|---|---|
| AndroidApplication |
A boolean value that indicates whether the project is for an
Android Application (True) or for an Android Library
Project (False or not present).
Only one project with
|
| AndroidEnableMultiDex |
A boolean property that determines whether or not
multi-dex support will be used in the final .apk.
Support for this property was added in Xamarin.Android 5.1. This property is |
| AndroidFastDeploymentType |
A : (colon)-separated list of values to control
what types can be deployed to the
Fast Deployment directory
on the target device when the
$(EmbedAssembliesIntoApk)
MSBuild property is False. If a resource is fast deployed,
it is not embedded into the generated .apk,
which can speed up deployment times. (The more that is fast deployed,
then the less frequently the .apk needs to be rebuilt,
and the install process can be faster.)
Valid values include:
The default value is Experimental. Added in Xamarin.Android 6.1. |
| AndroidApplicationJavaClass |
The full Java class name to use in place of
android.app.Application when a class inherits from
Android.App.Application.
This property is generally set by other properties, such as the
Added in Xamarin.Android 6.1. |
| AndroidHttpClientHandlerType |
Allow setting the value of the XA_HTTP_CLIENT_HANDLER_TYPE environment variable.
This value will not override an explicitly specified
Added in Xamarin.Android 6.1. |
| AndroidLinkMode |
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 |
| AndroidLinkSkip |
Specifies a semicolon-delimited (;) list of assembly names,
without file extensions, of assemblies that should not be linked.
Only used within Android Application projects.
|
| AndroidManagedSymbols |
A boolean property that controls whether sequence points are generated
so that file name and line number information can be extracted from
Release stack traces.
Added in Xamarin.Android 6.1. |
| AndroidManifest |
Specifies a filename to use as the template for the app's
AndroidManifest.xml. During the build, any other
necessary values will be merged into to produce the actual
AndroidManifest.xml.
The |
| AndroidSdkBuildToolsVersion |
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. |
| AndroidSupportedAbis |
A string property that contains a semicolon (;)-delimited
list of ABIs which should be included into the .apk.
Supported values include:
|
| AndroidUseSharedRuntime |
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
turnaround cycle.
This property should be |
| AotAssemblies |
A boolean property that determines whether or not
assemblies will be Ahead-of-Time compiled into native code and
included in the .apk.
Support for this property was added in Xamarin.Android 5.1. This property is |
| EmbedAssembliesIntoApk |
A boolean property that determines whether or not the app's assemblies
should be embedded into the Application package.
This property should be When this property is |
| EnableLLVM |
A boolean property that determines whether or not
LLVM will be used when Ahead-of-Time compiling assemblines
into native code.
Support for this property was added in Xamarin.Android 5.1. This property is This property is ignored unless the |
| EnableProguard |
A boolean property that determines whether or not
[proguard](http://developer.android.com/tools/help/proguard.html)
is run as part of the packaging process in order to link Java code.
Support for this property was added in Xamarin.Android 5.1. This property is When |
| JavaMaximumHeapSize |
Specifies the value of the java -Xmx
parameter value to use when building the .dex file
as part of the packaging process. If not specified, then the
-Xmx option is not provided to java.
Specifying this property is necessary if the
|
| JavaOptions |
Specifies additional command-line options to pass to java
when building the .dex file.
|
| MandroidI18n |
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
case-insensitive values:
|
Binding Project Build Properties
The following MSBuild properties are used with Binding projects:
Resource Properties
Resource properties control the generation of the Resource.designer.cs file, which provides access to Android
resources.
| Property Name | Description |
|---|---|
| AndroidResgenExtraArgs | Specifies additional command-line options to pass to the aapt command when processing Android assets and resources. |
| AndroidResgenFile |
Specifies the name of the Resource file to generate.
The default template sets this to Resource.designer.cs.
|
| MonoAndroidResourcePrefix |
Specifies a path prefix that is removed from the start
of filenames with a Build action of AndroidResource.
This is to allow changing where resources are located.
The default value is |
Signing Properties
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
directory.
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:
| Property Name | Description |
|---|---|
| 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. |
| AndroidSigningKeyPass |
Specifies the password of the key within the keystore file.
This is the value entered when keytool asks
Enter key password for $(AndroidSigningKeyAlias).
|
| AndroidSigningKeyStore |
Specifies the filename of the keystore file created by keytool.
This corresponds to the value provided to the
keytool -keystore option.
|
| AndroidSigningStorePass |
Specifies the password to $(AndroidSigningKeyStore).
This is the value provided to keytool when creating
the keystore file and asked Enter keystore password:.
|
For example, consider the following keytool invocation:
$ 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
Build actions are applied to files within the project and control how the file is processed.
AndroidEnvironment
Files with a Build action of AndroidEnvironment are used
to initialize environment variables and system properties during process startup.
The 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).
AndroidJavaSource
Files with a Build action of AndroidJavaSource are Java source code which
will be included in the final Android package.
AndroidJavaLibrary
Files with a Build action of AndroidJavaLibrary are Java
Archives ( .jar files) which will be included in the final Android
package.
AndroidResource
All files with an AndroidResource build action are compiled into
Android resources during the build process and made accessible via $(AndroidResgenFile).
<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 |
|---|---|
| LogicalName |
Specifies the resource path explicitly. Allows "aliasing" files so
that they will be available as multiple distinct resource names.
|
AndroidNativeLibrary
Native libraries are added to the build by setting their Build action
to AndroidNativeLibrary.
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
Abiitem attribute.
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"
as armeabi.
| Item Attribute Name | Description |
|---|---|
| Abi |
Specifies the ABI of the native library.
|
Content
The normal Content Build action is not supported (as we
haven't figured out how to support it without a possibly costly first-run
step).
Starting in Xamarin.Android 5.1, attempting to use thw @(Content)
Build action will result in a XA0101 warning.
LinkDescription
Files with a LinkDescription build action are used to control linker behavior.
ProguardConfiguration
Files with a ProguardConfiguration build action contain
proguard options
which are used to control proguard behavior.
These files are ignored unless the $(EnableProguard) MSBuild property
is True.
Target Definitions
The Xamarin.Android-specific parts of the build process are defined in $(MSBuildExtensionsPath)\Xamarin\Android\Xamarin.Android.CSharp.targets,
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.
Let us know how you feel about this.
0/250
Xamarin Workbook
If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.