ash: Hide provisional extensions behind new provisional feature flag

Provisional extensions are susceptible to **breaking** API changes
at any point (with accompanying `SPEC_VERSION` bump).  By hiding them
behind a non-default feature flag, we can document that opting into
this feature allows us to do breaking changes to these modules in
non-breaking `ash` releases when driven by upstream `Vulkan-Headers`
changes to `vk.xml`.

Moreover, upstream Khronos repositories that build `ash` in their CI
can continue to build-test their changes without compile-testing any
extension behind a `provisional` flag, which is especially useful if
we've already wrapped a `provisonal` extension that is seeing breaking
changes.

Author: MarijnS95

ash/Cargo.toml

@@ -34,6 +34,8 @@ loaded = ["libloading", "std"]
 debug = []
 # Whether the standard library should be required
 std = []
+# Enable provisional Vulkan extensions. May see *semver-breaking* code changes in non-breaking releases!
+provisional = []
 
 [package.metadata.release]
 no-dev-version = true

ash/src/extensions/amdx/shader_enqueue.rs

@@ -1,3 +1,4 @@
+#![cfg(feature = "provisional")]
 //! <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_AMDX_shader_enqueue.html>
 
 use crate::prelude::*;

ash/src/extensions/nv/cuda_kernel_launch.rs

@@ -1,3 +1,4 @@
+#![cfg(feature = "provisional")]
 //! <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_NV_cuda_kernel_launch.html>
 
 use crate::prelude::*;

ash/src/extensions_generated.rs

@@ -511,6 +511,7 @@ pub mod amd {
 #[doc = "Extensions tagged AMDX"]
 pub mod amdx {
     #[doc = "VK_AMDX_shader_enqueue"]
+    #[cfg(feature = "provisional")]
     pub mod shader_enqueue {
         use super::super::*;
         pub use {
@@ -14828,6 +14829,7 @@ pub mod khr {
         }
     }
     #[doc = "VK_KHR_portability_subset"]
+    #[cfg(feature = "provisional")]
     pub mod portability_subset {
         use super::super::*;
         pub use {
@@ -19248,6 +19250,7 @@ pub mod nv {
         };
     }
     #[doc = "VK_NV_cuda_kernel_launch"]
+    #[cfg(feature = "provisional")]
     pub mod cuda_kernel_launch {
         use super::super::*;
         pub use {
@@ -19656,6 +19659,7 @@ pub mod nv {
         }
     }
     #[doc = "VK_NV_displacement_micromap"]
+    #[cfg(feature = "provisional")]
     pub mod displacement_micromap {
         use super::super::*;
         pub use {

generator/src/lib.rs

@@ -1179,8 +1179,9 @@ impl<'a> ConstantExt for ExtensionConstant<'a> {
     }
 }
 
+/// Generates constants for `<extension>` or `<feature>` children
 pub fn generate_extension_constants<'a>(
-    extension_name: &str,
+    extension_name: &'a str,
     extension_number: i64,
     extension_items: &'a [vk_parse::ExtensionChild],
     const_cache: &mut HashSet<&'a str>,
@@ -1268,13 +1269,13 @@ pub struct ExtensionCommands<'a> {
 }
 
 pub fn generate_extension_commands<'a>(
-    full_extension_name: &'a str,
-    items: &'a [vk_parse::ExtensionChild],
+    extension: &'a vk_parse::Extension,
     cmd_map: &CommandMap<'a>,
     cmd_aliases: &HashMap<&'a str, &'a str>,
     fn_cache: &mut HashSet<&'a str>,
     has_lifetimes: &HashSet<Ident>,
 ) -> ExtensionCommands<'a> {
+    let full_extension_name = &extension.name;
     let byte_name_ident = Literal::byte_string(format!("{full_extension_name}\0").as_bytes());
 
     let extension_name = full_extension_name.strip_prefix("VK_").unwrap();
@@ -1287,7 +1288,8 @@ pub fn generate_extension_commands<'a>(
 
     let name_ident = format_ident!("{}_NAME", extension_name.to_uppercase());
     let spec_version_ident = format_ident!("{}_SPEC_VERSION", extension_name.to_uppercase());
-    let spec_version = items
+    let spec_version = extension
+        .children
         .iter()
         .filter_map(get_variant!(vk_parse::ExtensionChild::Require { items }))
         .flatten()
@@ -1306,7 +1308,8 @@ pub fn generate_extension_commands<'a>(
     let mut device_commands = Vec::new();
 
     let mut rename_commands = HashMap::new();
-    let names = items
+    let names = extension
+        .children
         .iter()
         .filter_map(get_variant!(vk_parse::ExtensionChild::Require {
             api,
@@ -1431,6 +1434,10 @@ pub fn generate_extension_commands<'a>(
     let (raw_instance_fp, hl_instance_fp) =
         instance_fp.map_or((None, None), |(a, b)| (Some(a), Some(b)));
 
+    let provisional = extension
+        .provisional
+        .then(|| quote!(#[cfg(feature = "provisional")]));
+
     ExtensionCommands {
         vendor,
         raw: quote! {
@@ -1443,6 +1450,7 @@ pub fn generate_extension_commands<'a>(
         },
         high_level: quote! {
             #[doc = #full_extension_name]
+            #provisional
             pub mod #extension_ident {
                 use super::super::*; // Use global imports (i.e. Vulkan structs and enums) from the root module defined by this file
 
@@ -3262,7 +3270,7 @@ pub fn write_source_code<P: AsRef<Path>>(vk_headers_dir: &Path, src_dir: P) {
         .map(|ext| {
             generate_extension_constants(
                 &ext.name,
-                ext.number.unwrap_or(0),
+                ext.number.unwrap(),
                 &ext.children,
                 &mut const_cache,
                 &mut const_values,
@@ -3274,8 +3282,7 @@ pub fn write_source_code<P: AsRef<Path>>(vk_headers_dir: &Path, src_dir: P) {
     let mut extension_cmds = Vec::<TokenStream>::new();
     for ext in extensions.iter() {
         let cmds = generate_extension_commands(
-            &ext.name,
-            &ext.children,
+            ext,
             &commands,
             &cmd_aliases,
             &mut fn_cache,