Multi page manual (denoland#5110)

docs/contributing.md

@@ -0,0 +1,60 @@
+# Contributing
+
+- Read the [style guide](style_guide.md).
+- Progress towards future releases is tracked
+  [here](https://github.com/denoland/deno/milestones).
+- Please don't make [the benchmarks](https://deno.land/benchmarks.html) worse.
+- Ask for help in the [community chat room](https://discord.gg/TGMHGv6).
+- If you are going to work on an issue, mention so in the issue comments
+  _before_ you start working on the issue.
+
+## Development
+
+Instructions on how to build from source can be found
+[here](./building-from-source).
+
+## Submitting a Pull Request
+
+Before submitting, please make sure the following is done:
+
+1. That there is a related issue and it is referenced in the PR text.
+2. There are tests that cover the changes.
+3. Ensure `cargo test` passes.
+4. Format your code with `tools/format.py`
+5. Make sure `./tools/lint.py` passes.
+
+## Changes to `third_party`
+
+[`deno_third_party`](https://github.com/denoland/deno_third_party) contains most
+of the external code that Deno depends on, so that we know exactly what we are
+executing at any given time. It is carefully maintained with a mixture of manual
+labor and private scripts. It's likely you will need help from @ry or
+@piscisaureus to make changes.
+
+## Adding Ops (aka bindings)
+
+We are very concerned about making mistakes when adding new APIs. When adding an
+Op to Deno, the counterpart interfaces on other platforms should be researched.
+Please list how this functionality is done in Go, Node, Rust, and Python.
+
+As an example, see how `Deno.rename()` was proposed and added in
+[PR #671](https://github.com/denoland/deno/pull/671).
+
+## Documenting APIs
+
+It is important to document public APIs and we want to do that inline with the
+code. This helps ensure that code and documentation are tightly coupled
+together.
+
+### Utilize JSDoc
+
+All publicly exposed APIs and types, both via the `deno` module as well as the
+global/`window` namespace should have JSDoc documentation. This documentation is
+parsed and available to the TypeScript compiler, and therefore easy to provide
+further downstream. JSDoc blocks come just prior to the statement they apply to
+and are denoted by a leading `/**` before terminating with a `*/`. For example:
+
+```ts
+/** A simple JSDoc comment */
+export const FOO = "foo";
+```

docs/contributing/architecture.md

@@ -0,0 +1,50 @@
+## Internal details
+
+### Deno and Linux analogy
+
+|                       **Linux** | **Deno**                         |
+| ------------------------------: | :------------------------------- |
+|                       Processes | Web Workers                      |
+|                        Syscalls | Ops                              |
+|           File descriptors (fd) | [Resource ids (rid)](#resources) |
+|                       Scheduler | Tokio                            |
+| Userland: libc++ / glib / boost | https://deno.land/std/           |
+|                 /proc/\$\$/stat | [Deno.metrics()](#metrics)       |
+|                       man pages | deno types                       |
+
+#### Resources
+
+Resources (AKA `rid`) are Deno's version of file descriptors. They are integer
+values used to refer to open files, sockets, and other concepts. For testing it
+would be good to be able to query the system for how many open resources there
+are.
+
+```ts
+const { resources, close } = Deno;
+console.log(resources());
+// { 0: "stdin", 1: "stdout", 2: "stderr" }
+close(0);
+console.log(resources());
+// { 1: "stdout", 2: "stderr" }
+```
+
+#### Metrics
+
+Metrics is Deno's internal counter for various statistics.
+
+```shell
+> console.table(Deno.metrics())
+┌──────────────────┬────────┐
+│     (index)      │ Values │
+├──────────────────┼────────┤
+│  opsDispatched   │   9    │
+│   opsCompleted   │   9    │
+│ bytesSentControl │  504   │
+│  bytesSentData   │   0    │
+│  bytesReceived   │  856   │
+└──────────────────┴────────┘
+```
+
+### Schematic diagram
+
+![architectural schematic](https://deno.land/images/schematic_v0.2.png)

docs/contributing/building_from_source.md

@@ -0,0 +1,89 @@
+## Building from source
+
+Below are instructions on how to build Deno from source. If you just want to use
+Deno you can download a prebuilt executable (more information in the
+`Getting Started` chapter).
+
+### Cloning the Repository
+
+Clone on Linux or Mac:
+
+```bash
+git clone --recurse-submodules https://github.com/denoland/deno.git
+```
+
+Extra steps for Windows users:
+
+1. [Enable "Developer Mode"](https://www.google.com/search?q=windows+enable+developer+mode)
+   (otherwise symlinks would require administrator privileges).
+2. Make sure you are using git version 2.19.2.windows.1 or newer.
+3. Set `core.symlinks=true` before the checkout:
+   ```bash
+   git config --global core.symlinks true
+   git clone --recurse-submodules https://github.com/denoland/deno.git
+   ```
+
+### Prerequisites
+
+The easiest way to build Deno is by using a precompiled version of V8:
+
+```
+cargo build -vv
+```
+
+However if you want to build Deno and V8 from source code:
+
+```
+V8_FROM_SOURCE=1 cargo build -vv
+```
+
+When building V8 from source, there are more dependencies:
+
+[Python 2](https://www.python.org/downloads). Ensure that a suffix-less
+`python`/`python.exe` exists in your `PATH` and it refers to Python 2,
+[not 3](https://github.com/denoland/deno/issues/464#issuecomment-411795578).
+
+For Linux users glib-2.0 development files must also be installed. (On Ubuntu,
+run `apt install libglib2.0-dev`.)
+
+Mac users must have [XCode](https://developer.apple.com/xcode/) installed.
+
+For Windows users:
+
+1. Get [VS Community 2019](https://www.visualstudio.com/downloads/) with
+   "Desktop development with C++" toolkit and make sure to select the following
+   required tools listed below along with all C++ tools.
+
+   - Visual C++ tools for CMake
+   - Windows 10 SDK (10.0.17763.0)
+   - Testing tools core features - Build Tools
+   - Visual C++ ATL for x86 and x64
+   - Visual C++ MFC for x86 and x64
+   - C++/CLI support
+   - VC++ 2015.3 v14.00 (v140) toolset for desktop
+
+2. Enable "Debugging Tools for Windows". Go to "Control Panel" → "Programs" →
+   "Programs and Features" → Select "Windows Software Development Kit - Windows
+   10" → "Change" → "Change" → Check "Debugging Tools For Windows" → "Change" ->
+   "Finish". Or use:
+   [Debugging Tools for Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/)
+   (Notice: it will download the files, you should install
+   `X64 Debuggers And Tools-x64_en-us.msi` file manually.)
+
+See [rusty_v8's README](https://github.com/denoland/rusty_v8) for more details
+about the V8 build.
+
+### Building
+
+Build with Cargo:
+
+```bash
+# Build:
+cargo build -vv
+
+# Build errors?  Ensure you have latest master and try building again, or if that doesn't work try:
+cargo clean && cargo build -vv
+
+# Run:
+./target/debug/deno cli/tests/002_hello.ts
+```

docs/contributing/development_tools.md

@@ -0,0 +1,171 @@
+## Testing and Tools
+
+### Tests
+
+Test `deno`:
+
+```bash
+# Run the whole suite:
+cargo test
+
+# Only test cli/js/:
+cargo test js_unit_tests
+```
+
+Test `std/`:
+
+```bash
+cargo test std_tests
+```
+
+### Lint and format
+
+Lint the code:
+
+```bash
+./tools/lint.py
+```
+
+Format the code:
+
+```bash
+./tools/format.py
+```
+
+### Profiling
+
+To start profiling,
+
+```sh
+# Make sure we're only building release.
+# Build deno and V8's d8.
+ninja -C target/release d8
+
+# Start the program we want to benchmark with --prof
+./target/release/deno run tests/http_bench.ts --allow-net --v8-flags=--prof &
+
+# Exercise it.
+third_party/wrk/linux/wrk http://localhost:4500/
+kill `pgrep deno`
+```
+
+V8 will write a file in the current directory that looks like this:
+`isolate-0x7fad98242400-v8.log`. To examine this file:
+
+```sh
+D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor
+isolate-0x7fad98242400-v8.log > prof.log
+# on macOS, use ./third_party/v8/tools/mac-tick-processor instead
+```
+
+`prof.log` will contain information about tick distribution of different calls.
+
+To view the log with Web UI, generate JSON file of the log:
+
+```sh
+D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor
+isolate-0x7fad98242400-v8.log --preprocess > prof.json
+```
+
+Open `third_party/v8/tools/profview/index.html` in your browser, and select
+`prof.json` to view the distribution graphically.
+
+Useful V8 flags during profiling:
+
+- --prof
+- --log-internal-timer-events
+- --log-timer-events
+- --track-gc
+- --log-source-code
+- --track-gc-object-stats
+
+To learn more about `d8` and profiling, check out the following links:
+
+- [https://v8.dev/docs/d8](https://v8.dev/docs/d8)
+- [https://v8.dev/docs/profile](https://v8.dev/docs/profile)
+
+### Debugging with LLDB
+
+We can use LLDB to debug Deno.
+
+```shell
+$ lldb -- target/debug/deno run tests/worker.js
+> run
+> bt
+> up
+> up
+> l
+```
+
+To debug Rust code, we can use `rust-lldb`. It should come with `rustc` and is a
+wrapper around LLDB.
+
+```shell
+$ rust-lldb -- ./target/debug/deno run --allow-net tests/http_bench.ts
+# On macOS, you might get warnings like
+# `ImportError: cannot import name _remove_dead_weakref`
+# In that case, use system python by setting PATH, e.g.
+# PATH=/System/Library/Frameworks/Python.framework/Versions/2.7/bin:$PATH
+(lldb) command script import "/Users/kevinqian/.rustup/toolchains/1.36.0-x86_64-apple-darwin/lib/rustlib/etc/lldb_rust_formatters.py"
+(lldb) type summary add --no-value --python-function lldb_rust_formatters.print_val -x ".*" --category Rust
+(lldb) type category enable Rust
+(lldb) target create "../deno/target/debug/deno"
+Current executable set to '../deno/target/debug/deno' (x86_64).
+(lldb) settings set -- target.run-args  "tests/http_bench.ts" "--allow-net"
+(lldb) b op_start
+(lldb) r
+```
+
+### V8 flags
+
+V8 has many many internal command-line flags.
+
+```shell
+# list available v8 flags
+$ deno --v8-flags=--help
+
+#  example for applying multiple flags
+$ deno --v8-flags=--expose-gc,--use-strict
+```
+
+Particularly useful ones:
+
+```
+--async-stack-trace
+```
+
+### Continuous Benchmarks
+
+See our benchmarks [over here](https://deno.land/benchmarks)
+
+The benchmark chart supposes
+https://github.com/denoland/benchmark_data/data.json has the type
+`BenchmarkData[]` where `BenchmarkData` is defined like the below:
+
+```ts
+interface ExecTimeData {
+  mean: number;
+  stddev: number;
+  user: number;
+  system: number;
+  min: number;
+  max: number;
+}
+
+interface BenchmarkData {
+  created_at: string;
+  sha1: string;
+  benchmark: {
+    [key: string]: ExecTimeData;
+  };
+  binarySizeData: {
+    [key: string]: number;
+  };
+  threadCountData: {
+    [key: string]: number;
+  };
+  syscallCountData: {
+    [key: string]: number;
+  };
+}
+```

docs/embedding_deno.md

@@ -0,0 +1,11 @@
+# Embedding Deno
+
+Deno consists of multiple parts, one of which is `deno_core`. This is a rust
+crate that can be used to embed a JavaScript runtime into your rust application.
+Deno is built on top of `deno_core`.
+
+The Deno crate is hosted on [crates.io](https://crates.io/crates/deno_core).
+
+You can view the API on [docs.rs](https://docs.rs/deno_core).
+
+<!-- TODO(lucacasonato): better docs -->

docs/examples.md

@@ -0,0 +1,4 @@
+# Examples
+
+In this chapter you can find some example programs that you can use to learn
+more about the runtime.