Make C++ Module use optional

[gpx1000]

Feedback on the tutorial has indicated that the current C++ ecosystem is not quite ready for modules. Investigate best way to make them optional and describe in the tutorial in the section on why they make sense some new language about setting expectations for the current limitations with several significant compile ecosystems.

[laplaceliu]

Yes, you're correct.
As shown here, g++ only partially supports modules as of version 11.
For users like me who are still using Ubuntu 20.04, apt-get can only install up to g++-10.
Currently, I'm using a global replacement, replacing the following code:

#ifdef __INTELLISENSE__
#include <vulkan/vulkan_raii.hpp>
#else
import vulkan_hpp;
#endif

with:

#if __GNUC__ > 11 && __cplusplus
import vulkan_hpp;
#else
#include <vulkan/vulkan_raii.hpp>
#endif

and rewriting CMakeLists.txt.

[gpx1000]

You're going to want to test that against C++ 20 instead of just better than 11. 20 is where modules were introduced to the C++ standard.

Also, I find that clang has better support than gcc.

The problem is that we need to effectively communicate the benefits and trade offs. Directly including the Vulkan_hpp headers has the potential to greatly increase the compile time of larger projects.

[TomServeaux]

You're going to want to test that against C++ 20 instead of just better than 11. 20 is where modules were introduced to the C++ standard.

I got the impression that they weren't still using Ubuntu 20.04 by choice. At my old job you were stuck with whatever Ubuntu LTS they installed until they were good and ready to upgrade you. But @laplaceliu can't you manually install a newer GCC straight from the source, bypassing the Ubuntu repos, or do you not even have permissions for that?

The problem is that we need to effectively communicate the benefits and trade offs. Directly including the Vulkan_hpp headers has the potential to greatly increase the compile time of larger projects.

How greatly? IMO being able to get code to JUST FREAKING COMPILE ALREADY (ahem, sorry) is a better boon to going through the tutorial than optimizing compile times. Unless we're talking like minutes per compile. For small test programs like we make during the tutorial is it a big deal or should they/we only really worry when working on "for real" projects?

That said, I'm able to compile with the module on GCC 15.1.1. It took days of trial and error and reading CMake documentation and probably also adding certain directories to my path environment variables (I honestly can't remember), but if anybody wants it here is the CMakeLists.txt that makes it work:

# *****************************************************************************
#
#             CMakeLists.txt adapted from official Vulkan tutorial
#                               by Jacob Oost
#
#               Assumes LunarG Vulkan SDK and Vulkan libraries
#               all fully installed.
#
# *****************************************************************************

cmake_minimum_required(VERSION 4.0)

# *****************************************************************************
#
#                         set global variables
#
# *****************************************************************************
set(PROJECT_NAME triangle)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_OBJCXX_STANDARD_REQUIRED ON)
# Enable C++ module dependency scanning
set(CMAKE_CXX_SCAN_FOR_MODULES ON)
set(CMAKE_PREFIX_PATH /usr/include) # find_package needed help
set(MAIN_SOURCE main.cpp)
set(SHADER_SOURCE myShader.slang)
set(SOURCE_DIR ${CMAKE_SOURCE_DIR}/src)
set(INCLUDE_DIR ${CMAKE_SOURCE_DIR}/include)
set(BIN_DIR ${CMAKE_SOURCE_DIR}/bin)
set(LIB_DIR ${CMAKE_SOURCE_DIR}/lib)
set(SOURCE_FILES ${SOURCE_DIR}/${MAIN_SOURCE})
set(SHADER_SOURCE_FILES ${SOURCE_DIR}/${SHADER_SOURCE})
set(SLANG_SHADER_TARGET ${PROJECT_NAME}_slang_shader)
#set(MODEL_SOURCE ${ASSETS_DIR}/viking_room.obj)
#set(TEXTURE_SOURCE ${ASSETS_DIR}/viking_room.png)
#set(MY_LIBS glm::glm tinygltf::tinygltf KTX::ktx)
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${BIN_DIR})

project(${PROJECT_NAME})
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/CMake") # I don't know what this is for


