{"id":13610161,"url":"https://github.com/hazelgrove/hazel","last_synced_at":"2025-05-14T20:09:40.618Z","repository":{"id":37791186,"uuid":"80174692","full_name":"hazelgrove/hazel","owner":"hazelgrove","description":"Hazel, a live functional programming environment with typed holes","archived":false,"fork":false,"pushed_at":"2025-05-13T14:49:10.000Z","size":179273,"stargazers_count":923,"open_issues_count":329,"forks_count":55,"subscribers_count":15,"default_branch":"dev","last_synced_at":"2025-05-13T15:54:32.457Z","etag":null,"topics":["editor","elm","functional-programming","holes","ocaml","reasonml"],"latest_commit_sha":null,"homepage":"http://hazel.org/","language":"Reason","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hazelgrove.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-01-27T02:14:05.000Z","updated_at":"2025-05-08T20:22:41.000Z","dependencies_parsed_at":"2023-10-15T07:58:16.725Z","dependency_job_id":"ac8079c4-1932-4966-881d-bd8b26998495","html_url":"https://github.com/hazelgrove/hazel","commit_stats":{"total_commits":4926,"total_committers":78,"mean_commits":63.15384615384615,"dds":0.7775071051563134,"last_synced_commit":"82d39a967f304c24cce2e100b74ced00d67b6f2c"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hazelgrove%2Fhazel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hazelgrove%2Fhazel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hazelgrove%2Fhazel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hazelgrove%2Fhazel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hazelgrove","download_url":"https://codeload.github.com/hazelgrove/hazel/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254219374,"owners_count":22034397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["editor","elm","functional-programming","holes","ocaml","reasonml"],"created_at":"2024-08-01T19:01:41.913Z","updated_at":"2025-05-14T20:09:40.601Z","avatar_url":"https://github.com/hazelgrove.png","language":"Reason","funding_links":[],"categories":["Uncategorized","Reason"],"sub_categories":["Uncategorized"],"readme":"# Hazel ![Build Status](https://github.com/hazelgrove/hazel/actions/workflows/deploy_branches.yml/badge.svg) [![codecov](https://codecov.io/gh/hazelgrove/hazel/graph/badge.svg?token=lOGAH9Shqe)](https://codecov.io/gh/hazelgrove/hazel)\n\nHazel is a live functional-programming environment rooted in the principles of\ntype theory. You can find the relevant papers and more motivation at [the Hazel\nwebsite](https://hazel.org/).\n\nYou can try Hazel online: the \n[dev](https://hazel.org/build/dev) branch is the main branch at the\nmoment. Every other branch that has been pushed to GitHub and successfully builds\ncan also be accessed at:\n\n  `https://hazel.org/build/\u003cbranch_name\u003e`\n\n\u003c!-- TODO: include some screenshots / animated GIFs once the UI stabilizes --\u003e\n\n## Building and Running Hazel\n\n### Short version\n\nIf you already have `ocaml` version 5.2.0, at least version 2.0 of `opam`, and `npm`\ninstalled, you can build Hazel by running the following commands.\n\n- `git clone git@github.com:hazelgrove/hazel.git`\n- `cd hazel`\n- `make deps`\n- `make dev`\n\nTo view Hazel, you have to serve it, on localhost for development (you can't\nrun it from a `file:///` URL due to browser restrictions on e.g. web workers.) \n\nIf you have `python3` on your path, you can use the Python server via \n`make serve`, then navigate to `http://0.0.0.0:8000/` in your browser.\n\nAlternatively, if you would live hot reloading, you can use `make hot` instead of `make serve`.\n\nOtherwise, run `make echo-html-dir` which will echo the directory that needs \nto be served using some other server of your choice.\n\n### Long Version\n\nIf you are unfamiliar with `ocaml` or `opam`, do not have them installed, or\njust get stuck, we recommend you follow the step-by-step installation\ninstructions contained in [INSTALL.md](INSTALL.md).\n\n## Contributing\n\n### From OCaml to ReasonML\n\nHazel is written in ReasonML, which is a syntactic sugar atop OCaml. \nThis link lets you type OCaml and see what the corresponding ReasonML syntax is:\n\u003chttps://reasonml.github.io/en/try\u003e.\n\nThis is useful if you are trying to figure out the ReasonML syntax for something\nthat you know the OCaml syntax for.\n\nYou can also convert between OCaml and ReasonML syntax at the terminal using\n`refmt` at the terminal. See `refmt --help` for the details.\n\n### Suggested Extensions for VS Code\n\nMost of our team uses Visual Studio Code (VS Code) to write code. \nIf you use VS Code, here are a few extensions that might be helpful.\n\n- This extension provides full support for editing ReasonML source code and\n  relevant tools:\n\n  - [ocaml-platform](https://github.com/ocamllabs/vscode-ocaml-platform)\n\n- Due to Reason's poor parse errors, unbalanced parentheses can be difficult\n  to find.  The following extensions help with that.\n\n  - [Bracket Pair Colorizer 2](https://marketplace.visualstudio.com/items?itemName=coenraads.bracket-pair-colorizer-2)\n  - [Indenticator](https://marketplace.visualstudio.com/items?itemName=sirtori.indenticator)\n  - [indent-rainbow](https://marketplace.visualstudio.com/items?itemName=oderwat.indent-rainbow)\n\nIn addition to these extensions, enabling the breadcrumbs bar can make\nnavigating a large code base easier. There are multiple ways to make the\nbreadcrumbs bar visible:\n\n- Click **View** / **Show Breadcrumbs** from the menu bar.\n- Press `Ctrl+Shift+P` (macOS: `Cmd+Shift+P`), start typing `breadcrumbs`, and\n  select `View: Toggle Breadcrumbs` from the dropdown menu to toggle breadcrumbs\n  on and off.\n- Press `Ctrl+Shift+.` to start breadcrumbs navigation.\n\n### Suggested Setup for NeoVim\n\nIf you enjoy your Vim binding and Vim setup, the following may help you set up your Reason IDE in NeoVim.\n\nIf you use vim, I recommend you to switch to NeoVim since it has a better support for multi-thread,\nand thus less likely to block you when you are programming.\n\nTo set up the LSP (Language Server Protocol), you need to set up your Language Client for Neovim and Language Server for ocaml.\n- [ocaml-language-server](https://www.npmjs.com/package/ocaml-language-server)\n- [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)\n\nAfter installing the previous two, you may want to copy the following to your neovim config file. \n(assuming `npm` have ocaml-language-server installed under `/usr/bin`)\n```\nlet g:LanguageClient_serverCommands = {\n    \\ 'ocaml': ['/usr/bin/ocaml-language-server', '--stdio'],\n    \\ 'reason': ['/usr/bin/ocaml-language-server', '--stdio']\n    \\ }\n\" LanguageClient-neovim\nnnoremap \u003cF5\u003e :call LanguageClient_contextMenu()\u003cCR\u003e\n\" Or map each action separately\nnnoremap \u003csilent\u003e K :call LanguageClient#textDocument_hover()\u003cCR\u003e\nnnoremap \u003csilent\u003e gd :call LanguageClient#textDocument_definition()\u003cCR\u003e\nnnoremap \u003csilent\u003e gr :call LanguageClient#textDocument_references()\u003cCR\u003e\nnnoremap \u003csilent\u003e gf :call LanguageClient#textDocument_formatting()\u003ccr\u003e\nnnoremap \u003csilent\u003e \u003cF2\u003e :call LanguageClient#textDocument_rename()\u003cCR\u003e\n```\n\n### Build System Details\n\nHazel is compiled to Javascript for the web browser via the `js_of_ocaml` compiler.\n\nThough `make` targets are provided as a convenience, they mostly translate to\n`dune` commands.\n\nInvoking `make` by itself is equivalent to invoking `make dev`. With these\ncommands we pass additional flags to `js_of_ocaml` that cause the insertion of\ncomments that map locations in the generated JS to locations in the source\nfiles. This is useful for debugging purposes.\n\n`make dev` also auto-formats Reason source files using `refmt` (this is what the\n`@src/fmt` alias is for). This ensures code from all contributors follows the\nsame style.\n\nThe `make dev` and `make release` commands do three things:\n\n1. Generate some internal parsers using `menhir`.\n2. Compile the Reason code to OCaml bytecode using the OCaml compiler.\n3. Compile the OCaml bytecode to JavaScript\n   (`_build/default/src/hazelweb/www/hazel.js`) using `js_of_ocaml`.\n\nFor a smoother dev experience, use `make watch` to automatically watch \nfor file changes. This may require installing `fswatch` (see INSTALL.md).\nYou can also run `make watch-release` to continuously build the release\nbuild (takes longer per build).\n\n#### Clean Build\n\nTo obtain an clean build, you may need to:\n\n- Clone the repository (if you have not), and\n  enter the project root of your cloned Hazel project.\n\n  ```sh\n  git clone git@github.com:hazelgrove/hazel.git\n  cd hazel\n  ```\n\n- Setup a local OCaml environment specific to the project, and compile.\n  If you have setup a local OCaml environment (there is a directory\n  called `_opam`), you may want to first remove it.\n\n  ```sh\n  # opam switch remove ./\n  opam switch create ./ 5.2.0\n  eval $(opam env)\n  make deps\n  make\n  ```\n\nThis sets up a standalone OCaml environment in the cloned project,\nindependent of the one you sent in your home directory. This allow you to\nalternate dependencies, or test dependencies changes, without affect\nexisting OCaml projects.\n\nNOTE: You may see the following warning when building:\n\n```\nWarning 58 [no-cmx-file]: no cmx file was found in path for module Ezjs_idb, and its interface was not compiled with -opaque\n```\n\nThis is due to an upstream library issue and does not cause problems with Hazel: \n\n  https://github.com/OCamlPro/ezjs_idb/issues/1\n\n### Debugging\n\n#### Printing\nYou can print to the browser console using the standard `print_endline` function. This is probably the easiest method right now.\nMost datatypes in the codebase have something like `[@deriving (show({with_path: false}), sexp, yojson)]` on them. This generates\nhelper functions for printing and serializing this data. For a type named `t`, the `show` function will be named `show`. Otherwise,\nfor a type named something else like `q`, it will be `show_q`.\n\n#### Source Maps\nSource 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.\n\nSince 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.\n\n#### Debug Mode\nIf 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.\n\n#### Testing\nYou can run all of the unit tests located in `test` by running `make test`.\n\nUnit tests are written using the [Alcotest framework](https://github.com/mirage/alcotest).\n\n#### Coverage\nCode coverage is provided by [bisect_ppx](https://github.com/aantron/bisect_ppx). To collect coverage statistics from tests run `make coverage`. After coverage statistics are generated, running `make generate-coverage-html` will generate a local webpage at `_coverage/index.html` that can be viewed to see line coverage per module.\n\n### Continuous Integration\n\nWhen you push your branch to the main `hazelgrove/hazel` repository, we \nhave a GitHub Action setup (see `.github/workflows/deploy_branches.yml`) \nthat will build that branch (in `release` mode) and deploy it to the URL \n`https://hazel.org/build/\u003cbranch name\u003e`, assuming the build succeeds.\n\nIt usually takes about 2 minutes if the build environment cache hits, or \n20+ minutes if not. You can view the status of the build in the [Actions \ntab on Github](https://github.com/hazelgrove/hazel/actions).\n\nBuilds prior to July 2024 are archived at `https://hazel.org/build-pre-july2024/\u003cbranch name\u003e`.\n\nNote: If another archive needs to be performed, make sure to redeploy the following\nbranches manually since we refer to them in various public material (websites and\npublished papers):\n\n  dev\n  livelits\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhazelgrove%2Fhazel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhazelgrove%2Fhazel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhazelgrove%2Fhazel/lists"}