[cmake] Add emscan-deps tool to enable C++20 (#21987)

This is wrapper around clang-scan-deps. Currently this is just enough to
make C++20 work under cmake. We don't currently have any actaully tests
of C++20 modules.

See: #21042
Fixes: #21866 #22305

Author: sbc100

Diff for: ChangeLog.md

@@ -20,6 +20,9 @@ See docs/process.md for more on how version tagging works.
 
 4.0.3 (in development)
 ----------------------
+- emscan-deps tools was added.  This tool wraps clang-scan-deps and injects the
+  needed `--target` and `--sysroot` argument that would normally be injected by
+  emcc itself.  This enables support for C++20 in cmake projects. (#21987)
 
 4.0.2 - 01/30/25
 ----------------

Diff for: cmake/Modules/Platform/Emscripten.cmake

@@ -93,6 +93,7 @@ set(CMAKE_C_COMPILER_AR "${CMAKE_AR}")
 set(CMAKE_CXX_COMPILER_AR "${CMAKE_AR}")
 set(CMAKE_C_COMPILER_RANLIB "${CMAKE_RANLIB}")
 set(CMAKE_CXX_COMPILER_RANLIB "${CMAKE_RANLIB}")
+set(CMAKE_CXX_COMPILER_CLANG_SCAN_DEPS "${EMSCRIPTEN_ROOT_PATH}/emscan-deps")
 
 # Capture the Emscripten version to EMSCRIPTEN_VERSION variable.
 if (NOT EMSCRIPTEN_VERSION)

Diff for: emscan-deps

@@ -0,0 +1,35 @@
+#!/bin/sh
+# Copyright 2020 The Emscripten Authors.  All rights reserved.
+# Emscripten is available under two separate licenses, the MIT license and the
+# University of Illinois/NCSA Open Source License.  Both these licenses can be
+# found in the LICENSE file.
+#
+# Entry point for running python scripts on UNIX systems.
+#
+# Automatically generated by `create_entry_points.py`; DO NOT EDIT.
+#
+# To make modifications to this file, edit `tools/run_python.sh` and then run
+# `tools/maint/create_entry_points.py`
+
+# $PYTHON -E will not ignore _PYTHON_SYSCONFIGDATA_NAME an internal
+# of cpython used in cross compilation via setup.py.
+unset _PYTHON_SYSCONFIGDATA_NAME
+
+if [ -z "$PYTHON" ]; then
+  PYTHON=$EMSDK_PYTHON
+fi
+
+if [ -z "$PYTHON" ]; then
+  PYTHON=$(command -v python3 2> /dev/null)
+fi
+
+if [ -z "$PYTHON" ]; then
+  PYTHON=$(command -v python 2> /dev/null)
+fi
+
+if [ -z "$PYTHON" ]; then
+  echo 'unable to find python in $PATH'
+  exit 1
+fi
+
+exec "$PYTHON" -E "$0.py" "$@"

Diff for: emscan-deps.bat

@@ -0,0 +1,86 @@
+:: Entry point for running python scripts on windows systems.
+::
+:: Automatically generated by `create_entry_points.py`; DO NOT EDIT.
+::
+:: To make modifications to this file, edit `tools/run_python.bat` and then run
+:: `tools/maint/create_entry_points.py`
+
+:: N.b. In Windows .bat scripts, the ':' character cannot appear inside any if () blocks,
+:: or there will be a parsing error.
+
+:: All env. vars specified in this file are to be local only to this script.
+@setlocal
+:: -E will not ignore _PYTHON_SYSCONFIGDATA_NAME an internal
+:: of cpython used in cross compilation via setup.py.
+@set _PYTHON_SYSCONFIGDATA_NAME=
+@set EM_PY=%EMSDK_PYTHON%
+@if "%EM_PY%"=="" (
+  set EM_PY=python
+)
+
+:: Work around Windows bug https://github.com/microsoft/terminal/issues/15212 : If this
+:: script is invoked via enclosing the invocation in quotes via PATH lookup, then %~f0 and
+:: %~dp0 expansions will not work.
+:: So first try if %~dp0 might work, and if not, manually look up this script from PATH.
+@if exist "%~f0" (
+  set MYDIR=%~dp0
+  goto FOUND_MYDIR
+)
+@for %%I in (%~n0.bat) do (
+  @if exist %%~$PATH:I (
+    set MYDIR=%%~dp$PATH:I
+  ) else (
+    echo Fatal Error! Due to a Windows bug, we are unable to locate the path to %~n0.bat.
+    echo To help this issue, try removing unnecessary quotes in the invocation of emcc,
+    echo or add Emscripten directory to PATH.
+    echo See github.com/microsoft/terminal/issues/15212 and
+    echo github.com/emscripten-core/emscripten/issues/19207 for more details.
+  )
+)
+:FOUND_MYDIR
+
+:: Python Windows bug https://bugs.python.org/issue34780: If this script was invoked via a
+:: shared stdin handle from the parent process, and that parent process stdin handle is in
+:: a certain state, running python.exe might hang here. To work around this, if
+:: EM_WORKAROUND_PYTHON_BUG_34780 is defined, invoke python with '< NUL' stdin to avoid
+:: sharing the parent's stdin handle to it, avoiding the hang.
+
+:: On Windows 7, the compiler batch scripts are observed to exit with a non-zero errorlevel,
+:: even when the python executable above did succeed and quit with errorlevel 0 above.
+:: On Windows 8 and newer, this issue has not been observed. It is possible that this
+:: issue is related to the above python bug, but this has not been conclusively confirmed,
+:: so using a separate env. var EM_WORKAROUND_WIN7_BAD_ERRORLEVEL_BUG to enable the known
+:: workaround this issue, which is to explicitly quit the calling process with the previous
+:: errorlevel from the above command.
+
+:: Also must use goto to jump to the command dispatch, since we cannot invoke emcc from
+:: inside a if() block, because if a cmdline param would contain a char '(' or ')', that
+:: would throw off the parsing of the cmdline arg.
+@if "%EM_WORKAROUND_PYTHON_BUG_34780%"=="" (
+  @if "%EM_WORKAROUND_WIN7_BAD_ERRORLEVEL_BUG%"=="" (
+    goto NORMAL
+  ) else (
+    goto NORMAL_EXIT
+  )
+) else (
+  @if "%EM_WORKAROUND_WIN7_BAD_ERRORLEVEL_BUG%"=="" (
+    goto MUTE_STDIN
+  ) else (
+    goto MUTE_STDIN_EXIT
+  )
+)
+
+:NORMAL_EXIT
+@"%EM_PY%" -E "%MYDIR%%~n0.py" %*
+@exit %ERRORLEVEL%
+
+:MUTE_STDIN
+@"%EM_PY%" -E "%MYDIR%%~n0.py" %* < NUL
+@exit /b %ERRORLEVEL%
+
+:MUTE_STDIN_EXIT
+@"%EM_PY%" -E "%MYDIR%%~n0.py" %* < NUL
+@exit %ERRORLEVEL%
+
+:NORMAL
+@"%EM_PY%" -E "%MYDIR%%~n0.py" %*

Diff for: emscan-deps.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+# Copyright 2025 The Emscripten Authors.  All rights reserved.
+# Emscripten is available under two separate licenses, the MIT license and the
+# University of Illinois/NCSA Open Source License.  Both these licenses can be
+# found in the LICENSE file.
+
+"""emscan-deps - clang-scan-deps helper script
+
+This script acts as a frontend replacement for clang-scan-deps.
+"""
+
+import sys
+from tools import shared, cache
+
+args = sys.argv[1:]
+args.append('--sysroot=' + cache.get_sysroot(absolute=True))
+args.append('--target=' + shared.get_llvm_target())
+shared.exec_process([shared.CLANG_SCAN_DEPS] + args)

Diff for: test/cmake/cxx20/CMakeLists.txt

@@ -0,0 +1,7 @@
+cmake_minimum_required(VERSION 3.5...3.28)
+
+project(cxx20test)
+
+set(CMAKE_CXX_STANDARD 20)
+
+add_executable(cxx20test main.cpp)

Diff for: test/cmake/cxx20/main.cpp

@@ -0,0 +1,13 @@
+// Copyright 2025 The Emscripten Authors.  All rights reserved.
+// Emscripten is available under two separate licenses, the MIT license and the
+// University of Illinois/NCSA Open Source License.  Both these licenses can be
+// found in the LICENSE file.
+
+#include <stdio.h>
+
+class Test {}; // This will fail in C mode
+
+int main() {
+  printf("hello, world!\n");
+  return 0;
+}

Diff for: test/cmake/cxx20/out.txt

@@ -0,0 +1 @@
+hello, world!

Diff for: test/test_other.py

@@ -906,6 +906,7 @@ def test_emstrip(self):
     'whole_archive': ('whole_archive',  'whole.js',              []),
     'stdproperty':   ('stdproperty',    'helloworld.js',         []),
     'post_build':    ('post_build',     'hello.js',              []),
+    'cxx20':         ('cxx20',          'cxx20test.js',          []),
   })
   def test_cmake(self, test_dir, output_file, cmake_args):
     if test_dir == 'whole_archive' and 'EMTEST_SKIP_NEW_CMAKE' in os.environ:
