From 0a26230a8753c7bb4b0f318fb12af0b219337446 Mon Sep 17 00:00:00 2001 From: Ryan Dahl Date: Thu, 4 Apr 2019 09:35:52 -0400 Subject: [PATCH] Improve docs in core (#2049) --- core/Cargo.toml | 2 ++ core/README.md | 16 ++++++++++++++++ core/isolate.rs | 10 +++++----- website/manual.md | 17 +++++++---------- 4 files changed, 30 insertions(+), 15 deletions(-) create mode 100644 core/README.md diff --git a/core/Cargo.toml b/core/Cargo.toml index a922e8837d..63ca71767a 100644 --- a/core/Cargo.toml +++ b/core/Cargo.toml @@ -7,6 +7,8 @@ edition = "2018" description = "A secure JavaScript/TypeScript runtime built with V8, Rust, and Tokio" authors = ["The deno authors "] license = "MIT" +readme = "README.md" +repository = "https://github.com/denoland/deno" [lib] path = "lib.rs" diff --git a/core/README.md b/core/README.md new file mode 100644 index 0000000000..de7bfc3e38 --- /dev/null +++ b/core/README.md @@ -0,0 +1,16 @@ +# Deno Core + +This Rust crate contains the essential V8 bindings for Deno's command-line +interface (Deno CLI). The main abstraction here is the Isolate which proivdes a +way to execute JavaScript. The Isolate is modeled as a +`Future` which completes once all of its ops have +completed. The user must define what an Op is by implementing the `Behavior` +trait, and by doing so define any "built-in" functionality that would be +provided by the VM. Ops are triggered by `Deno.core.dispatch()`. + +Documentation for this crate is thin at the moment. Please see +[http_bench.rs](https://github.com/denoland/deno/blob/master/core/http_bench.rs) +as a simple example of usage. + +TypeScript support and a lot of other functionality is not available at this +layer. See the [cli](https://github.com/denoland/deno/tree/master/cli) for that. diff --git a/core/isolate.rs b/core/isolate.rs index f301ef680f..a722f5a3ce 100644 --- a/core/isolate.rs +++ b/core/isolate.rs @@ -68,8 +68,8 @@ pub trait Behavior { /// Isolate is created. fn startup_data(&mut self) -> Option; - /// Called whenever Deno.core.send() is called in JavaScript. zero_copy_buf - /// corresponds to the second argument of Deno.core.send(). + /// Called whenever Deno.core.dispatch() is called in JavaScript. zero_copy_buf + /// corresponds to the second argument of Deno.core.dispatch(). fn dispatch( &mut self, control: &[u8], @@ -82,9 +82,9 @@ pub trait Behavior { /// Tokio. The Isolate future complete when there is an error or when all /// pending ops have completed. /// -/// Ops are created in JavaScript by calling Deno.core.send(), and in Rust by -/// implementing Behavior::dispatch. An Op corresponds exactly to a Promise in -/// JavaScript. +/// Ops are created in JavaScript by calling Deno.core.dispatch(), and in Rust +/// by implementing deno::Behavior::dispatch. An Op corresponds exactly to a +/// Promise in JavaScript. pub struct Isolate { libdeno_isolate: *const libdeno::isolate, shared_libdeno_isolate: Arc>>, diff --git a/website/manual.md b/website/manual.md index 70bf555375..7480e25ff0 100644 --- a/website/manual.md +++ b/website/manual.md @@ -50,7 +50,7 @@ Deno provides a set of reviewed - File system and network access can be controlled in order to run sandboxed code. Access between V8 (unprivileged) and Rust (privileged) is only done via serialized messages defined in this - [flatbuffer](https://github.com/denoland/deno/blob/master/src/msg.fbs). This + [flatbuffer](https://github.com/denoland/deno/blob/master/cli/msg.fbs). This makes it easy to audit. For example, to enable write access use the flag `--allow-write` or for network access `--allow-net`. @@ -705,21 +705,18 @@ Current executable set to '../deno/target/debug/deno' (x86_64). (lldb) r ``` -### libdeno +### Deno Core -deno's privileged side will primarily be programmed in Rust. However there will -be a small C API that wraps V8 to 1) define the low-level message passing -semantics, 2) provide a low-level test target, 3) provide an ANSI C API binding -interface for Rust. V8 plus this C API is called "libdeno" and the important -bits of the API is specified here: -[deno.h](https://github.com/denoland/deno/blob/master/libdeno/deno.h) -[libdeno.ts](https://github.com/denoland/deno/blob/master/js/libdeno.ts) +The core binding layer for Deno. It is released as a +[standalone crate](https://crates.io/crates/deno). Inside of core is V8 itself, +with a binding API called "libdeno". See the crate documentation for more +details. ### Flatbuffers We use Flatbuffers to define common structs and enums between TypeScript and Rust. These common data structures are defined in -[msg.fbs](https://github.com/denoland/deno/blob/master/src/msg.fbs) +[msg.fbs](https://github.com/denoland/deno/blob/master/cli/msg.fbs) ### Updating prebuilt binaries