Make C++20 module support disabled by default for Vulkan tutorial

- Update tutorial documentation to reflect optional module usage.
- Adjust CMake option `ENABLE_CPP20_MODULE` default to `OFF`.
- Incorporate fallback to traditional header-based includes when modules are disabled.
- Clarify enablement steps and compatibility details in example code and instructions.

Author: gpx1000

attachments/CMakeLists.txt

@@ -5,7 +5,7 @@ project (VulkanTutorial)
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/CMake")
 
 # Add option to enable/disable C++ 20 module
-option(ENABLE_CPP20_MODULE "Enable C++ 20 module support for Vulkan" ON)
+option(ENABLE_CPP20_MODULE "Enable C++ 20 module support for Vulkan" OFF)
 
 # Enable C++ module dependency scanning only if C++ 20 module is enabled
 if(ENABLE_CPP20_MODULE)
@@ -121,7 +121,7 @@ function (add_chapter CHAPTER_NAME)
   set_target_properties (${CHAPTER_NAME} PROPERTIES CXX_STANDARD 20)
   target_link_libraries (${CHAPTER_NAME} Vulkan::cppm glfw)
   target_include_directories (${CHAPTER_NAME} PRIVATE ${STB_INCLUDEDIR})
-  
+
   # Add compile definition if C++ 20 module is enabled
   if(ENABLE_CPP20_MODULE)
     target_compile_definitions(${CHAPTER_NAME} PRIVATE USE_CPP20_MODULES=1)

en/00_Introduction.adoc

@@ -99,11 +99,12 @@ We will use C{pp} features like classes and RAII to organize logic and
 To make it easier to learn to work with Vulkan, we'll be using the newer
 https://github.com/KhronosGroup/Vulkan-Hpp[Vulkan-Hpp] bindings that
   abstract some of the dirty work and help prevent certain classes of errors.
-We'll also use Vulkan RAII and the Vulkan C{pp}20 module. With this
-combination, we show how to use Vulkan in a method that will translate
-directly into large projects where C{pp} libraries have traditionally caused
-large build times while also showing one method of making Vulkan a joy to
-work with.
+We'll also use Vulkan RAII and, optionally, the Vulkan C{pp}20 module. The
+attachments template has modules disabled by default for maximum compatibility,
+but we recommend enabling them if your toolchain supports it. With this
+combination, we show how to use Vulkan in a way that translates directly into
+large projects where C{pp} libraries have traditionally caused long build times,
+while also showing one method of making Vulkan a joy to work with.
 
 == License
 

en/02_Development_environment.adoc

@@ -115,54 +115,62 @@ for an example of a working project.
 
 Vulkan has support for C{pp} modules which became available with c{pp}20. A
 large advantage of C{pp} modules is they give all the benefits of C{pp} without
-the overhead long compile times. To do this, the .cppm file must be compiled
-for your target device. This tutorial serves as an example of taking
-advantage of C{pp} modules. The CMakeLists.txt in our tutorial has all the
-instructions needed for building the module automatically:
+the overhead of long compile times. To do this, the .cppm file must be compiled
+for your target device. This tutorial demonstrates how to take advantage of C{pp}
+modules. However, to maximize compatibility across compilers and IDEs, the
+attachments template has C{pp}20 module support disabled by default, but it is
+recommended to enable it if your toolchain supports it.
+
+To enable the Vulkan C{pp}20 module in the attachments template, configure CMake with:
+
+[,bash]
+----
+cmake -DENABLE_CPP20_MODULE=ON ..
+----
+
+When enabled, the CMakeLists.txt contains all the instructions needed for building the
+module automatically. The relevant snippet looks like this:
 
 [,cmake]
 ----
 find_package (Vulkan REQUIRED)
 
-# set up Vulkan C++ module
+# set up Vulkan C++ module (enabled when ENABLE_CPP20_MODULE=ON)
 add_library(VulkanCppModule)
 add_library(Vulkan::cppm ALIAS VulkanCppModule)
 
 target_compile_definitions(VulkanCppModule PUBLIC
         VULKAN_HPP_DISPATCH_LOADER_DYNAMIC=1
         VULKAN_HPP_NO_STRUCT_CONSTRUCTORS=1
 )
-target_include_directories(VulkanCppModule
-        PRIVATE
-        "${Vulkan_INCLUDE_DIR}"
-)
-target_link_libraries(VulkanCppModule
-        PUBLIC
-        Vulkan::Vulkan
-)
+
+target_include_directories(VulkanCppModule PRIVATE "${Vulkan_INCLUDE_DIR}")
+
+target_link_libraries(VulkanCppModule PUBLIC Vulkan::Vulkan)
 
 set_target_properties(VulkanCppModule PROPERTIES CXX_STANDARD 20)
 
 target_sources(VulkanCppModule
         PUBLIC
         FILE_SET cxx_modules TYPE CXX_MODULES
-        BASE_DIRS
-        "${Vulkan_INCLUDE_DIR}"
-        FILES
-        "${Vulkan_INCLUDE_DIR}/vulkan/vulkan.cppm"
+        BASE_DIRS "${Vulkan_INCLUDE_DIR}"
+        FILES "${Vulkan_INCLUDE_DIR}/vulkan/vulkan.cppm"
 )
 ----
 
 The VulkanCppModule target only needs to be defined once, then add it to the
