Skip to content

Latest commit

 

History

History
59 lines (42 loc) · 3.58 KB

CONTRIBUTING.md

File metadata and controls

59 lines (42 loc) · 3.58 KB
Raw

Contributing to rustyscript

Thank you for your interest in contributing to rustyscript! I appreciate your time, and your help in keeping rustyscript useful for everyone.

This document will lay out general instructions for several common tasks, as well as the general structure of the project

Adding Deno extensions

The deno extensions require extensive configuration on both the rust and JS sides to function, and have a complex dependency structure that can easily cause unpredictable issues

For that reason, rustyscript provides these extensions pre-configured and initialized to the user as crate-level features.

The process of adding an extension involves the following steps:

  1. Find the extensions in deno/ext

  2. Note the dependencies in lib.rs, in the deps portion of the call to deno_core::extension

  3. Add a new crate-feature for the extension in Cargo.toml

    • It should be preceded with a comment linking the portion of the spec it implements (see the extensions's readme)
    • It should begin with the extension's crate, which must be an optional dependency of rustyscript
    • It should then list the rustyscript crate-features associated with each of the dependencies found in step 2

  4. Add a new directory in src/ext/extension_name. It will contain mod.rs and init_extension_name.js

  5. Navigate to deno/runtime/js and find all the places in global the extension is added

  6. In init_extension_name.js, include -all- JS sources provided by the new extension, and add the relevant portions to global (see other exts for examples)

  7. In mod.rs, create your init_extension_name extensions and provide the extensions function

  8. Implement ExtensionTrait for the deno_extension and your initializer

  9. If the extension requires configuration, add a feature-gated section to ExtensionOptions

    • If only one field, add it directly to ExtensionOptions
    • Otherwise add an options structure in mod.rs and reference that

10- in src/ext/mod.rs add feature-gated imports, and add your extension to the extensions functions -BELOW- any of its dependencies 11- Add a section to the table in lib.rs for the new extension, and use cargo rdme to regenerate the readme

Project Structure

There are several public-facing portions of the project, most notably runtime, js_value, and module

But there are also portions that should never be public facing:

inner_runtime::InnerRuntime

This is the underlying logic that runtime wraps - it should be async-only, and exposed only through runtime's calls out to it
This should be kept private to simplify the APi

module_loader::RustyLoader

This is the logic underlying transpilation, fetching module code, generating errors, and security around FS/URL imports
This should be kept private due to the sheer number of ways the crate depends on the behaviour of the loader.

transpiler

This is simply a set of utilities for TS -> JS transpilation and is only useful in the context of the module-loader
There is no reason to expose this to the user

ext::*

The deno extensions require extensive configuration on both the rust and JS sides to function, and have a complex dependency structure that can easily cause unpredictable issues

For that reason, rustyscript provides these extensions pre-configured and initialized to the user as crate-level features. Because we managed load-order and dependencies between extensions, exposing these could be dangerous.