Documentation cmake (#1549)

* Documenting the compiler flags * Moved some android compiler flags and added documentation on them too. * Some more restructuring. Removed unnecessary comments that were self described by the code. Added some more explanations around certain parts of CMake and especially around compiler flags.
2021-01-26 15:34:27 +02:00 · 2021-01-26 15:34:27 +02:00 · 88a6f16c9a
commit 88a6f16c9a
parent 65b299c6cf
5 changed files with 217 additions and 147 deletions
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@ -2,9 +2,11 @@ cmake_minimum_required(VERSION 3.0)
 project(raylib)

 # Directory for easier includes
+# Anywhere you see include(...) you can check <root>/cmake for that file
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)

-# RAYLIB_IS_MAIN determines whether the project is being used from root, or as a dependency.
+# RAYLIB_IS_MAIN determines whether the project is being used from root
+# or if it is added as a dependency (through add_subdirectory for example).
 if ("${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_CURRENT_SOURCE_DIR}")
  set(RAYLIB_IS_MAIN TRUE)
 else()
@ -17,7 +19,7 @@ include(CompilerFlags)
 # Registers build options that are exposed to cmake
 include(CMakeOptions.txt)

-# Checks a few environment and compiler configurations
+# Enforces a few environment and compiler configurations
 include(BuildOptions)

 # Main sources directory (the second parameter sets the output directory name to raylib)
--- a/cmake/CompilerFlags.cmake
+++ b/cmake/CompilerFlags.cmake
@ -1,28 +1,52 @@
 include(AddIfFlagCompiles)

+# Makes +/- operations on void pointers be considered an error
+# https://gcc.gnu.org/onlinedocs/gcc/Pointer-Arith.html
 add_if_flag_compiles(-Werror=pointer-arith CMAKE_C_FLAGS)
+
+# Generates error whenever a function is used before being declared
+# https://gcc.gnu.org/onlinedocs/gcc-4.0.1/gcc/Warning-Options.html
 add_if_flag_compiles(-Werror=implicit-function-declaration CMAKE_C_FLAGS)
-# src/external/jar_xm.h does shady stuff
+
+# Allows some casting of pointers without generating a warning
 add_if_flag_compiles(-fno-strict-aliasing CMAKE_C_FLAGS)

