Should the C++20 module be recommended to beginners?

[M2-TE]

While the Vulkan-Hpp C++20 module can make Vulkan quite nice for beginners in the (hopefully near) future, it is currently still in a very experimental state and introduces breaking changes every now and then. This might frustrate newcomers who follow the tutorial.

Sections such as the one under 02_Development_environment are already outdated:

Vulkan-Tutorial/en/02_Development_environment.adoc

Lines 127 to 184 in 0aad08a

	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 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 (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)
	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"
	)
	----
	The VulkanCppModule target only needs to be defined once, then add it to the
	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)
	----
	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`).

Once the module changes in KhronosGroup/Vulkan-Hpp#2443 are complete, I can update the tutorial sections regarding modules here, similar to the updates to our own README and tutorial we are working on in KhronosGroup/Vulkan-Hpp#2358.

Until then, it would probably be a good idea to very explictly mark that section as experimental, or at least write the matching SDK version for the shown sample.

[LordKobra]

I see we both had the same idea. My issue is a duplicate #300
(I will keep it up for now though, because it's a different viewpoint: vulkan beginner)

[SaschaWillems]

See #301. We won't be removing them, as they'll soon become non-experimental.

[M2-TE]

I reckon you mean #301 ;)

The warning notice in that PR is good, I didn't want to make it sound like I wanted it removed.

We aren't really planning on making them non-experimental that soon though, since CMake support itself is still experimental. Once import std lands in one of their stable releases, we will make a stable Vulkan-Hpp modules release as well!

[gpx1000]

I was hopeful to not have to make a more permanent change along the lines of completely removing even knowledge of Modules existing as they come with massive benefits to compile time.

However, if it's really going to be a long term horizon as to where it's not really expected to be a next few year thing, or somewhere in the reasonable time frame thing, then I don't think we're doing tutorial users any benefit by even mentioning they exist. We can chalk it up to my mistake for putting them in to begin with and remove everything we can find about them from the tutorial.
It is starting to seem like it'd be easier to just rework the tutorial to include them in a few years when they are available rather than give the impression they exist right now and have an easy to change note to discourage their use until they're available. I guess it's something for us to discuss at the next docs call.

[M2-TE]

I don't think their complete removal from the tutorial is the right call, I was merely advocating for proper notices about their experimental nature.

The module itself is in a good state now; the problem is just the tooling. I don't want newcomers to be made to believe that it is currently the superior choice over headers.

[sharadhr]

next docs call

Could we (specifically, @M2-TE and myself) get invites to this call, as stakeholders and implementers? As @M2-TE mentioned, the module and corresponding documentation are in much better shape pending a couple of merges—we hope to land big fixes and documentation changes over the next couple of weeks. Going forward it is also likely we will reduce the churn in the module, as it is in a state which we are mostly satisfied with. We'd like to synchronise with you guys directly.

Strictly speaking, this is really a tooling issue, and even more specifically, a tooling issue with CMake. In private discussions I have mentioned that other build systems are a bit more swashbuckling and have enabled features that CMake hasn't—most notably, import std, which module vulkan now explicitly depends on.

[gpx1000]

I would love for you guys to be a part of this. The Samples and Docs meeting is in the causeway calendar. It happens every other Monday. @marty-johnson59 can we ensure this is on our agenda?

Also, if you guys need help with documentation or any support in Samples or Docs, please let us know.

[marty-johnson59]

Sure. Just subscribe to "Vulkan Developer Relations" to see the invites. Look for the "docs.vulkan.org project sync" meeting on alternate Mondays @9am PT. LMK when ready and I can add you to the agenda..

[sharadhr]

I'm not sure if we have access to these calendars; are they public?

[marty-johnson59]

They're available for Khronos members only. If that includes you, you should be able to go to Causeway where you can manage your subscriptions. Unfortunately, there's no way for general public to join our meetings..

[sharadhr]

Hmm, I thought that might be the case. Sadly no, we're not Khronos members, just enthusiastic open-source contributors.

[gpx1000]

We definitely welcome feedback and participation from the community. We welcome working with you guys and the best way to help is through the github PRs/issues/comments and Slack/discord channels for directly corresponding as most of us are there. Or, if you ever join Khronos, we'd welcome the help as well.

[SaschaWillems]

A good first step would be creating a new issue.

Once #301 is merged, this issue will be automatically closed and the discussions might get lost in tern. A new issue would ensure we can keep track of the module state in the tutorial.