Repository: brendanzab/gl-rs (language: rust)

Issue:
Hide custom generators behind a non-default feature
As mentioned in #338, @mjkoo is relying on some of the `gl_generator::generators` functionality in his [epoxy-rs](https://github.com/mjkoo/epoxy-rs) crate. In the interests of moving towards releasing v1.0, it might make sense to hide it behind a feature flag named `"custom_generators"`.



Discussion / hints:

Fix patch:
diff --git a/gl_generator/Cargo.toml b/gl_generator/Cargo.toml
index 47e7f542..79a46458 100644
--- a/gl_generator/Cargo.toml
+++ b/gl_generator/Cargo.toml
@@ -17,6 +17,9 @@ readme = "README.md"
 name = "gl_generator"
 path = "lib.rs"
 
+[features]
+unstable_generator_utils = []
+
 [dependencies]
 khronos_api = { version = "1.0.0", path = "../khronos_api" }
 log = "0.3.2"
diff --git a/gl_generator/README.md b/gl_generator/README.md
index 53c2aa9e..1eec5e6d 100644
--- a/gl_generator/README.md
+++ b/gl_generator/README.md
@@ -105,9 +105,21 @@ OpenGL 1.1 on Windows, you will need to add
 
 ### Custom Generators
 
-The `gl_generator` crate is extensible. This is a niche feature useful only in
-very rare cases. To create a custom generator, implement the
-`gl_generator::generators::Generator` trait.
+The `gl_generator` can be extended with custom generators. This is a niche
+feature useful only in very rare cases. To create a custom generator, implement
+the `gl_generator::Generator` trait. See the source of the
+`gl_generator::generators` module for examples.
+
+Various utility functions are provided in the `generators` module, but the api
+is unstable, so it has been placed behind a feature flag. In access these
+functions, you will need to add the `"unstable_generator_utils"` feature to
+your `Cargo.toml`:
+
+```toml
+[build-dependencies.gl_generator]
+version = "0.4.2"
+features = ["unstable_generator_utils"]
+```
 
 ## Extra features
 
diff --git a/gl_generator/generators/mod.rs b/gl_generator/generators/mod.rs
index 3df70dc2..2967ed36 100644
--- a/gl_generator/generators/mod.rs
+++ b/gl_generator/generators/mod.rs
@@ -16,7 +16,7 @@ use Api;
 use registry::{Enum, Registry, Cmd};
 use std::io;
 
-mod ty;
+pub mod ty;
 pub mod debug_struct_gen;
 pub mod global_gen;
 pub mod static_gen;
diff --git a/gl_generator/lib.rs b/gl_generator/lib.rs
index 11292d18..e4958229 100644
--- a/gl_generator/lib.rs
+++ b/gl_generator/lib.rs
@@ -64,7 +64,11 @@
 extern crate log;
 extern crate xml;
 
+#[cfg(feature = "unstable_generator_utils")]
 pub mod generators;
+#[cfg(not(feature = "unstable_generator_utils"))]
+mod generators;
+
 mod registry;
 
 pub use generators::Generator;


Test patch:
diff --git a/gl_tests/test_unstable_api/Cargo.toml b/gl_tests/test_unstable_api/Cargo.toml
new file mode 100644
index 00000000..be741020
--- /dev/null
+++ b/gl_tests/test_unstable_api/Cargo.toml
@@ -0,0 +1,12 @@
+[package]
+# we don't include some metadata to avoid accidental publishes
+name = "test_unstable_api"
+version = "0.0.0"
+build = "build.rs"
+
+[lib]
+path = "lib.rs"
+
+[build-dependencies.gl_generator]
+path = "../../gl_generator"
+features = ["unstable_generator_utils"]
diff --git a/gl_tests/test_unstable_api/build.rs b/gl_tests/test_unstable_api/build.rs
new file mode 100644
index 00000000..7a8be141
--- /dev/null
+++ b/gl_tests/test_unstable_api/build.rs
@@ -0,0 +1,33 @@
+// Copyright 2015 Brendan Zabarauskas and the gl-rs developers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+extern crate gl_generator;
+
+use gl_generator::generators;
+
+fn main() {
+    let _ = generators::gen_struct_name;
+    let _ = generators::gen_enum_item::<Vec<u8>>;
+    let _ = generators::gen_type_aliases::<Vec<u8>>;
+    let _ = generators::gen_parameters;
+    let _ = generators::gen_return_type;
+    let _ = generators::gen_symbol_name;
+    let _ = generators::ty::to_rust_ty;
+    let _ = generators::ty::build_gl_aliases::<Vec<u8>>;
+    let _ = generators::ty::build_x_aliases::<Vec<u8>>;
+    let _ = generators::ty::build_glx_aliases::<Vec<u8>>;
+    let _ = generators::ty::build_win_aliases::<Vec<u8>>;
+    let _ = generators::ty::build_wgl_aliases::<Vec<u8>>;
+    let _ = generators::ty::build_egl_aliases::<Vec<u8>>;
+}
diff --git a/gl_tests/test_unstable_api/lib.rs b/gl_tests/test_unstable_api/lib.rs
new file mode 100644
index 00000000..5abcfedb
--- /dev/null
+++ b/gl_tests/test_unstable_api/lib.rs
@@ -0,0 +1,13 @@
+// Copyright 2015 Brendan Zabarauskas and the gl-rs developers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.