Part 1 - Preparing an Application for Release

After an application has been coded and tested, it is necessary to prepare a package for distribution. The first task in preparing this package is to build the application for release, which mainly entails setting some application attributes. Use the following steps to build the app for release:

  • Disable Debugging – This prevents users from trying to debug the application on a device by using adb or other tools.

  • Specify the Application Icon – Each Xamarin.Android application should have an application icon specified. Although not technically necessary, some markets, such as Google Play, require it.

  • Version the Application – This step involves initializing or updating the versioning information. This is important for future application updates and to ensure that the users are aware of which version of the application they have installed.

  • Configure the Linker – Linking is a step that is specific to Xamarin.Android and can substantially reduce the size of the final APK by removing unused code.

  • Set Packaging Properties – Packaging properties control the creation of the Android application package (APK). This step optimizes the APK, protects its assets, and modularizes the packaging as needed.

  • Specify Supported Architectures – This step specifies which CPU architectures the application can run on.

  • Compile – This step compiles the code and assets to verify that it builds in Release mode.

  • Archive for Publishing – This step builds the app and places it in an archive for signing and publishing.

  • Disable Debugging – This prevents users from trying to debug the application on a device by using adb or other tools.

  • Specify the Application Icon – Each Xamarin.Android application should have an application icon specified. It is not technically required; however, some markets, such as Google Play, require it.

  • Version the Application – This step involves initializing or updating the versioning information. This is important for future application updates and to ensure that the users are aware of which version of the application they have installed.

  • Configure the Linker – Linking is a step that is specific to Xamarin.Android and can substantially reduce the size of the final APK by removing unused code.

  • Set Packaging Properties – Packaging properties control the creation of the Android application package (APK). This step optimizes the APK, protects its assets, and modularizes the packaging as needed.

  • Specify Supported Architectures – This step specifies which CPU architectures the application can run on.

  • Compile – This step compiles the code and assets to verify that it builds in Release mode.

Each of these steps is described below in more detail.

Disable Debugging

During development of an Android application, debugging is performed with the use of the Java Debug Wire Protocol (JDWP). This is a technology that allows tools such as adb to communicate with a JVM for the purposes of debugging. JDWP is turned on by default for Debug builds of a Xamarin.Android application. While JDWP is important during development, it can pose a security issue for released applications.

Note: Always disable the debug state in a released application as it is possible (via JDWP) to gain full access to the Java process and execute arbitrary code in the context of the application if this debug state is not disabled.

The Android Manifest contains the android:debuggable attribute, which controls whether or not the application may be debugged. It is considered a good practice to set the android:debuggable attribute to false. The simplest way to do this is by adding a conditional compile statement in AssemblyInfo.cs:

#if DEBUG
[assembly: Application(Debuggable=true)]
#else
[assembly: Application(Debuggable=false)]
#endif

Specify the Application Icon

It is strongly recommended that each Xamarin.Android application specify an application icon. Some application marketplaces will not allow an Android application to be published without one.

The Icon property of the Application attribute is used to specify the application icon for a Xamarin.Android project. This attribute can be declared in the file Properties\AssemblyInfo.cs, as shown in this sample snippet:

[assembly: Application(Icon = "@drawable/icon")]

In Xamarin Studio, it is also possible to specify the application icon through the Android Application section of Project Options, as shown in the following screenshot:

In Visual Studio, it is also possible to specify the application icon through the Android Manifest section of project Properties, as shown in the following screenshot:

Version the Application

Versioning is important for Android application maintenance and distribution. Without some sort of versioning in place, it is difficult to determine if or how an application should be updated. To assist with versioning, Android recognizes two different types of information:

  • Version Number – An integer value (used internally by Android and the application) that represents the version of the application. Most applications start out with this value set to 1, and then it is incremented with each build. This value has no relationship or affinity with the version name attribute (see below). Applications and publishing services should not display this value to users. This value is stored in the AndroidManifest.xml file as android:versionCode.

  • Version Name – A string that is used only for communicating information to the user about the version of the application (as installed on a specific device). The version name is intended to be displayed to users or in Google Play. This string is not used internally by Android. The version name can be any string value that would help a user identify the build that is installed on their device. This value is stored in the AndroidManifest.xml file as android:versionName.

In Xamarin Studio, these values can be set via the Build > Android Application section of Project Options as shown in the following screenshot:

In Visual Studio, these values can be set in the Android Manifest section of project Properties, as shown in the following screenshot:

Configure the Linker

Release mode turns off the shared runtime and turns on linking so that the application only ships the pieces of Xamarin.Android required at runtime. The linker in Xamarin.Android uses static analysis to determine which assemblies, types, and type members are used or referenced by a Xamarin.Android application. The linker then discards all the unused assemblies, types, and members that are not used (or referenced). This can result in a significant reduction in the package size. For example, consider the HelloWorld sample, which experiences an 83% reduction in the final size of its APK:

