Put custom generator utility functions behind a feature flag

Fixes #392

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"

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
 

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;

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;

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

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>>;
+}

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.