2022-10-26 23:03:48 +03:00
< img src = "Documentation/images/banner.png" alt = ".NET Android banner" height = "145" >
2017-03-30 15:28:44 +03:00
2022-10-26 23:03:48 +03:00
.NET Android
[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
===============
2022-10-26 23:03:48 +03:00
.NET Android provides open-source bindings of the Android SDK and tooling for use with
.NET managed languages such as C#. This ships as an optional [.NET workload][net-workload] for .NET 6+ that can
be updated independently from .NET in order to respond to external dependency updates like new Android
platform and tooling.
While .NET Android is an essential part of [MAUI][maui-intro], it is still fully supported to be
used independently for native Android development using .NET.
This repository is also home to the classic Xamarin.Android product.
[net-workload]: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-workload-install
[maui-intro]: https://learn.microsoft.com/en-us/dotnet/maui/what-is-maui
# Support
.NET Android is now part of .NET 6+ and follows the same support lifecycle as the [MAUI Support Lifecycle][maui-support-lifecycle].
Support for classic Xamarin.Android will end on **May 1, 2024** as per the [Xamarin Support Policy][xamarin-support-policy]:
> Xamarin support will end on May 1, 2024 for all classic Xamarin SDKs. Android 13 will be the final version classic Xamarin.Android will target.
[maui-support-lifecycle]: https://dotnet.microsoft.com/en-us/platform/support/policy/maui
[xamarin-support-policy]: https://dotnet.microsoft.com/en-us/platform/support/policy/xamarin
[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-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] |
2020-12-02 18:02:06 +03:00
2021-12-02 21:24:08 +03:00
[oss-macOS-x86_64-icon]: https://dev.azure.com/xamarin/public/_apis/build/status/xamarin/xamarin-android/Xamarin.Android-OSS?branchName=main& stageName=Mac
[oss-macOS-x86_64-status]: https://dev.azure.com/xamarin/public/_build/latest?definitionId=48& branchName=main& stageName=Mac
[oss-ubuntu-x86_64-icon]: https://dev.azure.com/xamarin/public/_apis/build/status/xamarin/xamarin-android/Xamarin.Android-OSS?branchName=main& stageName=Linux
[oss-ubuntu-x86_64-status]: https://dev.azure.com/xamarin/public/_build/latest?definitionId=48& branchName=main& stageName=Linux
2016-08-09 17:37:47 +03:00
# Downloads
2020-04-17 03:01:27 +03:00
## Current
2022-10-26 23:03:48 +03:00
.NET Android ships as a workload through the `dotnet` workload system in [.NET 6+][dotnet-download]. See
2022-09-26 22:57:11 +03:00
the [workload documentation][workload-documentation] for installation commands.
[dotnet-download]: https://dotnet.microsoft.com/en-us/download
[workload-documentation]: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-workload-install
2022-10-26 23:03:48 +03:00
Classic Xamarin.Android installers are available here:
2022-09-26 22:57:11 +03:00
2020-04-17 03:01:27 +03:00
| Platform | Link |
2016-08-09 17:37:47 +03:00
|-----------------|--------|
2022-11-09 18:50:20 +03:00
| **Commercial Xamarin.Android 13.1 (d17-4)** for Windows+Visual Studio 2022 | [Download][commercial-d17-4-Windows-x86_64] |
| **Commercial Xamarin.Android 13.1 (d17-4)** for macOS | [Download][commercial-d17-4-macOS-x86_64] |
2022-08-11 23:07:57 +03:00
| **OSS Xamarin.Android (main)** for Ubuntu\* | [![OSS Linux/Ubuntu x86_64][oss-ubuntu-x86_64-icon]][oss-ubuntu-x86_64-status] |
2019-06-21 04:39:02 +03:00
*\* Please note that the OSS installer packages are not digitally signed.*
2018-03-03 19:50:20 +03:00
2022-08-11 23:07:57 +03:00
[Previous Releases ](Documentation/previous-releases.md ) are also available for download.
2020-04-17 03:01:27 +03:00
2022-11-09 18:50:20 +03:00
[commercial-d17-4-Windows-x86_64]: https://aka.ms/xamarin-android-commercial-d17-4-windows
[commercial-d17-4-macOS-x86_64]: https://aka.ms/xamarin-android-commercial-d17-4-macos
[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
2018-03-03 19:50:20 +03:00
# Contributing
2016-05-04 21:40:41 +03:00
2018-03-03 19:50:20 +03:00
If you are interested in fixing issues and contributing directly to the code base, please see the following:
2016-05-04 21:40:41 +03:00
2018-08-19 17:19:07 +03:00
- [How to build and run from source ](Documentation/README.md#building-from-source )
- [The development workflow, and using your build ](Documentation/README.md#development-workflow )
2018-03-03 19:50:20 +03:00
- [Coding Guidelines ](http://www.mono-project.com/community/contributing/coding-guidelines/ )
- [Submitting pull requests ](https://github.com/xamarin/xamarin-android/wiki/Submitting-Bugs,-Feature-Requests,-and-Pull-Requests#pull-requests )
2016-05-04 21:40:41 +03:00
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 ).
2018-03-03 19:50:20 +03:00
# Feedback
2016-04-28 18:15:08 +03:00
2021-12-02 21:24:08 +03:00
- Ask a question on [Stack Overflow ](https://stackoverflow.com/questions/tagged/xamarin.android ) or [Microsoft Q&A ](https://docs.microsoft.com/en-us/answers/topics/dotnet-android.html ).
- [Request a new feature or vote for popular feature requests ](https://developercommunity.visualstudio.com/search?entry=suggestion&space=8&preview2=true&q=xamarin+android&stateGroup=active&ftype=idea&sort=votes ) on Microsoft Developer Community.
- File an issue in [GitHub Issues ](https://github.com/xamarin/xamarin-android/issues/new/choose ).
- Discuss development and design on [Discord ](https://aka.ms/dotnet-discord ).
2016-04-28 18:15:08 +03:00
2020-08-03 20:02:00 +03:00
[](https://aka.ms/dotnet-discord)
2016-04-28 18:15:08 +03:00
2018-03-03 19:50:20 +03:00
# License
2016-08-14 00:40:37 +03:00
2018-03-03 19:50:20 +03:00
Copyright (c) .NET Foundation Contributors. All rights reserved.
Licensed under the [MIT ](LICENSE ) License.
