Support for printing help from scala compiler without passing any sources

modules/build/src/main/scala/scala/build/compiler/SimpleJavaCompiler.scala

@@ -6,6 +6,13 @@ import scala.build.internal.Runner
 import scala.build.{Logger, Project}
 import scala.util.Properties
 
+/** A simple Java compiler to handle pure Java projects.
+  *
+  * @param defaultJavaCommand
+  *   the default `java` command to be used
+  * @param defaultJavaOptions
+  *   the default jvm options to be used with the `java` command
+  */
 final case class SimpleJavaCompiler(
   defaultJavaCommand: String,
   defaultJavaOptions: Seq[String]
@@ -16,8 +23,9 @@ final case class SimpleJavaCompiler(
     logger: Logger
   ): Boolean =
     project.sources.isEmpty || {
-      val javacCommand = SimpleJavaCompiler.javaCommand(project, "javac")
-        .getOrElse(defaultJavaCommand)
+      val javacCommand =
+        project.javaHomeOpt.map(javaHome => SimpleJavaCompiler.javaCommand(javaHome, "javac"))
+          .getOrElse(defaultJavaCommand)
 
       val args = project.javacOptions ++
         Seq(
@@ -42,10 +50,9 @@ final case class SimpleJavaCompiler(
 
 object SimpleJavaCompiler {
 
-  def javaCommand(project: Project, command: String = "java"): Option[String] =
-    project.javaHomeOpt.map { javaHome =>
-      val ext  = if (Properties.isWin) ".exe" else ""
-      val path = javaHome / "bin" / s"$command$ext"
-      path.toString
-    }
+  def javaCommand(javaHome: os.Path, command: String = "java"): String = {
+    val ext  = if (Properties.isWin) ".exe" else ""
+    val path = javaHome / "bin" / s"$command$ext"
+    path.toString
+  }
 }

modules/build/src/main/scala/scala/build/compiler/SimpleScalaCompiler.scala

@@ -5,6 +5,15 @@ import java.io.File
 import scala.build.internal.Runner
 import scala.build.{Logger, Positioned, Project}
 
+/** A simple Scala compiler designed to handle scaladocs, Java projects & get `scalac` outputs.
+  *
+  * @param defaultJavaCommand
+  *   the default `java` command to be used
+  * @param defaultJavaOptions
+  *   the default jvm options to be used with the `java` command
+  * @param scaladoc
+  *   a flag for setting whether this compiler will handle scaladocs
+  */
 final case class SimpleScalaCompiler(
   defaultJavaCommand: String,
   defaultJavaOptions: Seq[String],
@@ -24,47 +33,164 @@ final case class SimpleScalaCompiler(
   override def usesClassDir: Boolean =
     !scaladoc
 
+  /** Run a synthetic (created in runtime) `scalac` as a JVM process with the specified parameters
+    *
+    * @param mainClass
+    *   the main class of the synthetic Scala compiler
+    * @param javaHomeOpt
+    *   Java home path (optional)
+    * @param javacOptions
+    *   options to be passed for the Java compiler
+    * @param scalacOptions
+    *   options to be passed for the Scala compiler
+    * @param classPath
+    *   class path to be passed to `scalac`
+    * @param compilerClassPath
+    *   class path for the Scala compiler itself
+    * @param sources
+    *   sources to be passed when running `scalac` (optional)
+    * @param outputDir
+    *   output directory for the compiler (optional)
+    * @param cwd
+    *   working directory for running the compiler
+    * @param logger
+    *   logger
+    * @return
+    *   compiler process exit code
+    */
   private def runScalacLike(
-    project: Project,
     mainClass: String,
-    outputDir: os.Path,
+    javaHomeOpt: Option[os.Path],
+    javacOptions: Seq[String],
+    scalacOptions: Seq[String],
+    classPath: Seq[os.Path],
+    compilerClassPath: Seq[os.Path],
+    sources: Seq[String],
+    outputDir: Option[os.Path],
+    cwd: os.Path,
     logger: Logger
-  ): Boolean = {
+  ): Int = {
 
-    os.makeDir.all(outputDir)
+    outputDir.foreach(os.makeDir.all(_))
 
     // initially adapted from https://github.com/VirtusLab/scala-cli/pull/103/files#diff-d13a7e6d602b8f84d9177e3138487872f0341d006accfe425886a561f029a9c3R120 and around
+    val outputDirArgs = outputDir.map(od => Seq("-d", od.toString())).getOrElse(Nil)
+    val classPathArgs =
+      if (classPath.nonEmpty)
+        Seq("-cp", classPath.map(_.toString).mkString(File.pathSeparator))
+      else Nil
 
-    val args =
-      project.scalaCompiler.map(_.scalacOptions).getOrElse(Nil) ++
-        Seq(
-          "-d",
-          outputDir.toString,
-          "-cp",
-          project.classPath.map(_.toString).mkString(File.pathSeparator)
-        ) ++
-        project.sources.map(_.toString)
+    val args = scalacOptions ++ outputDirArgs ++ classPathArgs ++ sources
 
-    val javaCommand = SimpleJavaCompiler.javaCommand(project).getOrElse(defaultJavaCommand)
+    val javaCommand =
+      javaHomeOpt.map(SimpleJavaCompiler.javaCommand(_)).getOrElse(defaultJavaCommand)
 
     val javaOptions = defaultJavaOptions ++
-      project.javacOptions
+      javacOptions
         .filter(_.startsWith("-J"))
         .map(_.stripPrefix("-J"))
 
-    val res = Runner.runJvm(
+    Runner.runJvm(
       javaCommand,
       javaOptions,
-      project.scalaCompiler.map(_.compilerClassPath.map(_.toIO)).getOrElse(Nil),
+      compilerClassPath.map(_.toIO),
       mainClass,
       args,
       logger,
-      cwd = Some(project.workspace)
+      cwd = Some(cwd)
     ).waitFor()
+  }
 
+  /** Run a synthetic (created in runtime) `scalac` as a JVM process for a given
+    * [[scala.build.Project]]
+    *
+    * @param project
+    *   project to be compiled
+    * @param mainClass
+    *   the main class of the synthetic Scala compiler
+    * @param outputDir
+    *   the scala compiler output directory
+    * @param logger
+    *   logger
+    * @return
+    *   true if the process returned no errors, false otherwise
+    */
+  private def runScalacLikeForProject(
+    project: Project,
+    mainClass: String,
+    outputDir: os.Path,
+    logger: Logger
+  ): Boolean = {
+    val res = runScalacLike(
+      mainClass = mainClass,
+      javaHomeOpt = project.javaHomeOpt,
+      javacOptions = project.javacOptions,
+      scalacOptions = project.scalaCompiler.map(_.scalacOptions).getOrElse(Nil),
+      classPath = project.classPath,
+      compilerClassPath = project.scalaCompiler.map(_.compilerClassPath).getOrElse(Nil),
+      sources = project.sources.map(_.toString),
+      outputDir = Some(outputDir),
+      cwd = project.workspace,
+      logger = logger
+    )
     res == 0
   }
 
+  /** Run a synthetic (created in runtime) `scalac` as a JVM process with minimal parameters. (i.e.
+    * to print `scalac` help)
+    *
+    * @param scalaVersion
+    *   Scala version for which `scalac` is to be created
+    * @param javaHomeOpt
+    *   Java home path (optional)
+    * @param javacOptions
+    *   options to be passed for the Java compiler
+    * @param scalacOptions
+    *   options to be passed for the Scala compiler
+    * @param fullClassPath
+    *   classpath to be passed to the compiler (optional)
+    * @param compilerClassPath
+    *   classpath of the compiler itself
+    * @param logger
+    *   logger
+    * @return
+    *   compiler process exit code
+    */
+  def runSimpleScalacLike(
+    scalaVersion: String,
+    javaHomeOpt: Option[os.Path],
+    javacOptions: Seq[String],
+    scalacOptions: Seq[String],
+    fullClassPath: Seq[os.Path],
+    compilerClassPath: Seq[os.Path],
+    logger: Logger
+  ): Int =
+    compilerMainClass(scalaVersion) match {
+      case Some(mainClass) =>
+        runScalacLike(
+          mainClass = mainClass,
+          javaHomeOpt = javaHomeOpt,
+          javacOptions = javacOptions,
+          scalacOptions = scalacOptions,
+          classPath = fullClassPath,
+          compilerClassPath = compilerClassPath,
+          sources = Nil,
+          outputDir = None,
+          cwd = os.pwd,
+          logger = logger
+        )
+      case _ => 1
+    }
+
+  private def compilerMainClass(scalaVersion: String): Option[String] =
+    if (scalaVersion.startsWith("2."))
+      Some {
+        if (scaladoc) "scala.tools.nsc.ScalaDoc"
+        else "scala.tools.nsc.Main"
+      }
+    else if (scaladoc) None
+    else Some("dotty.tools.dotc.Main")
+
   def compile(
     project: Project,
     logger: Logger
@@ -74,22 +200,13 @@ final case class SimpleScalaCompiler(
       project.scalaCompiler match {
         case Some(compiler) =>
           val isScala2 = compiler.scalaVersion.startsWith("2.")
-          val mainClassOpt =
-            if (isScala2)
-              Some {
-                if (scaladoc) "scala.tools.nsc.ScalaDoc"
-                else "scala.tools.nsc.Main"
-              }
-            else if (scaladoc) None
-            else Some("dotty.tools.dotc.Main")
-
-          mainClassOpt.forall { mainClass =>
+          compilerMainClass(compiler.scalaVersion).forall { mainClass =>
 
             val outputDir =
               if (isScala2 && scaladoc) project.scaladocDir
               else project.classesDir
 
-            runScalacLike(project, mainClass, outputDir, logger)
+            runScalacLikeForProject(project, mainClass, outputDir, logger)
           }
 
         case None =>

modules/cli-options/src/main/scala/scala/cli/commands/ScalacOptions.scala

@@ -1,7 +1,7 @@
 package scala.cli.commands
 
 import caseapp._
-import caseapp.core.Arg
+import caseapp.core.{Arg, Error}
 import caseapp.core.parser.{Argument, NilParser, StandardArgument}
 import caseapp.core.util.Formatter
 import com.github.plokhotnyuk.jsoniter_scala.core._
@@ -17,7 +17,6 @@ final case class ScalacOptions(
     scalacOption: List[String] = Nil
 )
 // format: on
-
 object ScalacOptions {
 
   private val scalacOptionsArg = Arg("scalacOption")
@@ -33,29 +32,34 @@ object ScalacOptions {
     Set("-V", "-W", "-X", "-Y")
   private val scalacOptionsPrefixes =
     Set("-g", "-language", "-opt", "-P", "-target") ++ scalacOptionsPurePrefixes
+
+  /** This includes all the scalac options which disregard inputs and print a help and/or context
+    * message instead.
+    */
+  val ScalacPrintOptions: Set[String] =
+    scalacOptionsPurePrefixes ++ Set("-help", "-Xshow-phases", "-Vphases")
+
   private val scalacOptionsArgument: Argument[List[String]] =
     new Argument[List[String]] {
 
-      val underlying = StandardArgument[List[String]](scalacOptionsArg)
+      val underlying: StandardArgument[List[String]] = StandardArgument(scalacOptionsArg)
 
-      val arg = scalacOptionsArg
+      val arg: Arg = scalacOptionsArg
 
-      def withDefaultOrigin(origin: String) = this
-      def init                              = Some(Nil)
+      def withDefaultOrigin(origin: String): Argument[List[String]] = this
+      def init: Option[List[String]]                                = Some(Nil)
       def step(
         args: List[String],
         index: Int,
         acc: Option[List[String]],
         formatter: Formatter[Name]
-      ) =
+      ): Either[(Error, List[String]), Option[(Option[List[String]], List[String])]] =
         args match {
-          case h :: t
-              if scalacOptionsPrefixes.exists(h.startsWith) &&
-              !scalacOptionsPurePrefixes.contains(h) =>
+          case h :: t if scalacOptionsPrefixes.exists(h.startsWith) =>
             Right(Some((Some(h :: acc.getOrElse(Nil)), t)))
           case _ => underlying.step(args, index, acc, formatter)
         }
-      def get(acc: Option[List[String]], formatter: Formatter[Name]) =
+      def get(acc: Option[List[String]], formatter: Formatter[Name]): Either[Error, List[String]] =
         Right(acc.getOrElse(Nil))
     }
 

modules/cli-options/src/main/scala/scala/cli/commands/SharedOptions.scala

@@ -42,6 +42,10 @@ final case class SharedOptions(
   @Name("scalaBin")
   @Name("B")
     scalaBinaryVersion: Option[String] = None,
+
+  @Group("Scala")
+  @HelpMessage("Show help for scalac. This is an alias for --scalac-option -help")
+  scalacHelp: Boolean = false,
 
   @Group("Java")
   @HelpMessage("Add extra JARs in the class path")

modules/cli/src/main/scala/scala/cli/commands/Compile.scala

@@ -4,20 +4,22 @@ import caseapp._
 
 import java.io.File
 
-import scala.build.options.Scope
+import scala.build.options.{BuildOptions, Scope}
 import scala.build.{Build, BuildThreads, Builds, Os}
 import scala.cli.CurrentParams
 import scala.cli.commands.util.SharedOptionsUtil._
 
-object Compile extends ScalaCommand[CompileOptions] {
-  override def group                                  = "Main"
-  override def sharedOptions(options: CompileOptions) = Some(options.shared)
+object Compile extends ScalaCommand[CompileOptions] with ScalacLikeCommand[CompileOptions] {
+  override def group                                                         = "Main"
+  override def sharedOptions(options: CompileOptions): Option[SharedOptions] = Some(options.shared)
+  override def buildOptions(options: CompileOptions): BuildOptions = options.shared.buildOptions()
 
-  def outputPath(options: CompileOptions) =
+  def outputPath(options: CompileOptions): Option[os.Path] =
     options.output.filter(_.nonEmpty).map(p => os.Path(p, Os.pwd))
 
   def run(options: CompileOptions, args: RemainingArgs): Unit = {
     maybePrintGroupHelp(options)
+    maybePrintSimpleScalacOutput(options)
     CurrentParams.verbosity = options.shared.logging.verbosity
     val inputs = options.shared.inputsOrExit(args)
     CurrentParams.workspaceOpt = Some(inputs.workspace)