# *****************************************************************************
#
#                          find packages
#
# *****************************************************************************

find_package(glfw3 REQUIRED)
find_package(glm REQUIRED)
find_package(Vulkan REQUIRED)
#find_package(tinyobjloader REQUIRED)
#find_package(tinygltf REQUIRED)
#find_package(KTX REQUIRED)

# *****************************************************************************
#
#                       set up Vulkan C++ module
#
# *****************************************************************************

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
)

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"
)


# Add the vulkan.cppm file directly as a source file
target_sources(VulkanCppModule
        PRIVATE
        "${Vulkan_INCLUDE_DIR}/vulkan/vulkan.cppm"
)

# *****************************************************************************
#
#                          add STB libraries
#
# *****************************************************************************

#find_package(stb REQUIRED)
#set(STB_INCLUDEDIR ${stb_INCLUDE_DIRS})

# *****************************************************************************
#
#                             add Slang
#
# *****************************************************************************

find_program(SLANGC_EXECUTABLE slangc HINTS $ENV{VULKAN_SDK}/bin REQUIRED)

# *****************************************************************************
#
#                   wrap shader-adding stuff in function
#
# *****************************************************************************

function(add_slang_shader_target TARGET)
  cmake_parse_arguments("SHADER" "" "SOURCES" "POINTLESS" ${ARGN})
  set(SHADERS_DIR ${CMAKE_CURRENT_BINARY_DIR}/shader)
  set(ENTRY_POINTS -entry vertMain -entry fragMain)
  add_custom_command(
    OUTPUT ${SHADERS_DIR}
    COMMAND ${CMAKE_COMMAND} -E make_directory ${SHADERS_DIR}
  )
  add_custom_command(
    OUTPUT ${SHADERS_DIR}/slang.spv
    COMMAND ${SLANGC_EXECUTABLE} ${SHADER_SOURCES} -target spirv -profile spirv_1_4 -emit-spirv-directly -fvk-use-entrypoint-name ${ENTRY_POINTS} -o slang.spv
    WORKING_DIRECTORY ${SHADERS_DIR}
    DEPENDS ${SHADERS_DIR} ${SHADER_SOURCES}
    COMMENT "Compiling Slang Shaders"
    VERBATIM
  )
  add_custom_target(${TARGET} DEPENDS ${SHADERS_DIR}/slang.spv)
endfunction()

# *****************************************************************************
#
#                   Now create the main program
#
# *****************************************************************************

# create the main executable
add_executable (${PROJECT_NAME} ${SOURCE_FILES})

# set special properties like where the executable goes
set_target_properties (${PROJECT_NAME} PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${PROJECT_NAME})

# include the headers
target_include_directories(${PROJECT_NAME} PRIVATE ${INCLUDE_DIR})

# include the library objects
target_link_libraries (${PROJECT_NAME} PRIVATE glfw)
target_link_libraries (${PROJECT_NAME} PRIVATE Vulkan::cppm)

# add shaders
add_slang_shader_target(${SLANG_SHADER_TARGET} SOURCES ${SHADER_SOURCE_FILES} POINTLESS "FOO")
add_dependencies(${PROJECT_NAME} ${SLANG_SHADER_TARGET})

# keep this stuff?
if (DEFINED MY_MODELS)
  file (COPY assets/${MY_MODELS} DESTINATION ${CMAKE_BINARY_DIR}/${PROJECT_NAME}/models)
endif ()
if (DEFINED MY_TEXTURES)
  file (COPY assets/${MY_TEXTURES} DESTINATION ${CMAKE_BINARY_DIR}/${PROJECT_NAME}/textures)
endif ()

[JackPilley]

I'd like to second this issue. I haven't been able to get the tutorial to work using Premake, which is my preferred build system. Its module support just isn't there yet. I've gotten around using the modules by setting the #define VULKAN_HPP_NO_CONSTRUCTORS preprocessor directive and including vulkan_raii.hpp. The only issue I've had is with this line
vk::ClearValue clearColor = vk::ClearColorValue(0.0f, 0.0f, 0.0f, 1.0f);
which I just replace with
vk::ClearValue clearColor = { .color = vk::ClearColorValue{ std::array<float, 4> {0.0f, 0.0f, 0.0f, 1.0f} } };

