Fixes 895: Improve DA Bazel rules for building javadocs. (#896)

* Fixes 895: Improve DA Bazel rules for building javadocs.

Extend the da_java_library Bazel macro to also build the Javadoc for the
target. Add the Javadoc artefacts to the release procedure.

bazel_tools/java.bzl

@@ -2,6 +2,8 @@
 # SPDX-License-Identifier: Apache-2.0
 
 load("//bazel_tools:pom_file.bzl", "pom_file")
+load("@os_info//:os_info.bzl", "is_windows")
+load("@com_github_google_bazel_common//tools/javadoc:javadoc.bzl", "javadoc_library")
 
 _java_home_runtime_build_template = """
 java_runtime(
@@ -29,14 +31,53 @@ java_home_runtime = repository_rule(
 def _wrap_rule(rule, name = "", **kwargs):
     rule(name = name, **kwargs)
 
-def da_java_library(name, **kwargs):
+def da_java_library(
-    _wrap_rule(native.java_library, name, **kwargs)
+        name,
+        deps,
+        srcs,
+        data = [],
+        resources = [],
+        resource_jars = [],
+        resource_strip_prefix = None,
+        tags = [],
+        visibility = None,
+        exports = [],
+        **kwargs):
+    root_packages = None
+    for tag in tags:
+        if tag.startswith("javadoc_root_packages="):
+            root_packages = tag[len("javadoc_root_packages="):].split(":")
+
+    native.java_library(
+        name = name,
+        deps = deps,
+        srcs = srcs,
+        data = data,
+        resources = resources,
+        resource_jars = resource_jars,
+        resource_strip_prefix = resource_strip_prefix,
+        tags = tags,
+        visibility = visibility,
+        exports = exports,
+        **kwargs
+    )
     pom_file(
         name = name + "_pom",
+        tags = tags,
         target = ":" + name,
         visibility = ["//visibility:public"],
     )
 
+    # Disable the building of Javadoc on Windows as the rule fails to
+    # find the sources under Windows.
+    if root_packages and is_windows == False:
+        javadoc_library(
+            name = name + "_javadoc",
+            deps = deps + [name],
+            srcs = srcs,
+            root_packages = root_packages,
+        )
+
 def da_java_binary(name, **kwargs):
     _wrap_rule(native.java_binary, name, **kwargs)
     pom_file(

bazel_tools/pom_template.xml

@@ -7,6 +7,34 @@
   <artifactId>{artifactId}</artifactId>
   <version>{version}</version>
   <packaging>jar</packaging>
+
+  <name>{artifactId}</name>
+  <description>TBD</description>
+  <url>https://github.com/digital-asset/daml</url>
+
+  <licenses>
+    <license>
+      <name>Apache License, Version 2.0</name>
+      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+      <distribution>repo</distribution>
+    </license>
+  </licenses>
+
+  <developers>
+    <developer>
+      <name>Digital Asset SDK Feedback</name>
+      <email>sdk-feedback@digitalasset.com</email>
+      <organization>Digital Asset (Switzerland) GmbH</organization>
+      <organizationUrl>http://www.daml.com</organizationUrl>
+    </developer>
+  </developers>
+
+  <scm>
+    <connection>scm:git:git://github.com/digital-asset/daml.git</connection>
+    <developerConnection>scm:git:ssh://github.com:digital-asset/daml.git</developerConnection>
+    <url>http://github.com/digital-asset/daml/tree/master</url>
+  </scm>
+
   <dependencies>
 {generated_bzl_deps}
   </dependencies>

deps.bzl

@@ -232,3 +232,11 @@ java_import(
         name = "gson",
         actual = "@com_google_code_gson_gson//jar",
     )
+
+    if "com_github_google_bazel_common" not in native.existing_rules():
+        http_archive(
+            name = "com_github_google_bazel_common",
+            sha256 = "ccdd09559b49c7efd9e4b0b617b18e2a4bbdb2142fc30dfd3501eb5fa1294dcc",
+            strip_prefix = "bazel-common-f3dc1a775d21f74fc6f4bbcf076b8af2f6261a69",
+            urls = ["https://github.com/google/bazel-common/archive/f3dc1a775d21f74fc6f4bbcf076b8af2f6261a69.zip"],
+        )

docs/BUILD.bazel

@@ -157,7 +157,7 @@ genrule(
         ":theme",
         "//daml-foundations/daml-ghc:daml-base-rst-docs",
         "//daml-foundations/daml-ghc:daml-base-hoogle-docs",
-        "//language-support/java:javadocs",
+        "//language-support/java:javadoc",
     ],
     outs = ["html-only.tar.gz"],
     cmd = ("""
@@ -186,8 +186,8 @@ genrule(
             exit 1
         fi
 
-        # Copy Javadoc
+        # Copy Javadoc using unzip to avoid having to know the path to the 'jar' binary.
-        tar -zxf ../$(locations //language-support/java:javadocs) -C html/app-dev/bindings-java
+        unzip -f ../$(locations //language-support/java:javadoc) -d html/app-dev/bindings-java
 
         # Copy in hoogle DB
         mkdir -p html/hoogle_db

docs/source/support/release-notes.rst

@@ -118,6 +118,19 @@ Java Bindings
 - **Ledger API**: Added three new methods to the :ref:`CommandService <com.digitalasset.ledger.api.v1.commandservice>`:
 
   - ``SubmitAndWaitForTransactionId`` returns the transaction ID.
+- Beta release of the Windows SDK:
+  You can download the installer from
+  `GitHub releases <https://github.com/digital-asset/daml/releases>`_.
+  The Windows SDK ships with the new `daml` installer which will soon also
+  become the default on Linux and MacOS. Documentation is still in progress,
+  take a look at the `Migration guide <https://github.com/digital-asset/daml/pull/768>`_
+  and the `updated documentation <https://github.com/digital-asset/daml/pull/740>`_.
+- Add ``fromListWith`` and ``merge`` to ``DA.TextMap``.
+- Release Javadoc artifacts as part of the SDK. See more `here https://github.com/digital-asset/daml/pull/896`
+- Add ``DA.Next.Map`` and ``DA.Next.Set`` and deprecate ``DA.Map`` and ``DA.Set`` in favor of those.
+- Ledger API: Added three new methods to :ref:`CommandService <com.digitalasset.ledger.api.v1.commandservice>`:
+
+  - ``SubmitAndWaitForTransactionId`` returns the transaction id.
   - ``SubmitAndWaitForTransaction`` returns the transaction.
   - ``SubmitAndWaitForTransactionTree`` returns the transaction tree.
 

language-support/java/BUILD.bazel

@@ -1,50 +1,35 @@
 # Copyright (c) 2019 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-load("@os_info//:os_info.bzl", "is_windows")
+load("@com_github_google_bazel_common//tools/javadoc:javadoc.bzl", "javadoc_library")
 
-genrule(
+javadoc_library(
-    name = "javadocs",
+    name = "javadoc",
     srcs = [
-        "//language-support/java/bindings-rxjava:sources",
         "//language-support/java/bindings:sources",
-        "//language-support/java/bindings-rxjava",
+        "//language-support/java/bindings-rxjava:sources",
-        "//language-support/java/bindings:bindings-java",
+    ],
-        "//external:jar/org/slf4j/slf4j_api",
+    root_packages = [
-        "//ledger-api/rs-grpc-bridge",
+        "com.daml.ledger.javaapi.data",
-        "//external:jar/io/reactivex/rxjava2/rxjava",
+        "com.daml.ledger.rxjava",
-        "//external:jar/com/google/protobuf/protobuf_java",
+        "com.digitalasset.ledger.api.v1",
-        "//external:jar/org/pcollections/pcollections",
-        "//external:jar/org/checkerframework/checker",
-        "//external:jar/io/grpc/grpc_netty",
-        "//external:jar/io/grpc/grpc_core",
-        "//external:jar/io/grpc/grpc_stub",
-        "//external:jar/io/netty/netty_handler",
-        "//external:jar/com/google/code/findbugs/jsr305",
     ],
-    outs = ["javadocs.tar.gz"],
-    cmd = """
-        CP=$(location //external:jar/org/slf4j/slf4j_api)
-        CP=$$CP{delim}$(location //language-support/java/bindings-rxjava:bindings-rxjava)
-        CP=$$CP{delim}$(location //language-support/java/bindings:bindings-java)
-        CP=$$CP{delim}$(location //ledger-api/rs-grpc-bridge:rs-grpc-bridge)
-        CP=$$CP{delim}$(location //external:jar/io/reactivex/rxjava2/rxjava)
-        CP=$$CP{delim}$(location //external:jar/com/google/protobuf/protobuf_java)
-        CP=$$CP{delim}$(location //external:jar/org/pcollections/pcollections)
-        CP=$$CP{delim}$(location //external:jar/org/checkerframework/checker)
-        CP=$$CP{delim}$(location //external:jar/io/grpc/grpc_netty)
-        CP=$$CP{delim}$(location //external:jar/io/grpc/grpc_core)
-        CP=$$CP{delim}$(location //external:jar/io/grpc/grpc_stub)
-        CP=$$CP{delim}$(location //external:jar/io/netty/netty_handler)
-        CP=$$CP{delim}$(location //external:jar/com/google/code/findbugs/jsr305)
-        echo $$CP
-        $(location @javadoc_dev_env//:javadoc) -quiet -d javadocs -classpath $$CP $(locations //language-support/java/bindings-rxjava:sources) $(locations //language-support/java/bindings:sources)
-        tar -zcf $(location javadocs.tar.gz) javadocs
-    """.format(
-        delim = "\;" if is_windows else ":",
-    ),
-    tools = ["@javadoc_dev_env//:javadoc"],
     visibility = [
         "//visibility:public",
     ],
+    deps = [
+        "//external:jar/com/google/code/findbugs/jsr305",
+        "//external:jar/com/google/protobuf/protobuf_java",
+        "//external:jar/io/grpc/grpc_core",
+        "//external:jar/io/grpc/grpc_netty",
+        "//external:jar/io/grpc/grpc_stub",
+        "//external:jar/io/netty/netty_handler",
+        "//external:jar/io/reactivex/rxjava2/rxjava",
+        "//external:jar/org/checkerframework/checker",
+        "//external:jar/org/pcollections/pcollections",
+        "//external:jar/org/slf4j/slf4j_api",
+        "//language-support/java/bindings:bindings-java",
+        "//language-support/java/bindings-rxjava",
+        "//ledger-api/rs-grpc-bridge",
+    ],
 )

language-support/java/bindings-rxjava/BUILD.bazel

@@ -7,11 +7,15 @@ load(
     "da_scala_test_suite",
 )
 load("//bazel_tools:pom_file.bzl", "pom_file")
+load("//bazel_tools:java.bzl", "da_java_library")
 
-java_library(
+da_java_library(
     name = "bindings-rxjava",
     srcs = glob(["src/main/java/**/*.java"]),
-    tags = ["maven_coordinates=com.daml.ledger:bindings-rxjava:__VERSION__"],
+    tags = [
+        "javadoc_root_packages=com.daml.ledger.rxjava",
+        "maven_coordinates=com.daml.ledger:bindings-rxjava:__VERSION__",
+    ],
     visibility = [
         "//visibility:public",
     ],
@@ -31,12 +35,6 @@ java_library(
     ],
 )
 
-pom_file(
-    name = "bindings-rxjava_pom",
-    target = ":bindings-rxjava",
-    visibility = ["//visibility:public"],
-)
-
 testDependencies = [
     "//3rdparty/jvm/io/grpc:grpc_core",
     "//3rdparty/jvm/io/grpc:grpc_netty",

language-support/java/bindings/BUILD.bazel

@@ -52,7 +52,10 @@ da_java_library(
         ":ledger-api-java",
         ":ledger-api-java-grpc",
     ],
-    tags = ["maven_coordinates=com.daml.ledger:bindings-java:__VERSION__"],
+    tags = [
+        "javadoc_root_packages=com.daml.ledger.javaapi.data",
+        "maven_coordinates=com.daml.ledger:bindings-java:__VERSION__",
+    ],
     visibility = [
         "//visibility:public",
     ],

ledger-api/rs-grpc-bridge/BUILD.bazel

@@ -7,7 +7,10 @@ load("//bazel_tools:java.bzl", "da_java_library")
 da_java_library(
     name = "rs-grpc-bridge",
     srcs = glob(["src/main/java/**/*.java"]),
-    tags = ["maven_coordinates=com.digitalasset.ledger-api:rs-grpc-bridge:__VERSION__"],
+    tags = [
+        "javadoc_root_packages=com.digitalasset.grpc.adapter",
+        "maven_coordinates=com.digitalasset.ledger-api:rs-grpc-bridge:__VERSION__",
+    ],
     visibility = [
         "//visibility:public",
     ],

release/src/Util.hs

@@ -128,7 +128,8 @@ buildTargets art@Artifact{..} =
                 (directory, _) = splitBazelTarget artTarget
             in [jarTarget, pomTar] <>
                [BazelTarget ("//" <> directory <> ":" <> srcJar) | Just srcJar <- pure (sourceJarName art)] <>
-               [BazelTarget ("//" <> directory <> ":" <> srcJar) | Just srcJar <- pure (scalaSourceJarName art)]
+               [BazelTarget ("//" <> directory <> ":" <> srcJar) | Just srcJar <- pure (scalaSourceJarName art)] <>
+               [BazelTarget ("//" <> directory <> ":" <> javadocJar) | Just javadocJar <- pure (javadocJarName art)]
         Zip -> [artTarget]
         TarGz -> [artTarget]
 
@@ -216,6 +217,11 @@ scalaSourceJarName Artifact{..}
   | Jar Scala <- artReleaseType = Just $ snd (splitBazelTarget artTarget) <> "_src.jar"
   | otherwise = Nothing
 
+javadocJarName :: Artifact a -> Maybe Text
+javadocJarName Artifact{..}
+  | Jar Lib <- artReleaseType = Just $ snd (splitBazelTarget artTarget) <> "_javadoc.jar"
+  | otherwise = Nothing
+
 -- | Given an artifact, produce a list of pairs of an input file and the corresponding output file.
 artifactFiles :: E.MonadThrow m => AllArtifacts -> Artifact PomData -> m [(Path Rel File, Path Rel File)]
 artifactFiles allArtifacts art@Artifact{..} = do
@@ -238,11 +244,15 @@ artifactFiles allArtifacts art@Artifact{..} = do
     mbScalaSourceJarIn <- traverse (parseRelFile . unpack) (scalaSourceJarName art)
     scalaSourceJarOut <- parseRelFile (unpack (pomArtifactId #"-"# pomVersion # ostxt # "-sources" # mainExt artReleaseType))
 
+    mbJavadocJarIn <- traverse (parseRelFile . unpack) (javadocJarName art)
+    javadocJarOut <- parseRelFile (unpack (pomArtifactId #"-"# pomVersion # ostxt # "-javadoc" # mainExt artReleaseType))
+
     pure $
         [(directory </> mainArtifactIn, outDir </> mainArtifactOut) | shouldRelease allArtifacts artPlatformDependent] <>
         [(directory </> pomFileIn, outDir </> pomFileOut) | isJar artReleaseType, shouldRelease allArtifacts (PlatformDependent False)] <>
         [(directory </> sourceJarIn, outDir </> sourceJarOut) | shouldRelease allArtifacts (PlatformDependent False), Just sourceJarIn <- pure mbSourceJarIn] <>
-        [(directory </> scalaSourceJarIn, outDir </> scalaSourceJarOut) | shouldRelease allArtifacts (PlatformDependent False), Just scalaSourceJarIn <- pure mbScalaSourceJarIn]
+        [(directory </> scalaSourceJarIn, outDir </> scalaSourceJarOut) | shouldRelease allArtifacts (PlatformDependent False), Just scalaSourceJarIn <- pure mbScalaSourceJarIn] <>
+        [(directory </> javadocJarIn, outDir </> javadocJarOut) | shouldRelease allArtifacts (PlatformDependent False), Just javadocJarIn <- pure mbJavadocJarIn]
 
 shouldRelease :: AllArtifacts -> PlatformDependent -> Bool
 shouldRelease (AllArtifacts allArtifacts) (PlatformDependent platformDependent) =