[docs] Document use of Jenkins build artifacts. (#476)

Update README.md and related documentation, projects.
This commit is contained in:
Jonathan Pryor 2017-03-09 15:13:19 -05:00 коммит произвёл Marek Habersack
Родитель 3b893cd415
Коммит 87ca273712
3 изменённых файлов: 261 добавлений и 77 удалений

Просмотреть файл

@ -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
<a name="Android_SDK_Setup" />
# 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"

162
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 `<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`.
* `$(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 `<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`.
* `$(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 <package name>
# 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
<a name="Samples" />
# Samples
The [HelloWorld](samples/HelloWorld) sample may be built with the

Просмотреть файл

@ -15,10 +15,13 @@
<MonoAndroidResourcePrefix>Resources</MonoAndroidResourcePrefix>
<MonoAndroidAssetsPrefix>Assets</MonoAndroidAssetsPrefix>
<AndroidUseLatestPlatformSdk>true</AndroidUseLatestPlatformSdk>
<TargetFrameworkVersion>v7.0</TargetFrameworkVersion>
<TargetFrameworkVersion>v7.1</TargetFrameworkVersion>
</PropertyGroup>
<Import Project="..\..\Configuration.props" />
<PropertyGroup>
<Import
Condition="Exists('..\..\Configuration.props')"
Project="..\..\Configuration.props"
/>
<PropertyGroup Condition="Exists('..\..\Configuration.props')">
<TargetFrameworkVersion>$(AndroidFrameworkVersion)</TargetFrameworkVersion>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">