package melange
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=83101338bab931280c2e4f27baf246e0759ecb292ec451e2528ff8141663a135
sha512=062edb295cd8e78292ab9a381d8ff96ef8041aaaf0b540c9751c9c77d5f4a803027ed22da4ceb1248b2687e66c0ca3e2d2559945778c590cc50b663d5e6e63e2
Description
Published: 25 Oct 2022
README
Melange
Toolchain to produce JS from Reason/OCaml.
Melange is a compiler for producing performant JavaScript from Reason and OCaml. Powered by a strong static type system with best-in-class type inference based on the OCaml compiler, Melange facilitates producing robust JavaScript code.
Positioning in the broader OCaml ecosystem
This project is forked from the ReScript compiler shifting focus to integrating with the OCaml ecosystem. This enables code sharing between backend and frontend using Dune's virtual libraries.
Melange also introduces a ReScript compatibility layer to maintain compatibility with ReScript's Syntax - preserving access to ReScripts ecosystem of packages.
Write in Reason/OCaml, use OCaml libraries or ReScript packages to kickstart your project!
A small write-up with more details on the motivation behind this project can be found in this blog post.
Installation
This project is currently unreleased. There are, however, a few ways to try it out.
Esy
The easiest way to get started is to clone the basic template and run esy
in the project root. To install Esy, npm install -g esy
should cover most workflows. If you have NodeJS / npm
available, npx esy
is even shorter.
OPAM
You can also install melange with opam
:
Pin melange to the version on GitHub:
opam pin melange https://github.com/melange-re/melange.git
You should now be able to run melange from your switch:
opam exec -- mel --help
Melange also has some runtime dependencies that need to be symlinked into node_modules
to be discoverable by bundlers like webpack:
rm -rf node_modules/melange
mkdir -p node_modules/melange
ln -sfn $(opam var prefix)/lib/melange node_modules/melange/lib
(adapted from the equivalent step in the esy build for melange-basic-template
: https://github.com/melange-re/melange-basic-template/blob/3605fb491d45e74472be58f653482e15e21c9159/esy.json#L15).
Nix
Melange has good support for Nix:
nix run github:melange-re/melange -- build
runs melange.nix shell github:melange-re/melange -c $SHELL
enters a shell withmel
andmelc
in$PATH
. Try outmel --help
, for example. for available options.Adding
github:melange-re/melange
as a flake input exports melange as the default package
Please reach out on the ReasonML Discord if you can't figure it out!
Editor support
Until Melange has first-class support in Dune, ocaml-lsp
support relies on having Melange generate a .merlin
file to provide the language server with information about your project.
To enable editor support via ocaml-lsp
, add the following to your esy.json
:
// esy.json
{
"devDependencies": {
"@opam/ocaml-lsp-server": ">= 1.12.0",
"@opam/dot-merlin-reader": "*"
}
}
Then use the --fallback-read-dot-merlin
flag when running ocaml-lsp
.
VSCode
If using the VSCode OCaml Platform extension, use the Custom
sandbox option and provide the flag to ocaml-lsp
via the command template:
// .vscode/settings.json
{
"ocaml.sandbox": {
"kind": "custom",
"template": "esy $prog $args --fallback-read-dot-merlin"
}
}
A note on OCaml versions
The current Melange distribution works on OCaml 4.14 and OCaml 5.00+trunk. If you need to use Melange with OCaml 4.12 (the only formerly supported version), you can consume the 0.1.0 tag for this repo (make sure to similarly use the 4.12.0+mel
tag for melange-compiler-libs
).
FAQ
How does this project relate to other tools?
Name | Purpose | Dependencies | Notes |
---|---|---|---|
Esy | Package manager | Installed with NPM | Obtaining dependencies (e.g. dune or reason ) |
OPAM | Package manager | None | Obtaining dependencies (e.g. dune or reason ) |
Dune | Build tool | Installed with esy or opam |
Well-known OCaml build tool; supports custom rules that can be composed to build anything |
Reason | Syntax | Installed with esy or opam |
a library that implements an alternative syntax to OCaml |
Melange | Compiler that emits Script | Esy (to install), Dune (to build), Reason (used as a library) | Supports OCaml, Reason and ReScript syntaxes; derived from ReScript, focused on compatibility with the wider OCaml ecosystem |
ReScript | The brand around a syntax and a compiler that emits JavaScript | None | Distributed via NPM as prebuilt binaries; previously called BuckleScript |
Can I use ReScript syntax?
Yes! ReScript syntax is supported, but ReScript won't have as many features as the OCaml or Reason syntaxes due to ReScript being built on top of an old OCaml version (4.06 - Released 2018). (e.g. letop
binding operators, generalized module open expressions, or local substitutions in signatures).
Where has the refmt
flag gone?
Upstream removed the refmt
flag, which used to allow configuring the path to a custom Reason binary. This was a welcome change for this repo too, so we cherry-picked it. The rationale: this project uses Reason as a library, so you can simply depend on the Reason version that you'd like in the usual way, via your preferred package manager.
Contributing
See CONTRIBUTING.md.
Acknowledgments
Thanks to the ReScript project, its author and maintainer @bobzhang, and its many contributors. Melange is a fork of ReScript, and continues to incorporate patches to ReScript on a regular basis.
Thanks to the OCaml team, obviously, without such a beautiful yet practical language, this project would not exist.
Thanks to Bloomberg and Facebook. The ReScript project began at Bloomberg and was published in 2016; without the support of Bloomberg, it would not have happened. ReScript was funded by Facebook since July 2017.
See also Credits.md concerning some individual components of Melange.
Licensing
See COPYING and COPYING.LESSER
See Credits for more details.