2017-02-10 01:14:11 +03:00
< img src = "Documentation/banner.png" alt = "Xamarin.Android banner" height = "145" >
2017-03-30 15:28:44 +03:00
[android-toolchain] Permit zero-configuration builds.
This might be a suspect idea, but lets see if we can make this work.
[The Joel Test: 12 Steps to Better Code][0] outlines 12 steps
to better code. The first two steps are:
1. Do you use source control?
2. Can you make a build in one step?
github is being used for source control, so (1) is handled, but how
simple can we make (2)? How easy can we make it to build
Xamarin.Android upon a fresh checkout?
The ideal to strive for is simple:
Load Xamarin.Android.sln into your IDE and Build the project.
I *know* we're not going to be able to do this, if only because we're
going to be using git submodules, which will require a separate
`git submodule init` invocation [1].
Knowing we can't reach that level of simplicitly doesn't mean we
shouldn't *try* to reach it for all other parts of the build system.
Which brings us to the Android NDK and SDK. The Android NDK will be
required in order to build native code, such as libmonodroid.so, while
the Android SDK will be required in order to compile
Java Callable Wrappers (née Android Callable Wrappers [2]) and
eventual samples and unit tests.
There are three ways we can deal with the Android NDK and SDK:
1. Complicate the "build" process by requiring that developers go to
the Android SDK Download Page [3], download and install
"somewhere" the required bits, and then configure the
Xamarin.Android build to use these bits.
2. Complicate the "build" process by requiring that developers run
the Xamarin Unified Installer [4], let it install everything
required, then configure the Xamarin.Android build to use those
bits.
3. Painstakingly determine which files are actually required, then
automatically download and extract those files into a "well-known"
location known by the Xamarin.Android build process.
(1) and (2) can be infuriating. Let's give (3) a try. :-)
Add a Xamarin.Android.Tools.BootstrapTasks project which contains
MSBuild tasks to facilitate downloading the Android SDK and NDK files.
Add an android-toolchain project which uses
Xamarin.Android.Tools.BootstrapTasks to download a painstakingly
determined set of files and install them "somewhere".
Unfortunately [5] the "somewhere" to download and install these files
needs to be in a known absolute path, so I've arbitrary decided to
download the files into $(HOME)\android-archives and install them into
$(HOME)\android-toolchain. On windows, this is
%HOMEDRIVE%%HOMEPATH%\android-archives and
%HOMEDRIVE%%HOMEPATH%\android-toolchain.
These locations may be modified by creating a
Configuration.Override.props file; see README.md for details.
TL;DR: This setup is able to magically download the Android NDK and
SDK files and install them for later use in a reasonably overridable
location, all within MSBuild.
[0]: http://www.joelonsoftware.com/articles/fog0000000043.html
[1]: Though maybe there's some MSBuild-fu we can use to address that.
[2]: https://developer.xamarin.com/guides/android/advanced_topics/java_integration_overview/android_callable_wrappers/
[3]: http://developer.android.com/sdk/index.html
[4]: https://www.xamarin.com/download
[5]: Because I couldn't find a reliable way to use $(SolutionDir) when
only building a project, and relative paths would require an
in-tree installation location, which might not work.
2016-04-19 03:33:04 +03:00
Xamarin.Android
===============
Xamarin.Android provides open-source bindings of the Android SDK for use with
.NET managed languages such as C#.
2016-04-28 22:14:46 +03:00
[](https://gitter.im/xamarin/xamarin-android?utm_source=badge& utm_medium=badge& utm_campaign=pr-badge& utm_content=badge)
2016-08-09 17:37:47 +03:00
# Build Status
2016-08-01 23:18:48 +03:00
2016-08-09 17:37:47 +03:00
| Platform | Status |
|-----------------------|--------|
| **OSS macOS** | [![OSS macOS x86_64][oss-macOS-x86_64-icon]][oss-macOS-x86_64-status] |
| **OSS Ubuntu** | [![OSS Linux/Ubuntu x86_64][oss-ubuntu-x86_64-icon]][oss-ubuntu-x86_64-status] |
2017-09-08 22:25:46 +03:00
| **OSS Windows** | [![OSS Windows x86_64][oss-windows-x86_64-icon]][oss-windows-x86_64-status] |
2016-08-01 23:18:48 +03:00
2016-08-09 17:37:47 +03:00
[oss-macOS-x86_64-icon]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android/badge/icon
[oss-macOS-x86_64-status]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android/
[oss-ubuntu-x86_64-icon]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-linux/badge/icon
[oss-ubuntu-x86_64-status]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-linux/
2017-09-08 22:25:46 +03:00
[oss-windows-x86_64-icon]: https://devdiv.visualstudio.com/_apis/public/build/definitions/0bdbc590-a062-4c3f-b0f6-9383f67865ee/7212/badge
[oss-windows-x86_64-status]: https://devdiv.visualstudio.com/DevDiv/Default/_build/index?definitionId=7212
2016-08-09 17:37:47 +03:00
# Downloads
| Platform | Status |
|-----------------|--------|
2017-09-11 22:01:11 +03:00
| **Commercial Xamarin.Android 7.3 (d15-2)** for macOS | [![Commercial Xamarin.Android 7.3, macOS][commercial-d15-2-macOS-x86_64-icon]][commercial-d15-2-macOS-x86_64-status] |
| **Commercial Xamarin.Android 7.4 (d15-3)** for macOS | [![Commercial Xamarin.Android 7.4, macOS][commercial-d15-3-macOS-x86_64-icon]][commercial-d15-3-macOS-x86_64-status] |
| **Commercial Xamarin.Android 8.0 (d15-4)** for macOS & Windows+Visual Studio 2017 | [![Commercial Xamarin.Android 8.0, macOS+VS2017][commercial-d15-4-macOS-x86_64-icon]][commercial-d15-4-macOS-x86_64-status] |
| **Commercial Xamarin.Android 8.1 (d15-5)** for macOS & Windows+Visual Studio 2017 | [![Commercial Xamarin.Android 8.1, macOS+VS2017][commercial-d15-5-macOS-x86_64-icon]][commercial-d15-5-macOS-x86_64-status] |
| **Commercial Xamarin.Android 8.1.99 (master)** for macOS & Windows+Visual Studio 2017 | [![Commercial Xamarin.Android 8.1.99, macOS][commercial-master-macOS-x86_64-icon]][commercial-master-macOS-x86_64-status] |
2016-08-09 17:37:47 +03:00
2017-04-04 18:17:16 +03:00
[commercial-d15-2-macOS-x86_64-icon]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-d15-2/badge/icon
[commercial-d15-2-macOS-x86_64-status]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-d15-2/
2017-09-11 22:01:11 +03:00
[commercial-d15-3-macOS-x86_64-icon]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-d15-3/badge/icon
[commercial-d15-3-macOS-x86_64-status]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-d15-3/
[commercial-d15-4-macOS-x86_64-icon]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-d15-4/badge/icon
[commercial-d15-4-macOS-x86_64-status]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-d15-4/
[commercial-d15-5-macOS-x86_64-icon]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-d15-5/badge/icon
[commercial-d15-5-macOS-x86_64-status]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-d15-5/
2016-08-09 17:37:47 +03:00
[commercial-master-macOS-x86_64-icon]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-master/badge/icon
[commercial-master-macOS-x86_64-status]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-master/
2016-04-21 04:45:28 +03:00
# Build Requirements
[android-toolchain] Permit zero-configuration builds.
This might be a suspect idea, but lets see if we can make this work.
[The Joel Test: 12 Steps to Better Code][0] outlines 12 steps
to better code. The first two steps are:
1. Do you use source control?
2. Can you make a build in one step?
github is being used for source control, so (1) is handled, but how
simple can we make (2)? How easy can we make it to build
Xamarin.Android upon a fresh checkout?
The ideal to strive for is simple:
Load Xamarin.Android.sln into your IDE and Build the project.
I *know* we're not going to be able to do this, if only because we're
going to be using git submodules, which will require a separate
`git submodule init` invocation [1].
Knowing we can't reach that level of simplicitly doesn't mean we
shouldn't *try* to reach it for all other parts of the build system.
Which brings us to the Android NDK and SDK. The Android NDK will be
required in order to build native code, such as libmonodroid.so, while
the Android SDK will be required in order to compile
Java Callable Wrappers (née Android Callable Wrappers [2]) and
eventual samples and unit tests.
There are three ways we can deal with the Android NDK and SDK:
1. Complicate the "build" process by requiring that developers go to
the Android SDK Download Page [3], download and install
"somewhere" the required bits, and then configure the
Xamarin.Android build to use these bits.
2. Complicate the "build" process by requiring that developers run
the Xamarin Unified Installer [4], let it install everything
required, then configure the Xamarin.Android build to use those
bits.
3. Painstakingly determine which files are actually required, then
automatically download and extract those files into a "well-known"
location known by the Xamarin.Android build process.
(1) and (2) can be infuriating. Let's give (3) a try. :-)
Add a Xamarin.Android.Tools.BootstrapTasks project which contains
MSBuild tasks to facilitate downloading the Android SDK and NDK files.
Add an android-toolchain project which uses
Xamarin.Android.Tools.BootstrapTasks to download a painstakingly
determined set of files and install them "somewhere".
Unfortunately [5] the "somewhere" to download and install these files
needs to be in a known absolute path, so I've arbitrary decided to
download the files into $(HOME)\android-archives and install them into
$(HOME)\android-toolchain. On windows, this is
%HOMEDRIVE%%HOMEPATH%\android-archives and
%HOMEDRIVE%%HOMEPATH%\android-toolchain.
These locations may be modified by creating a
Configuration.Override.props file; see README.md for details.
TL;DR: This setup is able to magically download the Android NDK and
SDK files and install them for later use in a reasonably overridable
location, all within MSBuild.
[0]: http://www.joelonsoftware.com/articles/fog0000000043.html
[1]: Though maybe there's some MSBuild-fu we can use to address that.
[2]: https://developer.xamarin.com/guides/android/advanced_topics/java_integration_overview/android_callable_wrappers/
[3]: http://developer.android.com/sdk/index.html
[4]: https://www.xamarin.com/download
[5]: Because I couldn't find a reliable way to use $(SolutionDir) when
only building a project, and relative paths would require an
in-tree installation location, which might not work.
2016-04-19 03:33:04 +03:00
2016-04-29 18:09:50 +03:00
Building Xamarin.Android requires:
* [Mono 4.4 or later ](#mono-sdk )
* [The Java Development Kit (JDK) ](#jdk )
* [Autotools (`autoconf`, `automake`, etc.) ](#autotools )
* [The Android SDK and NDK ](#ndk )
2017-08-25 22:21:05 +03:00
The `make prepare` build step (or `PrepareWindows.targets` on Windows) will
check that all required dependencies are present.
If you would like `make prepare` to automatically install
2017-02-16 19:37:28 +03:00
required dependencies, set the `$(AutoProvision)` MSBuild property to True
and (if necessary) set the `$(AutoProvisionUsesSudo)` property to True.
(This is not supported on all operating systems.)
If `$(AutoProvision)` is False (the default) and a dependency is missing,
then the build will fail and an error message will be displayed attempting
to provide install instructions to obtain the missing dependency, e.g.:
error : Could not find required program '7za'. Please run: brew install 'p7zip'.
2016-04-29 18:09:50 +03:00
< a name = "mono-sdk" / >
2017-03-19 02:20:04 +03:00
2016-04-29 18:09:50 +03:00
## Mono MDK
Mono 4.4 or later is required to build on [OS X][osx-mono] and Linux.
(This is because the build system uses the [XmlPeek][xmlpeek] task, which
was first added in Mono 4.4.)
[osx-mono]: http://www.mono-project.com/download/#download-mac
[xmlpeek]: https://msdn.microsoft.com/en-us/library/ff598684.aspx
< a name = "jdk" / >
2017-03-19 02:20:04 +03:00
2016-04-29 18:09:50 +03:00
## Java Development Kit
[android-toolchain] Permit zero-configuration builds.
This might be a suspect idea, but lets see if we can make this work.
[The Joel Test: 12 Steps to Better Code][0] outlines 12 steps
to better code. The first two steps are:
1. Do you use source control?
2. Can you make a build in one step?
github is being used for source control, so (1) is handled, but how
simple can we make (2)? How easy can we make it to build
Xamarin.Android upon a fresh checkout?
The ideal to strive for is simple:
Load Xamarin.Android.sln into your IDE and Build the project.
I *know* we're not going to be able to do this, if only because we're
going to be using git submodules, which will require a separate
`git submodule init` invocation [1].
Knowing we can't reach that level of simplicitly doesn't mean we
shouldn't *try* to reach it for all other parts of the build system.
Which brings us to the Android NDK and SDK. The Android NDK will be
required in order to build native code, such as libmonodroid.so, while
the Android SDK will be required in order to compile
Java Callable Wrappers (née Android Callable Wrappers [2]) and
eventual samples and unit tests.
There are three ways we can deal with the Android NDK and SDK:
1. Complicate the "build" process by requiring that developers go to
the Android SDK Download Page [3], download and install
"somewhere" the required bits, and then configure the
Xamarin.Android build to use these bits.
2. Complicate the "build" process by requiring that developers run
the Xamarin Unified Installer [4], let it install everything
required, then configure the Xamarin.Android build to use those
bits.
3. Painstakingly determine which files are actually required, then
automatically download and extract those files into a "well-known"
location known by the Xamarin.Android build process.
(1) and (2) can be infuriating. Let's give (3) a try. :-)
Add a Xamarin.Android.Tools.BootstrapTasks project which contains
MSBuild tasks to facilitate downloading the Android SDK and NDK files.
Add an android-toolchain project which uses
Xamarin.Android.Tools.BootstrapTasks to download a painstakingly
determined set of files and install them "somewhere".
Unfortunately [5] the "somewhere" to download and install these files
needs to be in a known absolute path, so I've arbitrary decided to
download the files into $(HOME)\android-archives and install them into
$(HOME)\android-toolchain. On windows, this is
%HOMEDRIVE%%HOMEPATH%\android-archives and
%HOMEDRIVE%%HOMEPATH%\android-toolchain.
These locations may be modified by creating a
Configuration.Override.props file; see README.md for details.
TL;DR: This setup is able to magically download the Android NDK and
SDK files and install them for later use in a reasonably overridable
location, all within MSBuild.
[0]: http://www.joelonsoftware.com/articles/fog0000000043.html
[1]: Though maybe there's some MSBuild-fu we can use to address that.
[2]: https://developer.xamarin.com/guides/android/advanced_topics/java_integration_overview/android_callable_wrappers/
[3]: http://developer.android.com/sdk/index.html
[4]: https://www.xamarin.com/download
[5]: Because I couldn't find a reliable way to use $(SolutionDir) when
only building a project, and relative paths would require an
in-tree installation location, which might not work.
2016-04-19 03:33:04 +03:00
The Java Development Kit may be downloaded from the
[Oracle Java SE Downloads page][download-jdk].
[download-jdk]: http://www.oracle.com/technetwork/java/javase/downloads/
2016-04-29 18:09:50 +03:00
< a name = "autotools" / >
2017-03-19 02:20:04 +03:00
2016-04-29 18:09:50 +03:00
## Autotools
Autotools -- including `autoconf` and `automake` -- are required to build
the Mono runtimes.
On OS X, autotools are distributed with [Mono.framework][osx-mono].
2016-12-07 21:26:51 +03:00
If you run into issues regarding `autoconf` or `automake` try to install it with `brew` via:
brew install automake
2016-04-29 18:09:50 +03:00
< a name = "ndk" / >
2017-03-19 02:20:04 +03:00
2016-04-29 18:09:50 +03:00
## Android NDK, SDK
2017-03-19 02:20:04 +03:00
*Note*: A xamarin-android checkout maintains *its own* Android NDK + SDK
to ensure consistent builds and build behavior, permitting reproducible
builds and providing greater flexibility around when we need to perform
Android SDK + NDK updates. The Android SDK and NDK are maintained by default
via two directories in your home directory:
* `$(AndroidToolchainCacheDirectory)` : Where downloaded files are cached.
Defaults to the `$HOME/android-archives` directory.
* `$(AndroidToolchainDirectory)` : Where the Android NDK and SDK are installed.
Defaults to the `$HOME/android-toolchain` directory.
Developers may use these directories for their own use, but *please* **DO NOT**
update or alter the contents of the `$(AndroidToolchainDirectory)` , as that may
prevent the xamarin-android build from working as expected.
[android-toolchain] Permit zero-configuration builds.
This might be a suspect idea, but lets see if we can make this work.
[The Joel Test: 12 Steps to Better Code][0] outlines 12 steps
to better code. The first two steps are:
1. Do you use source control?
2. Can you make a build in one step?
github is being used for source control, so (1) is handled, but how
simple can we make (2)? How easy can we make it to build
Xamarin.Android upon a fresh checkout?
The ideal to strive for is simple:
Load Xamarin.Android.sln into your IDE and Build the project.
I *know* we're not going to be able to do this, if only because we're
going to be using git submodules, which will require a separate
`git submodule init` invocation [1].
Knowing we can't reach that level of simplicitly doesn't mean we
shouldn't *try* to reach it for all other parts of the build system.
Which brings us to the Android NDK and SDK. The Android NDK will be
required in order to build native code, such as libmonodroid.so, while
the Android SDK will be required in order to compile
Java Callable Wrappers (née Android Callable Wrappers [2]) and
eventual samples and unit tests.
There are three ways we can deal with the Android NDK and SDK:
1. Complicate the "build" process by requiring that developers go to
the Android SDK Download Page [3], download and install
"somewhere" the required bits, and then configure the
Xamarin.Android build to use these bits.
2. Complicate the "build" process by requiring that developers run
the Xamarin Unified Installer [4], let it install everything
required, then configure the Xamarin.Android build to use those
bits.
3. Painstakingly determine which files are actually required, then
automatically download and extract those files into a "well-known"
location known by the Xamarin.Android build process.
(1) and (2) can be infuriating. Let's give (3) a try. :-)
Add a Xamarin.Android.Tools.BootstrapTasks project which contains
MSBuild tasks to facilitate downloading the Android SDK and NDK files.
Add an android-toolchain project which uses
Xamarin.Android.Tools.BootstrapTasks to download a painstakingly
determined set of files and install them "somewhere".
Unfortunately [5] the "somewhere" to download and install these files
needs to be in a known absolute path, so I've arbitrary decided to
download the files into $(HOME)\android-archives and install them into
$(HOME)\android-toolchain. On windows, this is
%HOMEDRIVE%%HOMEPATH%\android-archives and
%HOMEDRIVE%%HOMEPATH%\android-toolchain.
These locations may be modified by creating a
Configuration.Override.props file; see README.md for details.
TL;DR: This setup is able to magically download the Android NDK and
SDK files and install them for later use in a reasonably overridable
location, all within MSBuild.
[0]: http://www.joelonsoftware.com/articles/fog0000000043.html
[1]: Though maybe there's some MSBuild-fu we can use to address that.
[2]: https://developer.xamarin.com/guides/android/advanced_topics/java_integration_overview/android_callable_wrappers/
[3]: http://developer.android.com/sdk/index.html
[4]: https://www.xamarin.com/download
[5]: Because I couldn't find a reliable way to use $(SolutionDir) when
only building a project, and relative paths would require an
in-tree installation location, which might not work.
2016-04-19 03:33:04 +03:00
The files that will be downloaded and installed are controlled by
[build-tools/android-toolchain/android-toolchain.projitems][android-toolchain.projitems]
via the `@(AndroidNdkItem)` and `@(AndroidSdkItem)` item groups, and the
URL to download files from is controlled by the `$(AndroidUri)` property.
[android-toolchain.projitems]: build-tools/android-toolchain/android-toolchain.projitems
2017-03-09 23:13:19 +03:00
# Build Configuration
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` ](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:
* `$(AutoProvision)` : Automatically install required dependencies, if possible.
* `$(AutoProvisionUsesSudo)` : Use `sudo` when installing dependencies.
* `$(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) ](http://developer.android.com/about/versions/android-4.0.3.html ).
* `$(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` .
2017-03-19 02:20:04 +03:00
* `$(AndroidSupportedTargetAotAbis)` : The Android ABIs for which to build the
Mono AOT compilers. The AOT compilers are required in order to set the
[`$(AotAssemblies)`][aot-assemblies] app configuration property to True.
[aot-assemblies]: https://developer.xamarin.com/guides/android/under_the_hood/build_process/#AotAssemblies
2017-03-09 23:13:19 +03:00
* `$(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` .
2017-04-17 19:23:44 +03:00
* `$(MonoRequiredMinimumVersion)` : The minimum *system* mono version that is
supported in order to allow a build to continue. Policy is to require a
system mono which corresponds vaguely to the [`external/mono` ](external )
version. This is not strictly required; older mono versions *may* work, they
just are not tested, and thus not guaranteed or supported.
By default this is `4.9.3` .
2017-03-09 23:13:19 +03:00
* `$(MonoSgenBridgeVersion)` : The Mono SGEN Bridge version to support.
Valid values include:
* `4` : Mono 4.6 support.
* `5` : Mono 4.8 and above support. This is the default.
[android-toolchain] Permit zero-configuration builds.
This might be a suspect idea, but lets see if we can make this work.
[The Joel Test: 12 Steps to Better Code][0] outlines 12 steps
to better code. The first two steps are:
1. Do you use source control?
2. Can you make a build in one step?
github is being used for source control, so (1) is handled, but how
simple can we make (2)? How easy can we make it to build
Xamarin.Android upon a fresh checkout?
The ideal to strive for is simple:
Load Xamarin.Android.sln into your IDE and Build the project.
I *know* we're not going to be able to do this, if only because we're
going to be using git submodules, which will require a separate
`git submodule init` invocation [1].
Knowing we can't reach that level of simplicitly doesn't mean we
shouldn't *try* to reach it for all other parts of the build system.
Which brings us to the Android NDK and SDK. The Android NDK will be
required in order to build native code, such as libmonodroid.so, while
the Android SDK will be required in order to compile
Java Callable Wrappers (née Android Callable Wrappers [2]) and
eventual samples and unit tests.
There are three ways we can deal with the Android NDK and SDK:
1. Complicate the "build" process by requiring that developers go to
the Android SDK Download Page [3], download and install
"somewhere" the required bits, and then configure the
Xamarin.Android build to use these bits.
2. Complicate the "build" process by requiring that developers run
the Xamarin Unified Installer [4], let it install everything
required, then configure the Xamarin.Android build to use those
bits.
3. Painstakingly determine which files are actually required, then
automatically download and extract those files into a "well-known"
location known by the Xamarin.Android build process.
(1) and (2) can be infuriating. Let's give (3) a try. :-)
Add a Xamarin.Android.Tools.BootstrapTasks project which contains
MSBuild tasks to facilitate downloading the Android SDK and NDK files.
Add an android-toolchain project which uses
Xamarin.Android.Tools.BootstrapTasks to download a painstakingly
determined set of files and install them "somewhere".
Unfortunately [5] the "somewhere" to download and install these files
needs to be in a known absolute path, so I've arbitrary decided to
download the files into $(HOME)\android-archives and install them into
$(HOME)\android-toolchain. On windows, this is
%HOMEDRIVE%%HOMEPATH%\android-archives and
%HOMEDRIVE%%HOMEPATH%\android-toolchain.
These locations may be modified by creating a
Configuration.Override.props file; see README.md for details.
TL;DR: This setup is able to magically download the Android NDK and
SDK files and install them for later use in a reasonably overridable
location, all within MSBuild.
[0]: http://www.joelonsoftware.com/articles/fog0000000043.html
[1]: Though maybe there's some MSBuild-fu we can use to address that.
[2]: https://developer.xamarin.com/guides/android/advanced_topics/java_integration_overview/android_callable_wrappers/
[3]: http://developer.android.com/sdk/index.html
[4]: https://www.xamarin.com/download
[5]: Because I couldn't find a reliable way to use $(SolutionDir) when
only building a project, and relative paths would require an
in-tree installation location, which might not work.
2016-04-19 03:33:04 +03:00
# Build
2017-08-25 22:21:05 +03:00
Xamarin.Android can be built on Linux, macOS, and Windows.
## Linux and macOS
[android-toolchain] Permit zero-configuration builds.
This might be a suspect idea, but lets see if we can make this work.
[The Joel Test: 12 Steps to Better Code][0] outlines 12 steps
to better code. The first two steps are:
1. Do you use source control?
2. Can you make a build in one step?
github is being used for source control, so (1) is handled, but how
simple can we make (2)? How easy can we make it to build
Xamarin.Android upon a fresh checkout?
The ideal to strive for is simple:
Load Xamarin.Android.sln into your IDE and Build the project.
I *know* we're not going to be able to do this, if only because we're
going to be using git submodules, which will require a separate
`git submodule init` invocation [1].
Knowing we can't reach that level of simplicitly doesn't mean we
shouldn't *try* to reach it for all other parts of the build system.
Which brings us to the Android NDK and SDK. The Android NDK will be
required in order to build native code, such as libmonodroid.so, while
the Android SDK will be required in order to compile
Java Callable Wrappers (née Android Callable Wrappers [2]) and
eventual samples and unit tests.
There are three ways we can deal with the Android NDK and SDK:
1. Complicate the "build" process by requiring that developers go to
the Android SDK Download Page [3], download and install
"somewhere" the required bits, and then configure the
Xamarin.Android build to use these bits.
2. Complicate the "build" process by requiring that developers run
the Xamarin Unified Installer [4], let it install everything
required, then configure the Xamarin.Android build to use those
bits.
3. Painstakingly determine which files are actually required, then
automatically download and extract those files into a "well-known"
location known by the Xamarin.Android build process.
(1) and (2) can be infuriating. Let's give (3) a try. :-)
Add a Xamarin.Android.Tools.BootstrapTasks project which contains
MSBuild tasks to facilitate downloading the Android SDK and NDK files.
Add an android-toolchain project which uses
Xamarin.Android.Tools.BootstrapTasks to download a painstakingly
determined set of files and install them "somewhere".
Unfortunately [5] the "somewhere" to download and install these files
needs to be in a known absolute path, so I've arbitrary decided to
download the files into $(HOME)\android-archives and install them into
$(HOME)\android-toolchain. On windows, this is
%HOMEDRIVE%%HOMEPATH%\android-archives and
%HOMEDRIVE%%HOMEPATH%\android-toolchain.
These locations may be modified by creating a
Configuration.Override.props file; see README.md for details.
TL;DR: This setup is able to magically download the Android NDK and
SDK files and install them for later use in a reasonably overridable
location, all within MSBuild.
[0]: http://www.joelonsoftware.com/articles/fog0000000043.html
[1]: Though maybe there's some MSBuild-fu we can use to address that.
[2]: https://developer.xamarin.com/guides/android/advanced_topics/java_integration_overview/android_callable_wrappers/
[3]: http://developer.android.com/sdk/index.html
[4]: https://www.xamarin.com/download
[5]: Because I couldn't find a reliable way to use $(SolutionDir) when
only building a project, and relative paths would require an
in-tree installation location, which might not work.
2016-04-19 03:33:04 +03:00
2016-04-20 04:30:00 +03:00
To build Xamarin.Android, first prepare the project:
make prepare
This will perform `git submodule update` , and any other pre-build tasks
2016-12-07 21:26:51 +03:00
that need to be performed. After this process is completed, ensure there
is no existing git changes in the `external` folder.
On the main repo, you can use `git status` to ensure a clean slate.
2016-04-20 04:30:00 +03:00
[build] Improve Visual Studio for Mac support (#782)
Context: https://bugzilla.xamarin.com/show_bug.cgi?id=58994
When loading `Xamarin.Android.sln` into Visual Studio for Mac, the
Solution Panel indicates an error on the `Mono.Android` and
`Mono.Android.Export` projects:
Project does not support framework 'MonoAndroid,v1.0'.
Fix this warning by adding `$(ProjectTypeGuids)` to
`Mono.Android.csproj` and `Mono.Android.Export.csproj`.
Additionally, some projects such as
`src/Xamarin.Android.Build.Tasks/Xamarin.Android.Build.Tasks.csproj`
*do not build* within Visual Studio for Mac, because Visual Studio for
Mac doesn't appear to support the use of MSBuild properties within
`<Import/>`s -- at least not *our* property use. Specifically, this:
<Import
Project="$(JavaInteropFullPath)\src\Java.Interop.Tools.TypeNameMappings\Java.Interop.Tools.TypeNameMappings.projitems"
Label="Shared"
Condition="Exists('$(JavaInteropFullPath)\src\Java.Interop.Tools.TypeNameMappings\Java.Interop.Tools.TypeNameMappings.projitems')"
/>
is *completely ignored*, which results in multiple C# compiler errors
as types which are provided by that shared project cannot be found.
Appease Visual Studio for Mac by *removing* use of such properties
within `.csproj` files, and instead hardcoding relative paths.
Unfortunately this kills the idea from commit d205cab2:
> Allow the Java.Interop checkout directory to be specified by
> overriding the `$(JavaInteropSourceDirectory)` MSBuild property.
> ...
> Normally `$(JavaInteropSourceDirectory)` wouldn't need to be
> overridden; the current use case is to allow a CI-like environment
> which grabs the latest commit of every referenced module to make sure
> they all work together. (Note: such a "CI-like environment"
> DOES NOT (yet) EXIST. This commit is to help *permit* such a thing.)
Such a "CI-like environment" still doesn't exist, and is arguably
moot/silly, as Jenkins has an option to
**Update tracking submodules to tip of branch**, which is more-or-
less what was being advocated for here.
Using e.g. `$(JavaInteropFullPath)` -- the value of which was based
off of `$(JavaInteropSourceDirectory)` -- actively prevents
Visual Studio for Mac from building projects, so remove that use.
Finally, Visual Studio for Mac is *still* unable to do a toplevel
Build, even after all of these changes: Visual Studio for Mac doesn't
like `@(ProjectReference)` items which are `Condition`al, and we have
those all over the place (for now).
The changes in this commit *improve*, but **do not** "fix",
Visual Studio for Mac use.
Just build projects individually, with Command+K. :-)
2017-08-25 01:06:01 +03:00
Next, run `make` :
2016-04-20 04:30:00 +03:00
[build] Improve Visual Studio for Mac support (#782)
Context: https://bugzilla.xamarin.com/show_bug.cgi?id=58994
When loading `Xamarin.Android.sln` into Visual Studio for Mac, the
Solution Panel indicates an error on the `Mono.Android` and
`Mono.Android.Export` projects:
Project does not support framework 'MonoAndroid,v1.0'.
Fix this warning by adding `$(ProjectTypeGuids)` to
`Mono.Android.csproj` and `Mono.Android.Export.csproj`.
Additionally, some projects such as
`src/Xamarin.Android.Build.Tasks/Xamarin.Android.Build.Tasks.csproj`
*do not build* within Visual Studio for Mac, because Visual Studio for
Mac doesn't appear to support the use of MSBuild properties within
`<Import/>`s -- at least not *our* property use. Specifically, this:
<Import
Project="$(JavaInteropFullPath)\src\Java.Interop.Tools.TypeNameMappings\Java.Interop.Tools.TypeNameMappings.projitems"
Label="Shared"
Condition="Exists('$(JavaInteropFullPath)\src\Java.Interop.Tools.TypeNameMappings\Java.Interop.Tools.TypeNameMappings.projitems')"
/>
is *completely ignored*, which results in multiple C# compiler errors
as types which are provided by that shared project cannot be found.
Appease Visual Studio for Mac by *removing* use of such properties
within `.csproj` files, and instead hardcoding relative paths.
Unfortunately this kills the idea from commit d205cab2:
> Allow the Java.Interop checkout directory to be specified by
> overriding the `$(JavaInteropSourceDirectory)` MSBuild property.
> ...
> Normally `$(JavaInteropSourceDirectory)` wouldn't need to be
> overridden; the current use case is to allow a CI-like environment
> which grabs the latest commit of every referenced module to make sure
> they all work together. (Note: such a "CI-like environment"
> DOES NOT (yet) EXIST. This commit is to help *permit* such a thing.)
Such a "CI-like environment" still doesn't exist, and is arguably
moot/silly, as Jenkins has an option to
**Update tracking submodules to tip of branch**, which is more-or-
less what was being advocated for here.
Using e.g. `$(JavaInteropFullPath)` -- the value of which was based
off of `$(JavaInteropSourceDirectory)` -- actively prevents
Visual Studio for Mac from building projects, so remove that use.
Finally, Visual Studio for Mac is *still* unable to do a toplevel
Build, even after all of these changes: Visual Studio for Mac doesn't
like `@(ProjectReference)` items which are `Condition`al, and we have
those all over the place (for now).
The changes in this commit *improve*, but **do not** "fix",
Visual Studio for Mac use.
Just build projects individually, with Command+K. :-)
2017-08-25 01:06:01 +03:00
make
2016-04-20 04:30:00 +03:00
[build] Improve Visual Studio for Mac support (#782)
Context: https://bugzilla.xamarin.com/show_bug.cgi?id=58994
When loading `Xamarin.Android.sln` into Visual Studio for Mac, the
Solution Panel indicates an error on the `Mono.Android` and
`Mono.Android.Export` projects:
Project does not support framework 'MonoAndroid,v1.0'.
Fix this warning by adding `$(ProjectTypeGuids)` to
`Mono.Android.csproj` and `Mono.Android.Export.csproj`.
Additionally, some projects such as
`src/Xamarin.Android.Build.Tasks/Xamarin.Android.Build.Tasks.csproj`
*do not build* within Visual Studio for Mac, because Visual Studio for
Mac doesn't appear to support the use of MSBuild properties within
`<Import/>`s -- at least not *our* property use. Specifically, this:
<Import
Project="$(JavaInteropFullPath)\src\Java.Interop.Tools.TypeNameMappings\Java.Interop.Tools.TypeNameMappings.projitems"
Label="Shared"
Condition="Exists('$(JavaInteropFullPath)\src\Java.Interop.Tools.TypeNameMappings\Java.Interop.Tools.TypeNameMappings.projitems')"
/>
is *completely ignored*, which results in multiple C# compiler errors
as types which are provided by that shared project cannot be found.
Appease Visual Studio for Mac by *removing* use of such properties
within `.csproj` files, and instead hardcoding relative paths.
Unfortunately this kills the idea from commit d205cab2:
> Allow the Java.Interop checkout directory to be specified by
> overriding the `$(JavaInteropSourceDirectory)` MSBuild property.
> ...
> Normally `$(JavaInteropSourceDirectory)` wouldn't need to be
> overridden; the current use case is to allow a CI-like environment
> which grabs the latest commit of every referenced module to make sure
> they all work together. (Note: such a "CI-like environment"
> DOES NOT (yet) EXIST. This commit is to help *permit* such a thing.)
Such a "CI-like environment" still doesn't exist, and is arguably
moot/silly, as Jenkins has an option to
**Update tracking submodules to tip of branch**, which is more-or-
less what was being advocated for here.
Using e.g. `$(JavaInteropFullPath)` -- the value of which was based
off of `$(JavaInteropSourceDirectory)` -- actively prevents
Visual Studio for Mac from building projects, so remove that use.
Finally, Visual Studio for Mac is *still* unable to do a toplevel
Build, even after all of these changes: Visual Studio for Mac doesn't
like `@(ProjectReference)` items which are `Condition`al, and we have
those all over the place (for now).
The changes in this commit *improve*, but **do not** "fix",
Visual Studio for Mac use.
Just build projects individually, with Command+K. :-)
2017-08-25 01:06:01 +03:00
The default `make all` target will only build a *subset* of runtime ABIs
and `$(TargetFrameworkVersion)` s. If you want a complete environment --
*all* the ABIs, all the API levels -- then instead use:
2016-04-20 04:30:00 +03:00
[build] Improve Visual Studio for Mac support (#782)
Context: https://bugzilla.xamarin.com/show_bug.cgi?id=58994
When loading `Xamarin.Android.sln` into Visual Studio for Mac, the
Solution Panel indicates an error on the `Mono.Android` and
`Mono.Android.Export` projects:
Project does not support framework 'MonoAndroid,v1.0'.
Fix this warning by adding `$(ProjectTypeGuids)` to
`Mono.Android.csproj` and `Mono.Android.Export.csproj`.
Additionally, some projects such as
`src/Xamarin.Android.Build.Tasks/Xamarin.Android.Build.Tasks.csproj`
*do not build* within Visual Studio for Mac, because Visual Studio for
Mac doesn't appear to support the use of MSBuild properties within
`<Import/>`s -- at least not *our* property use. Specifically, this:
<Import
Project="$(JavaInteropFullPath)\src\Java.Interop.Tools.TypeNameMappings\Java.Interop.Tools.TypeNameMappings.projitems"
Label="Shared"
Condition="Exists('$(JavaInteropFullPath)\src\Java.Interop.Tools.TypeNameMappings\Java.Interop.Tools.TypeNameMappings.projitems')"
/>
is *completely ignored*, which results in multiple C# compiler errors
as types which are provided by that shared project cannot be found.
Appease Visual Studio for Mac by *removing* use of such properties
within `.csproj` files, and instead hardcoding relative paths.
Unfortunately this kills the idea from commit d205cab2:
> Allow the Java.Interop checkout directory to be specified by
> overriding the `$(JavaInteropSourceDirectory)` MSBuild property.
> ...
> Normally `$(JavaInteropSourceDirectory)` wouldn't need to be
> overridden; the current use case is to allow a CI-like environment
> which grabs the latest commit of every referenced module to make sure
> they all work together. (Note: such a "CI-like environment"
> DOES NOT (yet) EXIST. This commit is to help *permit* such a thing.)
Such a "CI-like environment" still doesn't exist, and is arguably
moot/silly, as Jenkins has an option to
**Update tracking submodules to tip of branch**, which is more-or-
less what was being advocated for here.
Using e.g. `$(JavaInteropFullPath)` -- the value of which was based
off of `$(JavaInteropSourceDirectory)` -- actively prevents
Visual Studio for Mac from building projects, so remove that use.
Finally, Visual Studio for Mac is *still* unable to do a toplevel
Build, even after all of these changes: Visual Studio for Mac doesn't
like `@(ProjectReference)` items which are `Condition`al, and we have
those all over the place (for now).
The changes in this commit *improve*, but **do not** "fix",
Visual Studio for Mac use.
Just build projects individually, with Command+K. :-)
2017-08-25 01:06:01 +03:00
make jenkins
2017-09-15 02:45:08 +03:00
Unit tests are built in a separate target:
[build] Improve Visual Studio for Mac support (#782)
Context: https://bugzilla.xamarin.com/show_bug.cgi?id=58994
When loading `Xamarin.Android.sln` into Visual Studio for Mac, the
Solution Panel indicates an error on the `Mono.Android` and
`Mono.Android.Export` projects:
Project does not support framework 'MonoAndroid,v1.0'.
Fix this warning by adding `$(ProjectTypeGuids)` to
`Mono.Android.csproj` and `Mono.Android.Export.csproj`.
Additionally, some projects such as
`src/Xamarin.Android.Build.Tasks/Xamarin.Android.Build.Tasks.csproj`
*do not build* within Visual Studio for Mac, because Visual Studio for
Mac doesn't appear to support the use of MSBuild properties within
`<Import/>`s -- at least not *our* property use. Specifically, this:
<Import
Project="$(JavaInteropFullPath)\src\Java.Interop.Tools.TypeNameMappings\Java.Interop.Tools.TypeNameMappings.projitems"
Label="Shared"
Condition="Exists('$(JavaInteropFullPath)\src\Java.Interop.Tools.TypeNameMappings\Java.Interop.Tools.TypeNameMappings.projitems')"
/>
is *completely ignored*, which results in multiple C# compiler errors
as types which are provided by that shared project cannot be found.
Appease Visual Studio for Mac by *removing* use of such properties
within `.csproj` files, and instead hardcoding relative paths.
Unfortunately this kills the idea from commit d205cab2:
> Allow the Java.Interop checkout directory to be specified by
> overriding the `$(JavaInteropSourceDirectory)` MSBuild property.
> ...
> Normally `$(JavaInteropSourceDirectory)` wouldn't need to be
> overridden; the current use case is to allow a CI-like environment
> which grabs the latest commit of every referenced module to make sure
> they all work together. (Note: such a "CI-like environment"
> DOES NOT (yet) EXIST. This commit is to help *permit* such a thing.)
Such a "CI-like environment" still doesn't exist, and is arguably
moot/silly, as Jenkins has an option to
**Update tracking submodules to tip of branch**, which is more-or-
less what was being advocated for here.
Using e.g. `$(JavaInteropFullPath)` -- the value of which was based
off of `$(JavaInteropSourceDirectory)` -- actively prevents
Visual Studio for Mac from building projects, so remove that use.
Finally, Visual Studio for Mac is *still* unable to do a toplevel
Build, even after all of these changes: Visual Studio for Mac doesn't
like `@(ProjectReference)` items which are `Condition`al, and we have
those all over the place (for now).
The changes in this commit *improve*, but **do not** "fix",
Visual Studio for Mac use.
Just build projects individually, with Command+K. :-)
2017-08-25 01:06:01 +03:00
make all-tests
2016-04-20 04:30:00 +03:00
2017-08-25 22:21:05 +03:00
## Windows
2017-08-26 04:04:52 +03:00
To build Xamarin.Android, ensure you are using MSBuild version 15+ and run:
2017-08-25 22:21:05 +03:00
msbuild build-tools\scripts\PrepareWindows.targets
msbuild Xamarin.Android.sln
These are roughly the same as how `make prepare` and `make` are used on other platforms.
2017-09-15 02:45:08 +03:00
Unit tests are built on Windows via:
msbuild Xamarin.Android-Tests.sln /p:XAIntegratedTests=False
_NOTE: there is not currently an equivalent of `make jenkins` on Windows._
[Mono.Android] Import from monodroid/3e934261
(*Now* things are starting to come together...)
One of the important infrastructural pieces of Xamarin.Android is
Mono.Android.dll, a "binding" for the Android SDK `android.jar` file.
Bindings are generated by using the `generator` tool from
Java.Interop, along with tools/jnienv-gen, and various other programs.
This in turn requires adding a git submodule for Java.Interop.
Stitch all these pieces together so that we can take an
*API description* (stored in Profiles\api-*.xml.in) and generate a
binding for that API description.
The generated files are located in
obj\$(Configuration)\android-$(ApiLevel), and the resulting
Mono.Android.dll is copied to
$(topdir)\bin\$(Configuration)\xbuild-frameworks\MonoAndroid\$(XAFrameworkVersion).
One SNAFU: currently, Mono.Android.csproj conditinally <Import/>s a
Mono.Android.projitems file generated by Java.Interop's generator
tool, which contains a list of all the generated files.
When the project is first loaded, Mono.Android.projitems will not
exist, so on that initial build, source code will be generated but
xbuild won't re-read Mono.Android.projitems (once it exists). This
will result in a failing build.
Simply rebuild the project to get a valid build, or use the `make all`
Makefile target.
2016-04-21 03:50:21 +03:00
2017-08-26 04:04:52 +03:00
_Troubleshooting: Ensure you check your MSBuild version(`msbuild -version`) and path for the proper version of MSBuild._
[mono-runtimes] Build AOT+LLVM cross-compilers (#125)
The commit implements building of LLVM and cross-compilers to support
Xamarin.Android/Mono AOT. LLVM and cross-compilers can be built for
both the host platform (Linux and OS/X at the moment) as well as
cross-compiled for 32-bit and 64-bit Windows platforms.
Windows builds are done with MXE toolchain on OS/X and with the packaged
mingw-w64 toolchain on Linux (tested on Ubuntu 16.04 ONLY).
Also introducing a new set of MSBuild properties that contain information
about the host system. Some of those properties (HostOS, HostCC, HostCXX
for instance) have been moved from Configuration.props to better support
auto-detection. A new script, build-tools/scripts/generate-os-info, is
invoked as part of `make prepare` to generate file that contains the
new properties. The generated file is required for the build to work and
is also host-specific (it mustn't be moved between different machines)
Cross compiler builds require access to a configured Mono build tree, in
order to generate C structure offsets header file that is used by the AOT
compilers to properly generate AOT-ed binaries. Therefore, even if a JIT
target is not enabled in the configuration, enabling a cross-compiler for
some target will configure Mono for that JIT target but it will NOT build
it, to save time. To facilitate this, the _MonoRuntimes items defined in
build-tools/mono-runtimes/mono-runtimes.projitems gain an additional metadata
item called `DoBuild` which will be set to `true` if the runtime actually needs
to be built, as opposed to just configured.
MXE builds are disabled on Linux as mingw-w64 works just fine.
A `make prepare` warning is issued for Linux hosts which have the binfmt_misc
module enabled and either Wine of Mono (cli) registered as PE32/PE32+ binary
interpreters. In such instance building of the Windows cross-compilers will
fail because Autotools determine whether software is being cross compiled by
building a test program and attempting to execute it. In normal circumstances
such an attempt will fail, but with Windows cross-compilation and either Wine
or Mono registered to handle the PE32 executables this attempt will succeed
thus causing the cross compilation detection to fail.
Currently to build cross compilers on Linux you need to generate the C structure
offsets header file on OS/X and copy the resulting headers to appropriate places
on Linux. The header files should be placed in
build-tools/mono-runtimes/obj/Debug/cross-*/
directories. The header files are:
{cross-arm,cross-arm-win}/aarch64-v8a-linux-android.h
{cross-arm64,cross-arm64-win}/armv5-none-linux-androideabi.h
{cross-x86,cross-x86-win}/i686-none-linux-android.h
{cross-x86_64,cross-x86_64-win}/x86_64-none-linux-android.h
Offsets header generation doesn't work on Linux atm because of missing support
for it in the Mono utility used to generate the offsets. Hopefully this limitation
will be removed in the near future and a start-to-end build of everything will be
possible on Linux.
It is now mandatory to run at least `make prepare-props` before Xamarin.Android
can be built. The target generates the OS-specific props file which is required
by the build. `make prepare` depends on the target.
2016-07-26 16:27:31 +03:00
## 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:
2017-03-30 15:28:44 +03:00
echo 0 > /proc/sys/fs/binfmt_misc/status
[mono-runtimes] Build AOT+LLVM cross-compilers (#125)
The commit implements building of LLVM and cross-compilers to support
Xamarin.Android/Mono AOT. LLVM and cross-compilers can be built for
both the host platform (Linux and OS/X at the moment) as well as
cross-compiled for 32-bit and 64-bit Windows platforms.
Windows builds are done with MXE toolchain on OS/X and with the packaged
mingw-w64 toolchain on Linux (tested on Ubuntu 16.04 ONLY).
Also introducing a new set of MSBuild properties that contain information
about the host system. Some of those properties (HostOS, HostCC, HostCXX
for instance) have been moved from Configuration.props to better support
auto-detection. A new script, build-tools/scripts/generate-os-info, is
invoked as part of `make prepare` to generate file that contains the
new properties. The generated file is required for the build to work and
is also host-specific (it mustn't be moved between different machines)
Cross compiler builds require access to a configured Mono build tree, in
order to generate C structure offsets header file that is used by the AOT
compilers to properly generate AOT-ed binaries. Therefore, even if a JIT
target is not enabled in the configuration, enabling a cross-compiler for
some target will configure Mono for that JIT target but it will NOT build
it, to save time. To facilitate this, the _MonoRuntimes items defined in
build-tools/mono-runtimes/mono-runtimes.projitems gain an additional metadata
item called `DoBuild` which will be set to `true` if the runtime actually needs
to be built, as opposed to just configured.
MXE builds are disabled on Linux as mingw-w64 works just fine.
A `make prepare` warning is issued for Linux hosts which have the binfmt_misc
module enabled and either Wine of Mono (cli) registered as PE32/PE32+ binary
interpreters. In such instance building of the Windows cross-compilers will
fail because Autotools determine whether software is being cross compiled by
building a test program and attempting to execute it. In normal circumstances
such an attempt will fail, but with Windows cross-compilation and either Wine
or Mono registered to handle the PE32 executables this attempt will succeed
thus causing the cross compilation detection to fail.
Currently to build cross compilers on Linux you need to generate the C structure
offsets header file on OS/X and copy the resulting headers to appropriate places
on Linux. The header files should be placed in
build-tools/mono-runtimes/obj/Debug/cross-*/
directories. The header files are:
{cross-arm,cross-arm-win}/aarch64-v8a-linux-android.h
{cross-arm64,cross-arm64-win}/armv5-none-linux-androideabi.h
{cross-x86,cross-x86-win}/i686-none-linux-android.h
{cross-x86_64,cross-x86_64-win}/x86_64-none-linux-android.h
Offsets header generation doesn't work on Linux atm because of missing support
for it in the Mono utility used to generate the offsets. Hopefully this limitation
will be removed in the near future and a start-to-end build of everything will be
possible on Linux.
It is now mandatory to run at least `make prepare-props` before Xamarin.Android
can be built. The target generates the OS-specific props file which is required
by the build. `make prepare` depends on the target.
2016-07-26 16:27:31 +03:00
and to enable it again, issue the following command:
2017-03-30 15:28:44 +03:00
echo 1 > /proc/sys/fs/binfmt_misc/status
[mono-runtimes] Build AOT+LLVM cross-compilers (#125)
The commit implements building of LLVM and cross-compilers to support
Xamarin.Android/Mono AOT. LLVM and cross-compilers can be built for
both the host platform (Linux and OS/X at the moment) as well as
cross-compiled for 32-bit and 64-bit Windows platforms.
Windows builds are done with MXE toolchain on OS/X and with the packaged
mingw-w64 toolchain on Linux (tested on Ubuntu 16.04 ONLY).
Also introducing a new set of MSBuild properties that contain information
about the host system. Some of those properties (HostOS, HostCC, HostCXX
for instance) have been moved from Configuration.props to better support
auto-detection. A new script, build-tools/scripts/generate-os-info, is
invoked as part of `make prepare` to generate file that contains the
new properties. The generated file is required for the build to work and
is also host-specific (it mustn't be moved between different machines)
Cross compiler builds require access to a configured Mono build tree, in
order to generate C structure offsets header file that is used by the AOT
compilers to properly generate AOT-ed binaries. Therefore, even if a JIT
target is not enabled in the configuration, enabling a cross-compiler for
some target will configure Mono for that JIT target but it will NOT build
it, to save time. To facilitate this, the _MonoRuntimes items defined in
build-tools/mono-runtimes/mono-runtimes.projitems gain an additional metadata
item called `DoBuild` which will be set to `true` if the runtime actually needs
to be built, as opposed to just configured.
MXE builds are disabled on Linux as mingw-w64 works just fine.
A `make prepare` warning is issued for Linux hosts which have the binfmt_misc
module enabled and either Wine of Mono (cli) registered as PE32/PE32+ binary
interpreters. In such instance building of the Windows cross-compilers will
fail because Autotools determine whether software is being cross compiled by
building a test program and attempting to execute it. In normal circumstances
such an attempt will fail, but with Windows cross-compilation and either Wine
or Mono registered to handle the PE32 executables this attempt will succeed
thus causing the cross compilation detection to fail.
Currently to build cross compilers on Linux you need to generate the C structure
offsets header file on OS/X and copy the resulting headers to appropriate places
on Linux. The header files should be placed in
build-tools/mono-runtimes/obj/Debug/cross-*/
directories. The header files are:
{cross-arm,cross-arm-win}/aarch64-v8a-linux-android.h
{cross-arm64,cross-arm64-win}/armv5-none-linux-androideabi.h
{cross-x86,cross-x86-win}/i686-none-linux-android.h
{cross-x86_64,cross-x86_64-win}/x86_64-none-linux-android.h
Offsets header generation doesn't work on Linux atm because of missing support
for it in the Mono utility used to generate the offsets. Hopefully this limitation
will be removed in the near future and a start-to-end build of everything will be
possible on Linux.
It is now mandatory to run at least `make prepare-props` before Xamarin.Android
can be built. The target generates the OS-specific props file which is required
by the build. `make prepare` depends on the target.
2016-07-26 16:27:31 +03:00
2016-12-07 21:26:51 +03:00
## macOS Build Notes
The [`android-toolchain.projitems` ](build-tools/android-toolchain/android-toolchain.projitems ),
[`libzip.projitems` ](build-tools/libzip/libzip.projitems ), and
[`monodroid.projitems` ](src/monodroid/monodroid.projitems ) project files, among
others, use the `@(RequiredProgram)` build action to check for the existence
of a program within `$PATH` during the build. If a required program doesn't
exist, then the build will fail and a suggested `brew install` command line
will be provided to install the missing commands.
### Brew Programs
Suggested `brew install` commands:
brew install cmake
brew install libtool
brew install p7zip
brew install gdk-pixbuf
brew install gettext
brew install coreutils
brew install findutils
brew install gnu-tar
brew install gnu-sed
brew install gawk
brew install gnutls
brew install gnu-indent
brew install gnu-getopt
brew install intltool
brew install scons
brew install wget
brew install xz
If any program is still not found, try to ensure it's linked via:
brew link < package name >
2017-03-09 23:13:19 +03:00
# Using Your Build
Once the build has finished, [`tools/scripts/xabuild` ](tools/scripts/xabuild )
may be used on Unix-like platforms to build projects.
See the [Samples ](#Samples ) section for example usage.
2017-08-25 22:21:05 +03:00
Windows users will need to use the `setup-windows.exe` tool as described in
[`Documentation/UsingJenkinsBuildArtifacts.md` ](Documentation/UsingJenkinsBuildArtifacts.md#oss-xamarinandroidzip-installation ).
2017-03-09 23:13:19 +03:00
# Using Jenkins Build Artifacts
Please see
[`Documentation/UsingJenkinsBuildArtifacts.md` ](Documentation/UsingJenkinsBuildArtifacts.md )
for details on using prebuilt Xamarin.Android binaries.
2016-04-20 04:30:00 +03:00
# 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:
[structure] Rework installation directory structure (#704)
Context: https://github.com/xamarin/xamarin-android/pull/253#discussion_r82862993
The *intention* is that Jenkins-produced `oss-xamarin.android*.zip`
artifacts be usable on Windows, so that side-by-side testing can be
performed without replacing the system installation. Usage is in
[UsingJenkinsBuildArtifacts.md](Documentation/UsingJenkinsBuildArtifacts).
This isn't *entirely* the case. It was *apparently* the case at the
time of commit 87ca2737, but things have bitrotten since. For
example, following the 87ca2737 instructions would currently result
in an XA0020 `Could not find monodroid` error, because
`class-parse.exe` wasn't where Windows expects it to be (it was in
`lib/mandroid`, not `lib/xbuild/Xamarin/Android`).
This needs to be fixed.
Additionally, PR #253 mentions that, for filesystem organization, it
would be useful if the macOS/Linux directory structure --
`$prefix/bin`, `$prefix/lib/mandroid`,
`$prefix/lib/xbuild/Xamarin/Android`, `$prefix/lib/xbuild-frameworks`
-- more closely resembled the Windows directory structure of
`$MSBuild` and `$ReferenceAssemblies` (as seen in `.vsix` files).
This would turn macOS/Linux into using `$xa_prefix/xbuild` and
`$xa_prefix/xbuild-frameworks` directories.
`$prefix/bin` would only contain `xabuild`. What is currently in
`$prefix/lib/mandroid` would be merged with
`$xa_prefix/xbuild/Xamarin/Android`.
`$xa_prefix` would `$prefix/lib/xamarin.android`.
This would turn the current macOS structure:
$prefix/bin/xabuild
$prefix/bin/generator
$prefix/bin/cross-arm
$prefix/lib/mandroid/generator.exe
$prefix/lib/xbuild-frameworks/MonoAndroid/v1.0/mscorlib.dll
$prefix/lib/xbuild/Xamarin/Android/Xamarin.Android.Common.targets
Into:
$prefix/bin/xabuild
$prefix/lib/xamarin.android/xbuild-frameworks/MonoAndroid/v1.0/mscorlib.dll
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/generator.exe
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/Xamarin.Android.Common.targets
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/Darwin/cross-arm
Other notes:
* The `bundle-*.zip` filename has been has been changed to include a
*hash* of the contents of various files, in particular
`build-tools\mono-runtimes.*`. This was instigated via a
conversation with @kumpera about making the filename more
"idiot-proof": `mono-runtimes.props` contains *compiler flags*,
and if any of those change, then *logically* the bundle should
differ as well, as the mono runtimes may differ in significant
ways. In theory, the `-vXX` version should be used to track this,
but this is a manual change, easy to overlook. The new `-hHASH`
part of the filename should be more automagic.
The new `<HashFileContents/>` task in `xa-prep-tasks.dll` is
responsible for creating the hash value.
* `Configuration.Java.Interop.Override.props` was moved into
`build-tools/scripts`, because that would cleanup the root
directory a bit.
* OS-specific binaries are now placed into
`$prefix/lib/xamarin.android/xbuild/Xamarin/Android/$(HostOS)`.
On a theoretical plus side, this means that the same build
directory can contain OS-specific binaries for multiple operating
systems. (I don't know if anyone shares a build tree between e.g.
macOS and Linux, but if anyone *does*...)
Unfortunately this requires a workaround for an `xbuild` bug:
`%(_LlvmRuntime.InstallPath)` and
`%(_MonoCrossRuntime.InstallPath)` *cannot* use MSBuild
properties, e.g. `<InstallPath>$(HostOS)/</InstallPath>` doesn't
work as desired; it's instead treated literally.
Special-case `%(InstallPath)` until we fully migrate to MSBuild.
* `$(MonoAndroidToolsDirectory)` should be considered *dead*, along
with `$(MonoAndroidBinDirectory)`, as these should now *always*
be the same directory as where `Xamarin.Android.Build.Tasks.dll`
is located, or a `$(HostOS)` sub-directory.
* `Xamarin.ProjectTools.csproj` needed to be updated to ensure that
the build order was correct.
* Remove all `[Obsolete]` and unreferenced members from
`Xamarin.Android.Build.Utilities.dll`. There's too much in there,
and it makes my head hurt trying to understand the
interrelationships between it all. If it's not used, it's gone.
* The changes to `src/monodroid/jni/Android.mk` are...weird. The
removal of `-I$(topdir)/libmonodroid/zip`/etc. is to reduce use of
non-existent paths, as `$(topdir)` isn't defined, so that's
*actually* `-I/libmonodroid/zip`, which is nonsensical. So far,
so good. What's *odd* is the addition of `$(LOCAL_PATH)` to
`$(LOCAL_C_INCLUDES)`: This is needed so that
`external/mono/support/zlib-helper.c` exports `CreateZStream` and
related symbols, otherwise we get a unit test failure in
`GzipStreamTest.Compression` due to an
`EntryPointNotFoundException`, because `CreateZStream` isn't
exported/public.
What's odd here is that I don't understand what caused this
behavior to change. Previous builds exported `CreateZStream`,
otherwise the tests would fail, and I don't understand how any of
the other changes in this PR would be at fault, though that's
certainly the most plausible explanation.
Regardless, `-Ijni` *first* (due to adding `$(LOCAL_PATH)` to
`$(LOCAL_C_INCLUDES)`) is the desired behavior, so that
`jni/config.h` is included, thus ensuring that `MONO_API` has the
required definition when building `zlib-helper.c`.
2017-07-28 16:36:32 +03:00
* `bin\$(Configuration)\lib\xamarin.android\xbuild\Xamarin\Android` : MSBuild-related support
2016-04-20 04:30:00 +03:00
files and required runtimes used by the MSBuild tooling.
[structure] Rework installation directory structure (#704)
Context: https://github.com/xamarin/xamarin-android/pull/253#discussion_r82862993
The *intention* is that Jenkins-produced `oss-xamarin.android*.zip`
artifacts be usable on Windows, so that side-by-side testing can be
performed without replacing the system installation. Usage is in
[UsingJenkinsBuildArtifacts.md](Documentation/UsingJenkinsBuildArtifacts).
This isn't *entirely* the case. It was *apparently* the case at the
time of commit 87ca2737, but things have bitrotten since. For
example, following the 87ca2737 instructions would currently result
in an XA0020 `Could not find monodroid` error, because
`class-parse.exe` wasn't where Windows expects it to be (it was in
`lib/mandroid`, not `lib/xbuild/Xamarin/Android`).
This needs to be fixed.
Additionally, PR #253 mentions that, for filesystem organization, it
would be useful if the macOS/Linux directory structure --
`$prefix/bin`, `$prefix/lib/mandroid`,
`$prefix/lib/xbuild/Xamarin/Android`, `$prefix/lib/xbuild-frameworks`
-- more closely resembled the Windows directory structure of
`$MSBuild` and `$ReferenceAssemblies` (as seen in `.vsix` files).
This would turn macOS/Linux into using `$xa_prefix/xbuild` and
`$xa_prefix/xbuild-frameworks` directories.
`$prefix/bin` would only contain `xabuild`. What is currently in
`$prefix/lib/mandroid` would be merged with
`$xa_prefix/xbuild/Xamarin/Android`.
`$xa_prefix` would `$prefix/lib/xamarin.android`.
This would turn the current macOS structure:
$prefix/bin/xabuild
$prefix/bin/generator
$prefix/bin/cross-arm
$prefix/lib/mandroid/generator.exe
$prefix/lib/xbuild-frameworks/MonoAndroid/v1.0/mscorlib.dll
$prefix/lib/xbuild/Xamarin/Android/Xamarin.Android.Common.targets
Into:
$prefix/bin/xabuild
$prefix/lib/xamarin.android/xbuild-frameworks/MonoAndroid/v1.0/mscorlib.dll
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/generator.exe
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/Xamarin.Android.Common.targets
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/Darwin/cross-arm
Other notes:
* The `bundle-*.zip` filename has been has been changed to include a
*hash* of the contents of various files, in particular
`build-tools\mono-runtimes.*`. This was instigated via a
conversation with @kumpera about making the filename more
"idiot-proof": `mono-runtimes.props` contains *compiler flags*,
and if any of those change, then *logically* the bundle should
differ as well, as the mono runtimes may differ in significant
ways. In theory, the `-vXX` version should be used to track this,
but this is a manual change, easy to overlook. The new `-hHASH`
part of the filename should be more automagic.
The new `<HashFileContents/>` task in `xa-prep-tasks.dll` is
responsible for creating the hash value.
* `Configuration.Java.Interop.Override.props` was moved into
`build-tools/scripts`, because that would cleanup the root
directory a bit.
* OS-specific binaries are now placed into
`$prefix/lib/xamarin.android/xbuild/Xamarin/Android/$(HostOS)`.
On a theoretical plus side, this means that the same build
directory can contain OS-specific binaries for multiple operating
systems. (I don't know if anyone shares a build tree between e.g.
macOS and Linux, but if anyone *does*...)
Unfortunately this requires a workaround for an `xbuild` bug:
`%(_LlvmRuntime.InstallPath)` and
`%(_MonoCrossRuntime.InstallPath)` *cannot* use MSBuild
properties, e.g. `<InstallPath>$(HostOS)/</InstallPath>` doesn't
work as desired; it's instead treated literally.
Special-case `%(InstallPath)` until we fully migrate to MSBuild.
* `$(MonoAndroidToolsDirectory)` should be considered *dead*, along
with `$(MonoAndroidBinDirectory)`, as these should now *always*
be the same directory as where `Xamarin.Android.Build.Tasks.dll`
is located, or a `$(HostOS)` sub-directory.
* `Xamarin.ProjectTools.csproj` needed to be updated to ensure that
the build order was correct.
* Remove all `[Obsolete]` and unreferenced members from
`Xamarin.Android.Build.Utilities.dll`. There's too much in there,
and it makes my head hurt trying to understand the
interrelationships between it all. If it's not used, it's gone.
* The changes to `src/monodroid/jni/Android.mk` are...weird. The
removal of `-I$(topdir)/libmonodroid/zip`/etc. is to reduce use of
non-existent paths, as `$(topdir)` isn't defined, so that's
*actually* `-I/libmonodroid/zip`, which is nonsensical. So far,
so good. What's *odd* is the addition of `$(LOCAL_PATH)` to
`$(LOCAL_C_INCLUDES)`: This is needed so that
`external/mono/support/zlib-helper.c` exports `CreateZStream` and
related symbols, otherwise we get a unit test failure in
`GzipStreamTest.Compression` due to an
`EntryPointNotFoundException`, because `CreateZStream` isn't
exported/public.
What's odd here is that I don't understand what caused this
behavior to change. Previous builds exported `CreateZStream`,
otherwise the tests would fail, and I don't understand how any of
the other changes in this PR would be at fault, though that's
certainly the most plausible explanation.
Regardless, `-Ijni` *first* (due to adding `$(LOCAL_PATH)` to
`$(LOCAL_C_INCLUDES)`) is the desired behavior, so that
`jni/config.h` is included, thus ensuring that `MONO_API` has the
required definition when building `zlib-helper.c`.
2017-07-28 16:36:32 +03:00
* `bin\$(Configuration)\lib\xamarin.android\xbuild-frameworks\MonoAndroid` : Xamarin.Android
[Mono.Android] Import from monodroid/3e934261
(*Now* things are starting to come together...)
One of the important infrastructural pieces of Xamarin.Android is
Mono.Android.dll, a "binding" for the Android SDK `android.jar` file.
Bindings are generated by using the `generator` tool from
Java.Interop, along with tools/jnienv-gen, and various other programs.
This in turn requires adding a git submodule for Java.Interop.
Stitch all these pieces together so that we can take an
*API description* (stored in Profiles\api-*.xml.in) and generate a
binding for that API description.
The generated files are located in
obj\$(Configuration)\android-$(ApiLevel), and the resulting
Mono.Android.dll is copied to
$(topdir)\bin\$(Configuration)\xbuild-frameworks\MonoAndroid\$(XAFrameworkVersion).
One SNAFU: currently, Mono.Android.csproj conditinally <Import/>s a
Mono.Android.projitems file generated by Java.Interop's generator
tool, which contains a list of all the generated files.
When the project is first loaded, Mono.Android.projitems will not
exist, so on that initial build, source code will be generated but
xbuild won't re-read Mono.Android.projitems (once it exists). This
will result in a failing build.
Simply rebuild the project to get a valid build, or use the `make all`
Makefile target.
2016-04-21 03:50:21 +03:00
profiles.
[structure] Rework installation directory structure (#704)
Context: https://github.com/xamarin/xamarin-android/pull/253#discussion_r82862993
The *intention* is that Jenkins-produced `oss-xamarin.android*.zip`
artifacts be usable on Windows, so that side-by-side testing can be
performed without replacing the system installation. Usage is in
[UsingJenkinsBuildArtifacts.md](Documentation/UsingJenkinsBuildArtifacts).
This isn't *entirely* the case. It was *apparently* the case at the
time of commit 87ca2737, but things have bitrotten since. For
example, following the 87ca2737 instructions would currently result
in an XA0020 `Could not find monodroid` error, because
`class-parse.exe` wasn't where Windows expects it to be (it was in
`lib/mandroid`, not `lib/xbuild/Xamarin/Android`).
This needs to be fixed.
Additionally, PR #253 mentions that, for filesystem organization, it
would be useful if the macOS/Linux directory structure --
`$prefix/bin`, `$prefix/lib/mandroid`,
`$prefix/lib/xbuild/Xamarin/Android`, `$prefix/lib/xbuild-frameworks`
-- more closely resembled the Windows directory structure of
`$MSBuild` and `$ReferenceAssemblies` (as seen in `.vsix` files).
This would turn macOS/Linux into using `$xa_prefix/xbuild` and
`$xa_prefix/xbuild-frameworks` directories.
`$prefix/bin` would only contain `xabuild`. What is currently in
`$prefix/lib/mandroid` would be merged with
`$xa_prefix/xbuild/Xamarin/Android`.
`$xa_prefix` would `$prefix/lib/xamarin.android`.
This would turn the current macOS structure:
$prefix/bin/xabuild
$prefix/bin/generator
$prefix/bin/cross-arm
$prefix/lib/mandroid/generator.exe
$prefix/lib/xbuild-frameworks/MonoAndroid/v1.0/mscorlib.dll
$prefix/lib/xbuild/Xamarin/Android/Xamarin.Android.Common.targets
Into:
$prefix/bin/xabuild
$prefix/lib/xamarin.android/xbuild-frameworks/MonoAndroid/v1.0/mscorlib.dll
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/generator.exe
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/Xamarin.Android.Common.targets
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/Darwin/cross-arm
Other notes:
* The `bundle-*.zip` filename has been has been changed to include a
*hash* of the contents of various files, in particular
`build-tools\mono-runtimes.*`. This was instigated via a
conversation with @kumpera about making the filename more
"idiot-proof": `mono-runtimes.props` contains *compiler flags*,
and if any of those change, then *logically* the bundle should
differ as well, as the mono runtimes may differ in significant
ways. In theory, the `-vXX` version should be used to track this,
but this is a manual change, easy to overlook. The new `-hHASH`
part of the filename should be more automagic.
The new `<HashFileContents/>` task in `xa-prep-tasks.dll` is
responsible for creating the hash value.
* `Configuration.Java.Interop.Override.props` was moved into
`build-tools/scripts`, because that would cleanup the root
directory a bit.
* OS-specific binaries are now placed into
`$prefix/lib/xamarin.android/xbuild/Xamarin/Android/$(HostOS)`.
On a theoretical plus side, this means that the same build
directory can contain OS-specific binaries for multiple operating
systems. (I don't know if anyone shares a build tree between e.g.
macOS and Linux, but if anyone *does*...)
Unfortunately this requires a workaround for an `xbuild` bug:
`%(_LlvmRuntime.InstallPath)` and
`%(_MonoCrossRuntime.InstallPath)` *cannot* use MSBuild
properties, e.g. `<InstallPath>$(HostOS)/</InstallPath>` doesn't
work as desired; it's instead treated literally.
Special-case `%(InstallPath)` until we fully migrate to MSBuild.
* `$(MonoAndroidToolsDirectory)` should be considered *dead*, along
with `$(MonoAndroidBinDirectory)`, as these should now *always*
be the same directory as where `Xamarin.Android.Build.Tasks.dll`
is located, or a `$(HostOS)` sub-directory.
* `Xamarin.ProjectTools.csproj` needed to be updated to ensure that
the build order was correct.
* Remove all `[Obsolete]` and unreferenced members from
`Xamarin.Android.Build.Utilities.dll`. There's too much in there,
and it makes my head hurt trying to understand the
interrelationships between it all. If it's not used, it's gone.
* The changes to `src/monodroid/jni/Android.mk` are...weird. The
removal of `-I$(topdir)/libmonodroid/zip`/etc. is to reduce use of
non-existent paths, as `$(topdir)` isn't defined, so that's
*actually* `-I/libmonodroid/zip`, which is nonsensical. So far,
so good. What's *odd* is the addition of `$(LOCAL_PATH)` to
`$(LOCAL_C_INCLUDES)`: This is needed so that
`external/mono/support/zlib-helper.c` exports `CreateZStream` and
related symbols, otherwise we get a unit test failure in
`GzipStreamTest.Compression` due to an
`EntryPointNotFoundException`, because `CreateZStream` isn't
exported/public.
What's odd here is that I don't understand what caused this
behavior to change. Previous builds exported `CreateZStream`,
otherwise the tests would fail, and I don't understand how any of
the other changes in this PR would be at fault, though that's
certainly the most plausible explanation.
Regardless, `-Ijni` *first* (due to adding `$(LOCAL_PATH)` to
`$(LOCAL_C_INCLUDES)`) is the desired behavior, so that
`jni/config.h` is included, thus ensuring that `MONO_API` has the
required definition when building `zlib-helper.c`.
2017-07-28 16:36:32 +03:00
* `bin\$(Configuration)\lib\xamarin.android\xbuild-frameworks\MonoAndroid\v1.0` : Xamarin.Android
[Mono.Android] Import from monodroid/3e934261
(*Now* things are starting to come together...)
One of the important infrastructural pieces of Xamarin.Android is
Mono.Android.dll, a "binding" for the Android SDK `android.jar` file.
Bindings are generated by using the `generator` tool from
Java.Interop, along with tools/jnienv-gen, and various other programs.
This in turn requires adding a git submodule for Java.Interop.
Stitch all these pieces together so that we can take an
*API description* (stored in Profiles\api-*.xml.in) and generate a
binding for that API description.
The generated files are located in
obj\$(Configuration)\android-$(ApiLevel), and the resulting
Mono.Android.dll is copied to
$(topdir)\bin\$(Configuration)\xbuild-frameworks\MonoAndroid\$(XAFrameworkVersion).
One SNAFU: currently, Mono.Android.csproj conditinally <Import/>s a
Mono.Android.projitems file generated by Java.Interop's generator
tool, which contains a list of all the generated files.
When the project is first loaded, Mono.Android.projitems will not
exist, so on that initial build, source code will be generated but
xbuild won't re-read Mono.Android.projitems (once it exists). This
will result in a failing build.
Simply rebuild the project to get a valid build, or use the `make all`
Makefile target.
2016-04-21 03:50:21 +03:00
Base Class Library assemblies such as `mscorlib.dll` .
[structure] Rework installation directory structure (#704)
Context: https://github.com/xamarin/xamarin-android/pull/253#discussion_r82862993
The *intention* is that Jenkins-produced `oss-xamarin.android*.zip`
artifacts be usable on Windows, so that side-by-side testing can be
performed without replacing the system installation. Usage is in
[UsingJenkinsBuildArtifacts.md](Documentation/UsingJenkinsBuildArtifacts).
This isn't *entirely* the case. It was *apparently* the case at the
time of commit 87ca2737, but things have bitrotten since. For
example, following the 87ca2737 instructions would currently result
in an XA0020 `Could not find monodroid` error, because
`class-parse.exe` wasn't where Windows expects it to be (it was in
`lib/mandroid`, not `lib/xbuild/Xamarin/Android`).
This needs to be fixed.
Additionally, PR #253 mentions that, for filesystem organization, it
would be useful if the macOS/Linux directory structure --
`$prefix/bin`, `$prefix/lib/mandroid`,
`$prefix/lib/xbuild/Xamarin/Android`, `$prefix/lib/xbuild-frameworks`
-- more closely resembled the Windows directory structure of
`$MSBuild` and `$ReferenceAssemblies` (as seen in `.vsix` files).
This would turn macOS/Linux into using `$xa_prefix/xbuild` and
`$xa_prefix/xbuild-frameworks` directories.
`$prefix/bin` would only contain `xabuild`. What is currently in
`$prefix/lib/mandroid` would be merged with
`$xa_prefix/xbuild/Xamarin/Android`.
`$xa_prefix` would `$prefix/lib/xamarin.android`.
This would turn the current macOS structure:
$prefix/bin/xabuild
$prefix/bin/generator
$prefix/bin/cross-arm
$prefix/lib/mandroid/generator.exe
$prefix/lib/xbuild-frameworks/MonoAndroid/v1.0/mscorlib.dll
$prefix/lib/xbuild/Xamarin/Android/Xamarin.Android.Common.targets
Into:
$prefix/bin/xabuild
$prefix/lib/xamarin.android/xbuild-frameworks/MonoAndroid/v1.0/mscorlib.dll
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/generator.exe
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/Xamarin.Android.Common.targets
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/Darwin/cross-arm
Other notes:
* The `bundle-*.zip` filename has been has been changed to include a
*hash* of the contents of various files, in particular
`build-tools\mono-runtimes.*`. This was instigated via a
conversation with @kumpera about making the filename more
"idiot-proof": `mono-runtimes.props` contains *compiler flags*,
and if any of those change, then *logically* the bundle should
differ as well, as the mono runtimes may differ in significant
ways. In theory, the `-vXX` version should be used to track this,
but this is a manual change, easy to overlook. The new `-hHASH`
part of the filename should be more automagic.
The new `<HashFileContents/>` task in `xa-prep-tasks.dll` is
responsible for creating the hash value.
* `Configuration.Java.Interop.Override.props` was moved into
`build-tools/scripts`, because that would cleanup the root
directory a bit.
* OS-specific binaries are now placed into
`$prefix/lib/xamarin.android/xbuild/Xamarin/Android/$(HostOS)`.
On a theoretical plus side, this means that the same build
directory can contain OS-specific binaries for multiple operating
systems. (I don't know if anyone shares a build tree between e.g.
macOS and Linux, but if anyone *does*...)
Unfortunately this requires a workaround for an `xbuild` bug:
`%(_LlvmRuntime.InstallPath)` and
`%(_MonoCrossRuntime.InstallPath)` *cannot* use MSBuild
properties, e.g. `<InstallPath>$(HostOS)/</InstallPath>` doesn't
work as desired; it's instead treated literally.
Special-case `%(InstallPath)` until we fully migrate to MSBuild.
* `$(MonoAndroidToolsDirectory)` should be considered *dead*, along
with `$(MonoAndroidBinDirectory)`, as these should now *always*
be the same directory as where `Xamarin.Android.Build.Tasks.dll`
is located, or a `$(HostOS)` sub-directory.
* `Xamarin.ProjectTools.csproj` needed to be updated to ensure that
the build order was correct.
* Remove all `[Obsolete]` and unreferenced members from
`Xamarin.Android.Build.Utilities.dll`. There's too much in there,
and it makes my head hurt trying to understand the
interrelationships between it all. If it's not used, it's gone.
* The changes to `src/monodroid/jni/Android.mk` are...weird. The
removal of `-I$(topdir)/libmonodroid/zip`/etc. is to reduce use of
non-existent paths, as `$(topdir)` isn't defined, so that's
*actually* `-I/libmonodroid/zip`, which is nonsensical. So far,
so good. What's *odd* is the addition of `$(LOCAL_PATH)` to
`$(LOCAL_C_INCLUDES)`: This is needed so that
`external/mono/support/zlib-helper.c` exports `CreateZStream` and
related symbols, otherwise we get a unit test failure in
`GzipStreamTest.Compression` due to an
`EntryPointNotFoundException`, because `CreateZStream` isn't
exported/public.
What's odd here is that I don't understand what caused this
behavior to change. Previous builds exported `CreateZStream`,
otherwise the tests would fail, and I don't understand how any of
the other changes in this PR would be at fault, though that's
certainly the most plausible explanation.
Regardless, `-Ijni` *first* (due to adding `$(LOCAL_PATH)` to
`$(LOCAL_C_INCLUDES)`) is the desired behavior, so that
`jni/config.h` is included, thus ensuring that `MONO_API` has the
required definition when building `zlib-helper.c`.
2017-07-28 16:36:32 +03:00
* `bin\$(Configuration)\lib\xamarin.android\xbuild-frameworks\MonoAndroid\*` : Contains
[Mono.Android] Import from monodroid/3e934261
(*Now* things are starting to come together...)
One of the important infrastructural pieces of Xamarin.Android is
Mono.Android.dll, a "binding" for the Android SDK `android.jar` file.
Bindings are generated by using the `generator` tool from
Java.Interop, along with tools/jnienv-gen, and various other programs.
This in turn requires adding a git submodule for Java.Interop.
Stitch all these pieces together so that we can take an
*API description* (stored in Profiles\api-*.xml.in) and generate a
binding for that API description.
The generated files are located in
obj\$(Configuration)\android-$(ApiLevel), and the resulting
Mono.Android.dll is copied to
$(topdir)\bin\$(Configuration)\xbuild-frameworks\MonoAndroid\$(XAFrameworkVersion).
One SNAFU: currently, Mono.Android.csproj conditinally <Import/>s a
Mono.Android.projitems file generated by Java.Interop's generator
tool, which contains a list of all the generated files.
When the project is first loaded, Mono.Android.projitems will not
exist, so on that initial build, source code will be generated but
xbuild won't re-read Mono.Android.projitems (once it exists). This
will result in a failing build.
Simply rebuild the project to get a valid build, or use the `make all`
Makefile target.
2016-04-21 03:50:21 +03:00
`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` .
2016-04-21 21:32:11 +03:00
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)` .
[Mono.Android] Import from monodroid/3e934261
(*Now* things are starting to come together...)
One of the important infrastructural pieces of Xamarin.Android is
Mono.Android.dll, a "binding" for the Android SDK `android.jar` file.
Bindings are generated by using the `generator` tool from
Java.Interop, along with tools/jnienv-gen, and various other programs.
This in turn requires adding a git submodule for Java.Interop.
Stitch all these pieces together so that we can take an
*API description* (stored in Profiles\api-*.xml.in) and generate a
binding for that API description.
The generated files are located in
obj\$(Configuration)\android-$(ApiLevel), and the resulting
Mono.Android.dll is copied to
$(topdir)\bin\$(Configuration)\xbuild-frameworks\MonoAndroid\$(XAFrameworkVersion).
One SNAFU: currently, Mono.Android.csproj conditinally <Import/>s a
Mono.Android.projitems file generated by Java.Interop's generator
tool, which contains a list of all the generated files.
When the project is first loaded, Mono.Android.projitems will not
exist, so on that initial build, source code will be generated but
xbuild won't re-read Mono.Android.projitems (once it exists). This
will result in a failing build.
Simply rebuild the project to get a valid build, or use the `make all`
Makefile target.
2016-04-21 03:50:21 +03:00
2017-03-09 23:13:19 +03:00
The default values will target Android API-25, Android 7.1.
[Mono.Android] Import from monodroid/3e934261
(*Now* things are starting to come together...)
One of the important infrastructural pieces of Xamarin.Android is
Mono.Android.dll, a "binding" for the Android SDK `android.jar` file.
Bindings are generated by using the `generator` tool from
Java.Interop, along with tools/jnienv-gen, and various other programs.
This in turn requires adding a git submodule for Java.Interop.
Stitch all these pieces together so that we can take an
*API description* (stored in Profiles\api-*.xml.in) and generate a
binding for that API description.
The generated files are located in
obj\$(Configuration)\android-$(ApiLevel), and the resulting
Mono.Android.dll is copied to
$(topdir)\bin\$(Configuration)\xbuild-frameworks\MonoAndroid\$(XAFrameworkVersion).
One SNAFU: currently, Mono.Android.csproj conditinally <Import/>s a
Mono.Android.projitems file generated by Java.Interop's generator
tool, which contains a list of all the generated files.
When the project is first loaded, Mono.Android.projitems will not
exist, so on that initial build, source code will be generated but
xbuild won't re-read Mono.Android.projitems (once it exists). This
will result in a failing build.
Simply rebuild the project to get a valid build, or use the `make all`
Makefile target.
2016-04-21 03:50:21 +03:00
For example, to generate `Mono.Android.dll` for API-19 (Android 4.4):
cd src/Mono.Android
2016-04-21 21:32:11 +03:00
xbuild /p:AndroidApiLevel=19 /p:AndroidFrameworkVersion=v4.4
[structure] Rework installation directory structure (#704)
Context: https://github.com/xamarin/xamarin-android/pull/253#discussion_r82862993
The *intention* is that Jenkins-produced `oss-xamarin.android*.zip`
artifacts be usable on Windows, so that side-by-side testing can be
performed without replacing the system installation. Usage is in
[UsingJenkinsBuildArtifacts.md](Documentation/UsingJenkinsBuildArtifacts).
This isn't *entirely* the case. It was *apparently* the case at the
time of commit 87ca2737, but things have bitrotten since. For
example, following the 87ca2737 instructions would currently result
in an XA0020 `Could not find monodroid` error, because
`class-parse.exe` wasn't where Windows expects it to be (it was in
`lib/mandroid`, not `lib/xbuild/Xamarin/Android`).
This needs to be fixed.
Additionally, PR #253 mentions that, for filesystem organization, it
would be useful if the macOS/Linux directory structure --
`$prefix/bin`, `$prefix/lib/mandroid`,
`$prefix/lib/xbuild/Xamarin/Android`, `$prefix/lib/xbuild-frameworks`
-- more closely resembled the Windows directory structure of
`$MSBuild` and `$ReferenceAssemblies` (as seen in `.vsix` files).
This would turn macOS/Linux into using `$xa_prefix/xbuild` and
`$xa_prefix/xbuild-frameworks` directories.
`$prefix/bin` would only contain `xabuild`. What is currently in
`$prefix/lib/mandroid` would be merged with
`$xa_prefix/xbuild/Xamarin/Android`.
`$xa_prefix` would `$prefix/lib/xamarin.android`.
This would turn the current macOS structure:
$prefix/bin/xabuild
$prefix/bin/generator
$prefix/bin/cross-arm
$prefix/lib/mandroid/generator.exe
$prefix/lib/xbuild-frameworks/MonoAndroid/v1.0/mscorlib.dll
$prefix/lib/xbuild/Xamarin/Android/Xamarin.Android.Common.targets
Into:
$prefix/bin/xabuild
$prefix/lib/xamarin.android/xbuild-frameworks/MonoAndroid/v1.0/mscorlib.dll
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/generator.exe
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/Xamarin.Android.Common.targets
$prefix/lib/xamarin.android/xbuild/Xamarin/Android/Darwin/cross-arm
Other notes:
* The `bundle-*.zip` filename has been has been changed to include a
*hash* of the contents of various files, in particular
`build-tools\mono-runtimes.*`. This was instigated via a
conversation with @kumpera about making the filename more
"idiot-proof": `mono-runtimes.props` contains *compiler flags*,
and if any of those change, then *logically* the bundle should
differ as well, as the mono runtimes may differ in significant
ways. In theory, the `-vXX` version should be used to track this,
but this is a manual change, easy to overlook. The new `-hHASH`
part of the filename should be more automagic.
The new `<HashFileContents/>` task in `xa-prep-tasks.dll` is
responsible for creating the hash value.
* `Configuration.Java.Interop.Override.props` was moved into
`build-tools/scripts`, because that would cleanup the root
directory a bit.
* OS-specific binaries are now placed into
`$prefix/lib/xamarin.android/xbuild/Xamarin/Android/$(HostOS)`.
On a theoretical plus side, this means that the same build
directory can contain OS-specific binaries for multiple operating
systems. (I don't know if anyone shares a build tree between e.g.
macOS and Linux, but if anyone *does*...)
Unfortunately this requires a workaround for an `xbuild` bug:
`%(_LlvmRuntime.InstallPath)` and
`%(_MonoCrossRuntime.InstallPath)` *cannot* use MSBuild
properties, e.g. `<InstallPath>$(HostOS)/</InstallPath>` doesn't
work as desired; it's instead treated literally.
Special-case `%(InstallPath)` until we fully migrate to MSBuild.
* `$(MonoAndroidToolsDirectory)` should be considered *dead*, along
with `$(MonoAndroidBinDirectory)`, as these should now *always*
be the same directory as where `Xamarin.Android.Build.Tasks.dll`
is located, or a `$(HostOS)` sub-directory.
* `Xamarin.ProjectTools.csproj` needed to be updated to ensure that
the build order was correct.
* Remove all `[Obsolete]` and unreferenced members from
`Xamarin.Android.Build.Utilities.dll`. There's too much in there,
and it makes my head hurt trying to understand the
interrelationships between it all. If it's not used, it's gone.
* The changes to `src/monodroid/jni/Android.mk` are...weird. The
removal of `-I$(topdir)/libmonodroid/zip`/etc. is to reduce use of
non-existent paths, as `$(topdir)` isn't defined, so that's
*actually* `-I/libmonodroid/zip`, which is nonsensical. So far,
so good. What's *odd* is the addition of `$(LOCAL_PATH)` to
`$(LOCAL_C_INCLUDES)`: This is needed so that
`external/mono/support/zlib-helper.c` exports `CreateZStream` and
related symbols, otherwise we get a unit test failure in
`GzipStreamTest.Compression` due to an
`EntryPointNotFoundException`, because `CreateZStream` isn't
exported/public.
What's odd here is that I don't understand what caused this
behavior to change. Previous builds exported `CreateZStream`,
otherwise the tests would fail, and I don't understand how any of
the other changes in this PR would be at fault, though that's
certainly the most plausible explanation.
Regardless, `-Ijni` *first* (due to adding `$(LOCAL_PATH)` to
`$(LOCAL_C_INCLUDES)`) is the desired behavior, so that
`jni/config.h` is included, thus ensuring that `MONO_API` has the
required definition when building `zlib-helper.c`.
2017-07-28 16:36:32 +03:00
# creates bin\Debug\lib\xamarin.android\xbuild-frameworks\MonoAndroid\v4.4\Mono.Android.dll
2016-04-28 18:15:08 +03:00
2017-03-09 23:13:19 +03:00
< a name = "Samples" / >
2017-03-19 02:20:04 +03:00
2016-05-04 21:40:41 +03:00
# Samples
2016-04-28 18:15:08 +03:00
2016-05-04 21:40:41 +03:00
The [HelloWorld ](samples/HelloWorld ) sample may be built with the
[xabuild ](tools/scripts/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`][adb-commands]
command:
[adb-commands]: http://developer.android.com/tools/help/adb.html#commandsummary
$ 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
2017-02-01 21:59:51 +03:00
This project has adopted the code of conduct defined by the Contributor Covenant
to clarify expected behavior in our community. For more information, see the
[.NET Foundation Code of Conduct ](http://www.dotnetfoundation.org/code-of-conduct ).
2016-05-04 21:40:41 +03:00
## Mailing Lists
2016-04-28 18:15:08 +03:00
2016-04-28 18:16:44 +03:00
To discuss this project, and participate in the design, we use the [android-devel@lists.xamarin.com ](http://lists.xamarin.com/mailman/listinfo/android-devel ) mailing list.
2016-04-28 18:15:08 +03:00
2016-05-04 21:40:41 +03:00
## Coding Guidelines
2016-04-28 18:15:08 +03:00
We use [Mono's Coding Guidelines ](http://www.mono-project.com/community/contributing/coding-guidelines/ ).
2016-05-04 21:40:41 +03:00
## Reporting Bugs
2016-04-28 18:15:08 +03:00
2016-04-28 22:14:46 +03:00
We use [Bugzilla ](https://bugzilla.xamarin.com/enter_bug.cgi?product=Android ) to track issues.
2016-04-28 18:15:08 +03:00
2016-08-14 00:40:37 +03:00
# Maintainer FAQ
[tests] Run .apk unit tests and collect TestResults.xml (#305)
What do we want? Execution of unit tests!
When do we want it? Uh...4 months ago?
The `Xamarin.Android.NUnitLite` assembly allows writing NUnit-based
unit tests that execute on-device, and the `Mono.Android-Tests.csproj`
project contains a number of such unit tests.
The problem is that these unit tests aren't executed as part of the
Jenkins build process, so there's no way to know if a given commit
actually breaks anything.
In short, the existence of those unit tests is meaningless.
The task, then, is to fix the `make run-all-tests` target so that it
runs on-device unit tests...on an Android device.
Which raises all manner of problems. :-) (Hence 4+ months!)
For starters, our internal tooling is a horrible mish-mash of make(1),
ruby(1), bash(1), which creates an emulator, launches it, installs the
test .apk onto the emulator, and runs the tests. I don't want all of
that "cruft" in this repo, which means it needs to be rewritten in a
form more amenable to this repo: MSBuild tasks....and some make(1).
:-)
Add a new `build-tools/scripts/UnitTestApks.targets` file, which will
process an `@(UnitTestApk)` Item Group to permit deploying, running,
and undeploying test .apks from an attached Android device.
Add a slew of MSBuild tasks to support `@(UnitTestApk)`.
Update the default `$(AndroidSupportedTargetJitAbis)` value to be
`armeabi-v7a:x86`. The created Android emulator is x86.
2016-11-21 23:44:37 +03:00
See [DevelopmentTips.md ](Documentation/DevelopmentTips.md ).
