Macros — Visibility and export

// before!();                   // ERROR: the macro is not declared yet

macro_rules! before {
    () => { 1 };
}

fn f() -> i32 { before!() }      // OK: after the declaration

mod child {
    pub fn g() -> i32 { before!() }   // OK: module declared after the macro
}

// src/lib.rs
#[macro_use]
mod macros;        // defines the macros (see section 2.1)
mod forms;         // can use them
mod views;         // too

// src/lib.rs
#[macro_use]
mod macros;                     // the macros of this module stay visible after it
mod users;

// src/macros.rs
macro_rules! check {
    ($c:expr) => { assert!($c) };
}

// src/users.rs
pub fn create() {
    check!(true);               // visible thanks to #[macro_use] and the order of the mod items
}

// src/macros.rs
macro_rules! check {
    ($c:expr) => { assert!($c) };
}
pub(crate) use check;           // the macro becomes an ordinary item of the module

// src/users.rs
use crate::macros::check;       // explicit import, like a function

pub fn create() {
    check!(true);
}

pub(crate) use macro_name; right after the definition turns the macro into an item that can be imported by its path. The order of the mod items no longer matters, and the editor knows where the macro comes from.

// In the crate `my_lib`, any file
#[macro_export]
macro_rules! say {
    ($msg:expr) => { println!("my_lib: {}", $msg) };
}

// In a crate that depends on my_lib
use my_lib::say;               // from the root, never my_lib::module::say

fn main() {
    say!("hello");
    my_lib::say!("also possible without use");
}

// In my_lib
pub fn log_line(msg: &str) { println!("{msg}"); }

#[macro_export]
macro_rules! log_bad {
    ($m:expr) => { log_line($m) };     // resolved at the CALL site, in the user's code
}

In the user's code, log_line does not exist (or means something else): the macro breaks. Writing my_lib::log_line is not enough either: the user may have renamed the dependency (my_lib2 = { package = "my_lib" }), and inside my_lib itself, my_lib:: refers to nothing.

#[macro_export]
macro_rules! log {
    ($m:expr) => { $crate::log_line($m) };
}

$crate is replaced by the path of the crate that defines the macro, wherever it is called from and whatever name it is imported under. It is the only reliable way to refer to items of your own crate in an exported macro.

#[macro_export]
macro_rules! new_table {
    ($($k:expr => $v:expr),*) => {{
        let mut m = ::std::collections::HashMap::new();   // std: absolute path ::std
        $( m.insert($k, $v); )*
        $crate::Table::from(m)                             // own crate: $crate
    }};
}

The last point is a frequent trap: x.method() in the expansion only works if the user imported the trait. $crate::MyTrait::method(&x) always works.

// In my_lib (which depends on serde_json)
#[doc(hidden)]
pub use serde_json as __serde_json;      // hidden re-export

#[macro_export]
macro_rules! json_of {
    ($v:expr) => { $crate::__serde_json::to_string(&$v) };
}

pub struct Routes { /* ... */ }

impl Routes {
    #[doc(hidden)]
    pub fn new() -> Self { Routes { /* ... */ } }         // called by the macro

    #[doc(hidden)]
    pub fn add(&mut self, path: &str) { /* ... */ }       // called by the macro
}

#[macro_export]
macro_rules! routes {
    ($($path:literal),* $(,)?) => {{
        let mut r = $crate::Routes::new();
        $( r.add($path); )*
        r
    }};
}

// src/macros/mod.rs
#[macro_export]
macro_rules! my_macro { () => {} }

// src/lib.rs
pub mod macros;
// pub use macros::my_macro;      // useless: #[macro_export] already puts it at the root

A #[macro_export] macro is already at the root. You can add it to a prelude:

// src/prelude.rs
pub use crate::my_macro;

#[macro_use]
extern crate serde_derive;

// Old
#[macro_use]
extern crate my_lib;
fn main() { say!("x"); }

// Modern: an explicit use
use my_lib::say;
fn main() { say!("x"); }

/// Creates a `HashMap` from `key => value` pairs.
///
/// # Example
///
/// ```
/// let m = my_lib::table! { "a" => 1, "b" => 2 };
/// assert_eq!(m["a"], 1);
/// ```
#[macro_export]
macro_rules! table {
    ($($k:expr => $v:expr),* $(,)?) => {
        ::std::collections::HashMap::from([$(($k, $v)),*])
    };
}

The /// comment goes above #[macro_export]. The example is run by cargo test as a documentation test, from an external crate: it checks exactly what the user will see (paths through $crate, required imports).

/// ```compile_fail
/// let x = my_lib::table!(1, 2);     // syntax without =>: must be rejected
/// ```

// runique/src/macros/routeur/router.rs
#[macro_export]
macro_rules! urlpatterns {
    // ...
    (@parse $routes:ident; admin $path:expr => $handler:expr, /* ... */ $($rest:tt)*) => {
        $routes.add_admin_route::<$model>($path, $name, $handler, $view);
        $crate::urlpatterns!(@parse $routes; $($rest)*);      // recursion through $crate
    };
}

// runique/src/macros/routeur/routes.rs
impl Routes {
    /// Used by `urlpatterns!`; construct route sets through the macro.
    #[doc(hidden)]
    pub fn new() -> Self { /* ... */ }

    /// Used by `urlpatterns!` to add an ordinary route.
    #[doc(hidden)]
    pub fn add_route(&mut self, path: impl AsRef<str>, handler: MethodRouter) { /* ... */ }
}

The macro is exported at the root (runique::urlpatterns!), calls itself through $crate::, and uses public methods hidden from the documentation, which the user is not supposed to call directly.

// runique/src/macros/bdd/filter.rs
#[macro_export]
#[doc(hidden)]
macro_rules! search_apply_op { /* eq, icontains, gte... */ }

search! translates operators (eq, icontains, gte...) into SeaORM conditions through this helper macro, which is exported (so it can be called from the code expanded in the user's crate) but hidden.

// runique/src/lib.rs
pub use derive_form::{extend, model};

pub mod prelude {
    pub use derive_form::{extend, form, model};
    // ...
}

model!{}, extend!{} and #[form] live in the derive_form crate (a proc-macro crate). The user only declares runique and receives them through use runique::prelude::*.

// runique/src/lib.rs
// In the crate's own tests, `::runique::…` (what `model!{}` and `extend!{}`
// generate) names the crate itself.
#[cfg(test)]
extern crate self as runique;

The code generated by model!{} contains ::runique::... paths. In the user's code, runique is a dependency: all is well. In the framework's own tests, this line gives the crate the name runique, so the same generated code compiles (section 7.3).

macro_rules! m { .. }                // visible after its declaration, in the module and the following ones
#[macro_use] mod macros;             // keep the macros visible after the module
pub(crate) use m;                    // import by path inside the crate: use crate::macros::m;
#[macro_export] macro_rules! m { .. } // crate root, for everyone: use my_lib::m;
$crate::Item                         // path to your own crate in the expansion
::std::collections::HashMap          // std as an absolute path
$crate::Trait::method(&x)            // trait method without an import in the user's code
#[doc(hidden)] pub use dep as __dep; // dependency used by the macro
#[doc(hidden)] pub fn helper() {}    // public helper, hidden from the docs
pub use my_lib_macros::MyDerive;     // re-export a procedural macro
#[cfg(test)] extern crate self as my_lib;   // ::my_lib:: in its own tests