Better documentation

[Neurrone]

Hi,

I've just started learning how to use these bindings, and a lot of what I learnt was purely from reading the tests. Having at least the methods in the rust module documented would be really helpful, together with tutorials for getting started.

For example, the runtime struct appears to do JS_Init, the creation of the runtime and also assigning a context to it, which I investigated because the latest version of this crate was missing bindings to the JS_NewRuntime and JS_DestroyRuntime functions. These functions show up on the documentation link but not in the latest version of the crate.

[jdm]

Yeah, our documentation builds have been failing for some time so they haven't caught up to the most recent mammoth upgrade to this crate.

[Neurrone]

Ah. Could you describe what changed? Also, are there higher level ways of doing things like exposing rust functions to js?

On Wed, Aug 22, 2018 at 9:33 PM Josh Matthews notifications@github.com wrote:

Yeah, our documentation builds have been failing for some time so they haven't caught up to the most recent mammoth upgrade to this crate.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/servo/rust-mozjs/issues/436#issuecomment-415033073, or mute the thread https://github.com/notifications/unsubscribe-auth/APtXmnovEz6kf7vGUKQIaSnrf42hUlXKks5uTV22gaJpZM4WHep_ .

[jdm]

We upgraded from a version of SpiderMonkey that was two years old. A huge amount changed, unfortunately.

[Neurrone]

@jdm does Servo or any other Mozilla project use this internally? I'm trying to find out how to easily expose functions and objects to js, so examples of how this is used would be great.

[jdm]

I think the unit tests in this repository might be enough to get you started, however.

[jdm]

Also, we fixed our documentation builds so the link in the readme is once more accurate and up to date.

[Neurrone]

Hi,

I'm trying to create a function that returns the result of compiling a script using jsapi_wrapped::compile1 without having it GCed.

• How do I create the Rust::MutableHandleScript handle? Do I need to root it to prevent GC, convert it into a mutable handle, then return the rooted script? Something like

let script = jsapi::JSScript { }; // I couldn't find any functions that created this
mozjs::rooted!(in(cx) let rooted_script = script);
jsapi_wrapped::compile1(cx, options.ptr, script_cstr.as_ptr(), script_cstr.len(), rooted_script.handle_mut())
rooted_script

• I noticed that the mozjs::rooted! macro expands in this case to

let mut __root = ::jsapi::Rooted::new_unrooted();
let mut rooted_script = ::rust::RootedGuard::new(cx, &mut __root, script);

Do I need to keep both __root and rooted_script alive to prevent GC?

I'll need to execute these scripts later.

• What do compartments do, and do i need to create a compartment for every script executed?
• Can you specify more compilation options than just the filename and line number? CompileOptionsWrapper doesn't have ways to do that. E.g, use of ES6, and the path to a source map in the local filesystem.

If there's a better forum for these questions such as a mailing list, let me know.

[Neurrone]

Also, how do you store a RootGuard for the global object in a struct to prevent garbage collection?

The global is created with

let global : *mut JSObject = JS_NewGlobalObject(...);
mozjs::rooted!(in(cx) let rooted_global = global);

Attempting to store rooted_global causes a missing lifetime error.