states, invoking `trace_macros!(true)` will automatically print those
intermediate states out, and passing the flag `--pretty expanded` as a
command-line argument to the compiler will show the result of expansion.
+
+If Rust's macro system can't do what you need, you may want to write a
+[compiler plugin](guide-plugin.html) instead. Compared to `macro_rules!`
+macros, this is significantly more work, the interfaces are much less stable,
+and the warnings about debugging apply ten-fold. In exchange you get the
+flexibility of running arbitrary Rust code within the compiler. Syntax
+extension plugins are sometimes called "procedural macros" for this reason.
All of the above extensions are expressions with values.
+Users of `rustc` can define new syntax extensions in two ways:
+
+* [Compiler plugins](guide-plugin.html#syntax-extensions) can include arbitrary
+ Rust code that manipulates syntax trees at compile time.
+
+* [Macros](guide-macros.html) define new syntax in a higher-level,
+ declarative way.
+
## Macros
```{.ebnf .gram}
User-defined syntax extensions are called "macros", and the `macro_rules`
syntax extension defines them. Currently, user-defined macros can expand to
-expressions, statements, or items.
+expressions, statements, items, or patterns.
(A `sep_token` is any token other than `*` and `+`. A `non_special_token` is
any token other than a delimiter or `$`.)
- `main` - indicates that this function should be passed to the entry point,
rather than the function in the crate root named `main`.
- `plugin_registrar` - mark this function as the registration point for
- compiler plugins, such as loadable syntax extensions.
+ [compiler plugins][plugin], such as loadable syntax extensions.
- `start` - indicates that this function should be used as the entry point,
overriding the "start" language item. See the "start" [language
item](#language-items) for more details.
align fields.
- `phase` - on `extern crate` statements, allows specifying which "phase" of
compilation the crate should be loaded for. Currently, there are two
- choices: `link` and `plugin`. `link` is the default. `plugin` will load the
- crate at compile-time and use any syntax extensions or lints that the crate
+ choices: `link` and `plugin`. `link` is the default. `plugin` will [load the
+ crate at compile-time][plugin] and use any syntax extensions or lints that the crate
defines. They can both be specified, `#[phase(link, plugin)]` to use a crate
both at runtime and compiletime.
- `simd` - on certain tuple structs, derive the arithmetic operators, which
* `warn(C)` warns about violations of `C` but continues compilation.
The lint checks supported by the compiler can be found via `rustc -W help`,
-along with their default settings.
+along with their default settings. [Compiler
+plugins](guide-plugin.html#lint-plugins) can provide additional lint checks.
```{.ignore}
mod m1 {
considered unwholesome and in need of overhaul, and it is not clear
what they will look like moving forward.
-* `plugin_registrar` - Indicates that a crate has compiler plugins that it
+* `plugin_registrar` - Indicates that a crate has [compiler plugins][plugin] that it
wants to load. As with `phase`, the implementation is
in need of a overhaul, and it is not clear that plugins
defined using this will continue to work.
* The block syntax of Ruby.
[ffi]: guide-ffi.html
+[plugin]: guide-plugin.html