Readme.md

@@ -29,12 +29,14 @@ The Orca command-line tools must be installed to your system in order to use the
 
 - Windows or Mac (Linux is not yet supported)
 - [Python 3.8](https://www.python.org/) or newer (for command line tools)
-- Clang
+- Clang (version 11.0 or newer)
 	- **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 llvm`.
 - MSVC (Visual Studio 2022 17.5 or newer) (Windows only)
 	- 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.
+- Xcode command-line tools (Mac only)
+	- These can be installed with `xcode-select --install`.
 
 ### Installation instructions
 

samples/breakout/build.bat

@@ -1,4 +1,16 @@
 @echo off
+setlocal enabledelayedexpansion
+
+:: The following code checks if you have the necessary programs to compile the samples.
+:: This code exists to improve the experience of first-time Orca users and can
+:: be safely deleted in your own projects if you wish.
+if exist "..\..\scripts\sample_build_check.py" (
+       python ..\..\scripts\sample_build_check.py
+       if !ERRORLEVEL! neq 0 exit /b 1
+) else (
+       echo Could not check if you have the necessary tools to build the Orca samples.
+       echo If you have copied this script to your own project, you can delete this code.
+)
 
 set ORCA_DIR=..\..
 set STDLIB_DIR=%ORCA_DIR%\src\libc-shim
@@ -16,6 +28,6 @@ set wasmFlags=--target=wasm32^
        -I%ORCA_DIR%\src\ext
 
 clang %wasmFlags% -o .\module.wasm %ORCA_DIR%\src\orca.c %STDLIB_DIR%\src\*.c src\main.c
-IF %ERRORLEVEL% NEQ 0 EXIT /B %ERRORLEVEL%
+if !ERRORLEVEL! neq 0 exit /b !ERRORLEVEL!
 
 orca bundle --orca-dir %ORCA_DIR% --name Breakout --icon icon.png --resource-dir data module.wasm

samples/breakout/build.sh

@@ -2,13 +2,14 @@
 
 set -euo pipefail
 
-if [[ -x /usr/local/opt/llvm/bin/clang ]]; then
+# The following code checks if you have the necessary programs to compile the samples.
-  CLANG=/usr/local/opt/llvm/bin/clang
+# This code exists to improve the experience of first-time Orca users and can
-elif [[ -x /opt/homebrew/opt/llvm/bin/clang ]]; then
+# be safely deleted in your own projects if you wish.
-  CLANG=/opt/homebrew/opt/llvm/bin/clang
+if [ -f ../../scripts/sample_build_check.py ]; then
+  python3 ../../scripts/sample_build_check.py
 else
-  echo "Could not find Homebrew clang; this script will probably not work."
+  echo "Could not check if you have the necessary tools to build the Orca samples."
-  CLANG=clang
+  echo "If you have copied this script to your own project, you can delete this code."
 fi
 
 ORCA_DIR=../..
@@ -25,6 +26,6 @@ wasmFlags="--target=wasm32 \
   -I $ORCA_DIR/src \
   -I $ORCA_DIR/src/ext"
 
-$CLANG $wasmFlags -o ./module.wasm $ORCA_DIR/src/orca.c $STDLIB_DIR/src/*.c src/main.c
+clang $wasmFlags -o ./module.wasm $ORCA_DIR/src/orca.c $STDLIB_DIR/src/*.c src/main.c
 
 orca bundle --orca-dir $ORCA_DIR --name Breakout --icon icon.png --resource-dir data module.wasm

samples/clock/build.bat

@@ -1,4 +1,16 @@
 @echo off
+setlocal enabledelayedexpansion
+
+:: The following code checks if you have the necessary programs to compile the samples.
+:: This code exists to improve the experience of first-time Orca users and can
+:: be safely deleted in your own projects if you wish.
+if exist "..\..\scripts\sample_build_check.py" (
+       python ..\..\scripts\sample_build_check.py
+       if !ERRORLEVEL! neq 0 exit /b 1
+) else (
+       echo Could not check if you have the necessary tools to build the Orca samples.
+       echo If you have copied this script to your own project, you can delete this code.
+)
 
 set ORCA_DIR=..\..
 set STDLIB_DIR=%ORCA_DIR%\src\libc-shim
@@ -16,6 +28,6 @@ set wasmFlags=--target=wasm32^
        -I%ORCA_DIR%\src\ext
 
 clang %wasmFlags% -o .\module.wasm %ORCA_DIR%\src\orca.c %STDLIB_DIR%\src\*.c src\main.c
-IF %ERRORLEVEL% NEQ 0 EXIT /B %ERRORLEVEL%
+if !ERRORLEVEL! neq 0 exit /b !ERRORLEVEL!
 
 orca bundle --orca-dir %ORCA_DIR% --name Clock --icon icon.png --resource-dir data module.wasm

samples/clock/build.sh

@@ -2,13 +2,14 @@
 
 set -euo pipefail
 
-if [[ -x /usr/local/opt/llvm/bin/clang ]]; then
+# The following code checks if you have the necessary programs to compile the samples.
-  CLANG=/usr/local/opt/llvm/bin/clang
+# This code exists to improve the experience of first-time Orca users and can
-elif [[ -x /opt/homebrew/opt/llvm/bin/clang ]]; then
+# be safely deleted in your own projects if you wish.
-  CLANG=/opt/homebrew/opt/llvm/bin/clang
+if [ -f ../../scripts/sample_build_check.py ]; then
+  python3 ../../scripts/sample_build_check.py
 else
-  echo "Could not find Homebrew clang; this script will probably not work."
+  echo "Could not check if you have the necessary tools to build the Orca samples."
-  CLANG=clang
+  echo "If you have copied this script to your own project, you can delete this code."
 fi
 
 ORCA_DIR=../..
@@ -25,6 +26,6 @@ wasmFlags="--target=wasm32 \
   -I $ORCA_DIR/src \
   -I $ORCA_DIR/src/ext"
 
-$CLANG $wasmFlags -o ./module.wasm $ORCA_DIR/src/orca.c $STDLIB_DIR/src/*.c src/main.c
+clang $wasmFlags -o ./module.wasm $ORCA_DIR/src/orca.c $STDLIB_DIR/src/*.c src/main.c
 
 orca bundle --orca-dir $ORCA_DIR --name Clock --icon icon.png --resource-dir data module.wasm

samples/fluid/build.bat

@@ -1,4 +1,16 @@
 @echo off
+setlocal enabledelayedexpansion
+
+:: The following code checks if you have the necessary programs to compile the samples.
+:: This code exists to improve the experience of first-time Orca users and can
+:: be safely deleted in your own projects if you wish.
+if exist "..\..\scripts\sample_build_check.py" (
+       python ..\..\scripts\sample_build_check.py
+       if !ERRORLEVEL! neq 0 exit /b 1
+) else (
+       echo Could not check if you have the necessary tools to build the Orca samples.
+       echo If you have copied this script to your own project, you can delete this code.
+)
 
 set ORCA_DIR=..\..
 set STDLIB_DIR=%ORCA_DIR%\src\libc-shim
@@ -30,10 +42,10 @@ set shaders=src/shaders/advect.glsl^
 	src/shaders/subtract_pressure.glsl
 
 
-call python3 ../../scripts/embed_text_files.py --prefix=glsl_ --output src/glsl_shaders.h %shaders%
+call python ../../scripts/embed_text_files.py --prefix=glsl_ --output src/glsl_shaders.h %shaders%
-IF %ERRORLEVEL% NEQ 0 EXIT /B %ERRORLEVEL%
+if !ERRORLEVEL! neq 0 exit /b !ERRORLEVEL!
 
 clang %wasmFlags% -o .\module.wasm %ORCA_DIR%\src\orca.c %STDLIB_DIR%\src\*.c src\main.c
-IF %ERRORLEVEL% NEQ 0 EXIT /B %ERRORLEVEL%
+if !ERRORLEVEL! neq 0 exit /b !ERRORLEVEL!
 
 orca bundle --orca-dir %ORCA_DIR% --name Fluid --icon icon.png module.wasm

samples/fluid/build.sh

@@ -2,13 +2,14 @@
 
 set -euo pipefail
 
-if [[ -x /usr/local/opt/llvm/bin/clang ]]; then
+# The following code checks if you have the necessary programs to compile the samples.
-  CLANG=/usr/local/opt/llvm/bin/clang
+# This code exists to improve the experience of first-time Orca users and can
-elif [[ -x /opt/homebrew/opt/llvm/bin/clang ]]; then
+# be safely deleted in your own projects if you wish.
-  CLANG=/opt/homebrew/opt/llvm/bin/clang
+if [ -f ../../scripts/sample_build_check.py ]; then
+  python3 ../../scripts/sample_build_check.py
 else
-  echo "Could not find Homebrew clang; this script will probably not work."
+  echo "Could not check if you have the necessary tools to build the Orca samples."
-  CLANG=clang
+  echo "If you have copied this script to your own project, you can delete this code."
 fi
 
 ORCA_DIR=../..
@@ -27,6 +28,6 @@ wasmFlags="--target=wasm32 \
   -I $ORCA_DIR/src \
   -I $ORCA_DIR/src/ext"
 
-$CLANG $wasmFlags -o ./module.wasm $ORCA_DIR/src/orca.c $STDLIB_DIR/src/*.c src/main.c
+clang $wasmFlags -o ./module.wasm $ORCA_DIR/src/orca.c $STDLIB_DIR/src/*.c src/main.c
 
 orca bundle --orca-dir $ORCA_DIR --name Fluid --icon icon.png module.wasm

samples/triangle/build.bat

@@ -1,4 +1,16 @@
 @echo off
+setlocal enabledelayedexpansion
+
+:: The following code checks if you have the necessary programs to compile the samples.
+:: This code exists to improve the experience of first-time Orca users and can
+:: be safely deleted in your own projects if you wish.
+if exist "..\..\scripts\sample_build_check.py" (
+       python ..\..\scripts\sample_build_check.py
+       if !ERRORLEVEL! neq 0 exit /b 1
+) else (
+       echo Could not check if you have the necessary tools to build the Orca samples.
+       echo If you have copied this script to your own project, you can delete this code.
+)
 
 set ORCA_DIR=..\..
 set STDLIB_DIR=%ORCA_DIR%\src\libc-shim
@@ -16,6 +28,6 @@ set wasmFlags=--target=wasm32^
        -I%ORCA_DIR%\src\ext
 
 clang %wasmFlags% -o .\module.wasm %ORCA_DIR%\src\orca.c %STDLIB_DIR%\src\*.c src\main.c
-IF %ERRORLEVEL% NEQ 0 EXIT /B %ERRORLEVEL%
+if !ERRORLEVEL! neq 0 exit /b !ERRORLEVEL!
 
 orca bundle --orca-dir %ORCA_DIR% --name Triangle module.wasm

samples/triangle/build.sh

@@ -2,13 +2,14 @@
 
 set -euo pipefail
 
-if [[ -x /usr/local/opt/llvm/bin/clang ]]; then
+# The following code checks if you have the necessary programs to compile the samples.
-  CLANG=/usr/local/opt/llvm/bin/clang
+# This code exists to improve the experience of first-time Orca users and can
-elif [[ -x /opt/homebrew/opt/llvm/bin/clang ]]; then
+# be safely deleted in your own projects if you wish.
-  CLANG=/opt/homebrew/opt/llvm/bin/clang
+if [ -f ../../scripts/sample_build_check.py ]; then
+  python3 ../../scripts/sample_build_check.py
 else
-  echo "Could not find Homebrew clang; this script will probably not work."
+  echo "Could not check if you have the necessary tools to build the Orca samples."
-  CLANG=clang
+  echo "If you have copied this script to your own project, you can delete this code."
 fi
 
 ORCA_DIR=../..
@@ -25,6 +26,6 @@ wasmFlags="--target=wasm32 \
   -I $ORCA_DIR/src \
   -I $ORCA_DIR/src/ext"
 
-$CLANG $wasmFlags -o ./module.wasm $ORCA_DIR/src/orca.c $STDLIB_DIR/src/*.c src/main.c
+clang $wasmFlags -o ./module.wasm $ORCA_DIR/src/orca.c $STDLIB_DIR/src/*.c src/main.c
 
 orca bundle --orca-dir $ORCA_DIR --name Triangle module.wasm

samples/ui/build.bat

@@ -1,4 +1,16 @@
 @echo off
+setlocal enabledelayedexpansion
+
+:: The following code checks if you have the necessary programs to compile the samples.
+:: This code exists to improve the experience of first-time Orca users and can
+:: be safely deleted in your own projects if you wish.
+if exist "..\..\scripts\sample_build_check.py" (
+       python ..\..\scripts\sample_build_check.py
+       if !ERRORLEVEL! neq 0 exit /b 1
+) else (
+       echo Could not check if you have the necessary tools to build the Orca samples.
+       echo If you have copied this script to your own project, you can delete this code.
+)
 
 set ORCA_DIR=..\..
 set STDLIB_DIR=%ORCA_DIR%\src\libc-shim
@@ -16,6 +28,6 @@ set wasmFlags=--target=wasm32^
        -I%ORCA_DIR%\src\ext
 
 clang %wasmFlags% -o .\module.wasm %ORCA_DIR%\src\orca.c %STDLIB_DIR%\src\*.c src\main.c
-IF %ERRORLEVEL% NEQ 0 EXIT /B %ERRORLEVEL%
+if !ERRORLEVEL! neq 0 exit /b !ERRORLEVEL!
 
 orca bundle --orca-dir %ORCA_DIR% --name UI --resource-dir data module.wasm

samples/ui/build.sh

@@ -2,13 +2,14 @@
 
 set -euo pipefail
 
-if [[ -x /usr/local/opt/llvm/bin/clang ]]; then
+# The following code checks if you have the necessary programs to compile the samples.
-  CLANG=/usr/local/opt/llvm/bin/clang
+# This code exists to improve the experience of first-time Orca users and can
-elif [[ -x /opt/homebrew/opt/llvm/bin/clang ]]; then
+# be safely deleted in your own projects if you wish.
-  CLANG=/opt/homebrew/opt/llvm/bin/clang
+if [ -f ../../scripts/sample_build_check.py ]; then
+  python3 ../../scripts/sample_build_check.py
 else
-  echo "Could not find Homebrew clang; this script will probably not work."
+  echo "Could not check if you have the necessary tools to build the Orca samples."
-  CLANG=clang
+  echo "If you have copied this script to your own project, you can delete this code."
 fi
 
 ORCA_DIR=../..
@@ -25,6 +26,6 @@ wasmFlags="--target=wasm32 \
   -I $ORCA_DIR/src \
   -I $ORCA_DIR/src/ext"
 
-$CLANG $wasmFlags -o ./module.wasm $ORCA_DIR/src/orca.c $STDLIB_DIR/src/*.c src/main.c
+clang $wasmFlags -o ./module.wasm $ORCA_DIR/src/orca.c $STDLIB_DIR/src/*.c src/main.c
 
 orca bundle --orca-dir $ORCA_DIR --name UI --resource-dir data module.wasm

scripts/dev.py

@@ -17,7 +17,7 @@ from .embed_text_files import *
 from .version import check_if_source, is_orca_source, orca_version
 
 ANGLE_VERSION = "2023-07-05"
-
+MAC_SDK_DIR = "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk"
 
 def attach_dev_commands(subparsers):
     dev_cmd = subparsers.add_parser("dev", help="Commands for building Orca itself. Must be run from within an Orca source checkout.")
@@ -168,12 +168,10 @@ def build_platform_layer_lib_win(release):
     ], check=True)
 
 def build_platform_layer_lib_mac(release):
-    sdk_dir = "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk"
-
     flags = ["-mmacos-version-min=10.15.4"]
     cflags = ["-std=c11"]
     debug_flags = ["-O3"] if release else ["-g", "-DOC_DEBUG", "-DOC_LOG_COMPILE_DEBUG"]
-    ldflags = [f"-L{sdk_dir}/usr/lib", f"-F{sdk_dir}/System/Library/Frameworks/"]
+    ldflags = [f"-L{MAC_SDK_DIR}/usr/lib", f"-F{MAC_SDK_DIR}/System/Library/Frameworks/"]
     includes = ["-Isrc", "-Isrc/util", "-Isrc/platform", "-Isrc/ext", "-Isrc/ext/angle/include"]
 
     # compile metal shader
@@ -443,19 +441,24 @@ def ensure_programs():
             msg.more("and \"C++ Clang Compiler\": https://visualstudio.microsoft.com/")
             exit(1)
 
+    if platform.system() == "Darwin":
         try:
             subprocess.run(["clang", "-v"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
         except FileNotFoundError:
             msg = log_error("clang was not found on your system.")
-        if platform.system() == "Windows":
-            msg.more("We recommend installing clang via the Visual Studio installer.")
-        elif platform.system() == "Darwin":
             msg.more("Run the following to install it:")
             msg.more()
             msg.more("  brew install llvm")
             msg.more()
             exit(1)
-    # TODO(ben): Check for xcode command line tools
+
+        if not os.path.exists(MAC_SDK_DIR):
+            msg = log_error("The Xcode command-line tools are not installed.")
+            msg.more("Run the following to install them:")
+            msg.more()
+            msg.more("  xcode-select --install")
+            msg.more()
+            exit(1)
 
 
 def ensure_angle():

scripts/sample_build_check.py

@@ -0,0 +1,61 @@
+import platform
+import re
+import shutil
+import subprocess
+import textwrap
+
+CLANG_MAJOR, CLANG_MINOR = 11, 0
+
+def printw(str=""):
+    print(textwrap.fill(str))
+
+def print_clang_install_info(upgrade):
+    if platform.system() == "Windows":
+        printw(f"Please install Clang {CLANG_MAJOR}.{CLANG_MINOR} or newer. We recommend installing Clang via the Visual Studio installer. In the installer, search for \"C++ Clang Compiler\".")
+    elif platform.system() == "Darwin":
+        printw(f"Please install Clang {CLANG_MAJOR}.{CLANG_MINOR} or newer. We recommend installing Clang via Homebrew (https://brew.sh/):")
+        printw()
+        if upgrade:
+            printw("  brew upgrade llvm")
+        else:
+            printw("  brew install llvm")
+        printw()
+    else:
+        printw(f"Please install Clang {CLANG_MAJOR}.{CLANG_MINOR} or newer.")
+
+try:
+    out = subprocess.run(["clang", "--version"], capture_output=True, text=True, check=True)
+    m = re.search(r"clang version (\d+)\.(\d+)\.(\d+)", out.stdout)
+    major, minor, patch = int(m.group(1)), int(m.group(2)), int(m.group(3))
+    if major < CLANG_MAJOR or minor < CLANG_MINOR:
+        printw(f"ERROR: Your version of Clang is too old. You have version {major}.{minor}.{patch}, but version {CLANG_MAJOR}.{CLANG_MINOR} or greater is required.")
+        printw()
+        printw("This script is currently running the clang located at:")
+        printw(shutil.which("clang"))
+        printw()
+        print_clang_install_info(True)
+        exit(1)
+except FileNotFoundError:
+    printw("ERROR: clang is not installed. The Orca samples require Clang in order to compile C programs to WebAssembly.")
+    printw()
+    print_clang_install_info(False)
+    exit(1)
+except subprocess.CalledProcessError:
+    printw("WARNING: Could not check Clang version. You may encounter build errors.")
+
+try:
+    subprocess.run(["wasm-ld", "--version"], capture_output=True, check=True)
+except FileNotFoundError:
+    printw("ERROR: wasm-ld was not found on your system. This is a component of Clang that is required in order to produce WebAssembly modules. This likely means that an old or otherwise incompatible version of Clang is being used, such as Apple's version of Clang.")
+    printw()
+    print_clang_install_info(False)
+    exit(1)
+
+try:
+    subprocess.run(["orca", "version"], capture_output=True, shell=True, check=True)
+except subprocess.CalledProcessError:
+    printw("ERROR: The Orca tooling has not been installed to your system or is not on your PATH. From the root of the Orca source code, please run the following commands:")
+    printw()
+    printw("  python orca dev build-runtime")
+    printw("  python orca dev install")
+    exit(1)