Ted Campbell [:tcampbell] Reporter
	Description • 6 years ago

We should create a repository of embedding examples for SpiderMonkey that is outside of tree. Initially will be on personal github's (I think :jorendorff is itching to start this) and later we can move to either mozilla or maybe a "SpiderMonkey Embedders" organization.

One messy issue is releases of SpiderMonkey. Initially, we can leave this out of scope.

	Ted Campbell [:tcampbell] Reporter
	Comment 1 • 6 years ago

My feeling would be to have a number of small examples(jsshell has ballooned in complexity in comparison). Some ideas:

* hello_world: Minimal example that loads a .js and executes it once
* repl: Minimal REPL loop
* jsnative: Example of custom C++ methods, including rooting
* customtracing: Example of storing GC ptrs in embedding data structures and handling tracing
* resolvehook: Example of custom class using resolve hook for lazy resolution

(Feel free to ignore or do something different!)

	Ted Campbell [:tcampbell] Reporter
	Comment 2 • 6 years ago

We have automatic packages in:
* https://index.taskcluster.net/v1/task/gecko.v2.mozilla-central.latest.firefox.sm-package-linux64-opt/artifacts/public/build/ 
* https://index.taskcluster.net/v1/task/gecko.v2.mozilla-esr60.latest.firefox.sm-package-linux64-opt/artifacts/public/build/

Unfortunately, they include commits between ESR releases as they are being staged.

We also tried having manual releases in (see linked bugs):
http://ftp.mozilla.org/pub/spidermonkey/

	Philip Chimento [:ptomato]
	Comment 3 • 6 years ago

I love this idea! I will be happy to contribute some of these examples, and maybe getting them code reviewed by a SpiderMonkey team member will teach me something new!

This is a nice, though seriously outdated, tutorial: https://web.archive.org/web/20100820094305/http://egachine.berlios.de/embedding-sm-best-practice/embedding-sm-best-practice.html

I've also started collecting some documentation, although specific to developers of GJS, here: https://gitlab.gnome.org/GNOME/gjs/wikis/Understanding-SpiderMonkey-code

	Nicolas B. Pierron [:nbp]
	Comment 4 • 6 years ago

If we do create such collection of examples, I think we should also have some form of CI to know when we break our API.
This will help us provide documentation and code examples on how to fix these.

	Philip Chimento [:ptomato]
	Comment 5 • 6 years ago

Here's the still-useful MDN page that we talked about today: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/GC_Rooting_Guide

	Philip Chimento [:ptomato]
	Comment 6 • 6 years ago

I've pushed a bare-bones repo: https://github.com/ptomato/spidermonkey-embedding-examples

It's under my own namespace but I can certainly transfer it to a Mozilla organization, or we could create a new SpiderMonkey embedders organization.

The first example is at https://github.com/ptomato/spidermonkey-embedding-examples/pull/1, review is appreciated.

I've also started a REPL example at https://github.com/ptomato/spidermonkey-embedding-examples/tree/repl-example but it's not done yet. It's based on the REPL we have in GJS but it's not really "minimal".

I did format the C++ code with the "Mozilla" preset of clang-format and it looks a bit weird compared to the code I see in Searchfox, but you all would know better whether this preset is correct or not.

	Philip Chimento [:ptomato]
	Comment 7 • 6 years ago

I've captured all the ideas here in GitHub issues on https://github.com/spidermonkey-embedders/spidermonkey-embedding-examples/issues, so let's close this.