Fix #2321: Fix Clang discovery on Windows (#2334)

* Fix clang dicovery on Windows

* Add initial Windows docs, fix a couple of other doc issues

* Add a figure showing the install

* Update to LLVM_BIN in 2 more places

* Update documentation with links and mentions for Chocolatey and Scoop

docs/contrib/build.rst

@@ -219,7 +219,7 @@ The build has roughly five groups of sub-projects as follows:
 7. JUnit plugin, its tests and dependencies. Following sources define JUnit compiler
    for Scala Native and its runtime, as well as compliance tests and internal stubs.
 
-    - ``junitPlugin (junit-plugin) ``
+    - ``junitPlugin (junit-plugin)``
 
     - ``junitRuntime (junit-runtime)``
 

docs/lib/posixlib.rst

@@ -199,6 +199,7 @@ C Header          Scala Native Module
 .. _scala.scalanative.posix.pwd: https://github.com/scala-native/scala-native/blob/master/posixlib/src/main/scala/scala/scalanative/posix/pwd.scala
 .. _scala.scalanative.posix.regex: https://github.com/scala-native/scala-native/blob/master/posixlib/src/main/scala/scala/scalanative/posix/regex.scala
 .. _scala.scalanative.posix.sched: https://github.com/scala-native/scala-native/blob/master/posixlib/src/main/scala/scala/scalanative/posix/sched.scala
+.. _scala.scalanative.posix.signal: https://github.com/scala-native/scala-native/blob/master/posixlib/src/main/scala/scala/scalanative/posix/signal.scala
 .. _scala.scalanative.posix.stdlib: https://github.com/scala-native/scala-native/blob/master/posixlib/src/main/scala/scala/scalanative/posix/stdlib.scala
 .. _scala.scalanative.posix.sys.resource: https://github.com/scala-native/scala-native/blob/master/posixlib/src/main/scala/scala/scalanative/posix/sys/resource.scala
 .. _scala.scalanative.posix.sys.select: https://github.com/scala-native/scala-native/blob/master/posixlib/src/main/scala/scala/scalanative/posix/sys/select.scala

docs/user/setup.rst

@@ -19,7 +19,7 @@ These are only required if you use the corresponding feature.
 Installing sbt
 --------------
 
-**macOS and Linux**
+**macOS, Linux, and Windows**
 
 Please refer to `this link <https://www.scala-sbt.org/release/docs/Setup.html>`_
 for instructions for your operating system.
@@ -39,7 +39,7 @@ provided that it works with Scala Native. The Scala Native sbt
 plugin checks to ensure that `clang` is at least the minimum version
 shown above.
 
-Scala Native uses the `immix`_ garbage collector by default.
+Scala Native uses the `Immix`_ garbage collector by default.
 You can use the `Boehm`_ garbage collector instead.
 If you chose to use that alternate garbage collector both the native library
 and header files must be provided at build time.
@@ -110,11 +110,64 @@ installation of FreeBSD.
     $ wget https://raw.githubusercontent.com/scala-native/scala-native/master/scripts/scala-native.nix
     $ nix-shell scala-native.nix -A clangEnv
 