@@ -956,7 +957,7 @@ def test_cmake(self, test_dir, output_file, cmake_args):
         # Run through node, if CMake produced a .js file.
         if output_file.endswith('.js'):
           ret = self.run_js(output_file)
-          self.assertTextDataIdentical(read_file(cmakelistsdir + '/out.txt').strip(), ret.strip())
+          self.assertFileContents(os.path.join(cmakelistsdir, 'out.txt'), ret)
 
         if test_dir == 'post_build':
           ret = self.run_process(['ctest'], env=env)

Diff for: tools/maint/create_entry_points.py

@@ -43,6 +43,7 @@
 emnm
 emstrip
 emsymbolizer
+emscan-deps
 system/bin/sdl-config
 system/bin/sdl2-config
 tools/file_packager

Diff for: tools/shared.py

@@ -790,6 +790,7 @@ class OFormat(Enum):
 
 CLANG_CC = os.path.expanduser(build_clang_tool_path(exe_suffix('clang')))
 CLANG_CXX = os.path.expanduser(build_clang_tool_path(exe_suffix('clang++')))
+CLANG_SCAN_DEPS = build_llvm_tool_path(exe_suffix('clang-scan-deps'))
 LLVM_AR = build_llvm_tool_path(exe_suffix('llvm-ar'))
 LLVM_DWP = build_llvm_tool_path(exe_suffix('llvm-dwp'))
 LLVM_RANLIB = build_llvm_tool_path(exe_suffix('llvm-ranlib'))