Skip to content

Commit 16e0aa2

Browse files
jonpryorjonpryor
authored
[Xamarin.Android.Build.Tasks] Fix @(JavaDocJar) (#5479)
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"). Deprecate `@(JavaDocJar)`, and remove `Xamarin.Android.Bindings.Documentation.targets` from the .NET 6 installation packages. Support for `$(_UseLegacyJavadocImport)`=False won't exist for .NET 6; `@(JavaSourceJar)` support in .NET t will *only* use `java-source-utils.jar` (a7413a2). 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 518bda4 commit 16e0aa2

File tree

14 files changed

+180
-74
lines changed

14 files changed

+180
-74
lines changed

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -298,6 +298,22 @@ 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, and will not be
314+
supported in .NET 6.
315+
The `@(JavaSourceJar)` build action should be preferred.
316+
301317
## JavaSourceJar
302318

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

‎Documentation/release-notes/5479.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### Issues fixed
2+
3+
* [GitHub 2745](https://github.com/xamarin/xamarin-android/issues/2745):
4+
The `@(JavaDocJar)` build action would either cause an MSB3375 error,
5+
or wasn't used at all.
6+
7+
#### Deprecation of JavaDocJar Build action in favor of JavaSourceJar
8+
9+
The `@(JavaDocJar)` Build action is deprecated, and will not work in .NET 6.
10+
Please use the `@(JavaSourceJar)` build action.

‎build-tools/installers/create-installers.targets‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -239,7 +239,7 @@
239239
<_MSBuildFiles Include="$(MSBuildSrcDir)\Xamarin.Android.Bindings.targets" ExcludeFromAndroidNETSdk="true" />
240240
<_MSBuildFiles Include="$(MSBuildSrcDir)\Xamarin.Android.Bindings.ClassParse.targets" />
241241
<_MSBuildFiles Include="$(MSBuildSrcDir)\Xamarin.Android.Bindings.Core.targets" />
242-
<_MSBuildFiles Include="$(MSBuildSrcDir)\Xamarin.Android.Bindings.Documentation.targets" />
242+
<_MSBuildFiles Include="$(MSBuildSrcDir)\Xamarin.Android.Bindings.Documentation.targets" ExcludeFromAndroidNETSdk="true" />
243243
<_MSBuildFiles Include="$(MSBuildSrcDir)\Xamarin.Android.Bindings.JarToXml.targets" ExcludeFromAndroidNETSdk="true" />
244244
<_MSBuildFiles Include="$(MSBuildSrcDir)\Xamarin.Android.Build.Tasks.dll" />
245245
<_MSBuildFiles Include="$(MSBuildSrcDir)\Xamarin.Android.Build.Tasks.pdb" />

‎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: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -437,6 +437,30 @@ public void RemoveEventHandlerResolution ()
437437
}
438438
}
439439

440+
[Test]
441+
[Category ("DotNetIgnore")]
442+
public void JavaDocJar ()
443+
{
444+
var binding = new XamarinAndroidBindingProject () {
445+
AndroidClassParser = "class-parse",
446+
};
447+
binding.SetProperty ("DocumentationFile", "UnnamedProject.xml");
448+
using (var bindingBuilder = CreateDllBuilder ()) {
449+
binding.Jars.Add (new AndroidItem.EmbeddedJar ("javasourcejartest.jar") {
450+
BinaryContent = () => ResourceData.JavaSourceJarTestJar,
451+
});
452+
binding.OtherBuildItems.Add (new BuildItem ("JavaDocJar", "javasourcejartest-javadoc.jar") {
453+
BinaryContent = () => ResourceData.JavaSourceJarTestJavadocJar,
454+
});
455+
Assert.IsTrue (bindingBuilder.Build (binding), "binding build should have succeeded");
456+
457+
var cs_file = bindingBuilder.Output.GetIntermediaryPath (
458+
Path.Combine ("generated", "src", "Com.Xamarin.Android.Test.Msbuildtest.JavaSourceJarTest.cs"));
459+
FileAssert.Exists (cs_file);
460+
StringAssert.Contains ("Greet (string name, global::Java.Util.Date date)", File.ReadAllText (cs_file));
461+
}
462+
}
463+
440464
[Test]
441465
public void JavaSourceJar ()
442466
{
@@ -446,10 +470,10 @@ public void JavaSourceJar ()
446470
binding.SetProperty ("DocumentationFile", "UnnamedProject.xml");
447471
using (var bindingBuilder = CreateDllBuilder ()) {
448472
binding.Jars.Add (new AndroidItem.EmbeddedJar ("javasourcejartest.jar") {
449-
BinaryContent = () => Convert.FromBase64String (InlineData.JavaClassesJarBase64)
473+
BinaryContent = () => ResourceData.JavaSourceJarTestJar,
450474
});
451475
binding.OtherBuildItems.Add (new BuildItem ("JavaSourceJar", "javasourcejartest-sources.jar") {
452-
BinaryContent = () => Convert.FromBase64String (InlineData.JavaSourcesJarBase64)
476+
BinaryContent = () => ResourceData.JavaSourceJarTestSourcesJar,
453477
});
454478
Assert.IsTrue (bindingBuilder.Build (binding), "binding build should have succeeded");
455479

@@ -496,7 +520,7 @@ public void NullableReferenceTypes (string classParser)
496520
AndroidClassParser = classParser,
497521
Jars = {
498522
new AndroidItem.EmbeddedJar ("foo.jar") {
499-
BinaryContent = () => Convert.FromBase64String (InlineData.JavaClassesJarBase64),
523+
BinaryContent = () => ResourceData.JavaSourceJarTestJar,
500524
}
501525
}
502526
};

‎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: 0 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -8,61 +8,6 @@ namespace Xamarin.Android.Build.Tests
88
{
99
static class InlineData
1010
{
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==";
65-
6611
const string Resx = @"<?xml version=""1.0"" encoding=""utf-8""?>
6712
<root>
6813
<resheader name=""resmimetype"">

0 commit comments

Comments
 (0)