dev merge into haz3l-modules, not compiling

.gitattributes

@@ -2,3 +2,16 @@
 # decides that the content is text, its line endings are converted to LF on
 # checkin. When the file has been committed with CRLF, no conversion is done.
 * text=auto
+
+
+# Mark generated code and documentation as such to exclude them from PR diffs and stats.
+# More information: https://github.com/github-linguist/linguist/blob/master/docs/overrides.md#generated-code
+src/haz3lweb/Init.ml linguist-generated
+src/haz3lweb/exercises/**/*.ml linguist-generated
+
+hazel.opam linguist-generated
+hazel.opam.locked linguist-generated
+
+*.md linguist-documentation
+docs/** linguist-documentation
+

.github/workflows/deploy_branches.yml

@@ -16,55 +16,42 @@ jobs:
           path: source
       - name: Add the name of the current branch to the environment as BRANCH_NAME
         uses: nelonoel/[email protected]
-      - name: Retrieve the build environment if cached
-        id: opam-cache
-        uses: actions/cache@v2
-        with:
-          path: '/home/runner/.opam/'
-          key: ${{ runner.os }}-modules-${{ hashFiles('./source/opam.export') }}
       - name: Set-up OCaml
-        run: |
-          sudo apt --assume-yes install curl m4 opam
-          export OPAMYES=1
-          opam init --compiler=ocaml-base-compiler.5.0.0
+        uses: ocaml/setup-ocaml@v3
+        with:
+          ocaml-compiler: 5.2.0
+          dune-cache: true
+      - name: Retrieve the switch environment if cached
+        id: opam-cache-switch
+        uses: actions/cache@v4
+        with:
+          path: '_opam'
+          key: ${{ runner.os }}-modules-${{ hashFiles('./source/hazel.opam.locked') }}
       - name: Install dependencies
         run: |
           eval $(opam env)
           export OPAMYES=1
-          make deps 
+          export DUNE_CACHE=enabled
+          opam install . --deps-only --with-test --locked
         working-directory: ./source
-      - name: Build Hazel
+      - name: Clean opam switch
         run: |
           eval $(opam env)
-          make release
-        working-directory: ./source
-      - name: Run Tests
-        id: test
-        continue-on-error: true
+          export OPAMYES=1
+          opam clean --all-switches --download-cache --logs --repo-cache --unused-repositories
+      - name: Build Release
         run: |
-          eval $(opam env)
-          make test > test_output
-          if [ $? -eq 0 ]; then
-            echo "::set-output name=tests_passed::true"
-          else
-            echo "::set-output name=tests_passed::false"
-          fi
+          export DUNE_CACHE=enabled
+          opam exec -- dune build @src/fmt --auto-promote src --profile release
         working-directory: ./source
-      - name: Test Report
-        uses: dorny/test-reporter@v1
-        continue-on-error: true
-        with:
-          name: Test Report
-          path: junit_tests*.xml
-          reporter: java-junit
-          fail-on-error: true
-          working-directory: ./source
       - name: Checkout the website build artifacts repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
         with:
           repository: hazelgrove/build
           token: ${{ secrets.ACCESS_TOKEN }}
           path: server
+          sparse-checkout: |
+            ${{ env.BRANCH_NAME }}
       - name: Clear any old build of this branch
         run: if [ -d "${BRANCH_NAME}" ] ; then rm -rf "${BRANCH_NAME}" ; fi 
         working-directory: ./server
@@ -78,4 +65,19 @@ jobs:
           git pull --no-edit
           git status
           git diff-index --quiet HEAD || (git commit -m "github-deploy-action-${BRANCH_NAME}"; git push)
-        working-directory: ./server
+        working-directory: ./server
+      - name: Run Tests
+        id: test
+        run: |
+          eval $(opam env)
+          make test
+        working-directory: ./source
+      - name: Test Report
+        uses: dorny/test-reporter@v1
+        with:
+          name: Test Report
+          path: junit_tests*.xml
+          reporter: java-junit
+          fail-on-error: true
+          fail-on-empty: true # Use an empty test report to detect when something failed with the test runner
+          working-directory: ./source

.gitignore

@@ -53,3 +53,6 @@ setup.log
 
 # unit tests
 *.xml
+
+# Backup of opam lock file
+hazel.opam.locked.old

INSTALL.md

@@ -119,16 +119,16 @@ follow these instructions instead of the shorter instructions in the
   opam update
   ```
 
-- Install OCaml 5.0.0 (some older versions may also work; see the
+- Install OCaml 5.2.0 (some older versions may also work; see the
   ["Current version" section of `Updating.md`](docs/Updating-OCaml-Version.md) for
   why we may not use the newest version of OCaml).
 
   ```sh
-   opam switch create 5.0.0 ocaml-base-compiler.5.0.0
+   opam switch create 5.2.0 ocaml-base-compiler.5.2.0
   ```
 - Update the current switch environment
   ```sh
-  eval $(opam env --switch=5.0.0)
+  eval $(opam env --switch=5.2.0)
   ```
 ## Clone the Source Code
 

Makefile

@@ -8,23 +8,28 @@ all: dev
 
 deps:
 	opam update
-	opam switch import opam.export
+	opam install ./hazel.opam.locked --deps-only --with-test --with-doc
 
 change-deps:
-	opam switch export opam.export
+	opam update
+	dune build hazel.opam
+	opam install ./hazel.opam --deps-only --with-test --with-doc
+	opam lock .
+	sed -i'.old' '/host-/d' hazel.opam.locked  # remove host- lines which are arch-specific. Not using -i '' because of portability issues https://stackoverflow.com/questions/4247068/sed-command-with-i-option-failing-on-mac-but-works-on-linux
 
 setup-instructor:
 	cp src/haz3lweb/ExerciseSettings_instructor.re src/haz3lweb/ExerciseSettings.re
 
 setup-student: 
 	cp src/haz3lweb/ExerciseSettings_student.re src/haz3lweb/ExerciseSettings.re
 
-dev-helper: 
+dev-helper:
+	dune fmt --auto-promote || true
 	dune build @src/fmt --auto-promote src --profile dev
 
 dev: setup-instructor dev-helper
 
-dev-student: setup-student dev
+dev-student: setup-student dev-helper
 
 fmt:
 	dune fmt --auto-promote
@@ -39,7 +44,7 @@ release: setup-instructor
 	dune build @src/fmt --auto-promote src --profile release
 
 release-student: setup-student
-	dune build @src/fmt --auto-promote src --profile dev
+	dune build @src/fmt --auto-promote src --profile dev # Uses dev profile for performance reasons. It may be worth it to retest since the ocaml upgrade
 
 echo-html-dir:
 	@echo $(HTML_DIR)
@@ -54,8 +59,12 @@ repl:
 	dune utop src/haz3lcore
 
 test:
+	dune fmt --auto-promote || true
 	dune build @src/fmt @test/fmt --auto-promote src test --profile dev
 	node $(TEST_DIR)/haz3ltest.bc.js
 
+watch-test:
+	dune build @fmt @runtest --auto-promote --watch
+
 clean:
 	dune clean

README.md

@@ -17,7 +17,7 @@ can also be accessed at:
 
 ### Short version
 
-If you already have `ocaml` version 5.0.0 and least version 2.0 of `opam`
+If you already have `ocaml` version 5.2.0 and at least version 2.0 of `opam`
 installed, you can build Hazel by running the following commands.
 
 - `git clone [email protected]:hazelgrove/hazel.git`
@@ -155,7 +155,7 @@ To obtain an clean build, you may need to:
 
   ```sh
   # opam switch remove ./
-  opam switch create ./ 5.0.0
+  opam switch create ./ 5.2.0
   eval $(opam env)
   make deps
   make
@@ -185,7 +185,9 @@ helper functions for printing and serializing this data. For a type named `t`, t
 for a type named something else like `q`, it will be `show_q`.
 
 #### Source Maps
-`js_of_ocaml` does support source maps and has some other flags that might be useful. If you experiment with those and get them to work, please update this README with some notes.
+Source maps for `js_of_ocaml` should be configured when making locally with the dev profile (`make`). This is configured using the env stanzas present in the `dune` files for each top-level directory.
+
+Since source maps are generated browser developer tools should show reason code in the debugger and source tree. Stack traces should also include reason line numbers.
 
 #### Debug Mode
 If Hazel is hanging on load or when you perform certain actions, you can load into Debug Mode by appending `#debug` to the URL and reloading. From there, you have some buttons that will change settings or reset local storage. Refresh without the `#debug` flag and hopefully you can resolve the situation from there.
@@ -205,3 +207,12 @@ that will build that branch (in `release` mode) and deploy it to the URL
 It usually takes about 2 minutes if the build environment cache hits, or 
 20+ minutes if not. You can view the status of the build in the [Actions 
 tab on Github](https://github.com/hazelgrove/hazel/actions).
+
+Builds prior to July 2024 are archived at `https://hazel.org/build/<branch name>`.
+
+Note: If another archive needs to be performed, make sure to redeploy the following
+branches manually since we refer to them in various public material (websites and
+published papers):
+
+  dev
+  livelits

docs/Change-OCaml-Dependencies.md

@@ -0,0 +1,12 @@
+# Instructions for Changing Ocaml Dependencies
+
+## How to update dependencies
+
+- Update the dune-project file to reflect the new dependency constraints
+- `make change-deps`
+  - This should generate the hazel.opam file from dune.
+  - Depending on your installed dependencies you may need to make a new clean switch
+- Interrogate the `hazel.opam.locked` file to see what dependencies have changed
+- `make release`
+- Test in Firefox and Chrome. 
+- Commit changed files and push

docs/Updating-OCaml-Version.md

@@ -2,7 +2,7 @@
 
 ## Current version
 
-The most recent version that we use is Ocaml 5.0.0.
+The most recent version that we use is Ocaml 5.2.0.
 If there are known issues with more recent version of OCaml, we will list them here.
 
 ## How to update Hazel to use a new version of ocaml
@@ -16,15 +16,15 @@ To update do the following:
 - `opam switch list-available`
 
 - Choose the most recent version, but no later than the public release on 
-  ocaml.org (e.g., `5.0.0`).
+  ocaml.org (e.g., `5.2.0`).
 
 - Create a new branch called `update_ocaml_VERSION` where VERSION is the 
   version of OCaml you intend to upgrade to. 
 
     `git checkout -b update_ocaml_VERSION`
 
 - `opam switch create VERSION`, where `VERSION` is the most recent OCaml version
-  that does not contain a `+` character (e.g., `4.12.1`).
+  that does not contain a `+` character (e.g., `5.2.0`).
 
 - `make deps`
 
@@ -59,10 +59,23 @@ To update do the following:
       
       - Merge your branch with either `dev` or `update_ocaml_VERSION` if that is tricky.
 
-      - Update your OCaml installation by running the following:
+      - Update your `opam`.
 
         ```
         opam update
+        ```
+
+        If you get the following warning:
+
+        ```
+        [WARNING] opam is out-of-date. Please consider updating it (https://opam.ocaml.org/doc/Install.html)
+        ```
+
+        You may want to update opam by following the instructions for your platform at that link.
+
+      - Update your OCaml installation by running the following:
+
+        ```
         opam switch create VERSION
         eval $(opam env)
         make deps

dune-project

@@ -1,2 +1,43 @@
-(lang dune 3.0)
+(lang dune 3.16)
 (using menhir 2.0)
+
+(name hazel)
+
+(generate_opam_files true)
+
+(source
+ (github hazelgrove/hazel))
+
+(authors "Hazel Development Team")
+(maintainers "Hazel Development Team")
+
+(license MIT)
+
+(package
+ (name hazel)
+ (allow_empty)
+ (synopsis "Hazel, a live functional programming environment with typed holes")
+;  (description "A longer description")
+ ; (tags
+ ; (topics "to describe" your project))
+ (depends
+  (ocaml
+   (>= 5.2.0))
+  (menhir
+   (>= 2.0))
+  yojson
+  reason
+  ppx_yojson_conv_lib
+  ppx_yojson_conv
+  (omd (>= 2.0.0~alpha4))
+  ezjs_idb
+  bonsai
+  ppx_deriving
+  ptmap
+  (uuidm (= 0.9.8)) ; 0.9.9 has breaking deprecated changes
+  unionFind
+  ocamlformat
+  (junit_alcotest :with-test)
+  ocaml-lsp-server)) ; After upgrading to opam 2.2 use with-dev https://opam.ocaml.org/blog/opam-2-2-0/
+
+; See the complete stanza docs at https://dune.readthedocs.io/en/stable/reference/dune-project/index.html

dune-workspace

@@ -0,0 +1,9 @@
+(lang dune 3.16)
+
+(env
+ (dev
+  (flags
+   (:standard -warn-error -A)))
+ (release
+  (flags
+   (:standard -warn-error +A-58))))