Add --doc, --sources, and --transitive options to publishLocal command (forwardport #4697)

example/javalib/publishing/2-publish-module/build.mill

@@ -27,3 +27,12 @@ object foo extends JavaModule with PublishModule {
 Publishing Artifact(com.lihaoyi,foo,0.0.1) to ivy repo...
 
 */
+
+// `publishLocal` accepts options like `--doc=false` and `--sources=false`,
+// to disable publishing javadoc JARs and source JARs, which are generated and
+// published by default. This can be helpful if you're not interested in javadoc JARs,
+// and javadoc generation fails, and you would rather address those errors later for example.
+
+// `publishLocal` also accepts `--transitive=true`, to also publish locally the
+// transitive dependencies of the module being published. This ensures the module
+// can be resolved from the local repository, with no missing dependencies.

example/kotlinlib/publishing/2-publish-module/build.mill

@@ -32,3 +32,12 @@ object foo extends KotlinModule with PublishModule {
 Publishing Artifact(com.lihaoyi,foo,0.0.1) to ivy repo...
 
 */
+
+// `publishLocal` accepts options like `--doc=false` and `--sources=false`,
+// to disable publishing javadoc JARs and source JARs, which are generated and
+// published by default. This can be helpful if you're not interested in javadoc JARs,
+// and javadoc generation fails, and you would rather address those errors later for example.
+
+// `publishLocal` also accepts `--transitive=true`, to also publish locally the
+// transitive dependencies of the module being published. This ensures the module
+// can be resolved from the local repository, with no missing dependencies.

example/scalalib/publishing/2-publish-module/build.mill

@@ -38,3 +38,14 @@ Publishing Artifact(com.lihaoyi,foo_2.13,0.0.1) to ivy repo...
 // is useful as a lightweight way of testing out the published artifacts, without
 // the setup overhead and long latencies of publishing artifacts globally accessible
 // to anyone in the world.
+
+// `publishLocal` accepts options like `--doc=false` and `--sources=false`,
+// to disable publishing javadoc JARs and source JARs, which are generated and
+// published by default. This can be helpful if you're not interested in javadoc JARs,
+// and javadoc generation fails or takes too much time. When using Scala 2, disabling
+// javadoc generation can bring large speedups, given it entails compiling your code
+// a second time.
+
+// `publishLocal` also accepts `--transitive=true`, to also publish locally the
+// transitive dependencies of the module being published. This ensures the module
+// can be resolved from the local repository, with no missing dependencies.

scalalib/src/mill/scalalib/PublishModule.scala

@@ -307,9 +307,7 @@ trait PublishModule extends JavaModule { outer =>
       pomPackagingType match {
         case PackagingType.Pom => Task.Anon(Seq())
         case _ => Task.Anon(Seq(
-            (jar(), PublishInfo.jar),
-            (sourceJar(), PublishInfo.sourcesJar),
-            (docJar(), PublishInfo.docJar)
+            (jar(), PublishInfo.jar)
           ))
       }
     }
@@ -336,34 +334,83 @@ trait PublishModule extends JavaModule { outer =>
    * Publish artifacts to a local ivy repository.
    * @param localIvyRepo The local ivy repository.
    *                     If not defined, the default resolution is used (probably `$HOME/.ivy2/local`).
+   * @param sources whether to generate and publish a sources JAR
+   * @param doc whether to generate and publish a javadoc JAR
+   * @param transitive if true, also publish locally the transitive module dependencies of this module
+   *                   (this includes the runtime transitive module dependencies, but not the compile-only ones)
    */
-  def publishLocal(localIvyRepo: String = null): define.Command[Unit] = Task.Command {
-    publishLocalTask(Task.Anon {
-      Option(localIvyRepo).map(os.Path(_, Task.workspace))
-    })()
+  def publishLocal(
+      localIvyRepo: String = null,
+      sources: Boolean = true,
+      doc: Boolean = true,
+      transitive: Boolean = false
+  ): define.Command[Unit] = Task.Command {
+    publishLocalTask(
+      Task.Anon {
+        Option(localIvyRepo).map(os.Path(_, Task.workspace))
+      },
+      sources,
+      doc,
+      transitive
+    )()
     Result.Success(())
   }
 
+  // bin-compat shim
+  def publishLocal(
+      localIvyRepo: String
+  ): define.Command[Unit] =
+    publishLocal(localIvyRepo, sources = true, doc = true, transitive = false)
+
   /**
    * Publish artifacts the local ivy repository.
    */
   def publishLocalCached: T[Seq[PathRef]] = Task {
-    publishLocalTask(Task.Anon(None))().map(p => PathRef(p).withRevalidateOnce)
+    val res = publishLocalTask(
+      Task.Anon(None),
+      sources = true,
+      doc = true,
+      transitive = false
+    )()
+    res.map(p => PathRef(p).withRevalidateOnce)
   }
 
-  private def publishLocalTask(localIvyRepo: Task[Option[os.Path]]): Task[Seq[Path]] = Task.Anon {
-    val publisher = localIvyRepo() match {
-      case None => LocalIvyPublisher
-      case Some(path) => new LocalIvyPublisher(path)
+  private def publishLocalTask(
+      localIvyRepo: Task[Option[os.Path]],
+      sources: Boolean,
+      doc: Boolean,
+      transitive: Boolean
+  ): Task[Seq[Path]] =
+    if (transitive) {
+      val publishTransitiveModuleDeps = (transitiveModuleDeps ++ transitiveRunModuleDeps).collect {
+        case p: PublishModule => p
+      }
+      Target.traverse(publishTransitiveModuleDeps.distinct) { publishMod =>
+        publishMod.publishLocalTask(localIvyRepo, sources, doc, transitive = false)
+      }.map(_.flatten)
+    } else {
+      val sourcesJarOpt =
+        if (sources) Task.Anon(Some(PublishInfo.sourcesJar(sourceJar())))
+        else Task.Anon(None)
+      val docJarOpt =
+        if (doc) Task.Anon(Some(PublishInfo.docJar(docJar())))
+        else Task.Anon(None)
+
+      Task.Anon {
+        val publisher = localIvyRepo() match {
+          case None => LocalIvyPublisher
+          case Some(path) => new LocalIvyPublisher(path)
+        }
+        val publishInfos =
+          defaultPublishInfos() ++ sourcesJarOpt().toSeq ++ docJarOpt().toSeq ++ extraPublish()
+        publisher.publishLocal(
+          pom = pom().path,
+          ivy = Right(ivy().path),
+          artifact = artifactMetadata(),
+          publishInfos = publishInfos
+        )
+      }
     }
-    val publishInfos = defaultPublishInfos() ++ extraPublish()
-    publisher.publishLocal(
-      pom = pom().path,
-      ivy = Right(ivy().path),
-      artifact = artifactMetadata(),
-      publishInfos = publishInfos
-    )
-  }
 
   /**
    * Publish artifacts to a local Maven repository.
@@ -396,7 +443,12 @@ trait PublishModule extends JavaModule { outer =>
 
   private def publishM2LocalTask(m2RepoPath: Task[os.Path]): Task[Seq[PathRef]] = Task.Anon {
     val path = m2RepoPath()
-    val publishInfos = defaultPublishInfos() ++ extraPublish()
+    val publishInfos = defaultPublishInfos() ++
+      Seq(
+        PublishInfo.sourcesJar(sourceJar()),
+        PublishInfo.docJar(docJar())
+      ) ++
+      extraPublish()
 
     new LocalM2Publisher(path)
       .publish(pom().path, artifactMetadata(), publishInfos)

scalalib/test/src/mill/scalalib/PublishModuleTests.scala

@@ -82,18 +82,20 @@ object PublishModuleTests extends TestSuite {
     lazy val millDiscover = Discover[this.type]
   }
 
-  trait TestPublishModule extends PublishModule {
-    def publishVersion = "0.1.0-SNAPSHOT"
-    def pomSettings = PomSettings(
-      organization = "com.lihaoyi.pubmodtests",
-      description = "test thing",
-      url = "https://github.com/com-lihaoyi/mill",
-      licenses = Seq(License.Common.Apache2),
-      versionControl = VersionControl.github("com-lihaoyi", "mill"),
-      developers = Nil
-    )
-  }
   object compileAndRuntimeStuff extends TestBaseModule {
+    def organization = "com.lihaoyi.pubmodtests"
+    def version = "0.1.0-SNAPSHOT"
+    trait TestPublishModule extends PublishModule {
+      def publishVersion = version
+      def pomSettings = PomSettings(
+        organization = organization,
+        description = "test thing",
+        url = "https://github.com/com-lihaoyi/mill",
+        licenses = Seq(License.Common.Apache2),
+        versionControl = VersionControl.github("com-lihaoyi", "mill"),
+        developers = Nil
+      )
+    }
     object main extends JavaModule with TestPublishModule {
       def ivyDeps = Seq(
         ivy"org.slf4j:slf4j-api:2.0.15"
@@ -343,6 +345,148 @@ object PublishModuleTests extends TestSuite {
       runtimeClassPathCheck(ivy2RuntimeTransitiveRunCp)
       runtimeClassPathCheck(m2RuntimeTransitiveRunCp)
     }
+
+    test("docSourcesArgs") - UnitTester(compileAndRuntimeStuff, null).scoped { eval =>
+      val ivy2Repo = eval.evaluator.workspace / "ivy2Local"
+      val moduleName = "main"
+      val subDir =
+        os.sub / compileAndRuntimeStuff.organization / moduleName / compileAndRuntimeStuff.version
+      def repoHasIvyXml(): Boolean =
+        os.isFile(ivy2Repo / subDir / "ivys/ivy.xml")
+      def repoHasJar(): Boolean =
+        os.isFile(ivy2Repo / subDir / "jars" / s"$moduleName.jar")
+      def repoHasSourcesJar(): Boolean =
+        os.isFile(ivy2Repo / subDir / "srcs" / s"$moduleName-sources.jar")
+      def repoHasDocJar(): Boolean =
+        os.isFile(ivy2Repo / subDir / "docs" / s"$moduleName-javadoc.jar")
+      def clearRepo(): Unit =
+        os.remove.all(ivy2Repo)
+
+      eval(compileAndRuntimeStuff.main.publishLocal(ivy2Repo.toString)).right.get
+      assert(repoHasIvyXml())
+      assert(repoHasJar())
+      assert(repoHasSourcesJar())
+      assert(repoHasDocJar())
+
+      clearRepo()
+
+      eval(compileAndRuntimeStuff.main.publishLocal(ivy2Repo.toString, doc = false)).right.get
+      assert(repoHasIvyXml())
+      assert(repoHasJar())
+      assert(repoHasSourcesJar())
+      assert(!repoHasDocJar())
+
+      clearRepo()
+
+      eval(compileAndRuntimeStuff.main.publishLocal(
+        ivy2Repo.toString,
+        doc = false,
+        sources = false
+      )).right.get
+      assert(repoHasIvyXml())
+      assert(repoHasJar())
+      assert(!repoHasSourcesJar())
+      assert(!repoHasDocJar())
+    }
+
+    test("transitive") - UnitTester(compileAndRuntimeStuff, null).scoped { eval =>
+      val ivy2Repo = eval.evaluator.workspace / "ivy2Local"
+      val mainModuleName = "main"
+      val transitiveModuleName = "transitive"
+      val runtimeTransitiveModuleName = "runtimeTransitive"
+      def subDir(moduleName: String) =
+        os.sub / compileAndRuntimeStuff.organization / moduleName / compileAndRuntimeStuff.version
+      def repoHasIvyXml(moduleName: String): Boolean =
+        os.isFile(ivy2Repo / subDir(moduleName) / "ivys/ivy.xml")
+      def repoHasJar(moduleName: String): Boolean =
+        os.isFile(ivy2Repo / subDir(moduleName) / "jars" / s"$moduleName.jar")
+      def repoHasSourcesJar(moduleName: String): Boolean =
+        os.isFile(ivy2Repo / subDir(moduleName) / "srcs" / s"$moduleName-sources.jar")
+      def repoHasDocJar(moduleName: String): Boolean =
+        os.isFile(ivy2Repo / subDir(moduleName) / "docs" / s"$moduleName-javadoc.jar")
+      def clearRepo(): Unit =
+        os.remove.all(ivy2Repo)
+
+      eval(compileAndRuntimeStuff.transitive.publishLocal(ivy2Repo.toString)).right.get
+      assert(!repoHasIvyXml(mainModuleName))
+      assert(!repoHasJar(mainModuleName))
+      assert(!repoHasSourcesJar(mainModuleName))
+      assert(!repoHasDocJar(mainModuleName))
+      assert(repoHasIvyXml(transitiveModuleName))
+      assert(repoHasJar(transitiveModuleName))
+      assert(repoHasSourcesJar(transitiveModuleName))
+      assert(repoHasDocJar(transitiveModuleName))
+
+      clearRepo()
+
+      eval(compileAndRuntimeStuff.transitive.publishLocal(
+        ivy2Repo.toString,
+        transitive = true
+      )).right.get
+      assert(repoHasIvyXml(mainModuleName))
+      assert(repoHasJar(mainModuleName))
+      assert(repoHasSourcesJar(mainModuleName))
+      assert(repoHasDocJar(mainModuleName))
+      assert(repoHasIvyXml(transitiveModuleName))
+      assert(repoHasJar(transitiveModuleName))
+      assert(repoHasSourcesJar(transitiveModuleName))
+      assert(repoHasDocJar(transitiveModuleName))
+
+      clearRepo()
+
+      eval(compileAndRuntimeStuff.transitive.publishLocal(ivy2Repo.toString, doc = false)).right.get
+      assert(!repoHasIvyXml(mainModuleName))
+      assert(!repoHasJar(mainModuleName))
+      assert(!repoHasSourcesJar(mainModuleName))
+      assert(!repoHasDocJar(mainModuleName))
+      assert(repoHasIvyXml(transitiveModuleName))
+      assert(repoHasJar(transitiveModuleName))
+      assert(repoHasSourcesJar(transitiveModuleName))
+      assert(!repoHasDocJar(transitiveModuleName))
+
+      clearRepo()
+
+      eval(compileAndRuntimeStuff.transitive.publishLocal(
+        ivy2Repo.toString,
+        doc = false,
+        transitive = true
+      )).right.get
+      assert(repoHasIvyXml(mainModuleName))
+      assert(repoHasJar(mainModuleName))
+      assert(repoHasSourcesJar(mainModuleName))
+      assert(!repoHasDocJar(mainModuleName))
+      assert(repoHasIvyXml(transitiveModuleName))
+      assert(repoHasJar(transitiveModuleName))
+      assert(repoHasSourcesJar(transitiveModuleName))
+      assert(!repoHasDocJar(transitiveModuleName))
+
+      clearRepo()
+
+      eval(compileAndRuntimeStuff.runtimeTransitive.publishLocal(ivy2Repo.toString)).right.get
+      assert(!repoHasIvyXml(mainModuleName))
+      assert(!repoHasJar(mainModuleName))
+      assert(!repoHasSourcesJar(mainModuleName))
+      assert(!repoHasDocJar(mainModuleName))
+      assert(repoHasIvyXml(runtimeTransitiveModuleName))
+      assert(repoHasJar(runtimeTransitiveModuleName))
+      assert(repoHasSourcesJar(runtimeTransitiveModuleName))
+      assert(repoHasDocJar(runtimeTransitiveModuleName))
+
+      clearRepo()
+
+      eval(compileAndRuntimeStuff.runtimeTransitive.publishLocal(
+        ivy2Repo.toString,
+        transitive = true
+      )).right.get
+      assert(repoHasIvyXml(mainModuleName))
+      assert(repoHasJar(mainModuleName))
+      assert(repoHasSourcesJar(mainModuleName))
+      assert(repoHasDocJar(mainModuleName))
+      assert(repoHasIvyXml(runtimeTransitiveModuleName))
+      assert(repoHasJar(runtimeTransitiveModuleName))
+      assert(repoHasSourcesJar(runtimeTransitiveModuleName))
+      assert(repoHasDocJar(runtimeTransitiveModuleName))
+    }
   }
 
 }