Add check to prevent in-source builds

Also update minimum cmake version in README.md to match CMakeLists.txt

Author: pedro-w

CMakeLists.txt

@@ -59,6 +59,9 @@ string(REPLACE "." "" ALLEGRO_DLL_SHORTVER ${ALLEGRO_SOVERSION})
 # Search in the `cmake' directory for additional CMake modules.
 list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
 
+# Reject in-source builds
+include(PreventInSourceBuilds)
+
 # Search in `deps' directories for dependency files.
 file(GLOB deps_subdirs
     "${PROJECT_SOURCE_DIR}/deps"

README.txt

@@ -41,7 +41,7 @@ Requirements
 We assume you have C and C++ compilers installed and functioning.
 We support gcc, clang and MSVC.
 
-Allegro also requires CMake 2.8.5 or later to build.
+Allegro also requires CMake 3.0 or later to build.
 You may download it from <http://www.cmake.org/>
 
 
@@ -166,6 +166,16 @@ installed on your system.  At the same time, you may select options to
 customise your build.  If you are unsure of what you are doing, leave all the
 options at the defaults.
 
+You must configure Allegro with a separate build directory. For example,
+
+    mkdir build
+    cd build
+    cmake ..
+
+If you configure Allegro to build in the source directory (i.e. `cmake .`)
+you will get an error message. Delete `CMakeCache.txt` and the `CMakeFiles`
+directory and re-configure as described above.
+
 Once the configuration step is successful, you will invoke another tool to
 build Allegro.  The tool depends on your compiler, but is usually either
 `make`, or your IDE.

cmake/PreventInSourceBuilds.cmake

@@ -0,0 +1,17 @@
+# This function will prevent in-source builds
+# Based on https://github.com/InsightSoftwareConsortium/ITK/blob/1b5da45dc706e6d6803b52740fa50e0e5e7705e9/CMake/PreventInSourceBuilds.cmake
+function(PreventInSourceBuilds)
+  # make sure the user doesn't play dirty with symlinks
+  get_filename_component(srcdir "${CMAKE_SOURCE_DIR}" REALPATH)
+  get_filename_component(bindir "${CMAKE_BINARY_DIR}" REALPATH)
+
+  # disallow in-source builds
+  if("${srcdir}" STREQUAL "${bindir}")
+    message(FATAL_ERROR
+      "Allegro must not be configured to build in the source directory.\n"
+      "Please refer to README.md\n"
+      "Quitting configuration step")
+  endif()
+endfunction()
+
+PreventInSourceBuilds()