Configuration

Xamarin.Android 4.2.5 Size

None

17.4 MB

SDK Assemblies Only

3.0 MB

 

In Xamarin Studio, you set linker options through the Linker tab in the Android Build section of Project Options, as shown in the following screenshot:

The options for controlling the linker are as follows:

  • Don't link – This turns off the linker; no linking will be performed.

  • Link SDK assemblies only – This will only link the assemblies that are required by Xamarin.Android. Other assemblies will not be linked.

  • Link all assemblies – This will link all assemblies that are required by the application, and not just the ones required by Xamarin.Android.

In Visual Studio, you configure the linker in the Android Options section of project Properties. To access the linker options, click the Linker tab as shown in the following screen shot:

The Linking pull-down menu provides the following options for controlling the linker:

  • None – This turns off the linker; no linking will be performed.

  • Sdk Assemblies Only – This will link only the assemblies that are required by Xamarin.Android. Other assemblies will not be linked.

  • Sdk and User Assemblies – This will link all assemblies that are required by the application, and not just the ones required by Xamarin.Android.

Linking can produce some unintended side effects, so it is important that an application be re-tested in Release mode. The testing must also occur on a physical device.

Set Packaging Properties

In Xamarin Studio, packaging properties can be set in the Android Build section of Project Options, as shown in the following screenshot:

In Visual Studio, packaging properties can be set in the Android Options section of project Properties, as shown in the following screenshot:

Many of these properties, such as Use Shared Runtime, and Use Fast Deployment are intended for Debug mode. However, when the application is configured for Release mode, there are other settings that determine how the app is optimized for size and execution speed, how it is protected from tampering, and how it can be packaged to support different architectures and size restrictions.

Bundle Assemblies into Native Code

When this option is enabled, assemblies are bundled into a native shared library. This option keeps your code safe; it protects managed assemblies by embedding them in native binaries. However, this does not mean that the assemblies are compiled into native code. You can use AOT Compilation, below, to compile assemblies into native code.

Note that this option requires an Enterprise license and is only available when Use Fast Deployment is disabled. Bundle assemblies into native code is disabled by default.

Generate One Package (.apk) per Selected ABI

When this option is enabled, one APK will be created for each of the supported ABI's (selected on the Advanced tab, as described below) rather than a single, large APK for all supported ABI's. This option is available only when the project is configured for Release mode, and it is disabled by default.

AOT Compilation

The AOT Compilation option enables Ahead-of-Time (AOT) compilation of assemblies. When this option is enabled, Just In Time (JIT) startup overhead is minimized by precompiling assemblies before runtime. The resulting native code is included in the APK along with the uncompiled assemblies. This results in shorter application startup time, but at the expense of slightly larger APK sizes.

Note that the AOT Compilation option requires an Enterprise license and is available only when the project is configured for Release mode. AOT Compilation is disabled by default. For more information about AOT Compilation, see AOT.

LLVM Optimizing Compiler

When the AOT Compilation option is enabled, you can choose to enable the LLVM Optimizing Compiler for converting AOT-compiled assemblies into native code. The LLVM compiler creates smaller and faster compiled code, but at the expense of slower build times. The LLVM compiler is disabled by default.

Note that the LLVM Optimizing Compiler option requires an Enterprise license and is available only when AOT Compilation is enabled.

ProGuard

