Docs: examining generated code

parent 95a79b62
......@@ -11,8 +11,8 @@ proc-macro = true
test = false
[features]
#If this feature is enabled, it's executes the tests with the rust-files
#generated during an earlier run.
# If this feature is enabled, it executes the tests with the
# rust files generated during an earlier run.
test-generated = []
[dependencies]
......
......@@ -4,7 +4,7 @@
//! Generates code to create a derived `glib::Object`
//!
//! This procedural macro defines an extension to the Rust language so
//! The `gobject_gen!` macro defines an extension to the Rust language so
//! that one can create GObject implementations, or define
//! GTypeInterfaces, using only safe code. All the boilerplate needed
//! to register the GObject type, its signals and properties, etc., is
......@@ -15,8 +15,9 @@
//! The macro is invoked as follows:
//!
//! ```norun
//! // see "Necessary imports" below on why this is needed
//! #[macro_use]
//! extern crate glib; // see "Necessary imports" below on why this is needed
//! extern crate glib;
//! use gobject_gen::gobject_gen;
//!
//! gobject_gen! {
......@@ -25,12 +26,13 @@
//! another_field: RefCell<String>,
//! }
//!
//! // Methods and signals;, their order defines the ABI of your class
//! // Methods and signals; their order defines
//! // the ABI of your class
//! impl Foo {
//! pub fn a_static_method(&self) {
//! // self.get_priv() gives us access to the private
//!fields declared in class Foo
//! do_something_with_u32(self.get_priv().private_field.get());
//! // fields declared in class Foo
//! do_something(self.get_priv().private_field.get());
//! }
//!
//! virtual fn a_virtual_method(&self) {
......@@ -63,13 +65,15 @@
//! use gobject_gen::gobject_gen;
//! ```
//!
//! You also need the following dependencies in `Cargo.toml`:
//! You need the following dependencies in `Cargo.toml`:
//!
//! ```norun
//! [dependencies]
//! glib = "0.5.0"
//! glib-sys = "0.6.0"
//! gobject-sys = "0.6.0"
//! libc = "0.2"
//! ```
//!
//! # Instance-private data
//!
......@@ -101,8 +105,45 @@
//!
//! FIXME
//!
//! # Debugging aids and examining generated code
//!
//! With gnome-class still under development, you may need to examine
//! the code that gets generated from the procedural macro. First,
//! create a directory called `generated` under your crate's toplevel
//! directory. Then, put a `generate` attribute for your class, like
//! this:
//!
//! ```norun
//! #[cfg(feature = "test-generated")]
//! include!("generated/foo-gen.rs");
//!
//! #[cfg(not(feature = "test-generated"))]
//! gobject_gen! {
//! #[generate("generated/foo-gen.rs")]
//! class Foo {
//! }
//! }
//! ```
//!
//! Correspondingly, add this to `Cargo.toml` to declare the `test-generated` feature:
//!
//! ```norun
//! [features]
//! # If this feature is enabled, it executes the tests with
//! # the rust files generated during an earlier run.
//! test-generated = []
//! ```
//!
//! If you just `cargo build` your code, then it will output the file
//! `generated/foo-gen.rs` which you can examine. You can then edit
//! that file and rebuild with `cargo build -- --features test-generated` - this will cause
//! the `foo-gen.rs` to get included, instead of using "fresh" generated code.
//!
//! **Remember that changes to the generated code will be overwritten
//! the next time the procedural macro runs!** Don't forget to [report
//! a bug][bugs] if gnome-class is generating incorrect code for you!
//!
//! [bugs]: https://gitlab.gnome.org/federico/gnome-class/issues
#[macro_use]
extern crate quote;
extern crate difference;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment