From 26a1abfea8cd4372e4dd7bec698a8c5bf6caada9 Mon Sep 17 00:00:00 2001 From: Jan Van Bruggen Date: Wed, 7 Sep 2022 22:07:00 -0600 Subject: [PATCH] Add blank lines around lists See https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md032 --- .markdownlint-cli2.yaml | 1 - BUILDING_FROM_SOURCE.md | 2 ++ README.md | 1 + TUTORIAL.md | 5 +++++ crates/compiler/builtins/README.md | 1 + crates/compiler/builtins/bitcode/README.md | 1 + crates/compiler/gen_wasm/README.md | 2 ++ crates/editor/README.md | 4 ++++ crates/editor/editor-ideas.md | 1 + crates/editor/snippet-ideas.md | 1 + devtools/README.md | 2 ++ 11 files changed, 20 insertions(+), 1 deletion(-) diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 17524c4f2c..aad1835071 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -1,5 +1,4 @@ config: - blanks-around-lists: false commands-show-output: false emphasis-style: false fenced-code-language: false diff --git a/BUILDING_FROM_SOURCE.md b/BUILDING_FROM_SOURCE.md index c44abea950..a4806a3452 100644 --- a/BUILDING_FROM_SOURCE.md +++ b/BUILDING_FROM_SOURCE.md @@ -15,6 +15,7 @@ On Macos and Linux, we highly recommend Using [nix](https://nixos.org/download.h If you are running ArchLinux or a derivative like Manjaro, you'll need to run `sudo sysctl -w kernel.unprivileged_userns_clone=1` before installing nix. Install nix (not necessary on NixOS): + - If you are using WSL (Windows subsystem for Linux): ``` @@ -119,6 +120,7 @@ sudo apt-get install libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev For any OS, you can use [`zigup`](https://github.com/marler8997/zigup) to manage zig installations. If you prefer a package manager, you can try the following: + - For MacOS, you can install with `brew install zig` - For, Ubuntu, you can use Snap, you can install with `snap install zig --classic --beta` - For other systems, checkout this [page](https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager) diff --git a/README.md b/README.md index 302467d347..8b858b9017 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # Work in progress! Roc is not ready for a 0.1 release yet, but we do have: + - [**installation** guide](https://github.com/roc-lang/roc/tree/main/getting_started) - [**tutorial**](https://github.com/roc-lang/roc/blob/main/TUTORIAL.md) - [frequently asked questions](https://github.com/roc-lang/roc/blob/main/FAQ.md) diff --git a/TUTORIAL.md b/TUTORIAL.md index fa058e5f88..10f618571d 100644 --- a/TUTORIAL.md +++ b/TUTORIAL.md @@ -165,6 +165,7 @@ There are 5 animals. short - namely, `main`, `birds`, `iguanas`, and `total`. A definition names an expression. + - The first def assigns the name `main` to the expression `Stdout.line "I have \(numDefs) definitions."`. The `Stdout.line` function takes a string and prints it as a line to [`stdout`] (the terminal's standard output device). - The next two defs assign the names `birds` and `iguanas` to the expressions `3` and `2`. - The last def assigns the name `total` to the expression `Num.toStr (birds + iguanas)`. @@ -231,6 +232,7 @@ addAndStringify = \num1, num2 -> ``` We did two things here: + * We introduced a local def named `sum`, and set it equal to `num1 + num2`. Because we defined `sum` inside `addAndStringify`, it will not be accessible outside that function. * We added an `if` / `then` / `else` conditional to return either `""` or `Num.toStr sum` depending on whether `sum == 0`. @@ -1524,11 +1526,13 @@ main = ``` This way, it reads like a series of instructions: + 1. First, run the `Stdout.line` task and await its completion. Ignore its output (hence the underscore in `_ <-`) 2. Next, run the `Stdin.line` task and await its completion. Name its output `text`. 3. Finally, run the `Stdout.line` task again, using the `text` value we got from the `Stdin.line` effect. Some important things to note about backpassing and `await`: + * `await` is not a language keyword in Roc! It's referring to the `Task.await` function, which we imported unqualified by writing `Task.{ await }` in our module imports. (That said, it is playing a similar role here to the `await` keyword in languages that have `async`/`await` keywords, even though in this case it's a function instead of a special keyword.) * Backpassing syntax does not need to be used with `await` in particular. It can be used with any function. * Roc's compiler treats functions defined with backpassing exactly the same way as functions defined the other way. The only difference between `\text ->` and `text <-` is how they look, so feel free to use whichever looks nicer to you! @@ -1608,6 +1612,7 @@ addHttps = \record -> ``` This function uses *constrained records* in its type. The annotation is saying: + * This function takes a record which has at least a `url` field, and possibly others * That `url` field has the type `Str` * It returns a record of exactly the same type as the one it was given diff --git a/crates/compiler/builtins/README.md b/crates/compiler/builtins/README.md index 274f46ed5c..e5d03c1e7a 100644 --- a/crates/compiler/builtins/README.md +++ b/crates/compiler/builtins/README.md @@ -21,6 +21,7 @@ Towards the bottom of `symbol.rs` there is a `define_builtins!` macro being used Some of these have `#` inside their name (`first#list`, `#lt` ..). This is a trick we are doing to hide implementation details from Roc programmers. To a Roc programmer, a name with `#` in it is invalid, because `#` means everything after it is parsed to a comment. We are constructing these functions manually, so we are circumventing the parsing step and dont have such restrictions. We get to make functions and values with `#` which as a consequence are not accessible to Roc programmers. Roc programmers simply cannot reference them. But we can use these values and some of these are necessary for implementing builtins. For example, `List.get` returns tags, and it is not easy for us to create tags when composing LLVM. What is easier however, is: + - ..writing `List.#getUnsafe` that has the dangerous signature of `List elem, Nat -> elem` in LLVM - ..writing `List elem, Nat -> Result elem [OutOfBounds]*` in a type safe way that uses `getUnsafe` internally, only after it checks if the `elem` at `Nat` index exists. diff --git a/crates/compiler/builtins/bitcode/README.md b/crates/compiler/builtins/bitcode/README.md index 1585c2e8fb..5c2d1acf87 100644 --- a/crates/compiler/builtins/bitcode/README.md +++ b/crates/compiler/builtins/bitcode/README.md @@ -3,6 +3,7 @@ ## Adding a bitcode builtin To add a builtin: + 1. Add the function to the relevant module. For `Num` builtin use it in `src/num.zig`, for `Str` builtins use `src/str.zig`, and so on. **For anything you add, you must add tests for it!** Not only does to make the builtins more maintainable, it's the the easiest way to test these functions on Zig. To run the test, run: `zig build test` 2. Make sure the function is public with the `pub` keyword and uses the C calling convention. This is really easy, just add `pub` and `callconv(.C)` to the function declaration like so: `pub fn atan(num: f64) callconv(.C) f64 { ... }` 3. In `src/main.zig`, export the function. This is also organized by module. For example, for a `Num` function find the `Num` section and add: `comptime { exportNumFn(num.atan, "atan"); }`. The first argument is the function, the second is the name of it in LLVM. diff --git a/crates/compiler/gen_wasm/README.md b/crates/compiler/gen_wasm/README.md index b99ff43fca..408843e3d8 100644 --- a/crates/compiler/gen_wasm/README.md +++ b/crates/compiler/gen_wasm/README.md @@ -234,12 +234,14 @@ We implement a few linking operations in the Wasm backend. The most important ar In the host .wasm file, `roc__mainForHost_1_exposed` is defined as a Wasm Import, as if it were an external JavaScript function. But when we link the host and app, we need to make it an internal function instead. There are a few important facts to note about the Wasm binary format: + - Function calls refer to the callee by its function index in the file. - If we move a function from one index to another, all of its call sites need to be updated. So we want to minimise this to make linking fast. - If we _remove_ a function, then all functions above it will implicitly have their indices shifted down by 1! This is not good for speed. We should try to _swap_ rather than remove. - JavaScript imports always get the lower indices. With that background, here are the linking steps for a single app function that gets called by the host: + - Remove `roc__mainForHost_1_exposed` from the imports, updating all call sites to the new index, which is somewhere in the app. - Swap the _last_ JavaScript import into the slot where `roc__mainForHost_1_exposed` was, updating all of its call sites in the host. - Insert an internally-defined dummy function at the index where the last JavaScript import used to be. diff --git a/crates/editor/README.md b/crates/editor/README.md index e4faf28df0..eceb6433ba 100644 --- a/crates/editor/README.md +++ b/crates/editor/README.md @@ -28,6 +28,7 @@ Make sure to [create an issue](https://github.com/roc-lang/roc/issues/new/choose ## Inspiration We thank the following open source projects in particular for inspiring us when designing the Roc editor: + - [learn-wgpu](https://github.com/sotrh/learn-wgpu) - [rgx](https://github.com/cloudhead/rgx) - [elm-editor](https://github.com/jxxcarlson/elm-editor) @@ -40,6 +41,7 @@ This debug view shows important data structures that can be found in `editor/src Add or delete some code to see how these data structures are updated. From roc to render: + - `./roc edit` or `cargo run edit` is first handled in `cli/src/main.rs`, from there the editor's launch function is called (`editor/src/editor/main.rs`). - In `run_event_loop` we initialize the winit window, wgpu, the editor's model(`EdModel`) and start the rendering loop. - The `ed_model` is filled in part with data obtained by loading and typechecking the roc file with the same function (`load_and_typecheck`) that is used by the compiler. @@ -56,6 +58,7 @@ From roc to render: ### Important files To understand how the editor works it is useful to know the most important files: + - editor/src/editor/main.rs - editor/src/editor/mvc/ed_update.rs - editor/src/editor/mvc/ed_model.rs @@ -64,6 +67,7 @@ To understand how the editor works it is useful to know the most important files - editor/src/editor/render_debug.rs Important folders/files outside the editor folder: + - code_markup/src/markup/convert - code_markup/src/markup/nodes.rs - ast/src/lang/core/def diff --git a/crates/editor/editor-ideas.md b/crates/editor/editor-ideas.md index 1e595202eb..acb289a61f 100644 --- a/crates/editor/editor-ideas.md +++ b/crates/editor/editor-ideas.md @@ -56,6 +56,7 @@ e.g. you have a test `calculate_sum_test` that only uses the function `add`, whe * For debugging we should aim for maximal useful observability. For example Rust's enum values can not be easily viewed in the CodeLLDB debugger, you actually need to call a print method that does pattern matching to be able to view useful information. * We previuously discussed recording full traces of programs so they do not have to be re-run multiple times in the debugging process. We should encourage roc developers to experiment with creating debugging representations of this AST+"execution trace", it could lead to some cool stuff. * We previuously mentioned showing expression values next to the code. I think when debugging it would be valuable to focus more on these valuas/data. A possible way to do this would be to create scrollable view(without need to jump between files) of inputs and outputs of user defined functions. Clicking on a function could then show the code with the expression values side by side. Having a good overview of how the values change could make it easy to find where exactly things go wrong. + - (Machine learning) algorithms to extract and show useful information from debug values. - Ability to mark e.g. a specific record field for tracking(filter out the noise) that is being repeatedly updated throughout the program. - Ability to collapse/fold debug output coming from specific line. diff --git a/crates/editor/snippet-ideas.md b/crates/editor/snippet-ideas.md index 822bd8dfb9..d6afe05e24 100644 --- a/crates/editor/snippet-ideas.md +++ b/crates/editor/snippet-ideas.md @@ -96,6 +96,7 @@ Snippets are inserted based on type of value on which the cursor is located. # fuzzy matching some pairs for fuzzy matching unit tests: + - hashmap > Dict - map > map (function), Dict - for > map, mapWithIndex, walk, walkBackwards, zip diff --git a/devtools/README.md b/devtools/README.md index 44c62d148d..d38ed58910 100644 --- a/devtools/README.md +++ b/devtools/README.md @@ -4,6 +4,7 @@ The easiest way to do this is to use another flake for all your dev tools that t Use the flake in this folder that uses your editor of choice as a starting template. If your editor is not listed, feel free to make a PR and add your flake. Further steps: + 1. Copy the flake for your favorite editor to a new folder outside of the roc repo folder. 1. Run `git init` in the new folder. 1. Rename the copied flake to `flake.nix`. @@ -20,6 +21,7 @@ I recommend creating a git repository to save this custom flake. If you use lorri or direnv it is possible to load the dev flake instead of the roc flake. For lorri: + 1. copy the `shell.nix` at the root of this repo to the folder containing your dev tools flake. 1. edit `.envrc` to contain: