[build] Add support for Configuration.Override.props (#45)

For proper use, the [xamarin-android][xa] build needs to place various
Java.Interop utilities such as class-parse.exe and generator.exe into
`$prefix/lib/mandroid`, so that Xamarin.Android.Build.Tasks.dll will
properly verify the installation environment.

There are three ways this could be accomplished:

1. The `xamarin-android` Makefile could explicitly build these
    utilities and override `$(OutputPath)`:

        xbuild external/Java.Interop/tools/class-parse /p:OutputPath=`pwd`/bin/$(CONFIGURATION)/lib/mandroid

    The problem with this is that we want to have the xamarin-android
    build system rely on MSBuild as much as possible, and this
    approach, while workable, runs counter to those desires.

2. We could add additional project configurations to control where the
    output directory should be. This was suggested by
    [@atsushieno][pr41].

    My concern with this approach is that it's not easily extensible:
    it's not just a few projects that need to place files into
    `$prefix/lib/mandroid`, but all of their dependencies as well.
    Such an approach would thus require adding lots of new
    configurations to lots of projects.

3. Java.Interop could adopt a `xamarin-android`-style
    `Configuration.props` system. This would allow xamarin-android to
    *generate* a `Configuration.Override.props` file to specify the
    correct output path for those utilities.

(3) is the chosen solution. It allows adding e.g.
`external/Java.Interop/tools/generator/generator.csproj` to
`Xamarin.Android.sln`, allowing it to be built "normally" from the
`xamarin-android` build system, while causing the built files to be
placed into e.g. `xamarin-android/bin/Debug/lib/mandroid` instead of
the less useful `xamarin-android/external/Java.Interop/bin/Debug`.

[xa]: https://github.com/xamarin/xamarin-android/
[pr41]: #41

.gitignore

@@ -1,4 +1,5 @@
 bin
+Configuration.Override.props
 obj
 JavaDeveloper-2013005_dp__11m4609.pkg
 LocalJDK

Configuration.Override.props.in

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <JdkJvmPath>/Library/Java/JavaVirtualMachines/jdk1.8.0_77.jdk/Contents/Home/jre/lib/server/libjvm.dylib</JdkJvmPath>
+    <MonoFrameworkPath>/Library/Frameworks/Mono.framework/Libraries/libmonosgen-2.0.1.dylib</MonoFrameworkPath>
+    <UtilityOutputFullPath>$(MSBuildThisFileDirectory)bin\$(Configuration)\</UtilityOutputFullPath>
+  </PropertyGroup>
+  <ItemGroup>
+    <!-- JDK C `include` directories -->
+    <JdkIncludePath Include="/Library/Java/JavaVirtualMachines/jdk1.8.0_77.jdk/Contents/Home/include" />
+    <JdkIncludePath Include="/Library/Java/JavaVirtualMachines/jdk1.8.0_77.jdk/Contents/Home/include/darwin" />
+  </ItemGroup>
+  <ItemGroup>
+    <!-- Mono C `include` directories -->
+    <MonoIncludePath Include="/Library/Frameworks/Mono.framework/Headers/mono-2.0" />
+  </ItemGroup>
+</Project>

Configuration.props

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <!-- Note: MUST be imported *after* $(Configuration) is set! -->
+  <Import
+      Project="$(MSBuildThisFileDirectory)Configuration.Override.props"
+      Condition="Exists('$(MSBuildThisFileDirectory)Configuration.Override.props')"
+  />
+  <Import
+      Project="$(MSBuildThisFileDirectory)bin\Build$(Configuration)\JdkInfo.props"
+      Condition="Exists('$(MSBuildThisFileDirectory)bin\Build$(Configuration)\JdkInfo.props')"
+  />
+  <Import
+      Project="$(MSBuildThisFileDirectory)bin\Build$(Configuration)\MonoInfo.props"
+      Condition="Exists('$(MSBuildThisFileDirectory)bin\Build$(Configuration)\MonoInfo.props')"
+  />
+  <PropertyGroup>
+    <UtilityOutputFullPath  Condition=" '$(UtilityOutputFullPath)' == '' ">$(MSBuildThisFileDirectory)bin\$(Configuration)\</UtilityOutputFullPath>
+  </PropertyGroup>
+</Project>

README.md

@@ -2,10 +2,13 @@
 
 [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/xamarin/xamarin-android?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-**Java.Interop** is a brain-delusional [Second System Syndrome][sss] rebuild
- of the monodroid/Xamarin.Android core, intended to fix some of the shortcomings
-  and design mistakes I've made over the years.
+**Java.Interop** is a binding of the [Java Native Interface][jni] for use from
+managed languages such as C#, and an associated set of code generators to
+allow Java code to invoke managed code. It is *also* a brain-delusional
+[Second System Syndrome][sss] rebuild of the monodroid/Xamarin.Android core,
+intended to fix some of the shortcomings and design mistakes I've made over the years.
 
+[jni]: http://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/jniTOC.html
 [sss]: http://en.wikipedia.org/wiki/Second-system_effect
 
 In particular, it attempts to fix the following issues: 
@@ -27,7 +30,7 @@ which returns a global reference while most other methods return a local ref.
 
 The `JNIEnv` API is also huge, unwieldy, and terrible.
 
-## Requirements
+## Build Requirements
 
 The current Oracle JDK7 installer only provides 64-bit binaries, while
 Mono for OS X is currently a 32-bit binary. These don't work together. :-(
@@ -63,6 +66,52 @@ then run the `osx-setup` target:
     $ make osx-setup JDK=JavaDeveloper.pkg
 
 
+## Build Configuration
+
+The Java.Interop build can be configured by overriding **make**(1) variables
+on the command line or by specifying MSBuild properties to control behavior.
+
+### **make**(1) variables
+
+The following **make**(1) variables may be specified:
+
+* `$(CONFIGURATION)`: The product configuration to build, and corresponds
+    to the `$(Configuration)` MSBuild property when running `$(XBUILD)`.
+    Valid values are `Debug` and `Release`. Default value is `Debug`.
+* `$(RUNTIME)`: The managed runtime to use to execute utilities, tests.
+    Default value is `mono64` if present in `$PATH`, otherwise `mono`.
+* `$(TESTS)`: Which unit tests to execute. Useful in conjunction with the
+    `make run-tests` target:
+
+        make run-tests TESTS=bin/Debug/Java.Interop.Dynamic-Tests.dll
+
+* `$(V)`: If set to a non-empty string, adds `/v:diag` to `$(XBUILD)`
+    invocations.
+* `$(XBUILD)`: The MSBuild build tool to execute for builds.
+    Default value is `xbuild`.
+
+
+### MSBuild Properties
+
+MSbuild properties may be placed into the file `Configuration.Override.props`,
+which can be copied from
+[`Configuration.Override.props.in`](Configuration.Override.props.in).
+The `Configuration.Override.props` file is `<Import/>`ed by
+[`Configuration.props`](Configuration.props); there is no need to `<Import/>`
+it within other project files.
+
+Overridable MSBuild properties include:
+
+* `$(JdkJvmPath)`: Full path name to the JVM native library to link
+    [`java-interop`](src/java-interop) against. By default this is
+    probed for from numerious locations within
+    [`build-tools/scripts/jdk.mk`](build-tools/scripts/jdk.mk).
+* `$(UtilityOutputFullPath)`: Directory to place various utilities such as
+    [`class-parse`](tools/class-parse), [`generator`](tools/generator),
+    and [`logcat-parse`](tools/logcat-parse). This value should be a full path.
+    By default this is `$(MSBuildThisFileDirectory)bin/$(Configuration)`.
+
+
 ## Type Safety
 
 The start of the reboot was to use strongly typed [`SafeHandle`][SafeHandle]

build-tools/scripts/jdk.mk

@@ -116,11 +116,11 @@ bin/Build$(CONFIGURATION)/JdkInfo.props: $(JI_JDK_INCLUDE_PATHS) $(JI_JVM_PATH)
 	-rm "$@"
 	echo '<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">' > "$@"
 	echo '  <PropertyGroup>' >> "$@"
-	echo "    <JdkJvmPath>$(JI_JVM_PATH)</JdkJvmPath>" >> "$@"
+	echo "    <JdkJvmPath     Condition=\" '\$$(JdkJvmPath)' == '' \">$(JI_JVM_PATH)</JdkJvmPath>" >> "$@"
 	echo '  </PropertyGroup>' >> "$@"
 	echo '  <ItemGroup>' >> "$@"
 	for p in $(JI_JDK_INCLUDE_PATHS); do \
-		echo "    <JdkIncludePath Include=\"$$p\" />" >> "$@"; \
+		echo "    <JdkIncludePath Condition=\" '\$$(JdkJvmPath)' == '' \" Include=\"$$p\" />" >> "$@"; \
 	done
 	echo '  </ItemGroup>' >> "$@"
 	echo '</Project>' >> "$@"

build-tools/scripts/mono.mk

@@ -21,12 +21,12 @@ bin/Build$(CONFIGURATION)/MonoInfo.props: $(JI_MONO_INCLUDE_PATHS) $(JI_MONO_FRA
 	-rm "$@"
 	echo '<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">' > "$@"
 	echo '  <PropertyGroup>' >> "$@"
-	echo "    <MonoFrameworkPath>$(JI_MONO_FRAMEWORK_PATH)</MonoFrameworkPath>" >> "$@"
-	echo '    <MonoLibs>$(JI_MONO_LIBS)</MonoLibs>'
+	echo "    <MonoFrameworkPath  Condition=\" '\$$(MonoFrameworkPath)' == '' \">$(JI_MONO_FRAMEWORK_PATH)</MonoFrameworkPath>" >> "$@"
+	echo "    <MonoLibs           Condition=\" '\$$(MonoLibs)' == ''          \">$(JI_MONO_LIBS)</MonoLibs>" >> "$@"
 	echo '  </PropertyGroup>' >> "$@"
 	echo '  <ItemGroup>' >> "$@"
 	for p in $(JI_MONO_INCLUDE_PATHS); do \
-		echo "    <MonoIncludePath Include=\"$$p\" />" >> "$@"; \
+		echo "    <MonoIncludePath    Condition=\" '\$$(MonoFrameworkPath)' == '' \" Include=\"$$p\" />" >> "$@"; \
 	done
 	echo '  </ItemGroup>' >> "$@"
 	echo '</Project>' >> "$@"

tools/class-parse/class-parse.csproj

@@ -12,11 +12,12 @@
     <ProductVersion>8.0.30703</ProductVersion>
     <SchemaVersion>2.0</SchemaVersion>
   </PropertyGroup>
+  <Import Project="..\..\Configuration.props" />
   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
     <DebugSymbols>true</DebugSymbols>
     <DebugType>full</DebugType>
     <Optimize>false</Optimize>
-    <OutputPath>..\..\bin\Debug</OutputPath>
+    <OutputPath>$(UtilityOutputFullPath)</OutputPath>
     <DefineConstants>DEBUG;</DefineConstants>
     <ErrorReport>prompt</ErrorReport>
     <WarningLevel>4</WarningLevel>
@@ -26,7 +27,7 @@
   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
     <DebugType>full</DebugType>
     <Optimize>true</Optimize>
-    <OutputPath>..\..\bin\Release</OutputPath>
+    <OutputPath>$(UtilityOutputFullPath)</OutputPath>
     <ErrorReport>prompt</ErrorReport>
     <WarningLevel>4</WarningLevel>
     <Externalconsole>true</Externalconsole>

tools/generator/generator.csproj

@@ -17,11 +17,12 @@
     </EnvironmentVariables>
     <TargetFrameworkVersion>v4.5</TargetFrameworkVersion>
   </PropertyGroup>
+  <Import Project="..\..\Configuration.props" />
   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
     <DebugSymbols>True</DebugSymbols>
     <DebugType>full</DebugType>
     <Optimize>False</Optimize>
-    <OutputPath>..\..\bin\Debug</OutputPath>
+    <OutputPath>$(UtilityOutputFullPath)</OutputPath>
     <DefineConstants>DEBUG;GENERATOR;USE_CECIL;JCW_ONLY_TYPE_NAMES</DefineConstants>
     <ErrorReport>prompt</ErrorReport>
     <WarningLevel>4</WarningLevel>
@@ -30,7 +31,7 @@
   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
     <DebugType>none</DebugType>
     <Optimize>False</Optimize>
-    <OutputPath>..\..\bin\Release</OutputPath>
+    <OutputPath>$(UtilityOutputFullPath)</OutputPath>
     <ErrorReport>prompt</ErrorReport>
     <WarningLevel>4</WarningLevel>
     <Externalconsole>True</Externalconsole>

tools/logcat-parse/logcat-parse.csproj

@@ -12,11 +12,12 @@
     <TargetFrameworkVersion>v4.5</TargetFrameworkVersion>
     <StartupObject>Xamarin.Android.Tools.LogcatParse.Program</StartupObject>
   </PropertyGroup>
+  <Import Project="..\..\Configuration.props" />
   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
     <DebugSymbols>true</DebugSymbols>
     <DebugType>full</DebugType>
     <Optimize>false</Optimize>
-    <OutputPath>..\..\bin\Debug</OutputPath>
+    <OutputPath>$(UtilityOutputFullPath)</OutputPath>
     <DefineConstants>DEBUG;TRACE</DefineConstants>
     <ErrorReport>prompt</ErrorReport>
     <WarningLevel>4</WarningLevel>
@@ -26,7 +27,7 @@
   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
     <DebugType>full</DebugType>
     <Optimize>true</Optimize>
-    <OutputPath>..\..\bin\Release</OutputPath>
+    <OutputPath>$(UtilityOutputFullPath)</OutputPath>
     <DefineConstants>TRACE</DefineConstants>
     <ErrorReport>prompt</ErrorReport>
     <WarningLevel>4</WarningLevel>