gecko-dev/third_party/rust/syntex/README.md

Syntex Code Generation Framework

syntex is a library that enables compile time syntax extension expansion. This allows users to use libraries like serde on stable Rust.

Configuring with Cargo

To create a package:

[package]
name = "hello_world_macros"
version = "0.2.0"
authors = [ "erick.tryzelaar@gmail.com" ]

[dependencies]
syntex = "*"
syntex_syntax = "*"

To use it:

Cargo.toml:

[package]
name = "hello_world"
version = "0.3.0"
authors = [ "erick.tryzelaar@gmail.com" ]
build = "build.rs"

[build-dependencies]
syntex = "*"

build.rs:

extern crate syntex;
extern crate hello_world_macros;

use std::env;
use std::path::Path;

fn main() {
    let mut registry = syntex::Registry::new();
    hello_world_macros::register(&mut registry);

    let src = Path::new("src/main.rs.in");
    let dst = Path::new(&env::var("OUT_DIR").unwrap()).join("main.rs");

    registry.expand("hello_world", &src, &dst).unwrap();
}

src/main.rs:

// Include the real main
include!(concat!(env!("OUT_DIR"), "/main.rs"));

src/main.rs.in:

fn main() {
    let s = hello_world!();
    println!("{}", s);
}

Limitations

Unfortunately because there is no stable plugin support in Rust yet, there are some things that syntex cannot do:

• The code generated by syntex reports errors in the generated file, not the source file.
• Syntex macros cannot be embedded in macros it doesn't know about, like the builtin vec![], println!(...), and etc. This is because those macros may override the macro_name!(...) to mean something different.