diff options
| -rw-r--r-- | Docs.md | 235 | ||||
| -rw-r--r-- | website/index.html | 13 |
2 files changed, 196 insertions, 52 deletions
@@ -1,18 +1,28 @@ -# Deno Docs +# Deno Documentation + +## Disclaimer + +A word of caution: Deno is very much under development. We encourage brave early +adopters, but expect bugs large and small. The API is subject to change without +notice. + +[Bug reports](https://github.com/denoland/deno/issues) do help! ## Install -Deno works on OSX, Linux, and Windows. We provide binary download scripts: +Deno works on OSX, Linux, and Windows. Deno is a single binary executable. It +has no external dependencies. -With Python: +[deno_install](https://github.com/denoland/deno_install) provides convenience +scripts to download and install the binary. + +Using Python: ``` curl -sSf https://raw.githubusercontent.com/denoland/deno_install/master/install.py | python ``` -See also [deno_install](https://github.com/denoland/deno_install). - -With PowerShell: +Or using PowerShell: ```powershell iex (iwr https://raw.githubusercontent.com/denoland/deno_install/master/install.ps1) @@ -22,10 +32,15 @@ _Note: Depending on your security settings, you may have to run `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` first to allow downloaded scripts to be executed._ +Deno can also be installed manually, by downloading a tarball or zip file at +[github.com/denoland/deno/releases](https://github.com/denoland/deno/releases). +These packages contain just a single executable file. You will have to set the +executable bit on Mac and Linux. + Try it: ``` -> deno http://deno.land/thumb.ts +> deno https://deno.land/thumb.ts ``` ## API Reference @@ -34,58 +49,186 @@ To get an exact reference of deno's runtime API, run the following in the command line: ``` -deno --types +> deno --types ``` -In case you don't have it installed yet, but are curious, here is an out-of-date -copy of the output: https://gist.github.com/78855aeeaddeef7c1fce0aeb8ffef8b2 +Or see the [doc website](https://deno.land/typedoc/index.html). -(We do not yet have an HTML version of this. See -https://github.com/denoland/deno/issues/573) +If you are embedding deno in a Rust program, see +[the rust docs](https://deno.land/rustdoc/deno/index.html). -## Examples +## Tutorial -### Example: An implementation of the unix "cat" program +### An implementation of the unix "cat" program -The copy here is actually zero-copy. That is, it reads data from the socket and -writes it back to it without ever calling a memcpy() or similar. +In this program each command-line argument is assumed to be a filename, the file +is opened, and printed to stdout. ```ts import * as deno from "deno"; -for (let i = 1; i < deno.args.length; i++) { - let filename = deno.args[i]; - let file = await deno.open(filename); - await deno.copy(deno.stdout, file); -} +(async () => { + for (let i = 1; i < deno.args.length; i++) { + let filename = deno.args[i]; + let file = await deno.open(filename); + await deno.copy(deno.stdout, file); + file.close(); + } +})(); ``` -### Example: A TCP Server echo server +The `copy()` function here actually makes no more than the necessary kernel -> +userspace -> kernel copies. That is, the same memory from which data is read +from the file, is written to stdout. This illustrates a general design goal for +I/O streams in Deno. -The copy here is actually zero-copy. That is, it reads data from the socket and -writes it back to it without ever calling a memcpy() or similar. +Try the program: + +``` +> deno https://deno.land/x/examples/cat.ts /etc/passwd +``` + +### TCP echo server + +This is an example of a simple server which accepts connections on port 8080, +and returns to the client anything it sends. ```ts import { listen, copy } from "deno"; -const listener = listen("tcp", ":8080"); -while (true) { - const conn = await listener.accept(); - copy(conn, conn); -} -// TODO top level await doesn't work yet. + +(async () => { + const addr = "0.0.0.0:8080"; + const listener = listen("tcp", addr); + console.log("listening on", addr); + while (true) { + const conn = await listener.accept(); + copy(conn, conn); + } +})(); +``` + +When this program is started, the user is prompted for permission to listen on +the network: + +``` +> deno https://deno.land/x/examples/echo_server.ts +deno requests network access to "listen". Grant? [yN] y +listening on 0.0.0.0:8080 +``` + +For security reasons, deno does not allow programs to access the network without +explicit permission. To avoid the console prompt, use a command-line flag: + +``` +> deno https://deno.land/x/examples/echo_server.ts --allow-net +``` + +To test it, try sending a HTTP request to it by using curl. The request gets +written directly back to the client. + ``` +> curl http://localhost:8080/ +GET / HTTP/1.1 +Host: localhost:8080 +User-Agent: curl/7.54.0 +Accept: */* +``` + +It's worth noting that like the `cat.ts` example, the `copy()` function here +also does not make unnecessary memory copies. It receives a packet from the +kernel and sends back, without further complexity. + +### Linking to third party code -### Example: Url imports +In the above examples, we saw that Deno could execute scripts from URLs. Like +browser JavaScript, Deno can import libraries directly from URLs. This example +uses a URL to import a test runner library: ```ts -import { printHello } from "https://raw.githubusercontent.com/denoland/deno/master/tests/subdir/print_hello.ts"; -printHello(); +import { test, assertEqual } from "https://deno.land/x/testing/testing.ts"; + +test(function t1() { + assertEqual("hello", "hello"); +}); + +test(function t2() { + assertEqual("world", "world"); +}); +``` + +Try running this: + +``` +> deno https://deno.land/x/examples/example_test.ts +Compiling /Users/rld/src/deno_examples/example_test.ts +Downloading https://deno.land/x/testing/testing.ts +Downloading https://deno.land/x/testing/util.ts +Compiling https://deno.land/x/testing/testing.ts +Compiling https://deno.land/x/testing/util.ts +running 2 tests +test t1 +... ok +test t2 +... ok + +test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out ``` -The next time you import the same file from same uri it will use the cached -resource instead of downloading it again. +Note that we did not have to provide the `--allow-net` flag for this program, +and yet it accessed the network. The runtime has special access to download +imports and cache them to disk. + +Deno caches remote imports in a special directory specified by the `$DENO_DIR` +environmental variable. It default to `$HOME/.deno` if `$DENO_DIR` is not +specified. The next time you run the program, no downloads will be made. If the +program hasn't changed, it won't be recompiled either. + +**But what if `https://deno.land/` goes down?** Relying on external servers is +convenient for development but brittle in production. Production software should +always bundle its dependencies. In Deno this is done by checking the `$DENO_DIR` +into your source control system, and specifying that path as the `$DENO_DIR` +environmental variable at runtime. + +**How do you import to a specific version?** Simply specify the version in the +URL. For example, this URL fully specifies the code being run: +`https://unpkg.com/liltest@0.0.5/dist/liltest.js`. Combined with the +aforementioned technique of setting `$DENO_DIR` in production to stored code, +one can fully specify the exact code being run, and execute the code without +network access. + +**It seems unwieldy to import URLs everywhere. What if one of the URLs links to +a subtly different version of a library? Isn't it error prone to maintain URLs +everywhere in a large project?** The solution is to import and re-export your +external libraries in a central `package.ts` file (which serves the same purpose +as Node's `package.json` file). For example, let's say you were using the above +testing library across a large project. Rather than importing +`"https://deno.land/x/testing/testing.ts"` everywhere, you could create a +`package.ts` file the exports the third-party code: + +```ts +export { test, assertEqual } from "https://deno.land/x/testing/testing.ts"; +``` -## How to Profile Deno +And throughout project one can import from the `package.ts` and avoid having +many references to the same URL: + +```ts +import { test, assertEqual } from "./package.ts"; +``` + +This design circumvents a plethora of complexity spawned by package management +software, centralized code repositories, and superfluous file formates. + +## Useful command line flags + +V8 has many many command-line flags, that you can see with `--v8-options`. Here +are a few particularly useful ones: + +``` +--async-stack-traces +``` + +## How to Profile deno ```sh # Make sure we're only building release. @@ -108,11 +251,11 @@ isolate-0x7fad98242400-v8.log ### Prerequisites: -To ensure reproducible builds, Deno has most of its dependencies in a git +To ensure reproducible builds, deno has most of its dependencies in a git submodule. However, you need to install separately: 1. [Rust](https://www.rust-lang.org/en-US/install.html) -2. [Node](http://nodejs.org/) +2. [Node](https://nodejs.org/) 3. Python 2. [Not 3](https://github.com/denoland/deno/issues/464#issuecomment-411795578). 4. [ccache](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/ccache) @@ -175,7 +318,7 @@ Environment variables: `DENO_BUILD_MODE`, `DENO_BUILD_PATH`, `DENO_BUILD_ARGS`, ### Internal: libdeno API. -Deno's privileged side will primarily be programmed in Rust. However there will +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 @@ -239,9 +382,9 @@ V8's GC will lead to difficult contention problems down the road. The V8Worker2 binding/concept is being ported to a new C++ library called libdeno. libdeno will include the entire JS runtime as a V8 snapshot. It still follows the message passing paradigm. Rust will be bound to this library to -implement the privileged part of Deno. See deno2/README.md for more details. +implement the privileged part of deno. See deno2/README.md for more details. -V8 Snapshots allow Deno to avoid recompiling the TypeScript compiler at startup. +V8 Snapshots allow deno to avoid recompiling the TypeScript compiler at startup. This is already working. When the rewrite is at feature parity with the Go prototype, we will release @@ -253,20 +396,18 @@ https://github.com/denoland/deno/tree/golang https://www.youtube.com/watch?v=M3BM9TB-8yA -http://tinyclouds.org/jsconf2018.pdf +https://tinyclouds.org/jsconf2018.pdf ### 2007-2017 / Prehistory https://github.com/ry/v8worker -http://libuv.org/ +https://libuv.org/ -http://tinyclouds.org/iocp-links.html +https://tinyclouds.org/iocp-links.html https://nodejs.org/ https://github.com/nodejs/http-parser -http://tinyclouds.org/libebb/ - -https://en.wikipedia.org/wiki/Merb +https://tinyclouds.org/libebb/ diff --git a/website/index.html b/website/index.html index f56a312ee..fc69f257b 100644 --- a/website/index.html +++ b/website/index.html @@ -2,20 +2,23 @@ <!DOCTYPE html> <html> <head> - <title>deno</title> + <title>Deno</title> <link rel="stylesheet" href="https://unpkg.com/c3@0.6.7/c3.min.css"> <link rel="stylesheet" href="style.css"> <meta content='width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0' name='viewport' /> </head> <body> <main> - <h1>deno</h1> + <h1>Deno</h1> + + <p>Deno is program for executing JavaScript and TypeScript outside of the + web browser. <p> <a href="https://github.com/denoland/deno">github.com/denoland/deno</a> - <p> <a href="https://github.com/denoland/deno/blob/master/Docs.md">Intro</a> - <p> <a href="typedoc/index.html">TypeScript API</a> - <p> <a href="rustdoc/deno/index.html">Rust API</a> + <p> <a href="https://github.com/denoland/deno/blob/master/Docs.md">Documentation</a> + + <p> <a href="typedoc/index.html">API Reference</a> <h2>Execution time</h2> This shows how much time total it takes to run a few simple deno programs: |