Ccache docs

ChangeLog.md

@@ -20,6 +20,10 @@ See docs/process.md for more on how version tagging works.
 
 Current Trunk
 -------------
+- Added support for wrapping emcc and em++ via ccache: install Emscripten port
+  of ccache via emsdk, or from https://github.com/juj/ccache/tree/emscripten,
+  and run explicitly with "ccache emcc ..." after installing, or automatically
+  just with "emcc ..." after activating ccache via emsdk. (#13498)
 - Using EM_ASM and EM_JS in a side module will now result in an error (since
   this is not implemented yet).  This could effect users were previously
   inadvertently including (but not actually using) EM_ASM or EM_JS functions in

docs/emcc.txt

@@ -634,7 +634,7 @@ Environment variables
 
    * "EMCC_STDERR_FILE" [general]
 
-   * "EMCC_CLOSURE_ARGS" : [link] arguments to be passed to *Closure
+   * "EMCC_CLOSURE_ARGS" [link] arguments to be passed to *Closure
      Compiler*
 
    * "EMCC_STRICT" [general]
@@ -647,6 +647,9 @@ Environment variables
 
    * "EM_LLVM_ROOT" [compile+link]
 
+   * "_EMCC_CCACHE" [general] Internal setting that is set to 1 by emsdk
+     when integrating with ccache compiler frontend
+
 Search for 'os.environ' in emcc.py to see how these are used. The most
 interesting is possibly "EMCC_DEBUG", which forces the compiler to
 dump its build and temporary files to a temporary directory where they

em++

@@ -26,9 +26,9 @@ if [ -z "$PYTHON" ]; then
   exit 1
 fi
 
-if [ -z "$EMCC_CCACHE" ]; then
+if [ -z "$_EMCC_CCACHE" ]; then
   exec "$PYTHON" "$0.py" "$@"
 else
-  unset EMCC_CCACHE
+  unset _EMCC_CCACHE
   exec ccache "$0" "$@"
 fi

em++.bat

@@ -8,11 +8,11 @@
   set EM_PY=python
 )
 
-@if "%EMCC_CCACHE%"=="" (
+@if "%_EMCC_CCACHE%"=="" (
   :: Do regular invocation of em++.py compiler
   "%EM_PY%" "%~dp0\%~n0.py" %*
 ) else (
   :: Remove the ccache env. var, invoke ccache and re-enter this script to take the above branch.
-  set EMCC_CCACHE=
+  set _EMCC_CCACHE=
   ccache "%~dp0\%~n0.bat" %*
 )

emcc

@@ -26,9 +26,9 @@ if [ -z "$PYTHON" ]; then
   exit 1
 fi
 
-if [ -z "$EMCC_CCACHE" ]; then
+if [ -z "$_EMCC_CCACHE" ]; then
   exec "$PYTHON" "$0.py" "$@"
 else
-  unset EMCC_CCACHE
+  unset _EMCC_CCACHE
   exec ccache "$0" "$@"
 fi

emcc.bat

@@ -8,11 +8,11 @@
   set EM_PY=python
 )
 
-@if "%EMCC_CCACHE%"=="" (
+@if "%_EMCC_CCACHE%"=="" (
   :: Do regular invocation of em++.py compiler
   "%EM_PY%" "%~dp0\%~n0.py" %*
 ) else (
   :: Remove the ccache env. var, invoke ccache and re-enter this script to take the above branch.
-  set EMCC_CCACHE=
+  set _EMCC_CCACHE=
   ccache "%~dp0\%~n0.bat" %*
 )

site/source/docs/tools_reference/emcc.rst

@@ -535,12 +535,13 @@ Environment variables
   - ``EMCC_ONLY_FORCED_STDLIBS`` [link]
   - ``EMCC_LOCAL_PORTS`` [compile+link]
   - ``EMCC_STDERR_FILE`` [general]
-  - ``EMCC_CLOSURE_ARGS`` : [link] arguments to be passed to *Closure Compiler*
+  - ``EMCC_CLOSURE_ARGS``  [link] arguments to be passed to *Closure Compiler*
   - ``EMCC_STRICT`` [general]
   - ``EMCC_SKIP_SANITY_CHECK`` [general]
   - ``EM_IGNORE_SANITY`` [general]
   - ``EM_CONFIG`` [general]
   - ``EM_LLVM_ROOT`` [compile+link]
+  - ``_EMCC_CCACHE`` [general] Internal setting that is set to 1 by emsdk when integrating with ccache compiler frontend
 
 Search for 'os.environ' in `emcc.py <https://github.com/emscripten-core/emscripten/blob/main/emcc.py>`_ to see how these are used. The most interesting is possibly ``EMCC_DEBUG``, which forces the compiler to dump its build and temporary files to a temporary directory where they can be reviewed.
 

tools/run_python_compiler.bat

@@ -8,11 +8,11 @@
   set EM_PY=python
 )
 
-@if "%EMCC_CCACHE%"=="" (
+@if "%_EMCC_CCACHE%"=="" (
   :: Do regular invocation of em++.py compiler
   "%EM_PY%" "%~dp0\%~n0.py" %*
 ) else (
   :: Remove the ccache env. var, invoke ccache and re-enter this script to take the above branch.
-  set EMCC_CCACHE=
+  set _EMCC_CCACHE=
   ccache "%~dp0\%~n0.bat" %*
 )

tools/run_python_compiler.sh

@@ -26,9 +26,9 @@ if [ -z "$PYTHON" ]; then
   exit 1
 fi
 
-if [ -z "$EMCC_CCACHE" ]; then
+if [ -z "$_EMCC_CCACHE" ]; then
   exec "$PYTHON" "$0.py" "$@"
 else
-  unset EMCC_CCACHE
+  unset _EMCC_CCACHE
   exec ccache "$0" "$@"
 fi