diff --git a/Documentation/UsingJenkinsBuildArtifacts.md b/Documentation/UsingJenkinsBuildArtifacts.md new file mode 100644 index 000000000..9e2886f40 --- /dev/null +++ b/Documentation/UsingJenkinsBuildArtifacts.md @@ -0,0 +1,167 @@ +# Jenkins Build Artifacts + +The [**Project xamarin-android** Jenkins page][xa-jenkins-page] has a link +to the [Latest Azure Artifacts][xa-macOS-azure-artifacts], which contains an +`oss-xamarin.android*.zip` file for every Jenkins build on macOS. +The `oss-xamarin.android*.zip` file can be downloaded and used, without +requiring a local `xamarin-android` repo build. + +[xa-jenkins-page]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android/ +[xa-macOS-azure-artifacts]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android/lastSuccessfulBuild/Azure/ + +The Jenkins build artifacts do *not* include Android SDK or NDK bits, +while requiring that parts of the Android SDK be installed to work. +Please see the [Android SDK Setup](#Android_SDK_Setup) section for instructions +on setting up the Android NDK & SDK if an Android SDK is not already setup. + +# Installing Jenkins Build Artifacts + +macOS and Windows users should go to the +[Latest xamarin-android Azure Artifacts][xa-macOS-azure-artifacts] page and +download the `oss-xamarin.android*.zip` file, e.g. +[oss-xamarin.android_v7.2.99.19_Darwin-x86_64_master_3b893cd.zip][oss-xa-macOS]. + +[oss-xa-macOS]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android/lastSuccessfulBuild/Azure/processDownloadRequest/xamarin-android/oss-xamarin.android_v7.2.99.19_Darwin-x86_64_master_3b893cd.zip + +macOS users may just extract this into their **Downloads** folder using +**Archive Utility.app** or `unzip` from **Terminal.app**. This will result +in a file such as: + + $HOME/Downloads/oss-xamarin.android_v7.2.99.19_Darwin-x86_64_master_3b893cd/bin/Debug/bin/xabuild + +Windows users should right-click this file within Explorer and click +**Extract All...**, and in the **Extract Compressed (Zipped) Folders** dialog +enter a *short* path such as `C:\xa-sdk`. This is necessary because some +of the contained filenames are quite long. This will result in a path +such as: + + C:\xa-sdk\oss-xamarin.android_v7.2.99.19_Darwin-x86_64_master_3b893cd\bin\Debug\bin\mono-symbolicate.cmd + +Linux/x86_64 users can go to the +[Latest xamarin-android-linux Azure Artifacts page][xa-linux-azure-artifacts] +and download the `oss-xamarin.android*.zip` file, e.g. +[xamarin-android/oss-xamarin.android_v7.2.99.19_Linux-x86_64_master_3b893cd.zip][oss-xa-Linux]. + +[xa-linux-azure-artifacts]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-linux/lastSuccessfulBuild/Azure/ +[oss-xa-Linux]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-linux/lastSuccessfulBuild/Azure/processDownloadRequest/xamarin-android/oss-xamarin.android_v7.2.99.19_Linux-x86_64_master_3b893cd.zip + +# Using Jenkins Build Artifacts + +## Command-line use: Linux and macOS + +Within the `oss-xamarin.android*.zip` extracted contents is a +`oss-xamarin.android*/bin/Debug/bin/xabuild` script. + +`xabuild` requires that the `$ANDROID_SDK_PATH` and `$ANDROID_NDK_PATH` +environment variables be set to the location of the Android SDK and +Android NDK directories, respectively. + +If you have a xamarin-android build environment, then +`$HOME/android-toolchain` will contain an Android SDK and NDK: + + export ANDROID_SDK_PATH=$HOME/android-toolchain/sdk + export ANDROID_NDK_PATH=$HOME/android-toolchain/ndk + +If you followed the [Android SDK Setup](#Android_SDK_Setup) instructions, then: + + export ANDROID_SDK_PATH=$HOME/xa-sdk/android-sdk + export ANDROID_NDK_PATH=$HOME/xa-sdk/android-ndk/android-ndk-r14 + +Once the `oss-xamarin.android*.zip` file has been installed, Unix users +may use the `oss-xamarin.android*/bin/Debug/bin/xabuild` script to build +projects. + + # macOS users: build the xamarin-android HelloWorld.csproj sample + $HOME/Downloads/oss-xamarin.android_v7.2.99.19_Darwin-x86_64_master_3b893cd/bin/Debug/bin/xabuild \ + /t:SignAndroidPackage \ + samples/HelloWorld/HelloWorld.csproj + + +## Command-line use: Windows + +There is not currently an `xabuild.cmd` script for Windows use. Instead, +Windows users should execute `msbuild.exe` directly, providing the following +MSBuild properties: + +* `AndroidSdkDirectory`: The location of the Android SDK. +* `AndroidNdkDirectory`: The location of the Android NDK. +* `JavaSdkDirectory`: The location of the Java SDK/JDK. +* `MonoAndroidBinDirectory`: The `xbuild\Xamarin\Android` directory in the + `oss-xamarin.android*.zip` installation. +* `MonoAndroidToolsDirectory`: The `xbuild\Xamarin\Android` directory in the + `oss-xamarin.android*.zip` installation. +* `TargetFrameworkRootPath`: The `xbuild-frameworks` directory in the + `oss-xamarin.android*.zip` installation. + +For example (using the paths from [Android SDK Setup](#Android_SDK_Setup)): + + msbuild /p:AndroidSdkDirectory="C:\xa-sdk\android-sdk" ^ + /p:AndroidNdkDirectory="C:\xa-sdk\android-ndk\android-ndk-r14" ^ + /p:MonoAndroidBinDirectory="C:\xa-sdk\oss-xamarin.android_v7.2.99.19_Darwin-x86_64_master_3b893cd\bin\Debug\lib\xbuild\Xamarin\Android" ^ + /p:MonoAndroidToolsDirectory="C:\xa-sdk\oss-xamarin.android_v7.2.99.19_Darwin-x86_64_master_3b893cd\bin\Debug\lib\xbuild\Xamarin\Android" ^ + /p:TargetFrameworkRootPath="C:\xa-sdk\oss-xamarin.android_v7.2.99.19_Darwin-x86_64_master_3b893cd\bin\Debug\lib\xbuild-frameworks" ^ + /t:SignAndroidPackage ^ + samples\HelloWorld\HelloWorld.csproj + + +# Android SDK Setup + +Please see the [Android Studio][android-studio] page to download the +Android SDK, if you do not already have the Android SDK installed. +If you don't want Android Studio, you can follow the +**Get just the command line tools** section at the Android Studio page. + +[android-studio]: https://developer.android.com/studio/index.html + +The Android NDK can be downloaded from the [NDK Downloads][ndk-downloads] +page. + +[ndk-downloads]: https://developer.android.com/ndk/downloads/index.html + +## macOS Android SDK Setup + +Download the macOS SDK tools package, e.g. +[tools_r25.2.3-macosx.zip][android-tools-macOS], and the + macOS NDK package, e.g. [android-ndk-r14-darwin-x86_64.zip][ndk-macOS] + +[android-tools-macOS]: https://dl.google.com/android/repository/tools_r25.2.3-macosx.zip +[ndk-macOS]: https://dl.google.com/android/repository/android-ndk-r14-darwin-x86_64.zip + +Within **Terminal.app**, run the following commands, assuming that the +above mentioned files were downloaded into `$HOME/Downloads`, and we want +to create a new Android SDK & NDK within `$HOME/xa-sdk`: + + mkdir -p $HOME/xa-sdk/android-sdk + cd $HOME/xa-sdk/android-sdk + unzip $HOME/Downloads/tools_r25.2.3-macosx.zip + tools/bin/sdkmanager build-tools;25.0.2" + tools/bin/sdkmanager "platform-tools" + tools/bin/sdkmanager "platforms;android-25" + + mkdir -p $HOME/xa-sdk/android-ndk + cd $HOME/xa-sdk/android-ndk + unzip $HOME/Downloads/android-ndk-r14-darwin-x86_64.zip + +## Windows Android SDK Setup + +1. Download the Windows SDK tools package, e.g. +[tools_r25.2.3-windows.zip][android-tools-windows], and the + Windows NDK package, e.g. [android-ndk-r14-windows-x86.zip][ndk-win64] + +[android-tools-windows]: https://dl.google.com/android/repository/tools_r25.2.3-windows.zip +[ndk-win64]: https://dl.google.com/android/repository/android-ndk-r14-windows-x86.zip + + +2. Right-click the `tools*.zip` file within Explorer, then click + **Extract All...** +3. Within the **Extract Compressed (Zipped) Folders** dialog, enter + a path such as `C:\xa-sdk\android-sdk`. Click **Next**. +4. Right-click the `android-ndk*.zip` file within Explorer, then click + **Extract All...** +5. Within the **Extract Compressed (Zipped) Folders** dialog, enter + a path such as `C:\xa-sdk\android-ndk`. Click **Next**. +6. Within `cmd.exe`: + cd C:\xa-sdk\android-sdk + tools\bin\sdkmanager "build-tools;25.0.2" + tools\bin\sdkmanager "platform-tools" + tools\bin\sdkmanager "platforms;android-25" diff --git a/README.md b/README.md index 92bcc8a4d..41d8f9e26 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Xamarin.Android provides open-source bindings of the Android SDK for use with |-----------------|--------| | **Commercial Xamarin.Android 7.0 (Cycle 8)** for macOS | [![Commercial Xamarin.Android 7.0, macOS][commercial-c8-macOS-x86_64-icon]][commercial-c8-macOS-x86_64-status] | | **Commercial Xamarin.Android 7.1 (Cycle 9)** for macOS | [![Commercial Xamarin.Android 7.1, macOS][commercial-c9-macOS-x86_64-icon]][commercial-c9-macOS-x86_64-status] | -| **Commercial Xamarin.Android 7.1.99 (master)** for macOS | [![Commercial Xamarin.Android 7.1.99, macOS][commercial-master-macOS-x86_64-icon]][commercial-master-macOS-x86_64-status] | +| **Commercial Xamarin.Android 7.2.99 (master)** for macOS | [![Commercial Xamarin.Android 7.2mon.99, macOS][commercial-master-macOS-x86_64-icon]][commercial-master-macOS-x86_64-status] | [commercial-c8-macOS-x86_64-icon]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-cycle8/badge/icon [commercial-c8-macOS-x86_64-status]: https://jenkins.mono-project.com/view/Xamarin.Android/job/xamarin-android-builds-cycle8/ @@ -34,78 +34,6 @@ Xamarin.Android provides open-source bindings of the Android SDK for use with [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/ -# Configuration.Override.props - -The Xamarin.Android build is heavily dependent on MSBuild, with the *intention* -that it should (eventually?) be possible to build the project simply by -checking out the repo, loading `Xamarin.Android.sln` into an IDE, and Building -the solution. (This isn't currently possible, and may never be, but it's -the *vision*.) - -However, some properties may need to be altered in order to suit your -requirements, such as the location of a cache directory to store -the Android SDK and NDK. - -To modify the build process, copy -[`Configuration.Override.props.in`](Configuration.Override.props.in) -to `Configuration.Override.props`, and edit the file as appropriate. -`Configuration.Override.props` is ``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`. -* `$(AndroidSupportedTargetJitAbis)`: The Android ABIs for which to build the - the Mono JIT for inclusion within apps. This is a `:`-separated list of - ABIs to build. Supported values are: - - * `armeabi` - * `armeabi-v7a` - * `arm64-v8a` - * `x86` - * `x86_64` -* `$(AndroidToolchainCacheDirectory)`: The directory to cache the downloaded - Android NDK and SDK files. This value defaults to - `$(HOME)\android-archives`. -* `$(AndroidToolchainDirectory)`: The directory to install the downloaded - Android NDK and SDK files. This value defaults to - `$(HOME)\android-toolchain`. -* `$(HostCc)`, `$(HostCxx)`: The C and C++ compilers to use to generate - host-native binaries. -* `$(JavaInteropSourceDirectory)`: The Java.Interop source directory to - build and reference projects from. By default, this is - `external/Java.Interop` directory, maintained by `git submodule update`. -* `$(MakeConcurrency)`: **make**(1) parameters to use intended to influence - the number of CPU cores used when **make**(1) executes. By default this uses - `-jCOUNT`, where `COUNT` is obtained from `sysctl hw.ncpu`. -* `$(MonoSgenBridgeVersion)`: The Mono SGEN Bridge version to support. - Valid values include: - - * `4`: Mono 4.6 support. - * `5`: Mono 4.8 support. This is the default. - # Build Requirements Building Xamarin.Android requires: @@ -185,6 +113,79 @@ URL to download files from is controlled by the `$(AndroidUri)` property. [android-toolchain.projitems]: build-tools/android-toolchain/android-toolchain.projitems +# 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 ``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`. +* `$(AndroidSupportedTargetJitAbis)`: The Android ABIs for which to build the + the Mono JIT for inclusion within apps. This is a `:`-separated list of + ABIs to build. Supported values are: + + * `armeabi` + * `armeabi-v7a` + * `arm64-v8a` + * `x86` + * `x86_64` + +* `$(AndroidToolchainCacheDirectory)`: The directory to cache the downloaded + Android NDK and SDK files. This value defaults to + `$(HOME)\android-archives`. +* `$(AndroidToolchainDirectory)`: The directory to install the downloaded + Android NDK and SDK files. This value defaults to + `$(HOME)\android-toolchain`. +* `$(HostCc)`, `$(HostCxx)`: The C and C++ compilers to use to generate + host-native binaries. +* `$(JavaInteropSourceDirectory)`: The Java.Interop source directory to + build and reference projects from. By default, this is + `external/Java.Interop` directory, maintained by `git submodule update`. +* `$(MakeConcurrency)`: **make**(1) parameters to use intended to influence + the number of CPU cores used when **make**(1) executes. By default this uses + `-jCOUNT`, where `COUNT` is obtained from `sysctl hw.ncpu`. +* `$(MonoSgenBridgeVersion)`: The Mono SGEN Bridge version to support. + Valid values include: + + * `4`: Mono 4.6 support. + * `5`: Mono 4.8 and above support. This is the default. + # Build At this point in time, building Xamarin.Android is only supported on OS X. @@ -265,6 +266,18 @@ If any program is still not found, try to ensure it's linked via: brew link +# 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. + +# Using Jenkins Build Artifacts + +Please see +[`Documentation/UsingJenkinsBuildArtifacts.md`](Documentation/UsingJenkinsBuildArtifacts.md) +for details on using prebuilt Xamarin.Android binaries. + # Build Output Directory Structure There are two configurations, `Debug` and `Release`, controlled by the @@ -307,7 +320,7 @@ To control which API level is bound, set the `$(AndroidApiLevel)` and Android API level, *usually* a number, while `$(AndroidFrameworkVersion)` is the Xamarin.Android `$(TargetFrameworkVersion)`. -The default values will target Android API-24, Android 7.0. +The default values will target Android API-25, Android 7.1. For example, to generate `Mono.Android.dll` for API-19 (Android 4.4): @@ -315,6 +328,7 @@ For example, to generate `Mono.Android.dll` for API-19 (Android 4.4): xbuild /p:AndroidApiLevel=19 /p:AndroidFrameworkVersion=v4.4 # creates bin\Debug\lib\xbuild-frameworks\MonoAndroid\v4.4\Mono.Android.dll + # Samples The [HelloWorld](samples/HelloWorld) sample may be built with the diff --git a/samples/HelloWorld/HelloWorld.csproj b/samples/HelloWorld/HelloWorld.csproj index ccf48c5e9..5c5ecd2da 100644 --- a/samples/HelloWorld/HelloWorld.csproj +++ b/samples/HelloWorld/HelloWorld.csproj @@ -15,10 +15,13 @@ Resources Assets true - v7.0 + v7.1 - - + + $(AndroidFrameworkVersion)