-if (ENABLE_ASAN)
-    add_if_flag_compiles(-fno-omit-frame-pointer CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
-    add_if_flag_compiles(-fsanitize=address CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
-endif()
-if (ENABLE_UBSAN)
-    add_if_flag_compiles(-fno-omit-frame-pointer CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
-    add_if_flag_compiles(-fsanitize=undefined CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
-endif()
-if (ENABLE_MSAN)
-    add_if_flag_compiles(-fno-omit-frame-pointer CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
-    add_if_flag_compiles(-fsanitize=memory CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
-endif()
-
 if (ENABLE_MSAN AND ENABLE_ASAN)
+    # MSAN and ASAN both work on memory - ASAN does more things
    MESSAGE(WARNING "Compiling with both AddressSanitizer and MemorySanitizer is not recommended")
 endif()

-add_definitions("-DRAYLIB_CMAKE=1")
+if (ENABLE_ASAN)
+    
+    # If enabled it would generate errors/warnings for all kinds of memory errors
+    # (like returning a stack variable by reference)
+    # https://clang.llvm.org/docs/AddressSanitizer.html
+    
+    add_if_flag_compiles(-fno-omit-frame-pointer CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
+    add_if_flag_compiles(-fsanitize=address CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
+    
+endif()
+
+if (ENABLE_UBSAN)
+    
+    # If enabled this will generate errors for undefined behavior points
+    # (like adding +1 to the maximum int value)
+    # https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html
+    
+    add_if_flag_compiles(-fno-omit-frame-pointer CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
+    add_if_flag_compiles(-fsanitize=undefined CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
+    
+endif()
+
+if (ENABLE_MSAN)
+    
+    # If enabled this will generate warnings for places where uninitialized memory is used
+    # https://clang.llvm.org/docs/MemorySanitizer.html
+    
+    add_if_flag_compiles(-fno-omit-frame-pointer CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
+    add_if_flag_compiles(-fsanitize=memory CMAKE_C_FLAGS CMAKE_LINKER_FLAGS)
+    
+endif()

 if(CMAKE_VERSION VERSION_LESS "3.1")
    if(CMAKE_C_COMPILER_ID STREQUAL "GNU")
@ -31,3 +55,25 @@ if(CMAKE_VERSION VERSION_LESS "3.1")
 else()
    set (CMAKE_C_STANDARD 99)
 endif()
+
+if(${PLATFORM} MATCHES "Android")
+    
+    # If enabled will remove dead code during the linking process
+    # https://gcc.gnu.org/onlinedocs/gnat_ugn/Compilation-options.html
+    add_if_flag_compiles(-ffunction-sections CMAKE_C_FLAGS)
+    
+    # If enabled will generate some exception data (usually disabled for C programs)
+    # https://gcc.gnu.org/onlinedocs/gcc-4.2.4/gcc/Code-Gen-Options.html
+    add_if_flag_compiles(-funwind-tables CMAKE_C_FLAGS)
+    
+    # If enabled adds stack protection guards around functions that allocate memory
+    # https://www.keil.com/support/man/docs/armclang_ref/armclang_ref_cjh1548250046139.htm
+    add_if_flag_compiles(-fstack-protector-strong CMAKE_C_FLAGS)
+    
+    # Marks that the library will not be compiled with an executable stack
+    add_if_flag_compiles(-Wa,--noexecstack CMAKE_C_FLAGS)
+    
+    # Do not expand symbolic links or resolve paths like "/./" or "/../", etc.
+    # https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html
+    add_if_flag_compiles(-no-canonical-prefixes CMAKE_C_FLAGS)
+endif()
--- a/cmake/LibraryConfigurations.cmake
+++ b/cmake/LibraryConfigurations.cmake
@ -1,7 +1,7 @@
-if(${PLATFORM} MATCHES "Desktop")
+if (${PLATFORM} MATCHES "Desktop")
    set(PLATFORM_CPP "PLATFORM_DESKTOP")
    
-    if(APPLE)
+    if (APPLE)
        # Need to force OpenGL 3.3 on OS X
        # See: https://github.com/raysan5/raylib/issues/341
        set(GRAPHICS "GRAPHICS_API_OPENGL_33")
@ -11,40 +11,35 @@ if(${PLATFORM} MATCHES "Desktop")
        if (NOT CMAKE_SYSTEM STRLESS "Darwin-18.0.0")
            add_definitions(-DGL_SILENCE_DEPRECATION)
            MESSAGE(AUTHOR_WARNING "OpenGL is deprecated starting with macOS 10.14 (Mojave)!")
-        endif()
-    elseif(WIN32)
+        endif ()
+    elseif (WIN32)
        add_definitions(-D_CRT_SECURE_NO_WARNINGS)
        set(LIBS_PRIVATE ${LIBS_PRIVATE} winmm)
-    else()
+    else ()
        find_library(pthread NAMES pthread)
        find_package(OpenGL QUIET)
        if ("${OPENGL_LIBRARIES}" STREQUAL "")
            set(OPENGL_LIBRARIES "GL")
-        endif()
+        endif ()
        
        if ("${CMAKE_SYSTEM_NAME}" MATCHES "(Net|Open)BSD")
            find_library(OSS_LIBRARY ossaudio)
-        endif()
+        endif ()
        
        set(LIBS_PRIVATE m pthread ${OPENGL_LIBRARIES} ${OSS_LIBRARY})
-    endif()
+    endif ()

-elseif(${PLATFORM} MATCHES "Web")
+elseif (${PLATFORM} MATCHES "Web")
    set(PLATFORM_CPP "PLATFORM_WEB")
    set(GRAPHICS "GRAPHICS_API_OPENGL_ES2")
-    set(CMAKE_C_FLAGS "-s USE_GLFW=3 -s ASSERTIONS=1 --profiling")
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -s USE_GLFW=3 -s ASSERTIONS=1 --profiling")
    set(CMAKE_STATIC_LIBRARY_SUFFIX ".a")

-elseif(${PLATFORM} MATCHES "Android")
+elseif (${PLATFORM} MATCHES "Android")
    set(PLATFORM_CPP "PLATFORM_ANDROID")
    set(GRAPHICS "GRAPHICS_API_OPENGL_ES2")
-    include(AddIfFlagCompiles)
-    add_if_flag_compiles(-ffunction-sections CMAKE_C_FLAGS)
-    add_if_flag_compiles(-funwind-tables CMAKE_C_FLAGS)
-    add_if_flag_compiles(-fstack-protector-strong CMAKE_C_FLAGS)
    set(CMAKE_POSITION_INDEPENDENT_CODE ON)
-    add_if_flag_compiles(-Wa,--noexecstack CMAKE_C_FLAGS)
-    add_if_flag_compiles(-no-canonical-prefixes CMAKE_C_FLAGS)
+    
    add_definitions(-DANDROID -D__ANDROID_API__=21)
    include_directories(external/android/native_app_glue)
    set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,--exclude-libs,libatomic.a -Wl,--build-id -Wl,-z,noexecstack -Wl,-z,relro -Wl,-z,now -Wl,--warn-shared-textrel -Wl,--fatal-warnings -uANativeActivity_onCreate")
@ -52,7 +47,7 @@ elseif(${PLATFORM} MATCHES "Android")
    find_library(OPENGL_LIBRARY OpenGL)
    set(LIBS_PRIVATE m log android EGL GLESv2 OpenSLES atomic c)

-elseif(${PLATFORM} MATCHES "Raspberry Pi")
+elseif (${PLATFORM} MATCHES "Raspberry Pi")
    set(PLATFORM_CPP "PLATFORM_RPI")
    set(GRAPHICS "GRAPHICS_API_OPENGL_ES2")
    
@ -65,7 +60,7 @@ elseif(${PLATFORM} MATCHES "Raspberry Pi")
    link_directories(/opt/vc/lib)
    set(LIBS_PRIVATE ${GLESV2} ${EGL} ${BCMHOST} pthread rt m dl)

-elseif(${PLATFORM} MATCHES "DRM")
+elseif (${PLATFORM} MATCHES "DRM")
    set(PLATFORM_CPP "PLATFORM_DRM")
    set(GRAPHICS "GRAPHICS_API_OPENGL_ES2")
    
@ -81,7 +76,7 @@ elseif(${PLATFORM} MATCHES "DRM")
    include_directories(/usr/include/libdrm)
    set(LIBS_PRIVATE ${GLESV2} ${EGL} ${DRM} ${GBM} pthread m dl)

-endif()
+endif ()

 if (${OPENGL_VERSION})
    set(${SUGGESTED_GRAPHICS} "${GRAPHICS}")
@ -93,12 +88,18 @@ if (${OPENGL_VERSION})
        set(GRAPHICS "GRAPHICS_API_OPENGL_11")
    elseif (${OPENGL_VERSION} MATCHES "ES 2.0")
        set(GRAPHICS "GRAPHICS_API_OPENGL_ES2")
-    endif()
+    endif ()
    if ("${SUGGESTED_GRAPHICS}" AND NOT "${SUGGESTED_GRAPHICS}" STREQUAL "${GRAPHICS}")
        message(WARNING "You are overriding the suggested GRAPHICS=${SUGGESTED_GRAPHICS} with ${GRAPHICS}! This may fail")
-    endif()
-endif()
+    endif ()
+endif ()

-if(NOT GRAPHICS)
+if (NOT GRAPHICS)
    set(GRAPHICS "GRAPHICS_API_OPENGL_33")
-endif()
+endif ()
+
+set(LIBS_PRIVATE ${LIBS_PRIVATE} ${OPENAL_LIBRARY})
+
+if (${PLATFORM} MATCHES "Desktop")
+    set(LIBS_PRIVATE ${LIBS_PRIVATE} glfw)
+endif ()
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@ -1,33 +1,29 @@
 # Setup the project and settings
 project(examples)

-# Get the sources together
-set(example_dirs audio core models others shaders shapes text textures)
+# Directories that contain examples
+set(example_dirs
+    audio
+    core
+    models
+    others
+    shaders
+    shapes
+    text
+    textures
+    )
+
+# Next few lines will check for existence of symbols or header files
+# They are needed for the physac example and threads examples
 set(CMAKE_REQUIRED_DEFINITIONS -D_POSIX_C_SOURCE=199309L)
-  include(CheckSymbolExists)
-  check_symbol_exists(CLOCK_MONOTONIC time.h HAVE_CLOCK_MONOTONIC)
-  check_symbol_exists(QueryPerformanceCounter windows.h HAVE_QPC)
+include(CheckSymbolExists)
+check_symbol_exists(CLOCK_MONOTONIC time.h HAVE_CLOCK_MONOTONIC)
+check_symbol_exists(QueryPerformanceCounter windows.h HAVE_QPC)
 set(CMAKE_REQUIRED_DEFINITIONS)
-if(HAVE_QPC OR HAVE_CLOCK_MONOTONIC)
+
+if (HAVE_QPC OR HAVE_CLOCK_MONOTONIC)
    set(example_dirs ${example_dirs} physac)
-endif()
-
-set(example_sources)
-set(example_resources)
-foreach(example_dir ${example_dirs})
-  # Get the .c files
-  file(GLOB sources ${example_dir}/*.c)
-  list(APPEND example_sources ${sources})
-
-  # Any any resources
-  file(GLOB resources ${example_dir}/resources/*)
-  list(APPEND example_resources ${resources})
-endforeach()
-
-if (APPLE AND NOT CMAKE_SYSTEM STRLESS "Darwin-18.0.0")
-  add_definitions(-DGL_SILENCE_DEPRECATION)
-  MESSAGE(AUTHOR_WARNING "OpenGL is deprecated starting with macOS 10.14 (Mojave)!")
-endif()
+endif ()

 include(CheckIncludeFile)
 CHECK_INCLUDE_FILE("stdatomic.h" HAVE_STDATOMIC_H)
@ -35,19 +31,39 @@ set(CMAKE_THREAD_PREFER_PTHREAD TRUE)
 find_package(Threads)
 if (CMAKE_USE_PTHREADS_INIT AND HAVE_STDATOMIC_H)
    add_if_flag_compiles("-std=c11" CMAKE_C_FLAGS)
-  if(THREADS_HAVE_PTHREAD_ARG)
+    if (THREADS_HAVE_PTHREAD_ARG)
        add_if_flag_compiles("-pthread" CMAKE_C_FLAGS)
-  endif()
-  if(CMAKE_THREAD_LIBS_INIT)
+    endif ()
+    if (CMAKE_THREAD_LIBS_INIT)
        link_libraries("${CMAKE_THREAD_LIBS_INIT}")
-  endif()
-else()
+    endif ()
+endif ()
+
+if (APPLE AND NOT CMAKE_SYSTEM STRLESS "Darwin-18.0.0")
+    add_definitions(-DGL_SILENCE_DEPRECATION)
+    MESSAGE(AUTHOR_WARNING "OpenGL is deprecated starting with macOS 10.14 (Mojave)!")
+endif ()
+
+# Collect all source files and resource files
+# into a CMake variable
+set(example_sources)
+set(example_resources)
+foreach (example_dir ${example_dirs})
+    # Get the .c files
+    file(GLOB sources ${example_dir}/*.c)
+    list(APPEND example_sources ${sources})
+    
+    # Any any resources
+    file(GLOB resources ${example_dir}/resources/*)
+    list(APPEND example_resources ${resources})
+endforeach ()
+
+if(NOT CMAKE_USE_PTHREADS_INIT OR NOT HAVE_STDATOMIC_H)
    # Items requiring pthreads
    list(REMOVE_ITEM example_sources ${CMAKE_CURRENT_SOURCE_DIR}/core/core_loading_thread.c)
-endif()
+endif ()

-
-if(${PLATFORM} MATCHES "Android")
+if (${PLATFORM} MATCHES "Android")
    list(REMOVE_ITEM example_sources ${CMAKE_CURRENT_SOURCE_DIR}/others/rlgl_standalone.c)
    list(REMOVE_ITEM example_sources ${CMAKE_CURRENT_SOURCE_DIR}/others/standard_lighting.c)
    list(REMOVE_ITEM example_sources ${CMAKE_CURRENT_SOURCE_DIR}/core/core_3d_picking.c)
@ -78,7 +94,7 @@ if(${PLATFORM} MATCHES "Android")
    list(REMOVE_ITEM example_sources ${CMAKE_CURRENT_SOURCE_DIR}/shaders/shaders_palette_switch.c)
    list(REMOVE_ITEM example_sources ${CMAKE_CURRENT_SOURCE_DIR}/shaders/shaders_basic_lighting.c)

-elseif(${PLATFORM} MATCHES "Web")
+elseif (${PLATFORM} MATCHES "Web")
    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Os -s USE_GLFW=3 -s ASSERTIONS=1 -s WASM=1 -s ASYNCIFY")
    # Since WASM is used, ALLOW_MEMORY_GROWTH has no extra overheads
    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -s ALLOW_MEMORY_GROWTH=1 --no-heap-copy")
@ -89,16 +105,16 @@ elseif(${PLATFORM} MATCHES "Web")
    # does not generate HTML+JS+WASM files, only a non-working
    # and fat HTML
    string(REPLACE "-rdynamic" "" CMAKE_SHARED_LIBRARY_LINK_C_FLAGS "${CMAKE_SHARED_LIBRARY_LINK_C_FLAGS}")
-endif()
+endif ()

 include_directories(BEFORE SYSTEM others/external/include)

 if (NOT TARGET raylib)
    find_package(raylib 2.0 REQUIRED)
-endif()
+endif ()

 # Do each example
-foreach(example_source ${example_sources})
+foreach (example_source ${example_sources})
    # Create the basename for the example
    get_filename_component(example_name ${example_source} NAME)
    string(REPLACE ".c" "" example_name ${example_name})
@ -111,12 +127,12 @@ foreach(example_source ${example_sources})
    string(REGEX MATCH ".*/.*/" resources_dir ${example_source})
    string(APPEND resources_dir "resources")
    
-  if(${PLATFORM} MATCHES "Web" AND EXISTS ${resources_dir})
+    if (${PLATFORM} MATCHES "Web" AND EXISTS ${resources_dir})
        # The local resources path needs to be mapped to /resources virtual path
        string(APPEND resources_dir "@resources")
        set_target_properties(${example_name} PROPERTIES LINK_FLAGS "--preload-file ${resources_dir}")
-  endif()
-endforeach()
+    endif ()
+endforeach ()

 # Copy all of the resource files to the destination
 file(COPY ${example_resources} DESTINATION "resources/")
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@ -10,6 +10,8 @@ include(JoinPaths)
 if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
    if(RAYLIB_IS_MAIN)
        set(default_build_type Debug)
+    else()
+        message(WARNING "Default build type is not set (CMAKE_BUILD_TYPE)")
    endif()

    message(STATUS "Setting build type to '${default_build_type}' as none was specified.")
@ -18,7 +20,7 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
    set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "MinSizeRel" "RelWithDebInfo")
 endif()

-# Get the sources together
+# Used as public API to be included into other projects
 set(raylib_public_headers
    raylib.h
    rlgl.h
@ -27,6 +29,7 @@ set(raylib_public_headers
    raudio.h
    )

+# Sources to be compiled
 set(raylib_sources
    core.c
    models.c
@ -36,7 +39,7 @@ set(raylib_sources
    utils.c
    )

-# cmake/GlfwImport.cmake handles the details around the inclusion of glfw
+# <root>/cmake/GlfwImport.cmake handles the details around the inclusion of glfw
 include(GlfwImport)


@ -47,10 +50,11 @@ else ()
    MESSAGE(STATUS "Audio Backend: None (-DUSE_AUDIO=OFF)")
 endif ()

+# Sets additional platform options and link libraries for each platform
+# also selects the proper graphics API and version for that platform
+# Produces a variable LIBS_PRIVATE that will be used later
 include(LibraryConfigurations)

-set(LIBS_PRIVATE ${LIBS_PRIVATE} ${OPENAL_LIBRARY})
-
 add_library(raylib ${raylib_sources} ${raylib_public_headers})

 if (NOT BUILD_SHARED_LIBS)
@ -66,7 +70,6 @@ else()
    endif ()
 endif()

-# Setting target properties
 set_target_properties(raylib PROPERTIES
                      PUBLIC_HEADER "${raylib_public_headers}"
                      VERSION ${PROJECT_VERSION}
@ -77,12 +80,11 @@ if (WITH_PIC OR BUILD_SHARED_LIBS)
    set_property(TARGET raylib PROPERTY POSITION_INDEPENDENT_CODE ON)
 endif ()

-# Linking libraries
 target_link_libraries(raylib "${LIBS_PRIVATE}")
-if (${PLATFORM} MATCHES "Desktop")
-    target_link_libraries(raylib glfw)
-endif ()

+# Sets some compile time definitions for the pre-processor
+# If CUSTOMIZE_BUILD option is on you will not use config.h by default
+# and you will be able to select more build options
 include(CompileDefinitions)

 # Registering include directories
@ -99,6 +101,8 @@ target_include_directories(raylib
 # Copy the header files to the build directory for convenience
 file(COPY ${raylib_public_headers} DESTINATION "include")

+# Includes information on how the library will be installed on the system
+# when cmake --install is run
 include(InstallConfigurations)

 # Print the flags for the user
@ -112,6 +116,7 @@ message(STATUS "Compiling with the flags:")
 message(STATUS "  PLATFORM=" ${PLATFORM_CPP})
 message(STATUS "  GRAPHICS=" ${GRAPHICS})

+# Options if you want to create an installer using CPack
 include(PackConfigurations)

 enable_testing()