diff options
Diffstat (limited to 'docs/contributing')
| -rw-r--r-- | docs/contributing/architecture.md | 50 | ||||
| -rw-r--r-- | docs/contributing/building_from_source.md | 89 | ||||
| -rw-r--r-- | docs/contributing/development_tools.md | 171 | ||||
| -rw-r--r-- | docs/contributing/profiling.md | 0 |
4 files changed, 310 insertions, 0 deletions
diff --git a/docs/contributing/architecture.md b/docs/contributing/architecture.md new file mode 100644 index 000000000..0a1ba3b4d --- /dev/null +++ b/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 + + diff --git a/docs/contributing/building_from_source.md b/docs/contributing/building_from_source.md new file mode 100644 index 000000000..fb1e1ef2c --- /dev/null +++ b/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 +``` diff --git a/docs/contributing/development_tools.md b/docs/contributing/development_tools.md new file mode 100644 index 000000000..35bd5a5fb --- /dev/null +++ b/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; + }; +} +``` diff --git a/docs/contributing/profiling.md b/docs/contributing/profiling.md new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/docs/contributing/profiling.md |