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.
2024-09-11 04:45:57 +03:00 · 2019-05-14 09:40:30 +02:00 · 2019-05-14 09:40:30 +02:00 · 6f6f3337c7
commit 6f6f3337c7
parent 838b81d3da
10 changed files with 145 additions and 56 deletions
--- a/bazel_tools/java.bzl
+++ b/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):
-    _wrap_rule(native.java_library, name, **kwargs)
+def da_java_library(
+        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(
--- a/bazel_tools/pom_template.xml
+++ b/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>
--- a/deps.bzl
+++ b/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"],
+        )
--- a/docs/BUILD.bazel
+++ b/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
-        tar -zxf ../$(locations //language-support/java:javadocs) -C html/app-dev/bindings-java
+        # Copy Javadoc using unzip to avoid having to know the path to the 'jar' binary.
+        unzip -f ../$(locations //language-support/java:javadoc) -d html/app-dev/bindings-java

        # Copy in hoogle DB
        mkdir -p html/hoogle_db
--- a/docs/source/support/release-notes.rst
+++ b/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.

--- a/language-support/java/BUILD.bazel
+++ b/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(
-    name = "javadocs",
+javadoc_library(
+    name = "javadoc",
    srcs = [
-        "//language-support/java/bindings-rxjava:sources",
        "//language-support/java/bindings:sources",
-        "//language-support/java/bindings-rxjava",
-        "//language-support/java/bindings:bindings-java",
-        "//external:jar/org/slf4j/slf4j_api",
-        "//ledger-api/rs-grpc-bridge",
-        "//external:jar/io/reactivex/rxjava2/rxjava",
-        "//external:jar/com/google/protobuf/protobuf_java",
-        "//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",
+        "//language-support/java/bindings-rxjava:sources",
+    ],
+    root_packages = [
+        "com.daml.ledger.javaapi.data",
+        "com.daml.ledger.rxjava",
+        "com.digitalasset.ledger.api.v1",
    ],
-    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",
+    ],
 )
--- a/language-support/java/bindings-rxjava/BUILD.bazel
+++ b/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",
--- a/language-support/java/bindings/BUILD.bazel
+++ b/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",
    ],
--- a/ledger-api/rs-grpc-bridge/BUILD.bazel
+++ b/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",
    ],
--- a/release/src/Util.hs
+++ b/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) =