Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Mar 9, 2017
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
167 changes: 167 additions & 0 deletions Documentation/UsingJenkinsBuildArtifacts.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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