Add mill.api.Debug helper (#6311)

Easier to use than constantly writing
`mill.constants.DebugLog.println("foo " + pprint.apply(foo))`

Also add a check that `DebugLog.println` isn't run in CI, so we don't
accidentally forget to remove some calls before publishing

Author: lihaoyi

core/api/src/mill/api/Debug.scala

@@ -0,0 +1,33 @@
+package mill.api
+
+import mill.api.daemon.experimental
+
+import java.io.{ByteArrayOutputStream, PrintStream}
+
+@experimental
+object Debug {
+  def apply[T](
+      x: sourcecode.Text[T],
+      tag: String = "",
+      width: Int = 100,
+      height: Int = 500,
+      indent: Int = 2,
+      escapeUnicode: Boolean = true,
+      showFieldNames: Boolean = true
+  )(implicit line: sourcecode.Line, fileName: sourcecode.FileName): T = {
+
+    val baos = new ByteArrayOutputStream()
+    pprint.logTo(
+      x,
+      tag,
+      width,
+      height,
+      indent,
+      escapeUnicode,
+      showFieldNames,
+      new PrintStream(baos)
+    )
+    mill.constants.DebugLog.println(baos.toString)
+    x.value
+  }
+}

core/constants/src/mill/constants/DebugLog.java

@@ -14,6 +14,10 @@ public static synchronized void apply(String s) {
   }
 
   public static synchronized void println(String s) {
+    if (System.getenv("CI") != null) {
+      throw new RuntimeException("DebugLog cannot be run in CI");
+    }
+    
     Path path = Paths.get(System.getProperty("user.home"), "mill-debug-log.txt");
     try {
       if (!Files.exists(path)) Files.createFile(path);

developer.adoc

@@ -33,9 +33,9 @@ The following table contains the main ways you can test the code in
 
 In general, `println` or `pprint.log` should work in most places and be sufficient for
 instrumenting and debugging the Mill codebase. In the occasional spot where `println`
-doesn't work you can use `mill.constants.DebugLog.println` which writes to a file
-`~/mill-debug-log.txt` in your home folder. `DebugLog` is useful for scenarios like
-debugging Mill's terminal UI (where `println` would mess things up) or subprocesses
+doesn't work you can use `mill.constants.DebugLog.println`/`mill.api.Debug` which writes
+to a file `~/mill-debug-log.txt` in your home folder. `DebugLog` is useful for scenarios
+like debugging Mill's terminal UI (where `println` would mess things up) or subprocesses
 (where stdout/stderr may get captured or used and cannot be used to display your own
 debug statements).
 

integration/ide/gen-idea/resources/extended/idea/mill_modules/mill-build.iml

@@ -96,7 +96,7 @@
         <orderEntry type="library" scope="RUNTIME" name="plexus-container-default-2.1.1.jar" level="project"/>
         <orderEntry type="library" scope="RUNTIME" name="plexus-io-3.5.1.jar" level="project"/>
         <orderEntry type="library" scope="RUNTIME" name="plexus-utils-4.0.2.jar" level="project"/>
-        <orderEntry type="library" name="pprint_3-0.9.5.jar" level="project"/>
+        <orderEntry type="library" name="pprint_3-0.9.6.jar" level="project"/>
         <orderEntry type="library" name="requests_3-0.9.0.jar" level="project"/>
         <orderEntry type="library" scope="RUNTIME" name="scala-collection-compat_2.13-2.13.0.jar" level="project"/>
         <orderEntry type="library" name="scala-collection-compat_3-2.12.0.jar" level="project"/>

integration/ide/gen-idea/resources/extended/idea/mill_modules/mill-build.mill-build.iml

@@ -98,7 +98,7 @@
         <orderEntry type="library" scope="RUNTIME" name="plexus-container-default-2.1.1.jar" level="project"/>
         <orderEntry type="library" scope="RUNTIME" name="plexus-io-3.5.1.jar" level="project"/>
         <orderEntry type="library" scope="RUNTIME" name="plexus-utils-4.0.2.jar" level="project"/>
-        <orderEntry type="library" name="pprint_3-0.9.5.jar" level="project"/>
+        <orderEntry type="library" name="pprint_3-0.9.6.jar" level="project"/>
         <orderEntry type="library" name="requests_3-0.9.0.jar" level="project"/>
         <orderEntry type="library" scope="RUNTIME" name="scala-collection-compat_2.13-2.13.0.jar" level="project"/>
         <orderEntry type="library" name="scala-collection-compat_3-2.12.0.jar" level="project"/>

integration/ide/gen-idea/resources/hello-idea/idea/mill_modules/mill-build.iml

@@ -92,7 +92,7 @@
         <orderEntry type="library" scope="RUNTIME" name="plexus-container-default-2.1.1.jar" level="project"/>
         <orderEntry type="library" scope="RUNTIME" name="plexus-io-3.5.1.jar" level="project"/>
         <orderEntry type="library" scope="RUNTIME" name="plexus-utils-4.0.2.jar" level="project"/>
-        <orderEntry type="library" name="pprint_3-0.9.5.jar" level="project"/>
+        <orderEntry type="library" name="pprint_3-0.9.6.jar" level="project"/>
         <orderEntry type="library" name="requests_3-0.9.0.jar" level="project"/>
         <orderEntry type="library" scope="RUNTIME" name="scala-collection-compat_2.13-2.13.0.jar" level="project"/>
         <orderEntry type="library" name="scala-collection-compat_3-2.12.0.jar" level="project"/>

mill-build/src/millbuild/Deps.scala

@@ -140,7 +140,7 @@ object Deps {
   val osLibVersion = "0.11.5"
   val osLib = mvn"com.lihaoyi::os-lib:$osLibVersion"
   val osLibWatch = mvn"com.lihaoyi::os-lib-watch:$osLibVersion"
-  val pprint = mvn"com.lihaoyi::pprint:0.9.5"
+  val pprint = mvn"com.lihaoyi::pprint:0.9.6"
   val mainargs = mvn"com.lihaoyi::mainargs:0.7.7"
   val millModuledefsVersion = "0.12.3"
   val millModuledefsString = s"com.lihaoyi::mill-moduledefs:${millModuledefsVersion}"