Add a small chapter on how to setup ccache to work correctly.

CMake/Modules/Urho3D-CMake-common.cmake

@@ -457,8 +457,8 @@ else ()
             # 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")
-            set (CMAKE_C_FLAGS_RELEASE "-Oz")
-            set (CMAKE_CXX_FLAGS_RELEASE "-Oz")
+            set (CMAKE_C_FLAGS_RELEASE "-Oz")
+            set (CMAKE_CXX_FLAGS_RELEASE "-Oz")
             if (DEFINED ENV{CI})
                 # Our CI server is slow, so do not optimize and discard all debug info when test building in Debug configuration
                 set (CMAKE_C_FLAGS_DEBUG "-g0")
@@ -848,8 +848,8 @@ macro (setup_emscripten_linker_flags LINKER_FLAGS)
         get_property (EMCC_OPTION SOURCE ${FILE} PROPERTY EMCC_OPTION)
         if (EMCC_OPTION)
             list (APPEND LINK_DEPENDS ${FILE})
-            unset (EMCC_FILE_ALIAS)
-            unset (EMCC_EXCLUDE_FILE)
+            unset (EMCC_FILE_ALIAS)
+            unset (EMCC_EXCLUDE_FILE)
             if (EMCC_OPTION STREQUAL embed-file OR EMCC_OPTION STREQUAL preload-file)
                 get_property (EMCC_FILE_ALIAS SOURCE ${FILE} PROPERTY EMCC_FILE_ALIAS)
                 get_property (EMCC_EXCLUDE_FILE SOURCE ${FILE} PROPERTY EMCC_EXCLUDE_FILE)

Docs/GettingStarted.dox

@@ -121,7 +121,7 @@ A number of build options can be defined when invoking the build scripts or when
 |EMSCRIPTEN_SHARE_DATA|0|Enable sharing data file support (Emscripten cross-compiling build only)|
 |EMSCRIPTEN_EMRUN_BROWSER|*|Specify the particular browser to be spawned by emrun during testing (Emscripten cross-compiling build only), default to firefox|
 
-Note that the specified build option values are cached by CMake after the initial configuration step. The cached values will be used by CMake in the subsequent configuration. The same build options are not required to be specified again and again. But once a non-default build option value is being cached, it can only be reverted back to its default value by explicitly resetting it. That is, simply by not passing the corresponding build option would not revert it back to its default. One way to revert all the build options to their default values is by clearing the CMake cache by calling cmake_clean.bat or cmake_clean.sh.
+Note that the specified build option values are cached by CMake after the initial configuration step. The cached values will be used by CMake in the subsequent configuration. The same build options are not required to be specified again and again. But once a non-default build option value is being cached, it can only be reverted back to its default value by explicitly resetting it. That is, simply by not passing the corresponding build option would not revert it back to its default. One way to revert all the build options to their default values is by clearing the CMake cache by executing cmake_clean.bat or cmake_clean.sh with the location of the build tree as the first argument or by executing it in the build tree itself.
 
 \section Building_Native Native build process
 
@@ -164,8 +164,6 @@ To run from Eclipse on Linux, locate and select the Urho3DPlayer executable in t
 
 To run from Xcode on Mac OS X, edit the Product Scheme to set "Run" setting to execute "Urho3DPlayer" in the "Info" tab. In the "Arguments" tab, specify the arguments required by Urho3DPlayer executable. Ensure the check boxes are ticked on the argument entries that you want to be active.
 
-CMake caches some internal variables to speed up the subsequent invocation of the CMake. This is normally a good thing. However, there are cases when this is not desirable, for instance when switching CMake generators or after upgrading development software components. In such cases, it is recomended to first clean the CMake cache by invoking cmake_clean.bat or cmake_clean.sh by passing the location of the build tree to one of these as the first argument or by executing it in the build tree itself.
-
 \section Building_Android Android build process
 
 First, if you are building under Windows host without MKLINK support then copy bin/Data and bin/CoreData directories to the Android/assets directory (you can use the provided batch file CopyData.bat). This step is not necessary for Windows host with MKLINK support and other non-Windows host systems.
@@ -278,6 +276,15 @@ When building for Direct3D9 with the Windows 8 SDK (Visual Studio 2012+), copy d
 
 OpenGL does not depend on a separate shader compiler DLL.
 
+\section Using_ccache Using ccache
+
+ccache is a compiler cache software available on Linux and Mac OS X host systems. It speeds up the build by bypassing the actual compilation and reusing the result from previous compilation. In order for this to work correctly when building/using Urho3D library with GCC/Clang precompiled header enabled, the following environment variable must be set:
+\verbatim
+CCACHE_SLOPPINESS=pch_defines,time_macros
+\endverbatim
+
+Failure to do so would cause the precompiled header cannot be used by ccache.
+
 \page Running Running Urho3D player application
 
 The Urho3D player application in the bin directory contains all the engine runtime functionality. However, it does not contain any inbuilt logic, and therefore must be supplied with the name of the application script file it should run:

Rakefile

@@ -117,6 +117,7 @@ task :make do
     end
   }
   build_tree = ENV["#{platform}_build_tree"] || ENV['build_tree'] || "../#{platform}-Build"
+  use_ccache = ''
   if !Dir.glob("#{build_tree}/*.xcodeproj").empty?
     # xcodebuild
     if !numjobs.empty?
@@ -130,6 +131,7 @@ task :make do
     filter = unfilter ? '' : '/nologo /verbosity:minimal'
   else
     # make
+    use_ccache = 'CCACHE_SLOPPINESS=pch_defines,time_macros CCACHE_COMPRESS=1' if ENV['USE_CCACHE']
     if numjobs.empty?
       case RUBY_PLATFORM
       when /linux/
@@ -146,7 +148,7 @@ task :make do
     build_options = "-j#{numjobs}#{build_options}"
     filter = ''
   end
-  system "cd \"#{build_tree}\" && cmake --build . #{cmake_build_options} -- #{build_options} #{filter}" or abort
+  system "cd \"#{build_tree}\" && #{use_ccache} cmake --build . #{cmake_build_options} -- #{build_options} #{filter}" or abort
 end
 
 # Usage: rake android [parameter='--es pickedLibrary Urho3DPlayer'] [intent=.SampleLauncher] [package=com.github.urho3d] [success_indicator='Initialized engine'] [payload='sleep 30'] [api=19] [abi=armeabi-v7a] [avd=test_#{api}_#{abi}] [retries=10] [retry_interval=10]