+**Windows**
+
+Corporate environments and Windows policies can affect the method
+used to setup your environment. The following procedure involves downloading
+installers and running the installers using Powershell (Administrative)
+to avoid some of these issues. If you have full access to your machine
+then you can install using your favorite method. `Chocolatey`_ or `Scoop`_
+can be substituted as needed or desired and are also mentioned above in the
+installing `sbt` documentation.
+
+1. Download and install Visual Studio Community 2019
+
+https://visualstudio.microsoft.com/
+
+You may install it via the command line if needed.
+
+.. code-block:: shell
+
+    > .\vs_community__<version>.exe
+
+Select the *Workloads* tab and then *Desktop development with C++* checkbox.
+The defaults are fine. The *C++ Clang tools for Windows* does not work so
+use the next step for details on installing LLVM.
+
+.. figure:: vs-install.png
+
+   Visual Studio install dialog showing options.
+
+2. Download and install LLVM
+
+https://github.com/llvm/llvm-project/releases/tag/llvmorg-12.0.1
+
+Select *LLVM-12.0.1-win64.exe* or newer. Digital signatures are provided.
+
+You may also install LLVM via the command line, and if needed, install it into
+your *C:\\Users\\<login>\\AppData\\Local* directory. The installer
+will add *LLVM* and the associated directories and files.
+
+.. code-block:: shell
+
+    > .\LLVM-12.0.1-win64.exe
+
+3. Add the binary location to your PATH
+
+Using the install path above, you would add the following:
+
+.. code-block:: shell
+
+    C:\Users\<login>\AppData\Local\LLVM\bin
+
+
 Continue to :ref:`sbt`.
 
 .. Comment - Sphinx linkcheck fails both http: and https://www.hboehm.info/gc 
 .. Comment - so use the roughly equivalent GitHub URL.
 .. _Boehm: https://github.com/ivmai/bdwgc
-.. _immix: https://www.cs.utexas.edu/users/speedway/DaCapo/papers/immix-pldi-2008.pdf
+.. _Immix: https://www.cs.utexas.edu/users/speedway/DaCapo/papers/immix-pldi-2008.pdf
 .. _LLVM: https://llvm.org
+.. _Chocolatey: https://chocolatey.org/
+.. _Scoop: https://scoop.sh/
 .. _here: :ref:`Sbt settings and tasks`

scripts/scala-native.nix

@@ -7,8 +7,7 @@ in rec {
     shellHook = ''
     alias cls=clear
     '';
-    CLANG_PATH = pkgs.clang + "/bin/clang";
-    CLANGPP_PATH = pkgs.clang + "/bin/clang++";
+    LLVM_BIN = pkgs.clang + "/bin";
     buildInputs = with pkgs; [
       stdenv
       sbt

tools/src/main/scala/scala/scalanative/build/Discover.scala

@@ -28,16 +28,16 @@ object Discover {
   def GC(): GC =
     getenv("SCALANATIVE_GC").map(build.GC(_)).getOrElse(build.GC.default)
 
-  /** Use the clang binary on the path or via CLANG_PATH env var. */
+  /** Use the clang binary on the path or via LLVM_BIN env var. */
   def clang(): Path = {
-    val path = discover("clang", "CLANG_PATH")
+    val path = discover("clang", "LLVM_BIN")
     checkClangVersion(path)
     path
   }
 
-  /** Use the clang++ binary on the path or via CLANGPP_PATH env var. */
+  /** Use the clang++ binary on the path or via LLVM_BIN env var. */
   def clangpp(): Path = {
-    val path = discover("clang++", "CLANGPP_PATH")
+    val path = discover("clang++", "LLVM_BIN")
     checkClangVersion(path)
     path
   }
@@ -146,16 +146,28 @@ object Discover {
       binaryName: String,
       envPath: String
   ): Path = {
-    val binaryNameOrPath = sys.env.getOrElse(envPath, binaryName)
-    val locateCmd = if (Platform.isWindows) "where" else "which"
-    val path = Process(Seq(locateCmd, binaryNameOrPath))
+    val binPath = sys.env.get(envPath)
+
+    val command: Seq[String] = {
+      if (Platform.isWindows) {
+        val arg = binPath.fold(binaryName)(p => s"$p:$binaryName")
+        Seq("where", arg)
+      } else {
+        val arg = binPath.fold(binaryName) { p =>
+          Paths.get(p, binaryName).toString()
+        }
+        Seq("which", arg)
+      }
+    }
+
+    val path = Process(command)
       .lineStream_!(silentLogger())
       .map { p => Paths.get(p) }
       .headOption
       .getOrElse {
         throw new BuildException(
-          s"""No '$binaryNameOrPath' found in PATH or via '$envPath' environment variable.
-             |Please refer to ($docSetup)""".stripMargin
+          s"""'$binaryName' not found in PATH or via '$envPath' environment variable.
+            |Please refer to ($docSetup)""".stripMargin
         )
       }
     path