denoland-deno/Docs.md

# Deno Docs

## Install

Deno works on OSX, Linux, and Windows. We provide binary download scripts:

With 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:

```powershell
iex (iwr https://raw.githubusercontent.com/denoland/deno_install/master/install.ps1)
```

_Note: Depending on your security settings, you may have to run
`Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` first to allow downloaded
scripts to be executed._

Try it:

```
> deno http://deno.land/thumb.ts
```

## API Reference

To get an exact reference of deno's runtime API, run the following in the
command line:

```
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

(We do not yet have an HTML version of this. See
https://github.com/denoland/deno/issues/573)

## Examples

### Example: An implementation of the unix "cat" program

The copy here is actualy zero-copy. That is, it reads data from the socket and
writes it back to it without ever calling a memcpy() or similiar.

```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);
}
```

### Example: A TCP Server echo server

The copy here is actualy zero-copy. That is, it reads data from the socket and
writes it back to it without ever calling a memcpy() or similiar.

```ts
import { listen, accept, copy } from "deno";
const listener = listen("tcp", ":8080");
while (true) {
  const conn = await listener.accept();
  deno.copy(conn, conn);
}
// TODO top level await doesn't work yet.
```

## How to Profile Deno.

```sh
# Make sure we're only building release.
export DENO_BUILD_MODE=release
# Build deno and V8's d8.
./tools/build.py d8 deno
# Start the program we want to benchmark with --prof
./out/release/deno tests/http_bench.ts --allow-net --prof &
# Exercise it.
third_party/wrk/linux/wrk http://localhost:4500/
kill `pgrep deno`
# When supplying --prof, V8 will write a file in the current directory that
# looks like this isolate-0x7fad98242400-v8.log
# To examine this file
D8_PATH=out/release/ ./third_party/v8/tools/linux-tick-processor
isolate-0x7fad98242400-v8.log
```

## Build instructions (for advanced users only)

### Prerequisists:

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/)
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)
   (Optional but helpful for speeding up rebuilds of V8.).
5. Extra steps for Windows users:
   1. Add `python.exe` to `PATH`. E.g. `set PATH=%PATH%;C:\Python27\python.exe`
   2. Get [VS Community 2017](https://www.visualstudio.com/downloads/), make
      sure to select the option to install C++ tools and the Windows SDK
   3. Enable `Debugging Tools for Windows`, Goto Control Panel -> Windows 10 SDK
      -> Right-Click -> Change -> Change -> Check Debugging Tools for Windows ->
      Change -> Finish
6. Before running `./tools/format.py`, make sure you have `yapf` installed for
   the current Python and `rustfmt` for Rust. They can be installed by:

   pip install yapf rustup component add rustfmt-preview

### Build:

    # Fetch deps.
    git clone --recurse-submodules https://github.com/denoland/deno.git
    cd deno
    ./tools/setup.py

    # Build.
    ./tools/build.py

    # Run.
    ./out/debug/deno tests/002_hello.ts

    # Test.
    ./tools/test.py

    # Format code.
    ./tools/format.py

Other useful commands:

    # Call ninja manually.
    ./third_party/depot_tools/ninja -C out/debug

    # Build a release binary.
    DENO_BUILD_MODE=release ./tools/build.py :deno

    # List executable targets.
    ./third_party/depot_tools/gn ls out/debug //:* --as=output --type=executable

    # List build configuation.
    ./third_party/depot_tools/gn args out/debug/ --list

    # Edit build configuration.
    ./third_party/depot_tools/gn args out/debug/

    # Describe a target.
    ./third_party/depot_tools/gn desc out/debug/ :deno
    ./third_party/depot_tools/gn help

Env vars: `DENO_BUILD_MODE`, `DENO_BUILD_PATH`, `DENO_BUILD_ARGS`, `DENO_DIR`.

## Internals

### Interal: libdeno API.

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:
https://github.com/denoland/deno/blob/master/libdeno/deno.h
https://github.com/denoland/deno/blob/master/js/libdeno.ts

### Internal: Flatbuffers provide shared data between Rust and V8

We use Flatbuffers to define common structs and enums between TypeScript and
Rust. These common data structures are defined in
https://github.com/denoland/deno/blob/master/src/msg.fbs

## Contributing

See
[CONTRIBUTING.md](https://github.com/denoland/deno/blob/master/.github/CONTRIBUTING.md).

## Change Log

### 2018.10.18 / v0.1.8 / Connecting to Tokio / Fleshing out APIs

Most file system ops were implemented. Basic TCP networking is implemented.
Basic stdio streams exposed. And many random OS facilities were exposed (e.g.
environmental variables)

Tokio was chosen as the backing event loop library. A careful mapping of JS
Promises onto Rust Futures was made, preserving error handling and the ability
to execute synchronously in the main thread.

Continuous benchmarks were added: https://denoland.github.io/deno/ Performance
issues are beginning to be addressed.

"deno --types" was added to reference runtime APIs.

Working towards https://github.com/denoland/deno/milestone/2 We expect v0.2 to
be released in last October or early November.

### 2018.09.09 / v0.1.3 / Scale binding infrastructure

ETA v.0.2 October 2018 https://github.com/denoland/deno/milestone/2

We decided to use Tokio https://tokio.rs/ to provide asynchronous I/O, thread
pool execution, and as a base for high level support for various internet
protocols like HTTP. Tokio is strongly designed around the idea of Futures -
which map quite well onto JavaScript promises. We want to make it as easy as
possible to start a Tokio future from JavaScript and get a Promise for handling
it. We expect this to result in preliminary file system operations, fetch() for
http. Additionally we are working on CI, release, and benchmarking
infrastructure to scale development.

### 2018.08.23 / v0.1.0 / Rust rewrite / V8 snapshot

https://github.com/denoland/deno/commit/68d388229ea6ada339d68eb3d67feaff7a31ca97

Complete! https://github.com/denoland/deno/milestone/1

Go is a garbage collected language and we are worried that combining it with
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.

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
binaries for people to try.

### 2018.09.32 / v0.0.0 / Golang Prototype / JSConf talk

https://github.com/denoland/deno/tree/golang

https://www.youtube.com/watch?v=M3BM9TB-8yA

http://tinyclouds.org/jsconf2018.pdf

### 2007-2017 / Prehistory

https://github.com/ry/v8worker

http://libuv.org/

http://tinyclouds.org/iocp-links.html

https://nodejs.org/

https://github.com/nodejs/http-parser

http://tinyclouds.org/libebb/

https://en.wikipedia.org/wiki/Merb