Reimplement routes! and catchers! as proc_macros

[jebrosen]

What the title says. Also adds compiletest to the codegen_next crate and updates all examples and tests to properly import the macros.

Unfortunately, at present #![feature(proc_macro_non_items)] is required on downstream crates. They are also imported with use like items are instead of with #[macro_use], which makes for a noisy commit.

This branch does not currently move any of the associated documentation.

[jebrosen]

Should rocket_codegen_next go in this list as well?

[jebrosen]

Testing for eof() is necessary, otherwise something like routes![a, b c] will be accepted and parse as only a,b. The compiler plugin macro says it expected ,, ::, or <eof>. This proc_macro currently just says expected eof.

[jebrosen]

I will try replacing the error message with a better one, like "expected paths separated by commas".

[jebrosen]

As discussed in IRC, it would be nice if users didn't need to import these macros just like today.

Current situation:
routes!, catchers!, uri!, and rocket_internal_uri! appear to be "magic" globally available macros because they're globally registered via the compiler plugin. They don't need to be (and probably can't) be imported via any means other than the plugin, that I know of.

proc_macro situation:
routes! and catchers! (so far) are proc_macros. These are only available via use_extern_macros, whether by a use statement or a full path at the call site. I thought that a macro_rules macro could get around that, but I always seem to end up needing use_extern_macros in the consumer crate anyway. It does look like it will be possible to use a macro_rules macro in conjunction with some pub use and $crate in order to allow #[macro_use] instead of use rocket::routes;, but the feature gate may have to stay.

2018 crates:
Crates targeting 2018 can drop 'extern crate' declarations, and importing individual macros via use is posed as an alternative for #[macro_use]. The question is, what path should Rocket's macros be available at for 2018 crates. I will do some more testing to figure out how modules, paths, and imports interact with this.

Proposed design, assuming this all works:

• proc_macros (routes, catchers, etc.) are defined in a proc_macro crate
• The rocket crate will import the proc_macros into <MODULE A>
• The rocket crate will define macro_rules wrapper macros in <MODULE B> that call $crate::<MODULE A>::macro!
• 2015 crates will now add #[macro_use] to extern crate rocket; and have access to the macro_rules macros
• 2018 crates do not need #[macro_use]. They should be able to use macros from either <MODULE A> or <MODULE B> (I will verify this) but we should recommend one or the other, probably the one with the direct proc_macro reexports.

One of <MODULE A> or <MODULE B> could be the crate root, depending on how we want the paths to look to the 2018 crates that import macros.

Note that attribute proc_macros and proc_macro derives are not covered above. They are in a similar situation as far as imports go, but a macro_rules workaround can't be used in this situation. Derives appear to be covered by #[macro_use], I'm not sure about attributes though.

[jebrosen]

Now implements the following variant of the above design:

• routes and catchers are reimplemented as proc_macros: rocket_routes_internal and rocket_catchers_internal, in rocket_codegen_next
• rocket already glob-reexports the macros from rocket_codegen_next
• rocket now defines a macro_rules! macro called routes! that simply forwards its arguments to $crate::rocket_routes_internal, and the same with catchers!
  • this requires use_extern_macros, which will hopefully be stable soon. It is already active in Rocket's examples and tests via the decl_macro feature.
• All consumer crates need to add #[feature(proc_macro_non_items)], and import the macros:
  • Import Option A, idiomatic for Rust 2015: add a #[macro_use] extern crate rocket;
  • Import Option B, idiomatic for Rust 2018: add a use rocket::routes; or use rocket::catchers; and omit extern crate rocket; completely.

My plan is to investigate the use of proc_macro_hack next. Hopefully it will make #[feature(proc_macro_path_invoc)] and maybe even the macro_rules wrappers unnecessary. mashup is another possibility, but the error messages can be very confusing when routes! is used incorrectly.

EDIT: proc_macro_hack looks undesirable because it goes through strings, discarding all useful span information.

[SergioBenitez]

Merged in 8e77961. Woo!