Skip to content

Commit 52db626

Browse files
jonpryorjonpryor
committed
[Xamarin.Android.Build.Tasks] Fix @(JavaDocJar)
Fixes: #2745 Fixes: #5474 Issue #2745 noted that `@(JavaDocJar)` didn't work; attempting to use it would result in an MSB3375 error: …/Xamarin.Android.Bindings.Documentation.targets(31,5): error MSB3375: The file "obj/Debug/javadocs/glide-3.7.0-javadoc.stamp" does not exist. This issue was subsequently hidden by 380e95e, which disabled the `_ExtractJavaDocJars` target unless JDK 1.8 was being used. There were two problems with 380e95e: 1. The `_ExtractJavaDocJars` target didn't need to be disabled! It just unzips the `.jar`; it does not require JDK 1.8. 2. The check for JDK 1.8 was bad, and was *never* True. The bad JDK 1.8 check was later removed in a7413a2, which "fixed" (2), but a7413a2 continued to disable `_ExtractJavaDocJars`, preventing `@(JavaDocJar)` from being used. The only documentation-related functionality that needed to be disabled because of JDK 11 was `@(JavaSourceJar)`, which got a better fix in commits a7413a2 and 0e95ec7. Fix the `_ExtractJavaDocJars` target so that it properly runs when there are any `@(JavaDocJar)` items, then fix the `_ExtractJavaDocJars` target so that it doesn't emit an MSB3375 error. Note: `@(JavaDocJar)` is still problematic: it involves parsing Javadoc HTML, which contains numerous "dialects" (it's why the JDK 11 commit skipped `@(JavaSourceJar)` support: trying to update our HTML scrapers was "too fiddly"). We will deprecate `@(JavaDocJar)` support in a future release. `@(JavaSourceJar)` should be preferred. Update the `BindingBuildTest.cs` infrastructure so that instead of having `.jar` files encoded in Base64, we instead use `@(EmbeddedResource)`s for the `.jar` files. A new `UpdateResources` target will update the appropriate `.jar` files.
1 parent 0f2dc44 commit 52db626

File tree

11 files changed

+150
-64
lines changed

11 files changed

+150
-64
lines changed

‎Documentation/guides/building-apps/build-items.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -298,6 +298,21 @@ such as `<AndroidLibrary Include="..." Bind="false" />`:
298298
</Project>
299299
```
300300

301+
## JavaDocJar
302+
303+
In a Xamarin.Android binding project, the **JavaDocJar** build action
304+
is used on `.jar` files which contain *Javadoc HTML*. The Javadoc HTML
305+
is parsed in order to extract parameter names.
306+
307+
Only certain "Javadoc HTML dialects" are supported, including:
308+
309+
* JDK 1.7 `javadoc` output
310+
* JDK 1.8 `javadoc` output
311+
* Droiddoc output
312+
313+
This build action is deprecated in Xamarin.Android 11.3.
314+
The `@(JavaSourceJar)` build action should be preferred.
315+
301316
## JavaSourceJar
302317

303318
In a Xamarin.Android binding project, the **JavaSourceJar** build action

‎src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Documentation.targets‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,14 +17,13 @@ This file is only used by binding projects. .NET 5 can eventually use it, once `
1717
<UsingTask TaskName="Xamarin.Android.Tasks.Unzip" AssemblyFile="Xamarin.Android.Build.Tasks.dll" />
1818

1919
<Target Name="_ExtractJavaDocJars"
20-
Condition=" '$(_UseLegacyJavadocImport)' == 'True' "
2120
Inputs="@(JavaDocJar)"
2221
Outputs="@(JavaDocJar->'$(IntermediateOutputPath)javadocs\%(FileName).stamp')">
2322
<Unzip
2423
Sources="@(JavaDocJar)"
2524
DestinationDirectories="@(JavaDocJar->'$(IntermediateOutputPath)javadocs\%(FileName)')"
2625
/>
27-
<Touch Files="@(JavaDocJar->'$(IntermediateOutputPath)javadocs\%(FileName).stamp')" />
26+
<Touch Files="@(JavaDocJar->'$(IntermediateOutputPath)javadocs\%(FileName).stamp')" AlwaysCreate="true" />
2827
<ItemGroup>
2928
<JavaDocIndex Include="@(JavaDocJar->'$(IntermediateOutputPath)javadocs\%(FileName)\index.html')" />
3029
</ItemGroup>

‎src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -437,6 +437,29 @@ public void RemoveEventHandlerResolution ()
437437
}
438438
}
439439

440+
[Test]
441+
public void JavaDocJar ()
442+
{
443+
var binding = new XamarinAndroidBindingProject () {
444+
AndroidClassParser = "class-parse",
445+
};
446+
binding.SetProperty ("DocumentationFile", "UnnamedProject.xml");
447+
using (var bindingBuilder = CreateDllBuilder ()) {
448+
binding.Jars.Add (new AndroidItem.EmbeddedJar ("javasourcejartest.jar") {
449+
BinaryContent = () => InlineData.JavaSourceJarTestJar,
450+
});
451+
binding.OtherBuildItems.Add (new BuildItem ("JavaDocJar", "javasourcejartest-javadoc.jar") {
452+
BinaryContent = () => InlineData.JavaSourceJarJavadocTestJar,
453+
});
454+
Assert.IsTrue (bindingBuilder.Build (binding), "binding build should have succeeded");
455+
456+
var cs_file = b.Output.GetIntermediaryPath (
457+
Path.Combine ("generated", "src", "Com.Xamarin.Android.Test.Msbuildtest.JavaSourceJarTest.cs"));
458+
FileAssert.Exists (cs_file);
459+
StringAssert.Contains ("Greet (string name, global::Java.Util.Date date)", File.ReadAllText (cs_file));
460+
}
461+
}
462+
440463
[Test]
441464
public void JavaSourceJar ()
442465
{
@@ -446,10 +469,10 @@ public void JavaSourceJar ()
446469
binding.SetProperty ("DocumentationFile", "UnnamedProject.xml");
447470
using (var bindingBuilder = CreateDllBuilder ()) {
448471
binding.Jars.Add (new AndroidItem.EmbeddedJar ("javasourcejartest.jar") {
449-
BinaryContent = () => Convert.FromBase64String (InlineData.JavaClassesJarBase64)
472+
BinaryContent = () => InlineData.JavaSourceJarTestJar,
450473
});
451474
binding.OtherBuildItems.Add (new BuildItem ("JavaSourceJar", "javasourcejartest-sources.jar") {
452-
BinaryContent = () => Convert.FromBase64String (InlineData.JavaSourcesJarBase64)
475+
BinaryContent = () => InlineData.JavaSourceJarSourcesTestJar,
453476
});
454477
Assert.IsTrue (bindingBuilder.Build (binding), "binding build should have succeeded");
455478

@@ -496,7 +519,7 @@ public void NullableReferenceTypes (string classParser)
496519
AndroidClassParser = classParser,
497520
Jars = {
498521
new AndroidItem.EmbeddedJar ("foo.jar") {
499-
BinaryContent = () => Convert.FromBase64String (InlineData.JavaClassesJarBase64),
522+
BinaryContent = () => InlineData.JavaSourceJarTestJar,
500523
}
501524
}
502525
};

‎src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/Directory.Build.targets‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
<Project>
2+
3+
<Target Name="UpdateResources"
4+
DependsOnTargets="_UpdateJavaSourceJar_Bytecode;_UpdateJavaSourceJar_Sources;_UpdateJavaSourceJar_Javadoc">
5+
</Target>
6+
7+
<ItemGroup>
8+
<JavaSourceJarTest Include="java/com/microsoft/android/test/msbuildtest/JavaSourceJarTest.java" />
9+
</ItemGroup>
10+
11+
<Target Name="_UpdateJavaSourceJar_Bytecode"
12+
Inputs="@(JavaSourceJarTest)"
13+
Outputs="Resources\javasourcejartest.jar">
14+
<PropertyGroup>
15+
<_SourceVersions>-source $(JavacSourceVersion) -target $(JavacTargetVersion)</_SourceVersions>
16+
<_Outdir>$(IntermediateOutputPath)/classes</_Outdir>
17+
</PropertyGroup>
18+
<MakeDir Directories="$(_Outdir)" />
19+
<!-- Note: do NOT include `-parameters`; we want parameter name inferrence via -sources or -javadoc -->
20+
<Exec Command="$(JavaCPath) $(_SourceVersions) -d $(_Outdir) @(JavaSourceJarTest, ' ')" />
21+
<Exec
22+
Command="$(JarPath) cf Resources/javasourcejartest.jar -C $(_Outdir) ."
23+
WorkingDirectory="$(MSBuildThisFileDirectory)"
24+
/>
25+
</Target>
26+
27+
<Target Name="_UpdateJavaSourceJar_Sources"
28+
Inputs="@(JavaSourceJarTest)"
29+
Outputs="Resources\javasourcejartest-sources.jar">
30+
<Exec
31+
Command="$(JarPath) cf Resources/javasourcejartest-sources.jar -C java ."
32+
WorkingDirectory="$(MSBuildThisFileDirectory)"
33+
/>
34+
</Target>
35+
36+
<Target Name="_UpdateJavaSourceJar_Javadoc"
37+
Inputs="@(JavaSourceJarTest)"
38+
Outputs="Resources/javasourcejartest-javadoc.jar">
39+
<PropertyGroup>
40+
<_Javadoc>"$(Java8SdkDirectory)/bin/javadoc"</_Javadoc>
41+
<_Outdir>$(IntermediateOutputPath)/javadoc</_Outdir>
42+
</PropertyGroup>
43+
<MakeDir Directories="$(_Outdir)" />
44+
<Exec
45+
Command="$(_Javadoc) -public -d &quot;$(_Outdir)&quot; @(JavaSourceJarTest, ' ')"
46+
WorkingDirectory="$(MSBuildThisFileDirectory)"
47+
/>
48+
<Exec
49+
Command="$(JarPath) cf Resources/javasourcejartest-javadoc.jar -C &quot;$(_Outdir)&quot; ."
50+
WorkingDirectory="$(MSBuildThisFileDirectory)"
51+
/>
52+
</Target>
53+
54+
</Project>

‎src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/Resources/javasourcejartest-javadoc.jar‎

389 KB
Binary file not shown.

‎src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/Resources/javasourcejartest-sources.jar‎

1.42 KB
Binary file not shown.

‎src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/Resources/javasourcejartest.jar‎

1.51 KB
Binary file not shown.

‎src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/Utilities/InlineData.cs‎

Lines changed: 17 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
using System;
22
using System.Collections.Generic;
3+
using System.IO;
34
using System.Linq;
45
using System.Text;
56
using System.Threading.Tasks;
@@ -8,60 +9,9 @@ namespace Xamarin.Android.Build.Tests
89
{
910
static class InlineData
1011
{
11-
#if false // Java source with javadoc
12-
package com.xamarin.android.test.msbuildtest;
13-
14-
public class JavaSourceJarTest
15-
{
16-
/**
17-
* Returns greeting message.
18-
* <p>
19-
* Returns "Morning, ", "Hello, " or "Evening, " with name argument,
20-
* depending on the argument hour.
21-
* </p>
22-
* @param name name to display.
23-
* @param date time to determine the greeting message.
24-
* @return the resulting message.
25-
*/
26-
public String greet (String name, java.util.Date date)
27-
{
28-
String head = date.getHours () < 11 ? "Morning, " : date.getHours () < 17 ? "Hello, " : "Evening, ";
29-
return head + name;
30-
}
31-
}
32-
#endif
33-
34-
public const string JavaSourcesJarBase64 = @"
35-
UEsDBBQACAgIAC2gP0wAAAAAAAAAAAAAAAAJAAQATUVUQS1JTkYv/soAAAMAUEsHCAAAAAACAAAAAAAAAFBLAwQUAAgIC
36-
AAtoD9MAAAAAAAAAAAAAAAAFAAAAE1FVEEtSU5GL01BTklGRVNULk1G803My0xLLS7RDUstKs7Mz7NSMNQz4OVyLkpNLE
37-
lN0XWqBAlY6BnEG5oaKmj4FyUm56QqOOcXFeQXJZYA1WvycvFyAQBQSwcIlldz8EQAAABFAAAAUEsDBBQACAgIACqgP0w
38-
AAAAAAAAAAAAAAAA7AAAAY29tL3hhbWFyaW4vYW5kcm9pZC90ZXN0L21zYnVpbGR0ZXN0L0phdmFTb3VyY2VKYXJUZXN0
39-
LmphdmF1kc1uwjAMx+99CosTsCqI0yRgG4dNQki7jL2Aaaw2Wz4qJ2WbJt59SSgfQsyq4kb+2X/babH6xJqgckZ8o0FWV
40-
qCV7JQUgXwQxm87pWX6nxdF2221qqDS6D2scYcb13FFa+T3CBS/BUSbjMfZwxjeKHRsPdRMFJStwZD3UU8cgUX7eM0OXh
41-
3byJYwiN+KtHbRg2MYvOyoj8CXCg1YNATIdWfIhvJYSFJLViY1ZyE0ZwKa2O1ZenLWXrbIaA718hEcSOVbjT/iipEYYlj
42-
1DAVioyxlnX+nXHKeLUNMvtO3qEn2/YY3gROSK8Kwv6XOSviIaxddUFo8p1ZSP6Oceth+sp5vCCU8ZELUFFZxeg/DESxg
43-
OoWny0XD7JSb7FbGfco4vcbs8jHmp+R+zix8l/s9xPbFvvgDUEsHCDlC8jY2AQAAawIAAFBLAQIUABQACAgIAC2gP0wAA
44-
AAAAgAAAAAAAAAJAAQAAAAAAAAAAAAAAAAAAABNRVRBLUlORi/+ygAAUEsBAhQAFAAICAgALaA/TJZXc/BEAAAARQAAAB
45-
QAAAAAAAAAAAAAAAAAPQAAAE1FVEEtSU5GL01BTklGRVNULk1GUEsBAhQAFAAICAgAKqA/TDlC8jY2AQAAawIAADsAAAA
46-
AAAAAAAAAAAAAwwAAAGNvbS94YW1hcmluL2FuZHJvaWQvdGVzdC9tc2J1aWxkdGVzdC9KYXZhU291cmNlSmFyVGVzdC5q
47-
YXZhUEsFBgAAAAADAAMA5gAAAGICAAAAAA==";
48-
49-
public const string JavaClassesJarBase64 = @"
50-
UEsDBBQACAgIAO+EP0wAAAAAAAAAAAAAAAAJAAQATUVUQS1JTkYv/soAAAMAUEsHCAAAAAACAAAAAAAAAFBLAwQUAAgIC
51-
ADvhD9MAAAAAAAAAAAAAAAAFAAAAE1FVEEtSU5GL01BTklGRVNULk1G803My0xLLS7RDUstKs7Mz7NSMNQz4OVyLkpNLE
52-
lN0XWqBAlY6BnEG5oaKmj4FyUm56QqOOcXFeQXJZYA1WvycvFyAQBQSwcIlldz8EQAAABFAAAAUEsDBBQACAgIALOEP0w
53-
AAAAAAAAAAAAAAAA8AAAAY29tL3hhbWFyaW4vYW5kcm9pZC90ZXN0L21zYnVpbGR0ZXN0L0phdmFTb3VyY2VKYXJUZXN0
54-
LmNsYXNzbVHZSsNAFD1j2yStaW3rvlvX1i0g4osiuKLi8lARfHPaDCWaJiWdit/ji6/6UkHBD/CjxDupIloDucuZO+fMn
55-
Hn/eHkDsIpCAp3oS6AfAwYGDQwZGNYxkoCmUA2jKozpGNcxwaBtOJ4jNxki+cIFQ3THtwVD17HjidNGtSSCc15yCYlVAi
56-
Ekw1r++JrfcsvlXsUqysDxKustpCEd19rlUqwX2kcYkkXJyzcnvBYS6sgxJIp+IyiLfUcJ9B3RnhZwxINzUZfLisWEiaS
57-
OSRNTmGaIn/iBR4SLdHT9QLiur6r43q34Rvv/am83HNcWgYkZzJqYQ54uUfar1h2vclq3uGcHvmNbkiStar2kxsO67UAM
58-
6R/ys9K1KP+GWnoMqd9+MBgVIQ+IqR7afEiu81pNeDbD0j92ttv3dQVy0ZD+t0pP/h+fkYN6fvV1gCnvKKaoG6XMKMfmn
59-
8GeqKBHpqiFYIRiGpmv0SvaGqW8sthER7rzHkY28oDusMuoLvqAWDZ2+grt8hn6UhPGAv1NxB9DWcWbIk4QYxeyGEc3Rc
60-
BAJJXc0qmjw4eTvZ9QSwcINzBZxakBAAC1AgAAUEsBAhQAFAAICAgA74Q/TAAAAAACAAAAAAAAAAkABAAAAAAAAAAAAAA
61-
AAAAAAE1FVEEtSU5GL/7KAABQSwECFAAUAAgICADvhD9Mlldz8EQAAABFAAAAFAAAAAAAAAAAAAAAAAA9AAAATUVUQS1J
62-
TkYvTUFOSUZFU1QuTUZQSwECFAAUAAgICACzhD9MNzBZxakBAAC1AgAAPAAAAAAAAAAAAAAAAADDAAAAY29tL3hhbWFya
63-
W4vYW5kcm9pZC90ZXN0L21zYnVpbGR0ZXN0L0phdmFTb3VyY2VKYXJUZXN0LmNsYXNzUEsFBgAAAAADAAMA5wAAANYCAA
64-
AAAA==";
12+
public static byte[] JavaSourceJarTestJar = GetResourceData ("javasourcejartest.jar");
13+
public static byte[] JavaSourceJarSourcesTestJar = GetResourceData ("javasourcejartest-sources.jar");
14+
public static byte[] JavaSourceJarJavadocTestJar = GetResourceData ("javasourcejartest-javadoc.jar");
6515

6616
const string Resx = @"<?xml version=""1.0"" encoding=""utf-8""?>
6717
<root>
@@ -84,5 +34,18 @@ public static string ResxWithContents (string contents)
8434
{
8535
return Resx.Replace ("<!--contents-->", contents);
8636
}
37+
38+
static byte[] GetResourceData (string name)
39+
{
40+
using var s = typeof (InlineData).Assembly.GetManifestResourceStream (name);
41+
var data = new List<byte> ();
42+
var buf = new byte[1024];
43+
int r;
44+
while ((r = s.Read (buf, 0, buf.Length)) > 0) {
45+
for (int i = 0; i < r; ++i)
46+
data.Add (buf [i]);
47+
}
48+
return data.ToArray ();
49+
}
8750
}
8851
}

‎src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/XASdkTests.cs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ public void DotNetBuildLibrary (bool isRelease, bool duplicateAar)
8989
TextContent = () => $"{env_var}={env_val}",
9090
});
9191
libB.OtherBuildItems.Add (new AndroidItem.AndroidLibrary ("sub\\directory\\foo.jar") {
92-
BinaryContent = () => Convert.FromBase64String (InlineData.JavaClassesJarBase64),
92+
BinaryContent = () => InlineData.JavaSourceJarTestJar,
9393
});
9494
libB.OtherBuildItems.Add (new AndroidItem.AndroidLibrary ("sub\\directory\\arm64-v8a\\libfoo.so") {
9595
BinaryContent = () => Array.Empty<byte> (),
@@ -183,7 +183,7 @@ public void DotNetNew ([Values ("android", "androidlib", "android-bindinglib")]
183183
{
184184
var dotnet = CreateDotNetBuilder ();
185185
Assert.IsTrue (dotnet.New (template), $"`dotnet new {template}` should succeed");
186-
File.WriteAllBytes (Path.Combine (dotnet.ProjectDirectory, "foo.jar"), Convert.FromBase64String (InlineData.JavaClassesJarBase64));
186+
File.WriteAllBytes (Path.Combine (dotnet.ProjectDirectory, "foo.jar"), InlineData.JavaSourceJarTestJar);
187187
Assert.IsTrue (dotnet.New ("android-activity"), "`dotnet new android-activity` should succeed");
188188
Assert.IsTrue (dotnet.New ("android-layout", Path.Combine (dotnet.ProjectDirectory, "Resources", "layout")), "`dotnet new android-layout` should succeed");
189189
Assert.IsTrue (dotnet.Build (), "`dotnet build` should succeed");
@@ -205,7 +205,7 @@ public void DotNetPack ([Values ("net6.0-android", "net6.0-android30")] string t
205205
BinaryContent = () => Array.Empty<byte> (),
206206
});
207207
proj.OtherBuildItems.Add (new AndroidItem.AndroidLibrary ("sub\\directory\\foo.jar") {
208-
BinaryContent = () => Convert.FromBase64String (InlineData.JavaClassesJarBase64),
208+
BinaryContent = () => InlineData.JavaSourceJarTestJar,
209209
});
210210
proj.OtherBuildItems.Add (new AndroidItem.AndroidLibrary ("sub\\directory\\arm64-v8a\\libfoo.so") {
211211
BinaryContent = () => Array.Empty<byte> (),
@@ -280,7 +280,7 @@ public void DotNetBuildBinding ()
280280
</metadata>",
281281
});
282282
proj.Sources.Add (new AndroidItem.AndroidLibrary ("javaclasses.jar") {
283-
BinaryContent = () => Convert.FromBase64String (InlineData.JavaClassesJarBase64)
283+
BinaryContent = () => InlineData.JavaSourceJarTestJar,
284284
});
285285
// TODO: bring back when Xamarin.Android.Bindings.Documentation.targets is working
286286
//proj.OtherBuildItems.Add (new BuildItem ("JavaSourceJar", "javasources.jar") {
@@ -350,7 +350,7 @@ public void DotNetBuild (string runtimeIdentifiers, bool isRelease)
350350
}
351351
};
352352
proj.OtherBuildItems.Add (new AndroidItem.InputJar ("javaclasses.jar") {
353-
BinaryContent = () => Convert.FromBase64String (InlineData.JavaClassesJarBase64)
353+
BinaryContent = () => InlineData.JavaSourceJarTestJar,
354354
});
355355
// TODO: bring back when Xamarin.Android.Bindings.Documentation.targets is working
356356
//proj.OtherBuildItems.Add (new BuildItem ("JavaSourceJar", "javasources.jar") {

‎src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/Xamarin.Android.Build.Tests.csproj‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,4 +38,16 @@
3838
</Content>
3939
</ItemGroup>
4040

41+
<ItemGroup>
42+
<EmbeddedResource Include="Resources\javasourcejartest.jar">
43+
<LogicalName>javasourcejartest.jar</LogicalName>
44+
</EmbeddedResource>
45+
<EmbeddedResource Include="Resources\javasourcejartest-sources.jar">
46+
<LogicalName>javasourcejartest-sources.jar</LogicalName>
47+
</EmbeddedResource>
48+
<EmbeddedResource Include="Resources\javasourcejartest-javadoc.jar">
49+
<LogicalName>javasourcejartest-javadoc.jar</LogicalName>
50+
</EmbeddedResource>
51+
</ItemGroup>
52+
4153
</Project>

0 commit comments

Comments
 (0)