ProGuard is an Android SDK tool that links and obfuscates Java code. ProGuard is normally used to create smaller applications by reducing the footprint of large included libraries (such as Google Play Services) in your APK. ProGuard removes unused Java bytecode, which makes the resulting app smaller. For example, using ProGuard on small Xamarin.Android apps usually achieves about a 24% reduction in size – using ProGuard on larger apps with multiple library dependencies typically achieves an even greater size reduction. ProGuard is not an alternative to the Xamarin.Android linker. The Xamarin.Android linker links managed code, while ProGuard links Java bytecode. The build process first uses the Xamarin.Android linker to optimize your app at the managed code (C#) level, and then it later uses ProGuard (if enabled) to optimize the APK at the Java bytecode level.

When Enable ProGuard is checked, Xamarin.Android runs the ProGuard tool on the resulting APK. Xamarin.Android also supports custom ProguardConfiguration build actions. You can add a custom ProGuard configuration file to your project, right-click it, and select it as a build action as shown in this example:

The ProGuard page at SourceForge explains the options that can be specified in a ProGuard configuration file. When Enable ProGuard is checked, Xamarin.Android also generates and uses a ProGuard configuration file at build time – this file is generated at obj/Release/proguard/proguard_xamarin.cfg. Keep in mind that your configuration file (if you provide one) does not replace the proguard_xamarin.cfg file since both are used by ProGuard.

ProGuard is disabled by default. The Enable ProGuard option is available only when the project is set to Release mode. All ProGuard build actions are ignored unless Enable ProGuard is checked. The Xamarin.Android ProGuard configuration does not obfuscate the APK, and it is not possible to enable obfuscation, even with custom configuration files.

For more information about the ProGuard tool and Android, see ProGuard.

Multi-Dex

When the Enable Multi-Dex option is enabled, Android SDK tools are used to bypass the 65K method limit of the .dex file format. The 65K method limitation is based on the number of Java methods that your app references (including those in any libraries that you use) – it is not based on the number of methods that you define. In other words, you can reach this limit even if your app defines only a few methods.

Chances are, your app is not using every method in its included libraries; therefore, you can avoid reaching this limit by using ProGuard (above) to remove unused code from your APK. The best practice is to use Enable Multi-Dex only if, after using ProGuard, your app still references more than 65K Java methods.

For more information about Multi-Dex, see Building Apps with Over 65K Methods.

Specify Supported Architectures

When you prepare your app for release, you must specify which platform CPU architectures your app supports. A single APK can contain machine code to support multiple, different architectures. Each collection of architecture-specific code is associated with an Application Binary Interface (ABI). Each ABI defines how this machine code is expected to interact with Android at run time. For more information about how this works, see Multi-Core Devices & Xamarin.Android.

In Xamarin Studio, you specify supported architectures in the Advanced tab of Android Build settings:

In Visual Studio, you specify supported architectures in the Advanced tab of Android Options:

Xamarin.Android supports the following architectures:

  • armeabi – ARM-based CPUs that support at least the ARMv5TE instruction set. Note that armeabi is not thread-safe and should not be used on multi-CPU devices.

  • armeabi-v7a – ARM-based CPUs with hardware floating-point operations and multiple CPU (SMP) devices. Note that armeabi-v7a machine code will not run on ARMv5 devices.

  • arm64-v8a – CPUs based on the 64-bit ARMv8 architecture.

  • x86 – CPUs that support the x86 (or IA-32) instruction set. This instruction set is equivalent to that of the Pentium Pro, including MMX, SSE, SSE2, and SSE3 instructions.

  • x86_64 CPUs that support the 64-bit x86 (also referred as x64 and AMD64) instruction set.

Xamarin.Android defaults to armeabi-v7a for Release builds. This setting provides significantly better performance than armeabi. If you are targeting a 64-bit ARM platform (such as the Nexus 9), select arm64-v8a. If you are deploying your app to an x86 device, select x86. If the target x86 device uses a 64-bit CPU architecture, select x86_64.

To target multiple platforms, you can select more than one architecture (at the expense of larger APK file size). You can use the Generate one package (.apk) per selected ABI option (described earlier) to create a separate APK for each supported architecture. Note that 64-bit support is not required in order to run your app on 64-bit hardware. For example, 64-bit ARM devices (such as the Nexus 9) can run apps configured for armeabi-v7a. The primary advantage of enabling 64-bit support is to make it possible for your app to address more memory.

Compile

After all of the above steps are completed, you are ready to compile the application (select Build > Rebuild Solution) to verify that it builds successfully in Release mode. Note that this step does not yet produce an APK.

In Part 2, we'll create an APK and manually sign the application.

After all of the above steps are completed, you are ready to compile the application (select Build > Build All) to verify that it builds successfully in Release mode. Note that this step does not yet produce an APK. If you are using a version of Xamarin Studio earlier than 5.9, the next step is to manually sign the application as described in Part 2. Otherwise, continue below to archive the project for publishing.

Archive for Publishing (Xamarin Studio 5.9 and Later).

Xamarin Studio 5.9 introduces a new, integrated workflow for signing and publishing apps. To begin this publishing process, select Build > Archive for Publishing:

Archive for Publishing builds the project and bundles it into an archive file. The Archive All menu choice archives all archivable projects in the solution. Both options automatically open the Archive Manager when the build and bundling operations complete:

In this example, the Archive Manager lists only one archived application, MyApp. Notice that the comment field allows you to enter a short comment that is saved with the archive. When you have an archived version of your application that you are ready to publish, select the app in the Archive Manager and click Sign and Distribute… as shown above. The resulting Sign and Distribute dialog presents two choices:

From here, you can choose one of the following distribution channels:

  • Ad-Hoc – Saves a signed APK to disk so you can use it for sideloading to Android devices. Continue to Part 2 to learn how to create an Android signing identity, create a new signing certificate for Android applications, and publish an “ad hoc” version of the app to disk. The resulting APK can be sideloaded into Android devices without going through an app store. This is a good way to test your app as a package before publishing it to Google Play.

  • Google Play – Publishes a signed APK to Google Play. Continue to Part 3 to learn how to sign and publish an APK in the Google Play store.