Docs & Example for "Roll Your Own JS Runtime" blog posts

[NfNitLoop]

I was surprised to find that one of the blog posts provided docs for the CreateSnapshotOptions instead of just linking to its Rustdoc. That's because the type itself didn't have docs.

The first commit here is me just inlining those docs into Rustdocs.

But then, as I tried following the example, I found that the APIs have diverged significantly from the blog post series. So I've added another commit which adds an example project that can serve as a live/working example of creating a snapshot for JsRuntime. Hopefully, since this will get built with cargo build, it'll stay more up-to-date than the blog posts.

If this goes too far, I'm happy to create a separate PR that is just the first commit.

If you'd like me to go further, I think it might be a good idea to split the extension out into a separate ext crate, which I think allows for code re-use between build.rs and main.rs.

commit eb35c83

Add docs for create_snapshot() and its options.

commit 618d423

Add an example for "Roll Your Own JS Runtime"

The blog post series had become out-of-date.

Committing example code will hopefully bit-rot less?

[CLAassistant]

All committers have signed the CLA.

[NfNitLoop]

This was the only way I found to get this example crate to run build.rs, which is required for generating the V8 Snapshot. But I'd be happy to learn that there's a better way.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.90%. Comparing base (0c7f83e) to head (95f1036).
Report is 115 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #824      +/-   ##
==========================================
+ Coverage   81.43%   81.90%   +0.46%     
==========================================
  Files          97       98       +1     
  Lines       23877    24929    +1052     
==========================================
+ Hits        19445    20417     +972     
- Misses       4432     4512      +80     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[iuioiua]

@bartlomieju, PTAL

[bartlomieju]

Looks cool, can you update .github/workflows/ci.yml CI script to actually run core/examples/snapshot to ensure it's working fine and prints correct output? Let me know if you need any help or pointers.

[NfNitLoop]

@bartlomieju Done. No need to update the workflow, it already runs cargo test for the workspace, so I just dropped a little self-contained integration test into the example dir.

Result:
https://github.com/denoland/deno_core/actions/runs/10064433085/job/27821343522?pr=824#step:13:43

[irbull]

+1. I just took this for a spin, and from a user perspective this works really well.

Only comment, maybe mention in the README.md in examples/snapshot/ dir that you can simply run

cargo run

To try the example. Maybe that's obvious, but as it was in the examples directory I first thought we could use cargo run --example snapshot, but it's actually a binary crate.

Great work!

[irbull]

One more note, Deno commits typically follow Conventional Commits. I think these commits can be squashed when merged. Here is a proposed commit message from the 5 commits in this change-set.

docs: add "Roll Your Own JS Runtime" Example

Creates an example that demonstrates how to roll your own JS runtime using Deno Core.
In particular, this example shows how to use a build script (`build.rs`) to create a snapshot,
and how to load the snapshot when the JS runtime is started.

This change-set also includes documentation for `create_snapshot()` and its options.

[irbull]

Anything I can do to help push this one through? I can rebase this and update the commit message if that helps? I can add my suggestion about the docs for cargo run. Let me know if I can help in any way.

[NfNitLoop]

Likewise. If there are any blockers to merging this, I'm happy to make them.

[irbull]

The build error here is related to a change in Rust nightly. Specifically, the linter changed when elided lifetimes end up becoming named ones. I've put together a PR to fix this: #895

[irbull]

The build error here is related to a change in Rust nightly. Specifically, the linter changed when elided lifetimes end up becoming named ones. I've put together a PR to fix this: #895

The PR that fixes the build failure is now merged. I can't seem to rebase / merge main into this PR so someone else will need to do that. Hopefully then we can merge this.