Setting up codegen

Serde provides code generation to generate implementations of the Serialize and Deserialize traits for structs defined in your crate, allowing them to be used conveniently with all of Serde's data formats.

You only need codegen if your code is using #[derive(Serialize, Deserialize)]

Codegen is based on Rust's #[derive] mechanism, just like what you would use to automatically derive implementations of the built-in Clone, Copy, or Debug traits. It is able to generate implementations for most structs including ones with elaborate generic types or trait bounds. On rare occasions, for an especially convoluted type you may need to implement the traits manually.

There are two different ways of setting up code generation depending on whether your crate will be used with stable released versions of Rust or with unstable nightly versions. The approach intended for the nightly compiler takes advantage of Rust's experimental support for "Macros 1.1" plugins which can only be used on nightly. This feature will be stabilized in Rust 1.15 in February 2017. The approach intended for the stable compiler instead uses a code generation library called Syntex and a Cargo build script to write out the generated code to a file and include it into your crate. This approach will not be supported after Rust 1.15 in February 2017.

There is also a third hybrid approach which uses Syntex by default but uses a Cargo feature to switch to Macros 1.1 when running with nightly.

One downside of the Syntex (stable) approach is that errors and warnings emitted by rustc can sometimes point into the nasty generated code and those can be difficult to trace back to the true source of the problem. We recommend setting up the hybrid approach but doing your primary development and debugging using a nightly compiler.