Merge remote-tracking branch 'upstream/master' into dev-master-merged

.vscode/tasks.json

@@ -3,6 +3,24 @@
     // for the documentation about the tasks.json format
 	  "version": "2.0.0",
 	  "tasks": [
+		{
+			"label": "Compile",
+			"type": "shell",
+			"command": "${workspaceFolder}/bin/troupec -v ${file}",
+			"group": {
+				"kind": "build",
+				"isDefault": true
+			},
+			"presentation": {
+				"echo": true,
+				"reveal": "always",
+				"focus": false,
+				"panel": "shared",
+				"showReuseMessage": true,
+				"clear": false
+			},
+			"problemMatcher": []
+		},
 		{
 			"label": "Run local",
 			"type": "shell",

README.md

@@ -9,19 +9,21 @@ If you want to try out Troupe without manual installation (e.g., for a class exe
 
 ## Installation
 
+Once all dependencies have been installed, the whole project can be built and Troupe installed to the `bin` directory with `make all`. The following shows step-by-step which dependencies are needed for which parts and how to install them.
 
 ### Step 1. Install JS runtime
 1. Install NodeJS (e.g. `sudo apt-get install nodejs`)
 2. Get [yarn](https://yarnpkg.com/lang/en/) package manager (e.g. `npm install --global yarn`)
 3. Install js dependencies via `yarn install`
-4. Apply local js patches to the dependencies via `yarn patch-package`
+4. Apply local js patches to the dependencies via `yarn patch-package` (might already be executed by `yarn install`)
 5. Set the `TROUPE` environment variable to point to the folder that contains this README. In bash this is done by adding the following lines to a file such as `~/.bashrc` or `~/.bash_profile`:
    ```
    TROUPE=<path to the installation directory>
    export TROUPE=<path to the installation directory>
    ```
    Read <a href="https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-a-linux-vps"> here</a> for more info on environment variables.
 6. Install [TypeScript](https://www.typescriptlang.org/): `npm install -g typescript`
+   - To install to the home directory without root, first run `npm config set prefix ~/.npm` and add `~/.npm/bin` to your PATH
 7. Compile Troupe runtime by typing `make rt`
 
 ### Step 2. Install Troupe compiler
@@ -40,7 +42,10 @@ Type `make stack` (in the repository's root) to compile Troupe's bin scripts
 
 ### Step 4. Install Troupe standard library
 
-Type `make libs` to compile Troupe's built-in libraries, and `make service` to compile the service module placeholder.
+Type
+
+- `make libs` to compile Troupe's built-in libraries, and
+- `make service` to compile the service module placeholder.
 
 
 ### Step 5. Running the test suite
@@ -92,6 +97,13 @@ This will allow to develop on a remote machine, using VSCode on a local machine
 Now, when having opened the `compiler` folder, the Haskell Language Server should highlight errors and hints, support "Go to definition" and more.
 
 
+#### Syntax support for Troupe files
+
+As Troupe syntax is similar to SML, installing the [SML Environment](https://marketplace.visualstudio.com/items?itemName=vrjuliao.sml-environment) extension is useful. It adds syntax highlighting, some identation support and support for commenting with editor commands.
+
+Use `Ctrl-k m` ("Change language mode") to set the current file's language mode to SML. The suggestions will also allow to generally associate `.trp` files with SML mode.
+
+
 #### Building and running
 
 - **Building the compiler:** When having opened the `compiler` folder, there is a task "Build all", which is set as the default build task, so running "Run build task" (Ctrl-F9) should execute it.
@@ -108,6 +120,20 @@ Now, when having opened the `compiler` folder, the Haskell Language Server shoul
 The current user guide is accessible [here](https://troupe.cs.au.dk/userguide.pdf).
 
 ## Building and running
+### Building
+
+The following commands build specific parts of the project and install the results to the `bin`, `rt/built` and `lib` directories.
+
+- `make all`: build everything (use this whenever significant changes have been made to the project, to be sure that everything is up-to-date)
+- `make` / `make stack`: build the compiler
+- `make rt`: build the runtime (into the `rt/built` directory)
+- `make libs`: compile Troupe's built-in libraries (into the `lib` directory)
+- `make service` compile the service module placeholder
+
+### Tests
+
+- `make test` to run all tests
+- `bin/golden` to run the test suite with options
 
 ### Running examples that do not require network
 
@@ -117,7 +143,8 @@ infrastructure or key generation (which otherwise takes a few seconds).
 
 ### Building and naming the snapshot
 
-Script `build.sh` runs `make` and copies the executables to `../bin/<current git HEAD hash>`.
+Script `dev-utils/build.sh` runs `make` and copies the executables to `../bin/<current git HEAD hash>`.
+This is useful when wanting to compile some snapshots to compare how different versions behave.
 
 ## Networking
 

dev-utils/build-snapshot.sh

@@ -0,0 +1,8 @@
+# Builds and copies the executables to bin/<current git HEAD hash>
+# This is useful when wanting to compile some snapshots to compare how different versions behave.
+make
+echo ""
+dir="bin/$(git describe --long --dirty --always)"
+mkdir -p $dir
+cp bin/* $dir 2>/dev/null
+echo "Copied executables to $dir"

tests/rt/pos/core/funarg-shadow01.golden

@@ -0,0 +1,2 @@
+2023-03-10T08:32:11.371Z [RTM] info: Skipping network creation. Observe that all external IO operations will yield a runtime error.
+>>> Main thread finished with value: 2@{}%{}

tests/rt/pos/core/funarg-shadow01.trp

@@ -0,0 +1,3 @@
+let fun f x x = x in
+  f 1 2
+end

tests/rt/pos/core/funarg-shadow02.golden

@@ -0,0 +1,2 @@
+2023-03-10T08:32:11.371Z [RTM] info: Skipping network creation. Observe that all external IO operations will yield a runtime error.
+>>> Main thread finished with value: 3@{}%{}

tests/rt/pos/core/funarg-shadow02.trp

@@ -0,0 +1,3 @@
+let fun f x y x = x in
+  f 1 2 3
+end