Vulkan module without std module

[fknfilewalker]

Since std modules are still not well supported, could we get a way of including vulkan.cppm without the need for std modules? Please hide this behind a define. Unfortunately, this change was made recently.

[sharadhr]

Hi there!

We mandated export import std because Vulkan-Hpp uses the C++ standard library in its public interface. Mixing headers and modules is discouraged by most compiler vendors. If you are using C++20 modules, chances are your toolchain is already quite new, and it should be able to support import std as well. I urge you to update your toolchain if it doesn't. MSVC for instance fixed many ICEs in v19.50, and Clang 22 has set the Reduced BMI mode as default.

There are a few issues we experienced when we mixed the standard library headers and the module.

1. When exporting symbols that have operator<=>, compilers don't really know how to deal with this. This was a particular problem with MSVC, which was stricter than Clang; with the reduced BMI change mentioned above, Clang will probably behave similarly.
2. If the consumer wanted to write import std anyway, the fact that we had #include <stdheader> would also break the compile due to ODR violations.
3. From a UX perspective, writing #include <vulkan/vulkan.hpp> gives you quite a lot of the standard library, because vulkan.hpp transitively includes those headers. The same behaviour needs to be enforced with the module: if you write import vulkan;, we need to provide you with enough of the interface so that things like vk::raii::CommandBuffers : public std::vector<...> works as expected. It doesn't make sense to ask users to consume the module as module vulkan and then also #include <...> to complete that definition.

If you need the standard library as headers for whatever reason, then you'll have to consume Vulkan-Hpp as a header as well.

If you would like examples, please refer to the CI runs for Windows and Linux.

VulkanMemoryAllocator-Hpp also has a CI run structured differently that you might want to use.

[fknfilewalker]

I tried but I can not get them to work with cmake. The internet says to activate them via CMAKE_EXPERIMENTAL_CXX_IMPORT_STD with a uuid that changes with each cmake version... Currently I use c++20 because 23 is just not complete, though std modules are part of 23 and not 20 as far as I know. Still, switching to c++23 did not fix it for me.
Does your implementation work with all compilers and which c++ version is required? Do you have a cmake example?

As it was before I had it working on all OSs compiling with all c++ compilers, see: https://github.com/fknfilewalker/vulkan-triangle-modern

[M2-TE]

If you did not get import std working with CMake, there are two usual suspects (C++23 is still required, althouth major compilers have agreed to settle on it becoming a C++20 feature officially):

• Make sure to set the CMAKE_EXPERIMENTAL_CXX_IMPORT_STD gate before your project(...) call. Or do it on the commandline for your configuration step.
• Wrong UUID for your current CMake release. You can check out CMake git with a specific release tag and check Help/dev/experimental.rst for the correct UUID

CXX_MODULE_STD and CXX_SCAN_FOR_MODULES should both be enabled for your target that uses import std. You can also use the global versions with the CMAKE_ prefix.
If you still cannot get it working, share your toolchain setup (compiler and CMake versions) with us.

[fknfilewalker]

I don't like this solution. So far the vulkan module worked pretty well, why not just keep the ifdef VULKAN_HPP_NO_STD_MODULE in there to let people deactivate the std module similar to how it was before.

[sharadhr]

I don't like this solution.

Firstly, all three compiler vendors have shipped their module interface files for module std, and they all generally work well. Users can manually assemble the commands needed to precompile it.

Secondly, this is a CMake-only issue. That CMake decided to make its support experimental is not in our hands. I'm not sure if you are aware, but vulkan.cppm was first developed in early 2023 when CMake's support for modules itself was experimental, version 3.25 or something. The logic needed to manage that was quite complicated, but was subsequently removed when CMake landed 'official' support in version 3.28.

This too will pass; I expect that all this experimental UUID gate stuff will be removed in one to two versions, probably CMake 4.3 or 4.4.

So far the vulkan module worked pretty well

In my initial comment I have demonstrated how it hasn't. If I wanted to write import std as a consumer the module broke badly. If it has worked for you, then your toolchain is non-compliant or less strict. Like I said, mixing headers and modules especially for something that provides the same API has been very, very problematic.

Additionally, with import std we have drastically simplified all of our build tools logic, and the only additional thing is to set up this UUID (which, as mentioned above, will be gone soon).

And finally, vulkan.cppm contains a clear warning that it is experimental, and if you sign up to use it, it is bound to change in unexpected ways, and that the module itself can and will break in pursuit of correctness and ease-of-use. We hope to remove this warning by the end of 2026, but until then there will be plenty of churn.

[fknfilewalker]

Firstly, all three compiler vendors have shipped their module interface files for module std

There is not even a compiler that implements c++23 fully, so why force std modules when they are a c++23 feature

Like I said, mixing headers and modules especially for something that provides the same API has been very, very problematic.

Isn't this exactly why VULKAN_HPP_NO_STD_MODULE was good. You want to use std module, go ahead, you don't, not problem...

Additionally, with import std we have drastically simplified all of our build tools logic

Still looks way too complicated.
Literally all you need to make vulkan a module with c++20 (works with clang, gcc, msvc; mac, linux, windows)

add_library(VulkanCppModule)
target_sources(VulkanCppModule PUBLIC FILE_SET CXX_MODULES
    FILES "${VULKAN_DIR}/vulkan-headers/include/vulkan/vulkan.cppm"
)
target_include_directories(VulkanCppModule PUBLIC "${VULKAN_DIR}/vulkan-headers/include")
target_compile_definitions(VulkanCppModule PUBLIC 
    VULKAN_HPP_NO_STD_MODULE
    VK_NO_PROTOTYPES
)