-dependency of your consuming project, and it will be built automatically, and
-you won't need to also add Vulkan::Vulkan to your project.
+dependencies of your consuming project, and it will be built automatically. You
+won't need to also add Vulkan::Vulkan to your project.
 
 [,cmake]
 ----
 target_link_libraries (${PROJECT_NAME} Vulkan::cppm)
 ----
 
-That is all that is required to add Vulkan to any project.
+If you choose to keep modules disabled (the default), you can continue to use the
+traditional header-based includes (e.g., `#include <vulkan/vulkan_raii.hpp>`). The
+sample code in the attachments is written to compile either way and will import the
+module only when `ENABLE_CPP20_MODULE=ON` (which defines `USE_CPP20_MODULES`).
 
 === Window Management
 
@@ -491,4 +499,4 @@ You are now all set for xref:03_Drawing_a_triangle/00_Setup/00_Base_code.adoc[th
 
 == Android
 
-Vulkan is a first-class API on Android and widely supported. But using it differs in several key areas from window management to build systems. So while the basic chapters focus on desktop platforms, the tutorial also has a xref:14_Android.adoc[dedicated chapter] that walks you through setting up your development environment and getting the tutorial code up-and-running on Android.
+Vulkan is a first-class API on Android and widely supported. But using it differs in several key areas from window management to build systems. So while the basic chapters focus on desktop platforms, the tutorial also has a xref:14_Android.adoc[dedicated chapter] that walks you through setting up your development environment and getting the tutorial code up-and-running on Android.

en/03_Drawing_a_triangle/00_Setup/00_Base_code.adoc

@@ -10,7 +10,11 @@ from scratch with the following code:
 
 [,c++]
 ----
+#if defined(__INTELLISENSE__) || !defined(USE_CPP20_MODULES)
+#include <vulkan/vulkan_raii.hpp>
+#else
 import vulkan_hpp;
+#endif
 #include <GLFW/glfw3.h>
 
 #include <iostream>
@@ -53,10 +57,12 @@ int main() {
 }
 ----
 
-We first include the Vulkan module from the LunarG SDK, which provides the
-functions, structures and enumerations. The `stdexcept` and `iostream` headers
-are included for reporting and propagating errors. The `cstdlib`
-header provides the `EXIT_SUCCESS` and `EXIT_FAILURE` macros.
+We first include the Vulkan-Hpp RAII header by default, which provides the
+functions, structures and enumerations. If you enable C{pp}20 modules
+(`-DENABLE_CPP20_MODULE=ON`), the code will `import vulkan_hpp;` instead via the
+`USE_CPP20_MODULES` define set by CMake. The `stdexcept` and `iostream` headers
+are included for reporting and propagating errors. The `cstdlib` header
+provides the `EXIT_SUCCESS` and `EXIT_FAILURE` macros.
 
 The program itself is wrapped into a class where we'll store the Vulkan objects
 as private class members and add functions to initiate each of them, which will

en/14_Android.adoc

@@ -312,7 +312,7 @@ include_directories(${ANDROID_NDK}/sources/android/game-activity/include)
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
-# Add the Vulkan C++ module
+# (Optional) Add the Vulkan C++ module when ENABLE_CPP20_MODULE=ON
 add_library(VulkanCppModule SHARED)
 target_compile_definitions(VulkanCppModule
     PUBLIC VULKAN_HPP_DISPATCH_LOADER_DYNAMIC=1 VULKAN_HPP_NO_STRUCT_CONSTRUCTORS=1
@@ -388,7 +388,7 @@ Key points:
 
 * We find the Vulkan package and include the game-activity library instead of native_app_glue.
 * We set up shader compilation tools and define a function to compile shaders.
-* We set the C{pp} standard to C{pp}20 and create a Vulkan C{pp}  module.
+* We set the C{pp} standard to C{pp}20 and optionally create a Vulkan C{pp} module (recommended) when modules are enabled.
 * We set up shader compilation for the 34_android chapter, copying shader source files from the main project.
 * We add the main native library, which uses the 34_android.cpp file from the main project and a bridge file to connect with GameActivity.
 * We link against the necessary libraries, including game-activity.
@@ -840,4 +840,4 @@ The complete Android example can be found in the attachments/android directory.
 
 Remember that Vulkan HPP is not included by default in the Android NDK, so you'll need to download it separately from the https://github.com/KhronosGroup/Vulkan-Hpp[Vulkan-Hpp GitHub repository] or use the version included in the Vulkan SDK.
 
-link:/attachments/34_android.cpp[C{pp} code]
+link:/attachments/34_android.cpp[C{pp} code]