[SaschaWillems]

I don't know much about Premake, but would a define/option (similar to CMake's options) work here? The INTELLISENSE define was a last minute fix to Visual Studio having issues with the module.

Or maybe we should switch things around, use the RAII header as default and make the module optional until tooling support for C++ modules improves?

[JackPilley]

I'm not really an expert either, but I think a define or option would work. I include the vulkan headers like this:

#define VULKAN_HPP_NO_CONSTRUCTORS
#include <vulkan/vulkan_raii.hpp>
#include <vulkan/vk_platform.h>

So something like this would probably work:

#ifdef NO_VULKAN_MODULE
#define VULKAN_HPP_NO_CONSTRUCTORS
#include <vulkan/vulkan_raii.hpp>
#else
import vulkan_hpp;
#endif

#include <vulkan/vk_platform.h>

Like I said, the only issue I've encountered is that this line gives a compiler error:

vk::ClearValue clearColor = vk::ClearColorValue(0.0f, 0.0f, 0.0f, 1.0f);

But I'm not sure if that's something to do with not using the module, or the version of the SDK I'm using, or something else.

[SaschaWillems]

Like I said, the only issue I've encountered is that this line gives a compiler error:

Interesting. This compiles fine for me on MSVC 2022. Both with using modules and with using the RAII headers.

[gpx1000]

Fwiw I ran into issues with that line in an older version of the Vulkan sdk. I'm on my cell phone on vacation so I can't really check if that's the issue, but it sounds familiar.

[JackPilley]

I'm using version 1.4.321.1, which is the most recent release as far as I can tell.
Looking at the header where ClearValue is defined, it looks like setting VULKAN_HPP_NO_CONSTRUCTORS shouldn't allow assigning a ClearColorValue to a ClearValue. The whole thing isn't very long so I'm just going to copy it here

  union ClearValue
  {
    using NativeType = VkClearValue;
#if !defined( VULKAN_HPP_NO_CONSTRUCTORS ) && !defined( VULKAN_HPP_NO_UNION_CONSTRUCTORS )

    VULKAN_HPP_CONSTEXPR_14 ClearValue( VULKAN_HPP_NAMESPACE::ClearColorValue color_ = {} ) : color( color_ ) {}

    VULKAN_HPP_CONSTEXPR_14 ClearValue( VULKAN_HPP_NAMESPACE::ClearDepthStencilValue depthStencil_ ) : depthStencil( depthStencil_ ) {}
#endif /*VULKAN_HPP_NO_CONSTRUCTORS*/

#if !defined( VULKAN_HPP_NO_SETTERS ) && !defined( VULKAN_HPP_NO_UNION_SETTERS )
    VULKAN_HPP_CONSTEXPR_14 ClearValue & setColor( VULKAN_HPP_NAMESPACE::ClearColorValue const & color_ ) VULKAN_HPP_NOEXCEPT
    {
      color = color_;
      return *this;
    }

    VULKAN_HPP_CONSTEXPR_14 ClearValue & setDepthStencil( VULKAN_HPP_NAMESPACE::ClearDepthStencilValue const & depthStencil_ ) VULKAN_HPP_NOEXCEPT
    {
      depthStencil = depthStencil_;
      return *this;
    }
#endif /*VULKAN_HPP_NO_SETTERS*/

    operator VkClearValue const &() const
    {
      return *reinterpret_cast<const VkClearValue *>( this );
    }

    operator VkClearValue &()
    {
      return *reinterpret_cast<VkClearValue *>( this );
    }

#ifdef VULKAN_HPP_HAS_UNRESTRICTED_UNIONS
    VULKAN_HPP_NAMESPACE::ClearColorValue        color;
    VULKAN_HPP_NAMESPACE::ClearDepthStencilValue depthStencil;
#else
    VkClearColorValue        color;
    VkClearDepthStencilValue depthStencil;
#endif /*VULKAN_HPP_HAS_UNRESTRICTED_UNIONS*/
  };