Document and warn about old CMake versions with Ninja

Resolves #1369

CMakeLists.txt

@@ -21,6 +21,12 @@ OPTION(REMOVE_SYMBOLS_FROM_DF_STUBS "Remove debug symbols from DF stubs. (Reduce
 cmake_minimum_required(VERSION 2.8.12 FATAL_ERROR)
 project(dfhack)
 
+if("${CMAKE_GENERATOR}" STREQUAL Ninja)
+  if("${CMAKE_VERSION}" VERSION_LESS 3.9)
+    message(WARNING "You are using an old version of CMake (${CMAKE_VERSION}) with Ninja. This may result in ninja errors - see docs/Compile.rst for more details. Upgrading your CMake version is recommended.")
+  endif()
+endif()
+
 macro(CHECK_GCC COMPILER_PATH)
   execute_process(COMMAND ${COMPILER_PATH} -dumpversion OUTPUT_VARIABLE GCC_VERSION_OUT)
   string(STRIP "${GCC_VERSION_OUT}" GCC_VERSION_OUT)

docs/Compile.rst

@@ -68,6 +68,10 @@ and more, please see `contributing-code`.
 Build settings
 ==============
 
+This section describes build configuration options that apply to all platforms.
+If you don't have a working build environment set up yet, follow the instructions
+in the platform-specific sections below first, then come back here.
+
 Generator
 ---------
 
@@ -86,6 +90,12 @@ much slower than Ninja builds.
   generator cannot be changed after ``cmake`` has been run without creating a
   new build folder. Do not forget to specify this option.
 
+  CMake versions 3.6 and older, and possibly as recent as 3.9, are known to
+  produce project files with dependency cycles that fail to build
+  (see :issue:`1369`). Obtaining a recent version of CMake is recommended, either from
+  `cmake.org <https://cmake.org/download/>`_ or through a package manager. See
+  the sections below for more platform-specific directions for installing CMake.
+
 Build type
 ----------