Skip to content

Commit

Permalink
[docs] Document use of Jenkins build artifacts. (dotnet#476)
Browse files Browse the repository at this point in the history 
Update README.md and related documentation, projects.
  • Loading branch information
@jonpryor @grendello
jonpryor authored and grendello committed Mar 9, 2017
1 parent 3b893cd commit 87ca273
Show file tree
Hide file tree
Showing 3 changed files with 261 additions and 77 deletions.
167 changes: 167 additions & 0 deletions Documentation/UsingJenkinsBuildArtifacts.md
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 88 additions & 74 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand All @@ -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:
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -307,14 +320,15 @@ 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):

cd src/Mono.Android
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
Expand Down
9 changes: 6 additions & 3 deletions samples/HelloWorld/HelloWorld.csproj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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' ">
Expand Down

0 comments on commit 87ca273

Please sign in to comment.