feat(neon-macros): Add neon::main proc attr macro

[kjvalencik]

Summary

Adds a #[neon::main] proc macro.

tl;dr

Use an attribute to initialize either a legacy or napi neon module. The fn doesn't even need to be pub!

use neon::prelude::*;

#[neon::main]
fn main(mut cx: ModuleContext) -> NeonResult<()> {
    Ok(())
}

Migration

diff --git a/test/dynamic/native/src/lib.rs b/test/dynamic/native/src/lib.rs
index 3f2c937..409ab55 100644
--- a/test/dynamic/native/src/lib.rs
+++ b/test/dynamic/native/src/lib.rs
@@ -20,7 +20,8 @@ use js::classes::*;
 use js::tasks::*;
 use js::eventhandler::*;

-register_module!(mut cx, {
+#[neon::main]
+fn main(mut cx: ModuleContext) -> NeonResult<()> {
     cx.export_function("return_js_string", return_js_string)?;

     cx.export_function("return_js_number", return_js_number)?;
@@ -84,4 +85,4 @@ register_module!(mut cx, {
     cx.export_class::<JsPanickyConstructor>("PanickyConstructor")?;

     Ok(())
-});
+}

Thought Process

neon-macros

Procedural macros must be in their own crate. A new crate, neon-macros, is created. The crate has a single feature flag, napi for toggling between legacy and napi implementations.

Proc macros must be at the root of a crate. To keep the structure clean, actual implementations are in napi.rs and legacy.rs modules that are conditionally imported to lib.rs. The lib.rs has thin glue code for delegating to the correct implementation.

Re-export

Proc macros are re-exported from neon to keep users from needing to specify another crate.

Feature Flags

Proc macros can have a negative impact on compile time. A new feature flag, proc-macros is added to enable the feature. It is default disabled since most legacy users will continue to use the normal macros.

It is planned for proc macros to be the recommended way to use N-API. Therefore, the napi-runtime feature flag automatically enables the proc-macros feature flag.

Open Questions

1. Should we keep the panic hook? I think it should be removed. In my opinion, it's more harmful than helpful; especially since it is global. The hook is a holdover from earlier implementations and is no longer necessary. It will be removed.
2. Naming. I like neon::init because it initializes and can be called multiple times (once per context). However, neon::main is another option. Consensus on neon::main.
3. Should we try to protect against using #[neon::init] multiple times? I think we shouldn't because it would be complicated and brittle for limited value. This can be a follow-up.

[kjvalencik]

Updated with changes from feedback.

[goto-bus-stop]

i like it