[sharadhr]

Still looks way too complicated.

As I've mentioned, this is a CMake problem, and more importantly, a temporary measure. I have illustrated how complicated building the early vulkan.cppm was, and this was for a good 6+ months until CMake 3.28 was released.

Though both Vulkan-Hpp and Vulkan-Headers are built and distributed with CMake, the module interface file and the module std are independent of the CMake build and install mechanisms. Other build systems may support your use-case better, like XMake or Build2.

Once again, I urge you to upgrade your toolchain and try the steps detailed here, which will allow you to also remove your list of #include <header> in your test project.

[fknfilewalker]

I will update to std modules once it is properly supported. For now this is not the case. Is it so hard to leave VULKAN_HPP_NO_STD_MODULE in there. Compatibility is important!

Btw, why are you exporting the whole std module in vulkan.cppm... export import std;
just do import...

[sharadhr]

Is it so hard to leave VULKAN_HPP_NO_STD_MODULE in there

I have reiterated why and how having that setting available led to incomplete and incorrect compilation. Once again, even if your toolchain worked correctly, it doesn't mean it will in future and we are relying on unspecified implementation details.

Compatibility is important!

vulkan.cppm is still considered experimental, and we have warned users since the very beginning that the experience can and will change.

[n0F4x]

By including std, you subscribe to using std as part of the global module. This is completely normal and this is how many libraries are still going to be used for some time, as not everything has a module equivalent.
But at the point that you import std in any place, you also need to import it everywhere else and you are no longer allowed to include it. This applies to third-party libraries as well.
So when you have a bunch of third-party dependencies that don't import std, you effectively are not allowed to use it either. Once vulkan.cppm breaks this, it also breaks your whole build.

[sharadhr]

you are no longer allowed to include it
you effectively are not allowed to use it either

Neither of these are the case. As I've tested myself, having both import std; does not disallow #include statements as long as the #include comes before the import. So:

module;

#include <ThirdParty/ThirdPartyThatIncludesVector>
#include <string>

// can have `import vulkan;` here

export module foo;

import vulkan; // or here

using namespace std::literals;

auto bar() -> std::string
{
// do Vulkan things
  return "ok"s;
}

#include <print> // But why? All toolchains have `std`...
import foo;

auto main() -> int
{
  std::println("{}", bar()); // no problems...
}

I now see there is demand for this, and people aren't happy about upgrading their toolchains (which is odd, because modules already demand the latest toolchains and considerable legwork; once again, see the complication that was required when the module was first written).

I think I'll add the option back in, but with an unsilenceable #warning that this configuration is neither supported, tested, nor recommended, and that users should try using import std; ASAP. Of course, we will not test this configuration: caveat emptor, here be dragons, at your peril.

[fknfilewalker]

I now see there is demand for this, and people aren't happy about upgrading their toolchains (which is odd, because modules already demand the latest toolchains and considerable legwork; once again, see the complication that was required when the module was first written).

c++20 and c++23 are not the same! C++20 which is the default nowadays which supports modules but does not require std modules and many people use it like that.

I think I'll add the option back in, but with an unsilenceable #warning

It is completely legit to use the vulkan module with c++20 without std modules! You could add a warning if the person uses c++23 without the std module but not for c++20 (though I don't really see a point in having a warning at all).

Thank you for this decision, once again compatibility is important for something so fundamental!

[sharadhr]

c++20 and c++23 are not the same! C++20 which is the default nowadays which supports modules but does not require std modules

As @M2-TE said, you can use import std; in C++20, too. There appears to be a confusion of CMake's interface with the interface provided by toolchains.

To use module std; in C++20 in Clang:

// test.cpp
import std;

auto main() -> int
{
  std::cout << "Hello, " << "world" << std::endl;
}

clang++ -std=c++20 -stdlib=libc++ -Wno-reserved-identifier -Wno-reserved-module-identifier --precompile -o std.pcm /path/to/libc++/v1/std.cppm
clang++ -std=c++20 -stdlib=libc++ -fmodule-file=std=std.pcm -o test std.pcm test.cpp
./test

[M2-TE]

To add to @sharadhr's example using CMake:

# declare target to use C++23 for compilation, but be consumed as a C++20 target
target_compile_features(Vulkan-HppModule
  PRIVATE   cxx_std_23
  INTERFACE cxx_std_20)

I reckon CMake will make import std fully available in C++20 once it leaves the experimental state.

[sharadhr]

I've asked around compiler authors, and the general consensus seems to be that

1. Compilers are free to optimise the GMF/global module fragment—that is, where #include statements go—as they see fit
2. As such, module implementors cannot rely on the stability, or indeed, visibility of symbols defined in the GMF to expose in the module purview
3. This affects 'invisible'/implicit imports like std::partial_ordering, which is produced by operator<=>

Their advice is to either explicitly write using std::type in the public interface of the module (which is really impractical for any non-generated module library), or just export import the dependency, which is considerably more modern, safe, and reliable as the compiler has full visibility of the dependency graph.

---

I will say that I find the requirement for 'backwards compatibility' here ironic, because as already mentioned, modules require a modern toolchain.

I will add the option back in, but I sincerely urge you all to try and upgrade your toolchains first, not least because newer toolchains contain fewer bugs, more module compilation optimisations, and more importantly, it allows you to use vulkan.cppm as intended:

one line to rule them all. 💍