From 17beaef0e02f0bb285d904e7a07e2b73a6f14305 Mon Sep 17 00:00:00 2001
From: Ben Visness <ben@bvisness.me>
Date: Sun, 17 Sep 2023 10:29:44 -0500
Subject: [PATCH] Slightly improve MSVC documentation and error messages

---
 Readme.md      | 10 +++++++++-
 scripts/dev.py |  9 ++++++---
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/Readme.md b/Readme.md
index b82d878..31bf904 100644
--- a/Readme.md
+++ b/Readme.md
@@ -31,11 +31,13 @@ The Orca command-line tools must be installed to your system in order to use the
 	- **Windows users:** `clang` can be installed via the Visual Studio installer. Search for "C++ Clang Compiler".
 	- **Mac users:** Apple's built-in `clang` does not support WebAssembly. We recommend installing `clang` via [Homebrew](https://brew.sh/) with `brew install clang`.
 - MSVC (Visual Studio 2022 17.5 or newer) (Windows only)
-	- This can be installed through the [Visual Studio Community](https://visualstudio.microsoft.com/) installer.
+	- This can be installed through the [Visual Studio Community](https://visualstudio.microsoft.com/) installer. Ensure that your Visual Studio installation includes "Desktop development with C++".
 	- Please note the version requirement! Orca requires C11 atomics, which were only added to MSVC in late 2022.
 
 ### Installation instructions
 
+**Windows users:** You must perform all the following actions from a 64-bit Visual Studio command prompt. We recommend searching for "x64 Native Tools Command Prompt".
+
 Clone the repo, then `cd` into the `orca` directory:
 
 ```
@@ -116,6 +118,12 @@ We're currently working with contributors to add support for Odin and Zig, and w
 
 We currently use [wasm3](https://github.com/wasm3/wasm3) for our interpreter. We therefore support whatever features wasm3 supports. In practice this means all WebAssembly 1.0 features, bulk memory operations, and a couple other small features.
 
+**I am getting "unsupported OS" errors when building on Windows.**
+
+You are likely running from the wrong kind of Visual Studio command prompt. Search for "x64 Native Tools Command Prompt" or run `vcvarsall.bat` with `x64` for the architecture.
+
+To verify that you are in the correct type of command prompt, simply run `cl` with no arguments, and verify that you are building for x64.
+
 **I am getting errors about atomics when building the runtime on Windows.**
 
 Please ensure that you have the latest version of Visual Studio and MSVC installed. The Orca runtime requires the use of C11 atomics, which were not added to MSVC until late 2022.
diff --git a/scripts/dev.py b/scripts/dev.py
index 45cdeb2..74f22cc 100644
--- a/scripts/dev.py
+++ b/scripts/dev.py
@@ -391,12 +391,15 @@ def gen_all_bindings():
 def ensure_programs():
     if platform.system() == "Windows":
         try:
+            # TODO: Verify that the output includes `x64`
             subprocess.run(["cl"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
         except FileNotFoundError:
             msg = log_error("MSVC was not found on your system.")
-            msg.more("If you have already installed Visual Studio, make sure you are running in a")
-            msg.more("Visual Studio command prompt or you have run vcvarsall.bat. Otherwise, download")
-            msg.more("and install Visual Studio: https://visualstudio.microsoft.com/")
+            msg.more("If you have already installed Visual Studio, make sure you are running in an")
+            msg.more("x64 Visual Studio command prompt or you have run vcvarsall.bat with x64 for")
+            msg.more("the architecture. Otherwise, download and install Visual Studio, and ensure")
+            msg.more("that your installation includes \"Desktop development with C++\" and")
+            msg.more("\"C++ Clang Compiler\": https://visualstudio.microsoft.com/")
             exit(1)
 
     try: