Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/o1-labs/ocaml-gen
This crate provides automatic generation of OCaml bindings. Refer to the rustdoc for more information.
https://github.com/o1-labs/ocaml-gen
bindings ffi ocaml ocaml-rs rust
Last synced: 22 days ago
JSON representation
This crate provides automatic generation of OCaml bindings. Refer to the rustdoc for more information.
- Host: GitHub
- URL: https://github.com/o1-labs/ocaml-gen
- Owner: o1-labs
- License: apache-2.0
- Created: 2021-12-13T17:43:11.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-12-15T22:02:21.000Z (about 1 year ago)
- Last Synced: 2024-11-17T11:10:04.114Z (about 2 months ago)
- Topics: bindings, ffi, ocaml, ocaml-rs, rust
- Language: Rust
- Homepage: https://o1-labs.github.io/ocaml-gen
- Size: 1.6 MB
- Stars: 11
- Watchers: 17
- Forks: 5
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/o1-labs/ocaml-gen/actions/workflows/ci.yml)
[](https://deps.rs/repo/github/o1-labs/ocaml-gen)
[](https://crates.io/crates/ocaml-gen)
[](https://o1-labs.github.io/ocaml-gen/)
# OCaml-gen
## Motivation
[`ocaml-rs`](https://github.com/zshipko/ocaml-rs) provides functions and
wrappers to interact with the OCaml runtime which implements a garbage collector
to manage memory automatically. The library allows developers to write functions
in Rust that can be called from OCaml and vice versa. It provides automatic
conversion between OCaml and Rust value representations. The users can use
macros on the Rust side like `ocaml::FromValue` and `ocaml::ToValue` to convert
back and forth the values without thinking about the garbage
collector.
Macros `ocaml::func` in conjunction with `ocaml::sig` can be used on functions
to generate codes which will be compatible with the OCaml runtime.
More information is available in the [ocaml-rs book](https://zshipko.github.io/ocaml-rs/).
Even if `ocaml-rs` provides some macros, the user will need to write the OCaml
definitions with the corresponding types and use external definitions. Also,
macros to access nested values in structures are not provided in `ocaml-rs`.
The goal of `ocaml-gen` and `ocaml-gen-derive` is to provide automatic binding
generations and to add macros easing the development of large applications.
It is meant to be used in conjunction with [`ocaml-rs`](https://github.com/zshipko/ocaml-rs).
**SECURITY WARNING: this is still an experimental library, you should verify that the bindings generated are correct if you are using this in production**.
See the [ocaml-gen/README](/ocaml-gen) for more information.
## Setup development environment
```
opam switch create ./ 4.14.0
opam install merlin ocamlformat.$(awk -F = '$1 == "version" {print $2}' .ocamlformat)
```
## Run tests
```
dune build @runtest
```
If you change the file `tests/ocamlgen_test_stubs/src/bin/main.rs` or anything related to code generation, you will need to update `tests/expected_bindings.ml`. You can use:
```
dune build @runtest --auto-promote
```
to rely on `dune` to update the file. You will need to commit it to make the CI happy.
## Organization
* [ocaml-gen](ocaml-gen): the tool that allows us to generate the OCaml bindings from the Rust code.
* [ocaml-gen-derive](ocaml-gen/derive): derive macros have to be a in separate crate, so they are here. This crate is re-exported by ocaml-gen so end users should not have to worry about it.
* [tests/](tests/): contains some tests. If you are looking for examples on how to use ocaml-gen, you can check that folder.
## Additional resources
You can check the [recording](https://www.youtube.com/watch?v=LuXo2cNkgyA&feature=youtu.be) I made when I first introduced the tool internally.
## Publish a new release
An automatic release is set up with GitHub actions. To make a new release of
ocaml-gen and ocaml-gen-derive:
1. Change the version of `ocaml-gen-derive` in `ocaml-gen/Cargo.toml` to the new
release version.
2. Create a tag with `git tag -m "VERSION" -a "x.y.z"`
3. Push the tag with `git push --tags`