Caramel Versions Save

📙 Manual

• The manual is now automatically released in CI through Github Actions.
• We've got an open invite to Discord available on every page.
• Erlang as a runtime dependency has been clarified.
• Fixed several SEO issues.

🧰 Compiler

• Better support for bit-shift, unary float, and keyword operators
• Now support for floating point numbers without trailing digits (1. == 1.0)

📚 Standard Library

• Introduced the Math module
• Clean up several unimplemented bindings that were leftovers from the OCaml standard library

Read the Caramel Changelog

🌎 From a Backend to Language

Caramel is starting to take shape, and we'll now refer to it as a language rather than an OCaml backend to make it a little easier to talk about it.

After all, it isn't really 100% OCaml but a strict subset of it. It doesn't ship the same standard library or tools.

We also have a new website at: caramel.run

🗫 Community

We've updated our Code of Conduct to the Contributor Covenant v2.0.

We've opened the Github Discussions -- drop by and say hi or grab a Discord invite link! 👋

📙 Manual

I've started work on the Caramel Manual where we have an installation guide, an introduction, a small syntax cheatsheet, some examples, and a small guide on writing Caramel code that talks to existing Erlang code.

This is a big work in progress, so if you'd like to help, please reach out!

In the future I'm planning to write guides for how to use Caramel with existing build systems like Rebar3 or Mix, and include a reference guide to the standard library.

💅 Caramel Formatter

Caramel now ships a formatter that you can run to make sure your code is always stylish and you have no more bikesheds. It supports ZERO configuration, so what you see is what you get.

This is currently just a wrapper around ocamlformat, and all the kudos go to the amazing team putting that together.

You can use it by calling caramel fmt *.ml and it should work on both .ml and .mli sources.

It only does in-place formatting.

🧰 Compiler

The compiler has dropped support for several targets, including Core Erlang to Native, and the default OCaml compilation modes.

It will from now on focus only on taking Caramel sources into runnable Erlang and Core Erlang code. Over time we will move from Erlang to only Core Erlang support, to make it easier to reuse Caramel code from Erlang, Elixir, Gleam, and Hamler.

The additions to the compiler are:

• Replaced unbound vars in specs with wildcards (thanks @ilya-klyuchnikov, PR)
• Keyword atoms are automatically quoted now
• Removed unnecessary compilation steps (thanks @Drup)
• Removed unused object file generation (.cmo)
• Better support for operators like &&, ||, and >=

📚 Standard Library

The standard library has been simplified for contributing to it, and you can now find it at the top of the repository.

Changes:

• String concatenation now possible with the ^ operator: "yay" ^ "!!!"
• Binary.split/3 to split binary strings
• Erlang.floor/1 to round down floats to integers
• Erlang.list_to_float/1 to parse strings to floats
• Erlang.float_to_list/1 to turn floats into strings
• Erlang.list_to_integer/1 to parse strings to integers
• Erlang.integer_to_list/1 to turn integers into strings
• Lists.foldl/foldr signature has been fixed

Changelog

• erlang: the Erlang library included, with a lexer/parser/AST/printer for Standard Erlang, is now completely split from the Caramel code and will be published to opam shortly.

• caramelc: will return exit code 0 if everything went well. Otherwise expect a non-zero status!

• stdlib: remove dependency on the Erlang AST printer for parts of the runtime (like the recv function), and instead include the relevant .erl sources as part of the packed stdlib.

• docs: better contribution notes, documenting the release flow and saying a word about the rationale behind it. I've also put together a small website for Caramel here: https://caramel.abstractmachines.dev

• examples: the echo tcp server has been refactored to make it harder to accidentally override the gen_tcp module that is shipped with Erlang. We'll have to figure out a nice way to prevent these things from happening, which may just mean using all the modules on the Stdlib to avoid redefinition.

• ci: several changes to CI to ensure we can release the erlang library to opam.

Not much, just a few internal refactors that aren't very interesting.

Next release tag will include a better changelog.

Release Notes

This is the first actual release of Caramel that I'm making available 🎉

It includes 2 things:

• caramelc, the Caramel compiler
• erlang, an OCaml library for handling Erlang code, including an AST, lexer, parser, and printer

The Caramel compiler

Caramel can compile a large portion of the OCaml language, in particular most of the immutable functional OCaml, and into idiomatic Erlang code. Whenever possible it will look quite decent, and some times it will have pretty terrible formatting.

It runs as a single stand-alone binary with no dependencies (other than glibc or musl), and it should be blazing fast. Here's some benchmark results from the examples/ocaml_to_erlang.t folder:

The compiler also includes an additional target that may be of interest to those who want to dig into the compilation process: caramelc parse. This command will read Erlang and OCaml sources, and dump different ASTs of them. It was very useful to have around for testing purposes as well.

erlang library for OCaml

The Erlang library currently includes support for the vast majority of the Standard Erlang language, according to the grammar shipped with Erlang/OTP as of version 24.

It includes a series of modules to make it easy to construct Erlang programs from OCaml, as well as deconstruct them and operate on them.

A pretty printer is also included that right now is used within the Caramel compiler to generate the Erlang sources. It unfortunately still has some tiny remnants of Caramel logic in it, but they should be cleaned up in the near future and should not get in the way of more general usage of this library.

Changelog

• compiler: match expressions with cascading cases are not that straighforward to translate to Erlang and my gut tells me that doing the juggling here will get in the way of type-checking Erlang in the upcoming milestone, so this is forbidden as it is right now.

Changelog

• compiler: preliminary support for guards is added in this release. They are "safe" as long as you don't redefine any of the expected functions. There is no good way at the moment to prevent this from happening, but we could achieve it by essentially forbidding the use of the module name Erlang and requiring all guards to be fully qualified names.

  This still leaves us with the issue of compounded guard expressions.

  At the end of the day, we want a function is_valid_guard : expression -> bool that can traverse an arbitrary expression and tell us if it is or is not a valid guard based on the specification found at the Erlang docs.

• caramelc: the parse subcommand now can take a --lang and --tree parameters to print out the parse and typed trees for OCaml, as well as the parse tree of Erlang, and the parse tree of the result of compiling OCaml to Erlang.

  This is particularly useful for testing and understanding the AST translation, and will likely be used later on to see if the compile -> typecheck -> compile cycle yields the same inputs, and thus is an isomorphism.

Changelog

• Add support for record updates (see #23):

{ my_record with field = value }

My_record#{ field := value }

• Add tests showing that lambda function calls are now working as expected and will be called with the right number of parameters:

let f () =
  let g () = 1 in
  g ()

f() ->
  G = fun () -> 1 end,
  G().

Changelog

• compiler(#12): the compiler will now let you know when you're redefining a function on the OCaml side, which is not allowed on the Erlang side and stop compilation.

• compiler(#16): shadowing bindings with let are (for) now unsupported on the OCaml side, which makes translation runtime safe. We won't see any more X = X + 1 on the Erlang side.

• compiler(#15): to help with #16, priming of variables is now supported and translated to valid Erlang. We can write x' = x + 1 and it will translate to X_prime = X + 1.

• compiler(#13): recursive let bindings within a function definition are now not supported since they don't have a direct Erlang equivalent and require runtime overhead.

• error messages have been created for all of the above

Changelog

• stdlib: fix name of Io module so Merlin can pick it up properly.

Shoutouts

Thanks a lot to @seanhinde for playing opening issue #19 and working through the problems outlined there with me 🙌🏼

Better releases

• compiler: automatic function reference arities! As see in #10

• compiler: We're ignoring all fresh type variables when translating to Dialyzer specs for now. More work will be done in #20

• caramelc: caramelc compile now supports multiple --target flags, so you can compile both archives and Erlang sources at once.

• caramelc: standard library will now by default be in the respective installation directory (respecting dune install conventions)

• stdlib: Process.spawn/1 has been renamed to Process.make/1 until we have support for module attributes (see #21)

• stdlib: Dropped top-level namespacing until we figure out how it can work best with .merlin

• ci: several changes to release flow, including a nicer folder structure in the tarball

• ci: entire codebase is instrumentabled by bisect_ppx now to start gathering coverage reports

• erlang: removed an unused helper