From 59ff24ad258ead554f43da7b963deeb6d6b80693 Mon Sep 17 00:00:00 2001 From: Dean Ellis Date: Wed, 12 Jul 2017 14:34:06 +0100 Subject: [PATCH] Pull in the Build Process documentation from the docs repo. --- Documentation/build_process.md | 829 +++++++++++++++++++++++++++++++++ 1 file changed, 829 insertions(+) create mode 100644 Documentation/build_process.md diff --git a/Documentation/build_process.md b/Documentation/build_process.md new file mode 100644 index 00000000000..48a26dc6a72 --- /dev/null +++ b/Documentation/build_process.md @@ -0,0 +1,829 @@ +--- +id: 3BE5EE1E-3FF6-4E95-7C9F-7B443EE3E94C +title: "Build Process" +dateupdated: 2017-06-22 +--- + + + +# Overview + +The Xamarin.Android build process is responsible for gluing everything +together: +[generating `Resource.designer.cs`](/guides/android/advanced_topics/api_design#Resources), +supporting the `AndroidAsset`, `AndroidResource`, and other +[build actions](#Build_Actions), generating +[Android-callable wrappers](/guides/android/advanced_topics/java_integration_overview/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: + +- **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. **MyApp.csproj**, within +an [MSBuild PropertyGroup element](http://msdn.microsoft.com/en-us/library/t4w159bs.aspx). + +- **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 `Debug` configuration will result in the + `Install` and `SignAndroidPackage` targets creating a smaller + Android package which requires the presence of other files and + packages in order to operate. + + The default `Release` configuration will result in the in the + `Install` and `SignAndroidPackage` targets creating an Android + package which is *stand-alone*, and may be used without installing + any other packages or files. + +- **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](http://msdn.microsoft.com/en-us/library/s5c8athz.aspx) + to generate as part of the build, which also impacts whether the + Application is debuggable. Possible values include: + + - **Full**: Full symbols are generated. If the `DebugSymbols` + MSBuild property is also `True`, then the Application package is + debuggable. + + - **PdbOnly**: "PDB" symbols are generated. The + Application package will *not* be debuggable. + + If `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. + +- **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](http://developer.android.com/tools/help/adb.html#issuingcommands): + + # Install package onto emulator via -e + # Use `/Library/Frameworks/Mono.framework/Commands/xbuild` on OS X + MSBuild /t:Install ProjectName.csproj /p:AdbTarget=-e + + + +## Packaging Properties + +Packaging properties control the creation of the Android package, and are +used by the `Install` and `SignAndroidPackage` targets. +The [Signing Properties](#Signing_Properties) are also relevant +when packaing Release applications. + + +- **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 + `True` may be present + within an Android package. (Unfortunately this is not yet verified, + which can result in subtle and bizarre errors regarding Android + resources.) + +- **AndroidBuildApplicationPackage** – A boolean value that + indicates whether to create and sign the package (.apk). Setting + this value to `True` is equivalent to using the + [SignAndroidPackage](#Build_Targets) build target. + + Support for this property was added after Xamarin.Android 7.1. + + This property is `False` by default. + +- **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 `False` by default. + +- **AndroidEnableSGenConcurrent** – A boolean property that + determines whether or not Mono's + [concurrent GC collector](http://www.mono-project.com/docs/about-mono/releases/4.8.0/#concurrent-sgen) + will be used. + + Support for this property was added in Xamarin.Android 7.2. + + This property is `False` by default. + +- **AndroidFastDeploymentType** – A `:` (colon)-separated list + of values to control what types can be deployed to the + [Fast Deployment directory](#Fast_Deployment) on the target device + when the + [`$(EmbedAssembliesIntoApk)`](#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: + + - `Assemblies`: Deploy application assemblies. + + - `Dexes`: Deploy `.dex` files, Android Resources, and Android + Assets. **This value can *only* be used on devices running + Android 4.4 or later (API-19).** + + The default value is `Assemblies`. + + **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](/api/type/Android.App.Application/). + + This property is generally set by *other* properties, such as the [`$(AndroidEnableMultiDex)`](#AndroidEnableMultiDex) MSBuild property. + + Added in Xamarin.Android 6.1. + +- **AndroidHttpClientHandlerType** – Allow setting the value of the + [`XA_HTTP_CLIENT_HANDLER_TYPE` environment variable](/guides/android/advanced_topics/environment/#XA_HTTP_CLIENT_HANDLER_TYPE). + This value will not override an explicitly specified + `XA_HTTP_CLIENT_HANDLER_TYPE` value. An + `XA_HTTP_CLIENT_HANDLER_TYPE` environment variable value specified + in an + [`@(AndroidEnvironment)`](#AndroidEnvironment) file will take + precedence. + + Added in Xamarin.Android 6.1. + +- **AndroidTlsProvider** – A string value which specifies which + TLS provider should be used in an application. Possible values are: + Valid values include: + + - `btls`: Use + [Boring SSL](https://boringssl.googlesource.com/boringssl) for + TLS communication with + [HttpWebRequest](https://msdn.microsoft.com/en-us/library/system.net.httpwebrequest.aspx). + This allows use of TLS 1.2. + + - `legacy`: Use the historical managed SSL implementation for + network interaction. This *does not* support TLS 1.2. + + - `default`, or unset/the empty string: In Xamarin.Android 7.1, + this is equivalent to `legacy`. + + The default value is the empty string. + + **Experimental**. Added in Xamarin.Android 7.1. + +- **AndroidLinkMode** – Specifies which type of + [linking](/guides/android/advanced_topics/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: + + - **None**: No linking will be attempted. + + - **SdkOnly**: Linking will be performed on the base class + libraries only, not user's assemblies. + + - **Full**: Linking will be performed on base class libraries and + user assemblies. + + > ℹ️ **Note:** Using an `AndroidLinkMode` value of *Full* often results in broken apps, particularly when Reflection is used. Avoid unless you *really* know what you're doing. + + SdkOnly + +- **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. + + Assembly1;Assembly2 + +- **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`](/guides/android/advanced_topics/working_with_androidmanifest.xml/). + During the build, any other necessary values will be merged into to + produce the actual `AndroidManifest.xml`. + The `$(AndroidManifest)` must contain the package name in the `/manifest/@package` attribute. + +- **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: + + - `armeabi` + - `armeabi-v7a` + - `x86` + - `arm64-v8a`: Requires Xamarin.Android 5.1 and later. + - `x86_64`: Requires Xamarin.Android 5.1 and later. + +- **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 `True` for Debug builds, and `False` for + Release projects. + +- **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 `False` by default. + +- **EmbedAssembliesIntoApk** – A boolean property that + determines whether or not the app's assemblies should be embedded + into the Application package. + + This property should be `True` for Release builds and `False` for + Debug builds. It *may* need to be `True` in Debug builds if Fast + Deployment doesn't support the target device. + + When this property is `False`, then the + `$(AndroidFastDeploymentType)` MSBuild property also controls what + will be embedd into the `.apk`, which can impact deployment and + rebuidl times. + +- **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 `False` by default. + + This property is ignored unless the `$(AotAssemblies)` MSBuild + property is `True`. + +- **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 `False` by default. + + When `True`, + [ProguardConfiguration](#ProguardConfiguration) files will be used + to control `proguard` execution. + +- **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 + [`_CompileDex` target throws a `java.lang.OutOfMemoryError`](https://bugzilla.xamarin.com/show_bug.cgi?id=18327). + + 1G + +- **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: + + - **None**: Include no additional encodings. + + - **All**: Include all available encodings. + + - **CJK**: Include Chinese, Japanese, and Korean encodings such as + *Japanese (EUC)* \[enc-jp, CP51932\], *Japanese (Shift-JIS)* + \[iso-2022-jp, shift\_jis, CP932\], *Japanese (JIS)* \[CP50220\], + *Chinese Simplified (GB2312)* \[gb2312, CP936\], *Korean (UHC)* + \[ks\_c\_5601-1987, CP949\], *Korean (EUC)* \[euc-kr, CP51949\], + *Chinese Traditional (Big5)* \[big5, CP950\], and *Chinese + Simplified (GB18030)* \[GB18030, CP54936\]. + + - **MidEast**: Include Middle-Eastern encodings such as *Turkish + (Windows)* \[iso-8859-9, CP1254\], *Hebrew (Windows)* + \[windows-1255, CP1255\], *Arabic (Windows)* \[windows-1256, + CP1256\], *Arabic (ISO)* \[iso-8859-6, CP28596\], *Hebrew (ISO)* + \[iso-8859-8, CP28598\], *Latin 5 (ISO)* \[iso-8859-9, CP28599\], + and *Hebrew (Iso Alternative)* \[iso-8859-8, CP38598\]. + + - **Other**: Include Other encodings such as *Cyrillic (Windows)* + \[CP1251\], *Baltic (Windows)* \[iso-8859-4, CP1257\], *Vietnamese + (Windows)* \[CP1258\], *Cyrillic (KOI8-R)* \[koi8-r, CP1251\], + *Ukrainian (KOI8-U)* \[koi8-u, CP1251\], *Baltic (ISO)* + \[iso-8859-4, CP1257\], *Cyrillic (ISO)* \[iso-8859-5, CP1251\], + *ISCII Davenagari* \[x-iscii-de, CP57002\], *ISCII Bengali* + \[x-iscii-be, CP57003\], *ISCII Tamil* \[x-iscii-ta, CP57004\], + *ISCII Telugu* \[x-iscii-te, CP57005\], *ISCII Assamese* + \[x-iscii-as, CP57006\], *ISCII Oriya* \[x-iscii-or, CP57007\], + *ISCII Kannada* \[x-iscii-ka, CP57008\], *ISCII Malayalam* + \[x-iscii-ma, CP57009\], *ISCII Gujarati* \[x-iscii-gu, CP57010\], + *ISCII Punjabi* \[x-iscii-pa, CP57011\], and *Thai (Windows)* + \[CP874\]. + + - **Rare**: Include Rare encodings such as *IBM EBCDIC (Turkish)* + \[CP1026\], *IBM EBCDIC (Open Systems Latin 1)* \[CP1047\], *IBM + EBCDIC (US-Canada with Euro)* \[CP1140\], *IBM EBCDIC (Germany with + Euro)* \[CP1141\], *IBM EBCDIC (Denmark/Norway with Euro)* + \[CP1142\], *IBM EBCDIC (Finland/Sweden with Euro)* \[CP1143\], + *IBM EBCDIC (Italy with Euro)* \[CP1144\], *IBM EBCDIC (Latin + America/Spain with Euro)* \[CP1145\], *IBM EBCDIC (United Kingdom + with Euro)* \[CP1146\], *IBM EBCDIC (France with Euro)* \[CP1147\], + *IBM EBCDIC (International with Euro)* \[CP1148\], *IBM EBCDIC + (Icelandic with Euro)* \[CP1149\], *IBM EBCDIC (Germany)* + \[CP20273\], *IBM EBCDIC (Denmark/Norway)* \[CP20277\], *IBM EBCDIC + (Finland/Sweden)* \[CP20278\], *IBM EBCDIC (Italy)* \[CP20280\], + *IBM EBCDIC (Latin America/Spain)* \[CP20284\], *IBM EBCDIC (United + Kingdom)* \[CP20285\], *IBM EBCDIC (Japanese Katakana Extended)* + \[CP20290\], *IBM EBCDIC (France)* \[CP20297\], *IBM EBCDIC + (Arabic)* \[CP20420\], *IBM EBCDIC (Hebrew)* \[CP20424\], *IBM + EBCDIC (Icelandic)* \[CP20871\], *IBM EBCDIC (Cyrillic - Serbian, + Bulgarian)* \[CP21025\], *IBM EBCDIC (US-Canada)* \[CP37\], *IBM + EBCDIC (International)* \[CP500\], *Arabic (ASMO 708)* \[CP708\], + *Central European (DOS)* \[CP852\]*, Cyrillic (DOS)* \[CP855\], + *Turkish (DOS)* \[CP857\], *Western European (DOS with Euro)* + \[CP858\], *Hebrew (DOS)* \[CP862\], *Arabic (DOS)* \[CP864\], + *Russian (DOS)* \[CP866\], *Greek (DOS)* \[CP869\], *IBM EBCDIC + (Latin 2)* \[CP870\], and *IBM EBCDIC (Greek)* \[CP875\]. + + - **West**: Include Western encodings such as *Western European + (Mac)* \[macintosh, CP10000\], *Icelandic (Mac)* \[x-mac-icelandic, + CP10079\], *Central European (Windows)* \[iso-8859-2, CP1250\], + *Western European (Windows)* \[iso-8859-1, CP1252\], *Greek + (Windows)* \[iso-8859-7, CP1253\], *Central European (ISO)* + \[iso-8859-2, CP28592\], *Latin 3 (ISO)* \[iso-8859-3, CP28593\], + *Greek (ISO)* \[iso-8859-7, CP28597\], *Latin 9 (ISO)* + \[iso-8859-15, CP28605\], *OEM United States* \[CP437\], *Western + European (DOS)* \[CP850\], *Portuguese (DOS)* \[CP860\], *Icelandic + (DOS)* \[CP861\], *French Canadian (DOS)* \[CP863\], and *Nordic + (DOS)* \[CP865\]. + + + West + +- **MonoSymbolArchive** – A boolean property which controls + whether `.mSYM` artifacts are created for later use with + `mono-symbolicate`, to extract “real” filename and line + number information from Release stack traces. + + This is True by default for “Release” apps which have + debugging symbols enabled: + [`$(EmbedAssembliesIntoApk)`](#EmbedAssembliesIntoApk) is True, + `$(DebugSymbols)` is True, and `$(Optimize)` is True. + + Added in Xamarin.Android 7.1. + +## Binding Project Build Properties + +The following MSBuild properties are used with +[Binding projects](guides/android/advanced_topics/binding-a-java-library/): + +- **AndroidClassParser** – A string property which controls how + `.jar` files are parsed. Possible values include: + + - **class-parse**: Uses `class-parse.exe` to parse Java bytecode + directly, without assistance of a JVM. This value is + experimental. + + + - **jar2xml**: Use `jar2xml.jar` to use Java reflection to extract + types and members from a `.jar` file. + + The advantages of `class-parse` over `jar2xml` are: + + - `class-parse` is able to extract parameter names from Java + bytecode which contains *debug* symbols (e.g. bytecode compiled + with `javac -g`). + + - `class-parse` doesn't "skip" classes which inherit from or + contain members of unresolvable types. + + **Experimental**. Added in Xamarin.Android 6.0. + + The default value is `jar2xml`. + + The default value will change in a future release. + +- **AndroidCodegenTarget** – A string property which controls the code generation target ABI. Possible values include: + + - **XamarinAndroid**: Uses the JNI binding API present in since + Mono for Android 1.0. Binding assemblies built with with + Xamarin.Android 5.0 or later can only run on Xamarin.Android 5.0 + or later (API/ABI additions), but the *source* is compatible with + prior product versions. + + - **XAJavaInterop1**: Use Java.Interop for JNI invocations. Binding + assemblies using `XAJavaInterop1` can only build and execute with + Xamarin.Android 6.1 or later. Xamarin.Android 6.1 and later bind + `Mono.Android.dll` with this value. + + The benefits of `XAJavaInterop1` include: + + - Smaller assemblies. + + - `jmethodID` caching for `base` method invocations, + so long as all other binding types in the inheritance + hierarchy are built with `XAJavaInterop1` or later. + + - `jmethodID` caching of Java Callable Wrapper constructors for + managed subclasses. + + The default value is `XamarinAndroid`. + + The default value will change in a future release. + + + + + +## Resource Properties + +Resource properties control the generation of the +`Resource.designer.cs` file, which provides access to Android +resources. + +- **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 `Resources`. Change this to `res` for the + Java project structure. + +- **AndroidExplicitCrunch** – If you are building an app with a + very large number of local drawables, an initial build (or rebuild) + can take minutes to complete. To speed up the build process, try + including this property and setting it to `True`. When this + property is set, the build process pre-crunches the .png files. + + **Experimental**. Added in Xamarin.Android 7.0. + + + + + +## 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: + +- **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: + + + True + filename.keystore + keystore.filename password + keystore.alias + keystore.alias password + + + + + +# Build Actions + +*Build actions* are +[applied to files](http://msdn.microsoft.com/en-us/library/bb629388.aspx) +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](/guides/android/advanced_topics/environment/). +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)`. + +``` + + + +``` + +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: + +``` + + + + + + + + Resources;Resources-Debug + +``` + +- **LogicalName** – Specifies the resource path explicitly. + Allows “aliasing” files so that they will be available + as multiple distinct resource names. + + + + + + + values/strings.xml + + + + + + +## AndroidNativeLibrary + +[Native libraries](/guides/android/advanced_topics/cpu_architecture/#Android_Native_Library_Installation) +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: + +1. Path "sniffing". +2. Using the `Abi` item 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 + +- **Abi** – Specifies the ABI of the native library. + + + + armeabi + + + +## 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](/guides/cross-platform/advanced/custom_linking/). + + + + +## ProguardConfiguration + +Files with a *ProguardConfiguration* build action contain options which +are used to control `proguard` behavior. For more information about +this build action, see +[ProGuard](/guides/android/deployment,_testing,_and_metrics/proguard/). + +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: + + + MonoDroid + v1.0 + v2.2 + + +All of these these targets and properties can be included for C# by +importing *Xamarin.Android.CSharp.targets*: + + + +This file can easily be adapted for other languages.