Attempt to enable ccache support for Emscripten compiler toolchain.

Minor documentation update again on ccache usage.

CMake/Modules/Urho3D-CMake-common.cmake

@@ -464,7 +464,9 @@ else ()
         if (EMSCRIPTEN)
             # Emscripten-specific setup
             set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-warn-absolute-paths -Wno-unknown-warning-option")
-            set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-warn-absolute-paths -Wno-unknown-warning-option")
+            # Temporarily add the C++ standard explicitly because currently Emscripten does not consistently add the standard in its internall processing
+            # and this may cause compilation problem when precompiled header is involved (See https://github.com/kripken/emscripten/issues/3365 for more detail)
+            set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-warn-absolute-paths -Wno-unknown-warning-option -std=c++03")
             set (CMAKE_C_FLAGS_RELEASE "-Oz")
             set (CMAKE_CXX_FLAGS_RELEASE "-Oz")
             if (DEFINED ENV{CI})

CMake/Toolchains/emscripten.toolchain.cmake

@@ -46,7 +46,9 @@ if (CMAKE_HOST_WIN32)
     set (TOOL_EXT .bat)
 endif ()
 set (COMPILER_PATH ${EMSCRIPTEN_ROOT_PATH})
-if ("$ENV{USE_CCACHE}" AND NOT CMAKE_HOST_WIN32 AND FALSE)    # Disable ccache support for now until Emscripten has fixed https://github.com/kripken/emscripten/issues/3365
+# For now enable ccache support only when the CCACHE_CPP2 env var is also set to 1, until Emscripten has fixed https://github.com/kripken/emscripten/issues/3365
+# This ccache's option tells ccache to fallback to use original input source file instead of preprocessed source file which Emscripten does not support currently
+if ("$ENV{USE_CCACHE}" AND NOT CMAKE_HOST_WIN32 AND "$ENV{CCACHE_CPP2}")
     if (NOT $ENV{PATH} MATCHES ${EMSCRIPTEN_ROOT_PATH})
         message (FATAL_ERROR "The bin directory containing the compiler toolchain (${EMSCRIPTEN_ROOT_PATH}) has not been added in the PATH environment variable. "
             "This is required to enable ccache support for Emscripten compiler toolchain.")

Docs/GettingStarted.dox

@@ -287,7 +287,12 @@ CCACHE_SLOPPINESS=pch_defines,time_macros
 
 Failure to do so would cause the precompiled header cannot be used by ccache. When ccache is setup correctly and with more hits than misses then even clean build can be done as fast as incremental build.
 
-You may also want to set 'USE_CCACHE' and 'CCACHE_COMPRESS' environment variable to 1 to enable ccache support when cross-compiling using MinGW, Raspberry-Pi, and Android compiler toolchains; and to enable the compression of the cache objects, respectively.
+You may also want to set 'USE_CCACHE' and 'CCACHE_COMPRESS' environment variable to 1 to enable ccache support when cross-compiling using MinGW, Raspberry-Pi, Android, and Emscripten (with some caveat) cross-compiler toolchains; and to enable the compression of the cached objects, respectively. At the moment to enable ccache support for Emscripten, you also need to set 'CCACHE_CPP2' environment variable to 1 (see Emscripten issue [#3365](https://github.com/kripken/emscripten/issues/3365) for more detail).
+
+Ensure the ccache symlinks directory is being added as the first entry in the 'PATH' environment variable so the symlinks of the compiler toolchain is being found first by CMake rather than the actual compiler toolchain. This is especially important for native build. The 'PATH' environment variable has been set correctly for ccache in RedHat-based host system such as Fedora, but it is not the case in Debian-based host system such as Ubuntu nor in Mac OS X host system with homebrew's ccache installation. For the latter case, use "whereis -b ccache" or "brew info ccache" to find out where your ccache symlinks directory is and adjust the 'PATH' environment variable accordingly.
+
+Note that these environment variables are used by ccache itself and not by our CMake build rules, so they must remain set in the host system not only while generating the initial project file using CMake but also while building the project later.
+
 
 \page Running Running Urho3D player application