Xamarin.Android provides open-source bindings of the Android SDK for use with .NET managed languages such as C#
Перейти к файлу
Jonathan Pryor cfb82e4378 [xa-prep-tasks] Improve <DownloadUri/> behavior (#302)
The `<DownloadUri/>` Task had two problems:

1. It used `HttpClient.GetAsync()`, not `HttpClient.GetStreamAsync()`.
    It *looks* like a minor difference, but the former would
    apparently attempt to store the *entire* source URI contents
    *in memory*, which would fail if the URI contents are "big".

2. Exceptions leaving `Task.Execute()` are "uglier" than exceptions
    logged via `TaskLoggingHelper.LogErrorFromException()`.

Improve the `<DownloadUri/>` task so that
`HttpClient.GetStreamAsync()` is used, removing the "download to
in-memory" behavior, and use
`TaskLoggingHelper.LogErrorFromException()` so that error messages are
nicer.

Additionally, `xa-prep-tasks.targets`
*wasn't supposed to surface errors* from the `_DownloadBundle` target.
The bundle which is downloaded *may not exist*. The build shouldn't
fail if the specified URI can't be found.

What's odd is that this *used* to work for me, in that if the target
URI -- the bundle -- didn't exist, `<DownloadTask/>` wouldn't report
an error, and execution would continue.

I suspect, but have not tested or verified, that Azure had changed
it's handling here: previously, it would return an XML document
containing a "404" error, even when the URL didn't exist.
This is *still the case* now [^0], so I'm not sure why I was *ever*
getting an error in the first place! (Very odd...)

"Sanitize" the behavior here: since the `_DownloadBundle` task can be
expected to "fail" -- in that the target URI may not exist, even if
Azure/etc. doesn't give a 404 for it -- then the `<DownloadUri/>` task
invocation should contain a `ContinueOnError="True"` attribute so that
errors are ignored.

Additionally, there is no need for the `_ExtractBundle` target to
execute unless the downloaded file exists, so make `_ExtractBundle`
conditional on the file existing, and update the
`_DownloadAndExtractBundle` target so that it explicitly orders the
dependent targets, so that `_ExtractBundle` doesn't need to depend on
the `_DownloadBundle` target.

[^0]: For example:

    $ curl -o x.txt https://xamjenkinsartifact.blob.core.windows.net/xamarin-android/xamarin-android/bin/does-not-exist
    $ $ cat x.txt
    <?xml version="1.0" encoding="utf-8"?><Error><Code>BlobNotFound</Code><Message>The specified blob does not exist.
    RequestId:d54a8d4a-0001-007d-1a0e-415487000000
    Time:2016-11-17T20:12:32.8482654Z</Message></Error>
2016-11-18 14:49:08 +00:00
Documentation [mono-runtimes] Build AOT+LLVM cross-compilers (#125) 2016-07-26 09:27:31 -04:00
build-tools [xa-prep-tasks] Improve <DownloadUri/> behavior (#302) 2016-11-18 14:49:08 +00:00
external Bump to Java.Interop/7985cb97 (#300) 2016-11-17 11:14:08 -05:00
samples/HelloWorld [build] Package build artifacts with `make jenkins` (#153) 2016-08-09 22:16:46 +02:00
src [Mono.Android] Update ALL api.xml with the latest api-xml-adjuster. (#304) 2016-11-18 09:45:14 -05:00
tools [build] Package build artifacts with `make jenkins` (#153) 2016-08-09 22:16:46 +02:00
.gitattributes Fix line endings 2016-07-06 17:09:45 +02:00
.gitignore [mono-runtimes] Build AOT+LLVM cross-compilers (#125) 2016-07-26 09:27:31 -04:00
.gitmodules use mono/linker sources to build the linker (#291) 2016-11-11 10:02:53 -05:00
Configuration.Java.Interop.Override.props [build] Fix Java.Interop utilities directory 2016-06-09 08:28:30 -04:00
Configuration.Override.props.in [Xamarin.Android.Build.Tasks] Support new manifest attributes for API-24 (#128) 2016-08-01 09:12:20 -04:00
Configuration.props [build] Install API-25 android.jar, Build API-25 bindings 2016-11-14 11:18:32 -05:00
Dockerfile Add Dockerfile. (#204) 2016-09-02 12:37:12 -04:00
LICENSE [LICENSE] Add the libzip license. (#112) 2016-07-08 18:55:08 +02:00
Makefile [monodroid] Build the host libmono-android* files. (#276) 2016-10-24 17:05:01 +02:00
README.md Bump to mono/mono-4.8.0-branch/9e164326, Java.Interop/a1d3ecc8 (#223) 2016-09-15 18:13:56 +02:00
Xamarin.Android-Tests.sln [Xamarin.Android-Tests] Split out "full" apps (#146) 2016-08-08 16:46:13 -04:00
Xamarin.Android.sln [xa-prep-tasks] Use the Mono bundle (#162) 2016-08-16 16:02:48 -04:00
product.snk [Mono.Android, Mono.Android.Export] Sign assemblies. (#29) 2016-05-10 16:29:33 +01:00

README.md

Xamarin.Android

Xamarin.Android provides open-source bindings of the Android SDK for use with .NET managed languages such as C#.

Gitter

Build Status

Platform Status
OSS macOS OSS macOS x86_64
OSS Ubuntu OSS Linux/Ubuntu x86_64

Downloads

Platform Status
Commercial Xamarin.Android 6.2 (Cycle 8) for macOS Commercial Xamarin.Android 6.2, macOS
Commercial Xamarin.Android 7.0.99 (master) for macOS Commercial Xamarin.Android 7.1, macOS

Configuration.Override.props

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 the vision.)

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.in to Configuration.Override.props, and edit the file as appropriate. Configuration.Override.props is <Import/>ed by Configuration.props and will override any default values specified in Configuration.props.

Overridable MSBuild properties include:

  • $(AndroidApiLevel): The Android API level to bind in src/Mono.Android. This is an integer value, e.g. 15 for 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 v, e.g. v4.0.3 for API-15.

  • $(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.dll from OS X. Supported host values include:

    • Darwin
    • Linux
    • mxe-Win64: Cross-compile Windows 64-bit binaries from Unix.

    The default value is $(HostOS), where $(HostOS) is based on probing various environment variables and filesystem locations. On OS X, the default would be Darwin.

  • $(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:

    • armeabi
    • armeabi-v7a
    • arm64-v8a
    • x86
    • x86_64
  • $(AndroidToolchainCacheDirectory): The directory to cache the downloaded Android NDK and SDK files. This value defaults to $(HOME)\android-archives.

  • $(AndroidToolchainDirectory): The directory to install the downloaded Android NDK and SDK files. This value defaults to $(HOME)\android-toolchain.

  • $(HostCc), $(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.Interop directory, 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 -jCOUNT, where COUNT is obtained from sysctl hw.ncpu.

  • $(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.

Build Requirements

Building Xamarin.Android requires:

## Mono MDK

Mono 4.4 or later is required to build on OS X and Linux.

(This is because the build system uses the XmlPeek task, which was first added in Mono 4.4.)

## Java Development Kit

The Java Development Kit may be downloaded from the Oracle Java SE Downloads page.

## Autotools

Autotools -- including autoconf and automake -- are required to build the Mono runtimes.

On OS X, autotools are distributed with Mono.framework.

## `xxd`

The xxd utility is used to build src/monodroid. It is installed by default on OS X. Linux users may need to separately install it; it may be part of the vim-common package.

## 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 default into $(AndroidToolchainDirectory).

The files that will be downloaded and installed are controlled by build-tools/android-toolchain/android-toolchain.projitems via the @(AndroidNdkItem) and @(AndroidSdkItem) item groups, and the URL to download files from is controlled by the $(AndroidUri) property.

Build

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:

make prepare

This will perform git submodule update, and any other pre-build tasks that need to be performed.

Then, you may do one of the following:

  1. Run make:

     make
    
  2. Load Xamarin.Android.sln into Xamarin Studio and Build the project.

    Note: The Mono.Android project 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-Win32 or 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.

To disable 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

Build Output Directory Structure

There are two configurations, Debug and Release, controlled by the $(Configuration) MSBuild property.

The bin\Build$(Configuration) directory, e.g. bin\BuildDebug, contains artifacts needed for building the repository. They should not be needed for later execution.

The bin\$(Configuration) directory, e.g. bin\Debug, contains 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 mscorlib.dll.
  • bin\$(Configuration)\lib\xbuild-frameworks\MonoAndroid\*: Contains Mono.Android.dll for a given Xamarin.Android $(TargetFrameworkVersion).

Xamarin.Android $(TargetFrameworkVersion)s

Xamarin.Android uses the MSBuild $(TargetFrameworkVersion) mechanism to provide a separate Mono.Android.dll binding assembly for each API level.

This means there is no single Mono.Android.dll, there is instead a set of them.

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 Mono.Android.dll.

To control which API level is bound, set the $(AndroidApiLevel) and $(AndroidFrameworkVersion) properties. $(AndroidApiLevel) is the Android API level, usually a number, while $(AndroidFrameworkVersion) is the Xamarin.Android $(TargetFrameworkVersion).

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

Samples

The HelloWorld sample may be built with the xabuild script:

$ 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 command:

$ adb install samples/HelloWorld/bin/Debug/com.xamarin.android.helloworld-Signed.apk

HelloWorld may be launched manually through the Android app launcher, or via adb shell am:

$ adb shell am start com.xamarin.android.helloworld/example.MainActivity

Contributing

Mailing Lists

To discuss this project, and participate in the design, we use the android-devel@lists.xamarin.com mailing list.

Coding Guidelines

We use Mono's Coding Guidelines.

Reporting Bugs

We use Bugzilla to track issues.

Maintainer FAQ

How do I rebuild the Mono Runtime and Native Binaries?

The various Mono runtimes -- over 20 of them (!) -- all store object code within build-tools/mono-runtimes/obj/$(Configuration)/TARGET.

If you change sources within external/mono, a top-level make/xbuild invocation may not rebuild those mono native binaries. To explicitly rebuild all Mono runtimes, use the ForceBuild target:

# Build and install all runtimes
$ xbuild /t:ForceBuild build-tools/mono-runtimes/mono-runtimes.mdproj

To build Mono for a specific target, run make from the relevant directory and invoke the _InstallRuntimes target. For example, to rebuild Mono for armeabi-v7a:

$ cd build-tools/mono-runtimes
$ make -C obj/Debug/armeabi-v7a

# This updates bin/$(Configuration)/lib/xbuild/Xamarin/Android/lib/armeabi-v7a/libmonosgen-2.0.so
$ xbuild /t:_InstallRuntimes

How do I rebuild BCL assemblies?

The Xamarin.Android Base Class Library assemblies, such as mscorlib.dll, are built within external/mono, using Mono's normal build system:

# This updates external/mono/mcs/class/lib/monodroid/ASSEMBLY.dll
$ make -C external/mono/mcs/class/ASSEMBLY PROFILE=monodroid

Alternatively, if you want to rebuild all the assemblies, the "host" Mono needs to be rebuilt. Note that the name of the "host" directory varies based on the operating system you're building from:

$ make -C build-tools/mono-runtimes/obj/Debug/host-Darwin

Once the assemblies have been rebuilt, they can be copied into the appropriate Xamarin.Android SDK directory by using the _InstallBcl target:

# This updates bin/$(Configuration)/lib/xbuild-frameworks/MonoAndroid/v1.0/ASSEMBLY.dll
$ xbuild build-tools/mono-runtimes/mono-runtimes.mdproj /t:_InstallBcl