diff --git a/CMakeLists.txt b/CMakeLists.txt
index 15bfee8a..2ca7d353 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,36 +1,51 @@
 cmake_minimum_required(VERSION 3.16)
 project(MiniFB VERSION 0.10.1 LANGUAGES C CXX)
 
-if (APPLE)
+message(STATUS "Processing " ${PROJECT_NAME})
+
+# CMake configuration
+#--------------------------------------
+
+# prefer these over general `UNIX` or `APPLE`
+# `UNIX` also overlaps MacOS, iOS, and Emscripten, which we don't want
+if (CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    set(LINUX TRUE)
+elseif (CMAKE_SYSTEM_NAME STREQUAL "Darwin")
+    set(MACOS TRUE)
+endif()
+
+# ensure that an objective-c compiler exists when attempting to compile on any target that uses objective-c
+if (MACOS OR IOS)
     include(CheckLanguage)
     check_language(OBJC)
-    if (CMAKE_OBJC_COMPILER)
+    if (CMAKE_OBJC_COMPILER STREQUAL "NOTFOUND")
+        message(FATAL "No OBJC compiler could be found.")
+    else()
         enable_language(OBJC)
     endif()
 endif()
 
-message(STATUS "Processing " ${PROJECT_NAME})
-
 include(GNUInstallDirs)
-include("${CMAKE_CURRENT_SOURCE_DIR}/cmake/versioning.cmake")
-include("${CMAKE_CURRENT_SOURCE_DIR}/cmake/minifb_cmake_helpers.cmake")
-if (POLICY CMP0072)
-    cmake_policy(SET CMP0072 NEW)  # Prefer GLVND
-endif()
-set(OpenGL_GL_PREFERENCE "GLVND")
+include("cmake/minifb_cmake_helpers.cmake")
 
+# use IDE folders in build systems that support it. enabled by default in cmake 3.26+
+set_property(GLOBAL PROPERTY USE_FOLDERS ON)
+
+# directory to add generated headers (created during configuration)
+set(MINIFB_GENERATED_INCLUDE_DIR "${CMAKE_CURRENT_BINARY_DIR}/generated")
+file(MAKE_DIRECTORY "${MINIFB_GENERATED_INCLUDE_DIR}")
+
+# generate the version header from the templace (.in)
 minifb_compute_git_metadata(
     MINIFB_COMMITS_SINCE_TAG
     MINIFB_COMMIT_COUNT
     MINIFB_GIT_SHA
     MINIFB_GIT_DIRTY
 )
-
-set(MINIFB_GENERATED_INCLUDE_DIR "${CMAKE_CURRENT_BINARY_DIR}/generated")
-minifb_configure_version_header(
-    "${CMAKE_CURRENT_SOURCE_DIR}/include/minifb_version.h.in"
-    "${MINIFB_GENERATED_INCLUDE_DIR}"
+configure_file(
+    include/minifb_version.h.in
     "${MINIFB_GENERATED_INCLUDE_DIR}/minifb_version.h"
+    @ONLY
 )
 
 # Sources
@@ -43,6 +58,9 @@ set(SrcLib
     include/MiniFB_macros.h
     include/MiniFB_types.h
 
+    # remember to include generated headers as source files
+    "${MINIFB_GENERATED_INCLUDE_DIR}/minifb_version.h"
+
     src/MiniFB_common.c
     src/MiniFB_cpp.cpp
     src/MiniFB_internal.c
@@ -122,232 +140,305 @@ set(SrcDOS
     src/dos/vesa.c
 )
 
-# Set features
-#--------------------------------------
-set(MINIFB_C_STANDARD 11)
-set(MINIFB_CXX_STANDARD 11)
-
-set(MINIFB_COMPILE_OPTIONS)
-set(MINIFB_COMPILE_DEFINITIONS)
-set(MINIFB_LINK_OPTIONS_LIB)
-set(MINIFB_LINK_OPTIONS_EXE)
-
-if (DJGPP)
-    # DJGPP headers expose key DOS APIs only in GNU (non-strict ANSI) mode.
-    set(MINIFB_C_EXTENSIONS   ON)
-    set(MINIFB_CXX_EXTENSIONS ON)
-else()
-    set(MINIFB_C_EXTENSIONS   OFF)
-    set(MINIFB_CXX_EXTENSIONS OFF)
-endif()
-
 # Options
 #--------------------------------------
 option(MINIFB_BUILD_EXAMPLES "Build minifb example programs" TRUE)
 option(MINIFB_AVOID_CPP_HEADERS "Avoid including C++ Headers" FALSE)
 
-if (NOT IOS AND NOT ANDROID AND NOT EMSCRIPTEN)
-    option(MINIFB_BUILD_VERSION_INFO "Build version info utility" ON)
-else()
-    set(MINIFB_BUILD_VERSION_INFO OFF)
-endif()
+# purely for internal use, never exposed to the user
+set(MINIFB_USE_X11_API OFF)
 
-if (APPLE AND NOT IOS)
-    option(MINIFB_USE_METAL_API "Build the project using metal API code" ON)
-    option(MINIFB_USE_INVERTED_Y_ON_MACOS "Use default mouse position: (0, 0) at (left, down)" OFF)
-    minifb_apply_deprecated_option(USE_METAL_API MINIFB_USE_METAL_API "Build the project using metal API code")
+# unfortunatly these old deprecated options can't fit nicely into dependent options due to our custom function, but when we remove these, we can remove this whole block
+if (MACOS)
+    minifb_apply_deprecated_option(USE_METAL_API MINIFB_USE_METAL_API "Build the project using Metal API code")
     minifb_apply_deprecated_option(USE_INVERTED_Y_ON_MACOS MINIFB_USE_INVERTED_Y_ON_MACOS "Use default mouse position: (0, 0) at (left, down)")
-elseif (UNIX AND NOT EMSCRIPTEN)
-    option(MINIFB_USE_WAYLAND_API "Build the project using wayland API code" OFF)
-    option(MINIFB_USE_OPENGL_API "Build the project using OpenGL API code" ON)
-    minifb_apply_deprecated_option(USE_WAYLAND_API MINIFB_USE_WAYLAND_API "Build the project using wayland API code")
-    minifb_apply_deprecated_option(USE_OPENGL_API MINIFB_USE_OPENGL_API "Build the project using OpenGL API code")
+elseif (LINUX)
+    minifb_apply_deprecated_option(USE_WAYLAND_API MINIFB_USE_WAYLAND_API "Build the project using Wayland API code")
+    if (NOT MINIFB_USE_WAYLAND_API)
+        set(MINIFB_USE_X11_API ON)
+        minifb_apply_deprecated_option(USE_OPENGL_API MINIFB_USE_OPENGL_API "Build the project using OpenGL API code")
+    endif()
 elseif (WIN32)
-    option(MINIFB_USE_OPENGL_API "Build the project using OpenGL API code" ON)
     minifb_apply_deprecated_option(USE_OPENGL_API MINIFB_USE_OPENGL_API "Build the project using OpenGL API code")
 endif()
 
-# Set compile flags depending on the compiler
-#--------------------------------------
-if (NOT MSVC)
+if (NOT MINIFB_HAVE_SET_LEGACY_OPTION) # only use new options if no legacy options are used to prevent conflicts
 
-    # GCC/Clang
+if (CMAKE_VERSION VERSION_GREATER_EQUAL 3.22)
 
-    if (DJGPP)
-        list(APPEND MINIFB_COMPILE_OPTIONS
-            "$<$<CONFIG:Debug>:-gdwarf>"
-            "$<$<CONFIG:Debug>:-save-temps>"
-        )
-    else()
-        list(APPEND MINIFB_COMPILE_OPTIONS
-            "$<$<CONFIG:Debug>:-g>"
-        )
-    endif()
+    # requires 3.22+ to use full condition syntax, technically could use in 3.16, but it would be a lot worse
+    include(CMakeDependentOption)
 
-    list(APPEND MINIFB_COMPILE_OPTIONS
-        -Wall
-        -Wextra
-        -Wno-switch
-        -Wno-unused-function
-        -Wno-unused-parameter
-        -Wno-implicit-fallthrough
-        "$<IF:$<CONFIG:Debug>,-O0,-O2>"
-    )
+    # cmake_dependent_option is used to create a default value for options in case their specific condition isn't met.
+    # the first 3 args are the same as a normal option(), but the 4th is a condition, where if it's true, expose the option, and if it isn't, the 5th argument is a default value to use.
+    # setting the default value lets us de-nest `if(<platform>) if(<option>)` type stuff, into just `if(<option>)`.
 
-    if (NOT APPLE)
-        list(APPEND MINIFB_COMPILE_OPTIONS
-            -Wno-cast-function-type
-        )
+    cmake_dependent_option(MINIFB_BUILD_VERSION_INFO "Build version info utility" ON
+        "NOT IOS AND NOT ANDROID AND NOT EMSCRIPTEN" OFF)
+
+    cmake_dependent_option(MINIFB_USE_METAL_API "Build the project using Metal API code" ON
+        "MACOS" OFF)
+    cmake_dependent_option(MINIFB_USE_INVERTED_Y_ON_MACOS "Use default mouse position: (0, 0) at (left, down)" OFF
+        "MACOS" OFF)
+
+    cmake_dependent_option(MINIFB_USE_WAYLAND_API "Build the project using Wayland API code" OFF
+        "LINUX" OFF)
+
+    if (NOT MINIFB_USE_WAYLAND_API AND LINUX)
+        set(MINIFB_USE_X11_API ON)
     endif()
 
+    cmake_dependent_option(MINIFB_USE_OPENGL_API "Build the project using OpenGL API code" ON
+        "MINIFB_USE_X11_API OR WIN32" OFF)
+
 else()
 
-    # MSVC
-    #--------------------------------------
-
-    list(APPEND MINIFB_COMPILE_OPTIONS
-        # Security check
-        /GS
-        # Function level linking
-        /Gy
-        # Exceptions
-        /EHsc
-        # Fast floating point maths
-        /fp:fast
-        # Force Visual Studio to actualize __cplusplus version macro
-        /Zc:__cplusplus
-
-        # Program database for edit and continue
-        "$<IF:$<CONFIG:Debug>,/ZI,/Zi>"
-        # Optimizations
-        "$<IF:$<CONFIG:Debug>,/Od,/O2>"
-        # Inline function expansion
-        "$<IF:$<CONFIG:Debug>,/Ob0,/Ob2>"
-        # Basic runtime checks
-        "$<$<CONFIG:Debug>:/RTC1>"
-    )
+    # even if an `option()` isn't reached, if it's been reached in previous configurations then the old value still exists as a cache variable
+    # this means it can still be seen and edited by tools such as cmake-gui, without any indication that it's not meant to be enabled
+    # this can lead to cases where two conflicting options are active, so we need to manually `set()` values OFF if they're not reached
+    # dependent options fix this, which is why they should be prioritised if available
 
-    if (MSVC_VERSION GREATER_EQUAL 1900)
-        # SDL checks 2015+
-        list(APPEND MINIFB_COMPILE_OPTIONS /sdl)
+    if (NOT IOS AND NOT ANDROID AND NOT EMSCRIPTEN)
+        option(MINIFB_BUILD_VERSION_INFO "Build version info utility" ON)
+    else()
+        set(MINIFB_BUILD_VERSION_INFO OFF)
     endif()
 
-    if (MSVC_VERSION LESS_EQUAL 1920)
-        # Enable Minimal Rebuild (required for Edit and Continue) (deprecated)
-        list(APPEND MINIFB_COMPILE_OPTIONS /Gm)
+    if (MACOS)
+        option(MINIFB_USE_METAL_API "Build the project using Metal API code" ON)
+        option(MINIFB_USE_INVERTED_Y_ON_MACOS "Use default mouse position: (0, 0) at (left, down)" OFF)
+    else()
+        set(MINIFB_USE_METAL_API OFF)
+        set(MINIFB_USE_INVERTED_Y_ON_MACOS OFF)
     endif()
 
-endif()
+    if (LINUX)
+        option(MINIFB_USE_WAYLAND_API "Build the project using Wayland API code" OFF)
+    else()
+        set(MINIFB_USE_WAYLAND_API OFF)
+        set(MINIFB_USE_X11_API ON)
+    endif()
 
-list(APPEND MINIFB_COMPILE_DEFINITIONS
-    "$<$<CONFIG:Debug>:_DEBUG>"
-    "$<$<CONFIG:Debug>:DEBUG>"
-)
+    if (WIN32 OR MINIFB_USE_X11_API)
+        option(MINIFB_USE_OPENGL_API "Build the project using OpenGL API code" ON)
+    else()
+        set(MINIFB_USE_OPENGL_API OFF)
+    endif()
+
+endif()
 
-if (EMSCRIPTEN)
-    list(APPEND MINIFB_LINK_OPTIONS_EXE
-        "$<$<CONFIG:Debug>:-g>"
-    )
 endif()
 
-# Set compiler/platform specific flags and dependencies
+# Compilation configuration (will be ran on library and examples)
 #--------------------------------------
-if (WIN32)
+function(minifb_configure_target target)
+    if (NOT MSVC)
+        # GCC/Clang
+        target_compile_options(${target} PRIVATE
+            -Wall
+            -Wextra
+            -Wno-switch
+            -Wno-unused-function
+            -Wno-unused-parameter
+            -Wno-implicit-fallthrough
+            "$<IF:$<CONFIG:Debug>,-O0,-O2>"
+            "$<$<CONFIG:Debug>:-g>"
+        )
 
-    if (MSVC)
-        list(APPEND MINIFB_COMPILE_DEFINITIONS _CRT_SECURE_NO_WARNINGS)
+    else()
+        # MSVC
+        target_compile_options(${target} PRIVATE
+            # Security check
+            /GS
+            # Function level linking
+            /Gy
+            # Exceptions
+            /EHsc
+            # Fast floating point maths
+            /fp:fast
+            # Force Visual Studio to actualize __cplusplus version macro
+            /Zc:__cplusplus
+            # Additional security checks
+            /sdl
+
+            # Program database (edit and continue in debug mode)
+            "$<IF:$<CONFIG:Debug>,/ZI,/Zi>"
+            # Optimizations
+            "$<IF:$<CONFIG:Debug>,/Od,/O2>"
+            # Inline function expansion
+            "$<IF:$<CONFIG:Debug>,/Ob0,/Ob2>"
+            # Basic runtime checks
+            "$<$<CONFIG:Debug>:/RTC1>"
+        )
+
+        # prevent annoying c standard lib unsafety msvc warnings
+        target_compile_definitions(${target} PRIVATE _CRT_SECURE_NO_WARNINGS)
     endif()
-    list(APPEND MINIFB_COMPILE_DEFINITIONS _WIN32_WINNT=0x0601)  # Windows 7 (we are in 2026)
 
-    if (USE_OPENGL_API)
-        list(APPEND SrcLib ${SrcGL})
+    target_compile_definitions(${target} PRIVATE
+        "$<$<CONFIG:Debug>:_DEBUG>"
+        "$<$<CONFIG:Debug>:DEBUG>"
+    )
 
-        list(APPEND MINIFB_COMPILE_DEFINITIONS USE_OPENGL_API)
+    if (WIN32)
+        target_compile_definitions(${target} PRIVATE _WIN32_WINNT=0x0601)  # minimum supported version (and header version) = windows 7 (we are in 2026)
     endif()
 
-    list(APPEND SrcLib ${SrcWindows})
+    # DJGPP headers expose key DOS APIs only in GNU (non-strict ANSI) mode.
+    if (DJGPP)
+        set(MINIFB_C_EXTENSIONS   ON)
+        set(MINIFB_CXX_EXTENSIONS ON)
+    else()
+        set(MINIFB_C_EXTENSIONS   OFF)
+        set(MINIFB_CXX_EXTENSIONS OFF)
+    endif()
+
+    set_target_properties(${target} PROPERTIES
+        C_STANDARD 11
+        C_STANDARD_REQUIRED ON
+        C_EXTENSIONS ${MINIFB_C_EXTENSIONS}
+        CXX_STANDARD 11
+        CXX_STANDARD_REQUIRED ON
+        CXX_EXTENSIONS ${MINIFB_CXX_EXTENSIONS}
+    )
+
+endfunction()
+
+# Create library target and configure
+#--------------------------------------
+add_library(minifb STATIC ${SrcLib})
+add_library(minifb::minifb ALIAS minifb) # cmake installing will install the "minifb::" namespace
+
+set_property(TARGET minifb PROPERTY FOLDER "Libs")
+minifb_configure_target(minifb)
+
+# headers required for users (differs depending on if it's been built or installed)
+target_include_directories(minifb PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}/include>  # most headers
+    $<BUILD_INTERFACE:${MINIFB_GENERATED_INCLUDE_DIR}>    # auto-generated headers
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)     # (both of those are in the same location if installed)
+
+target_include_directories(minifb PRIVATE src)  # include internal headers
+
+# conditional main library target configuration
+
+if (MINIFB_USE_INVERTED_Y_ON_MACOS)
+    target_compile_definitions(minifb PRIVATE USE_INVERTED_Y_ON_MACOS)
+endif()
+
+# Add GL/Metal code if we're using GL/Metal, no matter the specific platform
+if (MINIFB_USE_OPENGL_API)
+    target_sources(minifb PRIVATE ${SrcGL})
+    target_compile_definitions(minifb PRIVATE USE_OPENGL_API)
+endif()
+if (MINIFB_USE_METAL_API)
+    target_compile_definitions(minifb PRIVATE USE_METAL_API)
+    target_sources(minifb PRIVATE ${SrcMacOSMetal})
+endif()
+
+if (WIN32)
+    target_sources(minifb PRIVATE ${SrcWindows})
 
 elseif (IOS)
+    target_sources(minifb PRIVATE ${SrcIOS})
 
-    list(APPEND SrcLib ${SrcIOS})
+elseif (MACOS)
+    target_sources(minifb PRIVATE ${SrcMacOS})
 
-elseif (APPLE)
+elseif (MINIFB_USE_WAYLAND_API)
+    target_sources(minifb PRIVATE ${SrcWayland})
 
-    if (USE_METAL_API)
-        list(APPEND MINIFB_COMPILE_DEFINITIONS USE_METAL_API)
-        list(APPEND SrcLib ${SrcMacOSMetal})
-    endif()
+elseif (MINIFB_USE_X11_API)
+    target_sources(minifb PRIVATE ${SrcX11})
 
-    if (USE_INVERTED_Y_ON_MACOS)
-        list(APPEND MINIFB_COMPILE_DEFINITIONS USE_INVERTED_Y_ON_MACOS)
+elseif (EMSCRIPTEN)
+    target_sources(minifb PRIVATE ${SrcWeb})
+
+elseif (DJGPP)
+    target_sources(minifb PRIVATE ${SrcDOS})
+endif()
+
+# Link main library
+#--------------------------------------
+if (MINIFB_USE_OPENGL_API)
+    find_package(OpenGL)
+    if (NOT OpenGL_FOUND)
+        if (WIN32)
+            message(FATAL_ERROR "OpenGL not found for Windows; install the required SDK components")
+        elseif (MINIFB_USE_X11_API)
+            message(FATAL_ERROR "OpenGL development files not found (install OpenGL headers/libs, e.g. mesa-common-dev/libgl1-mesa-dev)")
+        endif()
     endif()
 
-    list(APPEND SrcLib ${SrcMacOS})
+    target_link_libraries(minifb PRIVATE OpenGL::GL)
+endif()
 
-elseif (UNIX)
+if (IOS)
+    target_link_libraries(minifb PRIVATE
+        "-framework UIKit"
+        "-framework QuartzCore"
+        "-framework Metal"
+        "-framework MetalKit"
+    )
 
-    if (USE_WAYLAND_API)
-        list(APPEND SrcLib ${SrcWayland})
-    elseif (EMSCRIPTEN)
-        list(APPEND SrcLib ${SrcWeb})
-    else()
-        if (USE_OPENGL_API)
-            list(APPEND SrcLib ${SrcGL})
+elseif (MACOS)
+    # TODO: do we need to link cocoa if we're using metal, or metal if we're using cocoa?
+    target_link_libraries(minifb PRIVATE
+        "-framework Cocoa"
+        "-framework QuartzCore"
+        "-framework Metal"
+        "-framework MetalKit"
+    )
 
-            list(APPEND MINIFB_COMPILE_DEFINITIONS USE_OPENGL_API)
-        endif()
-        list(APPEND SrcLib ${SrcX11})
+elseif (MINIFB_USE_WAYLAND_API)
+    # wayland doesn't as of yet have a built-in cmake finder, so we use PkgConfig instead
+    find_package(PkgConfig)
+    if (NOT PKG_CONFIG_FOUND)
+        message(FATAL_ERROR "pkg-config is required to locate Wayland development files")
     endif()
+    pkg_check_modules(WAYLAND REQUIRED wayland-client wayland-cursor xkbcommon)
 
-elseif (DJGPP)
+    target_include_directories(minifb PRIVATE ${WAYLAND_INCLUDE_DIRS})
+    target_link_directories(minifb PRIVATE ${WAYLAND_LIBRARY_DIRS})
+    target_link_libraries(minifb PRIVATE ${WAYLAND_LIBRARIES})
+
+elseif(MINIFB_USE_X11_API)
+    find_package(X11)
+    if (NOT X11_FOUND)
+        message(FATAL_ERROR "X11 development files not found (install X11 headers/libs, e.g. libx11-dev)")
+    endif()
+    target_link_libraries(minifb PRIVATE X11::X11)
+
+    if (X11_Xrandr_FOUND)
+        target_link_libraries(minifb PRIVATE X11::Xrandr)
+        target_compile_definitions(minifb PRIVATE MINIFB_HAS_XRANDR)
+    endif()
 
-    list(APPEND SrcLib ${SrcDOS})
+elseif (EMSCRIPTEN)
+    # emscripten has no dedicated linking code
+
+elseif (WIN32)
+    target_link_libraries(minifb PRIVATE "winmm.lib")  # windows multimedia library, used in our case for precise timing
 
 endif()
 
-# Library
+# Examples and other targets
 #--------------------------------------
-add_library(minifb STATIC
-    ${SrcLib}
-)
-add_library(minifb::minifb ALIAS minifb)
 
-# Link
-#--------------------------------------
-if (APPLE)
-
-    if (IOS)
-        target_link_libraries(minifb PRIVATE
-            "-framework UIKit"
-            "-framework QuartzCore"
-            "-framework Metal"
-            "-framework MetalKit"
-        )
-    else()
-        target_link_libraries(minifb PRIVATE
-            "-framework Cocoa"
-            "-framework QuartzCore"
-            "-framework Metal"
-            "-framework MetalKit"
-        )
-    endif()
+# example use: minifb_add_example(NAME noise SOURCE examples/noise.c)
+function(minifb_add_example)
+    cmake_parse_arguments(PARSE_ARGV 0 arg "IOS_STORYBOARD IOS_NO_STORYBOARD" "NAME" "SOURCE")
 
-elseif (UNIX)
+    add_executable(${arg_NAME} ${arg_SOURCE})
+    target_link_libraries(${arg_NAME} PRIVATE minifb)
+    minifb_configure_target(${arg_NAME})
 
-    if (USE_WAYLAND_API)
-        find_package(PkgConfig)
-        if (NOT PKG_CONFIG_FOUND)
-            message(FATAL_ERROR "pkg-config is required to locate Wayland development files")
-        endif()
-        pkg_check_modules(WAYLAND REQUIRED wayland-client wayland-cursor xkbcommon)
+    set_property(TARGET ${arg_NAME} PROPERTY FOLDER "Examples")
 
-        target_include_directories(minifb PRIVATE ${WAYLAND_INCLUDE_DIRS})
-        target_link_directories(minifb PRIVATE ${WAYLAND_LIBRARY_DIRS})
-        target_link_libraries(minifb PRIVATE
-            ${WAYLAND_LIBRARIES}
-        )
-    elseif (EMSCRIPTEN)
-        list(APPEND MINIFB_LINK_OPTIONS_EXE
+    # conditional configuration
+    if (EMSCRIPTEN)
+        target_link_options(${arg_NAME} PRIVATE
+            "-sEXPORT_NAME=${arg_NAME}"
             "-sSTRICT=1"
             "-sENVIRONMENT=web"
             "-sMODULARIZE=1"
@@ -361,265 +452,104 @@ elseif (UNIX)
             "--no-entry"
             "-sSINGLE_FILE"
         )
-    else()
-        find_package(X11)
-        if (NOT X11_FOUND)
-            message(FATAL_ERROR "X11 development files not found (install X11 headers/libs, e.g. libx11-dev)")
-        endif()
 
-        target_link_libraries(minifb PRIVATE
-            X11::X11
-            #"-lxkbcommon"
-        )
-        if (X11_Xrandr_FOUND)
-            if (TARGET X11::Xrandr)
-                target_link_libraries(minifb PRIVATE X11::Xrandr)
-            else()
-                target_link_libraries(minifb PRIVATE ${X11_Xrandr_LIB})
-            endif()
-            target_compile_definitions(minifb PRIVATE MINIFB_HAS_XRANDR)
-        endif()
-        if (USE_OPENGL_API)
-            find_package(OpenGL)
-            if (NOT OpenGL_FOUND)
-                message(FATAL_ERROR "OpenGL development files not found (install OpenGL headers/libs, e.g. mesa-common-dev/libgl1-mesa-dev)")
-            endif()
-            target_link_libraries(minifb PRIVATE
-                OpenGL::GL
+        # copy the example's .html file into the build directory after the example is built
+        add_custom_command(TARGET ${arg_NAME} POST_BUILD
+            COMMAND ${CMAKE_COMMAND} -E copy
+                "examples/web/${arg_NAME}.html"
+                "${CMAKE_CURRENT_BINARY_DIR}"
             )
-        endif()
-    endif()
 
-elseif (WIN32)
+    elseif (IOS)
+        # TODO: why do examples need to include internal headers?
+        target_include_directories(${arg_NAME} PRIVATE src src/ios)
 
-    if (USE_OPENGL_API)
-        find_package(OpenGL)
-        if (NOT OpenGL_FOUND)
-            message(FATAL_ERROR "OpenGL not found for Windows; install the required SDK components")
+        if (${arg_IOS_STORYBOARD})
+            set_target_properties(${arg_NAME} PROPERTIES
+                MACOSX_BUNDLE_INFO_PLIST "examples/ios/Info.plist"
+                RESOURCE "examples/ios/LaunchScreen.storyboard"
+            )
+        elseif (${arg_IOS_NO_STORYBOARD})
+            set_target_properties(${arg_NAME} PROPERTIES
+                MACOSX_BUNDLE_INFO_PLIST "examples/ios/Info.no_storyboard.plist"
+            )
         endif()
-        target_link_libraries(minifb PRIVATE
-            "opengl32.lib"
-        )
     endif()
-
-    target_link_libraries(minifb PRIVATE
-        "winmm.lib"
-    )
-
-endif()
-
-# For all projects
-#--------------------------------------
-set_target_properties(minifb PROPERTIES
-    C_STANDARD ${MINIFB_C_STANDARD}
-    C_STANDARD_REQUIRED ON
-    C_EXTENSIONS ${MINIFB_C_EXTENSIONS}
-    CXX_STANDARD ${MINIFB_CXX_STANDARD}
-    CXX_STANDARD_REQUIRED ON
-    CXX_EXTENSIONS ${MINIFB_CXX_EXTENSIONS}
-)
-
-if (MINIFB_COMPILE_OPTIONS)
-    target_compile_options(minifb PRIVATE ${MINIFB_COMPILE_OPTIONS})
-endif()
-
-if (MINIFB_COMPILE_DEFINITIONS)
-    target_compile_definitions(minifb PRIVATE ${MINIFB_COMPILE_DEFINITIONS})
-endif()
-
-if (MINIFB_LINK_OPTIONS_LIB)
-    target_link_options(minifb PRIVATE ${MINIFB_LINK_OPTIONS_LIB})
-endif()
-
-target_include_directories(minifb PUBLIC
-    $<BUILD_INTERFACE:${MINIFB_GENERATED_INCLUDE_DIR}>
-    $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}/include>
-    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
-target_include_directories(minifb PRIVATE src)
-
-# Other targets
-#--------------------------------------
-set(MINIFB_EXAMPLE_TARGETS)
+endfunction()
 
 if (MINIFB_BUILD_VERSION_INFO)
-    add_executable(minifb_version_info examples/version_info.c)
-    list(APPEND MINIFB_EXAMPLE_TARGETS minifb_version_info)
+    minifb_add_example(NAME minifb_version_info SOURCE examples/version_info.c)
 endif()
 
-# Examples
-#--------------------------------------
 if (MINIFB_BUILD_EXAMPLES)
     if (NOT IOS)
-
-        add_executable(noise examples/noise.c)
-        add_executable(input_events examples/input_events.c)
-        add_executable(input_events_cpp examples/input_events_cpp.cpp)
-        add_executable(multiple_windows examples/multiple_windows.c)
-        add_executable(hidpi examples/hidpi.c)
-        add_executable(fullscreen examples/fullscreen.c)
-        add_executable(timer examples/timer.c)
-        add_executable(hide_cursor examples/hide_cursor.c)
-
-        list(APPEND MINIFB_EXAMPLE_TARGETS
-            noise
-            input_events
-            input_events_cpp
-            multiple_windows
-            hidpi
-            fullscreen
-            timer
-            hide_cursor
-        )
-
-        if (EMSCRIPTEN)
-
-            add_custom_target(web_assets
-                COMMAND ${CMAKE_COMMAND} -E copy_directory
-                    ${CMAKE_CURRENT_SOURCE_DIR}/examples/web
-                    ${CMAKE_CURRENT_BINARY_DIR}
-            )
-
-            add_dependencies(noise web_assets)
-            add_dependencies(input_events web_assets)
-            add_dependencies(hidpi web_assets)
-            add_dependencies(multiple_windows web_assets)
-            add_dependencies(timer web_assets)
-
-            target_link_options(noise PRIVATE "-sEXPORT_NAME=noise")
-            target_link_options(input_events PRIVATE "-sEXPORT_NAME=input_events")
-            target_link_options(hidpi PRIVATE "-sEXPORT_NAME=hidpi")
-            target_link_options(multiple_windows PRIVATE "-sEXPORT_NAME=multiple_windows")
-            target_link_options(timer PRIVATE "-sEXPORT_NAME=timer")
-
+        minifb_add_example(NAME noise                SOURCE examples/noise.c)
+        minifb_add_example(NAME input_events         SOURCE examples/input_events.c)
+        minifb_add_example(NAME hidpi                SOURCE examples/hidpi.c)
+        minifb_add_example(NAME multiple_windows     SOURCE examples/multiple_windows.c)
+        minifb_add_example(NAME timer                SOURCE examples/timer.c)
+        if (NOT EMSCRIPTEN)
+            minifb_add_example(NAME fullscreen       SOURCE examples/fullscreen.c)
+            minifb_add_example(NAME hide_cursor      SOURCE examples/hide_cursor.c)
+            minifb_add_example(NAME input_events_cpp SOURCE examples/input_events_cpp.cpp)
         endif()
-
         if (DJGPP)
-
-            add_executable(debug_dos
-                examples/dos/debug_dos.c
-            )
-            list(APPEND MINIFB_EXAMPLE_TARGETS debug_dos)
-
+            minifb_add_example(NAME debug_dos        SOURCE examples/dos/debug_dos.c)
         endif()
 
     else() # iOS
-
         set(IOS_NOISE_COMMON_SOURCES
             examples/ios/main.m
             examples/ios/AppDelegate.h
             examples/ios/AppDelegate.m
         )
 
-        add_executable(noise
-            ${IOS_NOISE_COMMON_SOURCES}
-        )
-        add_executable(noise_no_storyboard
-            ${IOS_NOISE_COMMON_SOURCES}
-        )
-        list(APPEND MINIFB_EXAMPLE_TARGETS noise noise_no_storyboard)
+        minifb_add_example(NAME noise               SOURCE ${IOS_NOISE_COMMON_SOURCES} IOS_STORYBOARD)
+        minifb_add_example(NAME noise_no_storyboard SOURCE ${IOS_NOISE_COMMON_SOURCES} IOS_NO_STORYBOARD)
 
+        # TODO: this is an IOS build, why do we need to set a minimum macos version?
         set(CMAKE_OSX_DEPLOYMENT_TARGET "11.0" CACHE STRING "Set CMake deployment target" ${FORCE_CACHE})
 
-        foreach(ios_noise_target IN ITEMS noise noise_no_storyboard)
-            target_include_directories(${ios_noise_target} PRIVATE src)
-            target_include_directories(${ios_noise_target} PRIVATE src/ios)
-        endforeach()
-
-        set_target_properties(noise PROPERTIES
-            MACOSX_BUNDLE_INFO_PLIST "${CMAKE_CURRENT_SOURCE_DIR}/examples/ios/Info.plist"
-            RESOURCE "examples/ios/LaunchScreen.storyboard"
-        )
-        set_target_properties(noise_no_storyboard PROPERTIES
-            MACOSX_BUNDLE_INFO_PLIST "${CMAKE_CURRENT_SOURCE_DIR}/examples/ios/Info.no_storyboard.plist"
-        )
-
     endif()
 
+    # example that will be ran on actions such as f5 in visual studio
+    set_property(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTY VS_STARTUP_PROJECT noise)
 endif()
 
-# Add options to targets
-#--------------------------------------
-foreach(minifb_test_target IN LISTS MINIFB_EXAMPLE_TARGETS)
-    target_link_libraries(${minifb_test_target} PRIVATE minifb)
-
-    set_target_properties(${minifb_test_target} PROPERTIES
-        C_STANDARD ${MINIFB_C_STANDARD}
-        C_STANDARD_REQUIRED ON
-        C_EXTENSIONS ${MINIFB_C_EXTENSIONS}
-        CXX_STANDARD ${MINIFB_CXX_STANDARD}
-        CXX_STANDARD_REQUIRED ON
-        CXX_EXTENSIONS ${MINIFB_CXX_EXTENSIONS}
-    )
-
-    if (MINIFB_COMPILE_OPTIONS)
-        target_compile_options(${minifb_test_target} PRIVATE ${MINIFB_COMPILE_OPTIONS})
-    endif()
-
-    if (MINIFB_COMPILE_DEFINITIONS)
-        target_compile_definitions(${minifb_test_target} PRIVATE ${MINIFB_COMPILE_DEFINITIONS})
-    endif()
-
-    if (MINIFB_LINK_OPTIONS_EXE)
-        target_link_options(${minifb_test_target} PRIVATE ${MINIFB_LINK_OPTIONS_EXE})
-    endif()
-endforeach()
-
-# Organize IDE Folders
+# Configure installation
 #--------------------------------------
-set_property(GLOBAL PROPERTY USE_FOLDERS ON)
-set_property(TARGET minifb PROPERTY FOLDER "Libs")
-
-if (MINIFB_BUILD_EXAMPLES AND NOT IOS)
-    set_property(TARGET noise PROPERTY FOLDER "Examples")
-    set_property(TARGET timer PROPERTY FOLDER "Examples")
-    set_property(TARGET fullscreen PROPERTY FOLDER "Examples")
-    set_property(TARGET input_events PROPERTY FOLDER "Examples")
-    set_property(TARGET input_events_cpp PROPERTY FOLDER "Examples")
-    set_property(TARGET multiple_windows PROPERTY FOLDER "Examples")
-    set_property(TARGET hidpi PROPERTY FOLDER "Examples")
-    set_property(TARGET hide_cursor PROPERTY FOLDER "Examples")
-endif()
-
-if (MINIFB_BUILD_VERSION_INFO)
-    set_property(TARGET minifb_version_info PROPERTY FOLDER "Examples")
-endif()
 
-#--------------------------------------
+# install the library, and all headers
 install(TARGETS minifb EXPORT minifb)
-install(DIRECTORY "${CMAKE_CURRENT_LIST_DIR}/include/"
+install(DIRECTORY "${CMAKE_CURRENT_LIST_DIR}/include/" "${MINIFB_GENERATED_INCLUDE_DIR}"
     DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
-    FILES_MATCHING
-    PATTERN "*.h"
-    PATTERN "*.hpp"
+    FILES_MATCHING PATTERN "*.h" PATTERN "*.hpp"
 )
-install(FILES "${MINIFB_GENERATED_INCLUDE_DIR}/minifb_version.h" DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
 
+# generate and install files required to find_package minifb
+include(CMakePackageConfigHelpers)
 set(MINIFB_CMAKE_CONFIG_INSTALL_DIR "${CMAKE_INSTALL_LIBDIR}/cmake/minifb")
-set(MINIFB_PACKAGE_FIND_OPENGL FALSE)
-set(MINIFB_PACKAGE_FIND_X11 FALSE)
-
-if (WIN32 AND USE_OPENGL_API)
-    set(MINIFB_PACKAGE_FIND_OPENGL TRUE)
-elseif (UNIX AND NOT APPLE AND NOT EMSCRIPTEN)
-    if (NOT USE_WAYLAND_API)
-        set(MINIFB_PACKAGE_FIND_X11 TRUE)
-        if (USE_OPENGL_API)
-            set(MINIFB_PACKAGE_FIND_OPENGL TRUE)
-        endif()
-    endif()
-endif()
 
-minifb_configure_package_config_file(
-    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/minifb-config.cmake.in"
-    "${CMAKE_CURRENT_BINARY_DIR}/minifb-config.cmake"
-    "${MINIFB_CMAKE_CONFIG_INSTALL_DIR}"
+# generate the cmake code that will create the minifb:: target when found, to minifb-targets.cmake
+install(EXPORT minifb
+    FILE minifb-targets.cmake
+    DESTINATION "${MINIFB_CMAKE_CONFIG_INSTALL_DIR}"
+    NAMESPACE minifb::
 )
 
-minifb_write_package_version_file(
+# generate file from our template that will be found directly by find_package (<name>-config.cmake is one of file filenames it searches for)
+# the file will find dependancies and `include`s the previously created minifb-targets.cmake
+configure_package_config_file(
+    "cmake/minifb-config.cmake.in"
+    "${CMAKE_CURRENT_BINARY_DIR}/minifb-config.cmake"
+    INSTALL_DESTINATION "${MINIFB_CMAKE_CONFIG_INSTALL_DIR}"
+)
+# in case find_package is called with the VERSION flag, generate the file that checks the version
+write_basic_package_version_file(
     "${CMAKE_CURRENT_BINARY_DIR}/minifb-config-version.cmake"
+    COMPATIBILITY SameMajorVersion
 )
-
-install(EXPORT minifb FILE minifb-targets.cmake DESTINATION "${MINIFB_CMAKE_CONFIG_INSTALL_DIR}" NAMESPACE minifb::)
+# install the previous two files
 install(FILES
     "${CMAKE_CURRENT_BINARY_DIR}/minifb-config.cmake"
     "${CMAKE_CURRENT_BINARY_DIR}/minifb-config-version.cmake"
@@ -627,7 +557,3 @@ install(FILES
 )
 
 message(STATUS "Done " ${PROJECT_NAME})
-
-if (MSVC AND MINIFB_BUILD_EXAMPLES)
-    set_property(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTY VS_STARTUP_PROJECT noise)
-endif()
diff --git a/cmake/minifb-config.cmake.in b/cmake/minifb-config.cmake.in
index 79aff2b8..e853fcd6 100644
--- a/cmake/minifb-config.cmake.in
+++ b/cmake/minifb-config.cmake.in
@@ -1,15 +1,18 @@
 @PACKAGE_INIT@
 
-include(CMakeFindDependencyMacro)
+# filled and installed by cmake
+# once filled, this file will be found by find_package
 
-if(@MINIFB_PACKAGE_FIND_OPENGL@)
+# depending on the configuration minifb was built with, make sure it has the required dependencies
+include(CMakeFindDependencyMacro)
+if(@MINIFB_USE_OPENGL_API@)
     find_dependency(OpenGL)
 endif()
-
-if(@MINIFB_PACKAGE_FIND_X11@)
+if(@MINIFB_USE_X11_API@)
     find_dependency(X11)
 endif()
 
+# run the auto-generated file to create the exported minifb:: target
 include("${CMAKE_CURRENT_LIST_DIR}/minifb-targets.cmake")
 
 check_required_components(minifb)
diff --git a/cmake/minifb_cmake_helpers.cmake b/cmake/minifb_cmake_helpers.cmake
index fa261a83..fbfc3302 100644
--- a/cmake/minifb_cmake_helpers.cmake
+++ b/cmake/minifb_cmake_helpers.cmake
@@ -7,4 +7,52 @@ function(minifb_apply_deprecated_option legacy_var new_var new_help)
         set(${new_var} "${_legacy_value}" CACHE BOOL "${new_help}" FORCE)
     endif()
     set(${legacy_var} "${${new_var}}" PARENT_SCOPE)
+	set(MINIFB_HAVE_USED_LEGACY_OPTION TRUE PARENT_SCOPE)
+endfunction()
+
+function(minifb_compute_git_metadata out_commits_since_tag out_commit_count out_git_sha out_git_dirty)
+    set(_commits_since_tag 0)
+    set(_commit_count 0)
+    set(_git_sha "unknown")
+    set(_git_dirty 0)
+
+    if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/.git")
+        find_package(Git QUIET)
+        if (GIT_FOUND)
+            execute_process(
+                COMMAND "${GIT_EXECUTABLE}" rev-list --count HEAD
+                WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+                RESULT_VARIABLE _git_count_result
+                OUTPUT_VARIABLE _git_count_output
+                ERROR_QUIET
+                OUTPUT_STRIP_TRAILING_WHITESPACE
+            )
+            if (_git_count_result EQUAL 0 AND _git_count_output MATCHES "^[0-9]+$")
+                set(_commit_count "${_git_count_output}")
+            endif()
+
+            execute_process(
+                COMMAND "${GIT_EXECUTABLE}" describe --tags --long --dirty
+                WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+                RESULT_VARIABLE _git_describe_result
+                OUTPUT_VARIABLE _git_describe_output
+                ERROR_QUIET
+                OUTPUT_STRIP_TRAILING_WHITESPACE
+            )
+            if (_git_describe_result EQUAL 0)
+                if (_git_describe_output MATCHES ".*-([0-9]+)-g([0-9a-fA-F]+)(-dirty)?$")
+                    set(_commits_since_tag "${CMAKE_MATCH_1}")
+                    set(_git_sha "${CMAKE_MATCH_2}")
+                    if (CMAKE_MATCH_3 STREQUAL "-dirty")
+                        set(_git_dirty 1)
+                    endif()
+                endif()
+            endif()
+        endif()
+    endif()
+
+    set(${out_commits_since_tag} "${_commits_since_tag}" PARENT_SCOPE)
+    set(${out_commit_count} "${_commit_count}" PARENT_SCOPE)
+    set(${out_git_sha} "${_git_sha}" PARENT_SCOPE)
+    set(${out_git_dirty} "${_git_dirty}" PARENT_SCOPE)
 endfunction()
diff --git a/cmake/versioning.cmake b/cmake/versioning.cmake
deleted file mode 100644
index 4025172a..00000000
--- a/cmake/versioning.cmake
+++ /dev/null
@@ -1,69 +0,0 @@
-function(minifb_compute_git_metadata out_commits_since_tag out_commit_count out_git_sha out_git_dirty)
-    set(_commits_since_tag 0)
-    set(_commit_count 0)
-    set(_git_sha "unknown")
-    set(_git_dirty 0)
-
-    if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/.git")
-        find_package(Git QUIET)
-        if (GIT_FOUND)
-            execute_process(
-                COMMAND "${GIT_EXECUTABLE}" rev-list --count HEAD
-                WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
-                RESULT_VARIABLE _git_count_result
-                OUTPUT_VARIABLE _git_count_output
-                ERROR_QUIET
-                OUTPUT_STRIP_TRAILING_WHITESPACE
-            )
-            if (_git_count_result EQUAL 0 AND _git_count_output MATCHES "^[0-9]+$")
-                set(_commit_count "${_git_count_output}")
-            endif()
-
-            execute_process(
-                COMMAND "${GIT_EXECUTABLE}" describe --tags --long --dirty
-                WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
-                RESULT_VARIABLE _git_describe_result
-                OUTPUT_VARIABLE _git_describe_output
-                ERROR_QUIET
-                OUTPUT_STRIP_TRAILING_WHITESPACE
-            )
-            if (_git_describe_result EQUAL 0)
-                if (_git_describe_output MATCHES ".*-([0-9]+)-g([0-9a-fA-F]+)(-dirty)?$")
-                    set(_commits_since_tag "${CMAKE_MATCH_1}")
-                    set(_git_sha "${CMAKE_MATCH_2}")
-                    if (CMAKE_MATCH_3 STREQUAL "-dirty")
-                        set(_git_dirty 1)
-                    endif()
-                endif()
-            endif()
-        endif()
-    endif()
-
-    set(${out_commits_since_tag} "${_commits_since_tag}" PARENT_SCOPE)
-    set(${out_commit_count} "${_commit_count}" PARENT_SCOPE)
-    set(${out_git_sha} "${_git_sha}" PARENT_SCOPE)
-    set(${out_git_dirty} "${_git_dirty}" PARENT_SCOPE)
-endfunction()
-
-function(minifb_configure_version_header template_path output_dir output_path)
-    file(MAKE_DIRECTORY "${output_dir}")
-    configure_file("${template_path}" "${output_path}" @ONLY)
-endfunction()
-
-function(minifb_write_package_version_file output_path)
-    include(CMakePackageConfigHelpers)
-    write_basic_package_version_file(
-        "${output_path}"
-        VERSION "${PROJECT_VERSION}"
-        COMPATIBILITY SameMajorVersion
-    )
-endfunction()
-
-function(minifb_configure_package_config_file input_path output_path install_destination)
-    include(CMakePackageConfigHelpers)
-    configure_package_config_file(
-        "${input_path}"
-        "${output_path}"
-        INSTALL_DESTINATION "${install_destination}"
-    )
-endfunction()
diff --git a/include/minifb_version.h.in b/include/minifb_version.h.in
index 4d4e2185..8380d75f 100644
--- a/include/minifb_version.h.in
+++ b/include/minifb_version.h.in
@@ -1,5 +1,7 @@
 #pragma once
 
+// filled by CMake
+
 #include <stdint.h>
 
 #define MINIFB_VERSION_MAJOR @PROJECT_VERSION_MAJOR@