@grain/libbinaryen

libbinaryen

Libbinaryen packaged for OCaml.

This is just the low-level C library. If you are looking for OCaml bindings to Binaryen, check out Binaryen.ml!

Usage

Inside your dune file, you can depend on libbinaryen as such:

(library
 (name binaryen)
 (public_name binaryen)
 (libraries libbinaryen.c)
 (foreign_stubs
  (language c)
  (names binaryen_stubs)
  (flags :standard -O2 -Wall -Wextra)))

Dependencies

This project requires CMake and python (v3.5 or greater).

When installing with opam, both of these dependencies will be checked using conf-cmake and conf-python-3.

When installing with esy, CMake will be built from source, and, on Mac or Linux, Python must be globally installed within a location that esy knows about (those being /usr/local/bin, /usr/bin, /bin, /usr/sbin, or /sbin). On Windows, a suitable python is already available from esy-bash.

MacOS C++ Compiler

When including this library in your dune MacOS executables, you'll need to specify -cc clang++ in your (flags) stanza. This is required because Binaryen will throw errors for itself to catch and using clang++ is the only way to handle them correctly. You can find more info on this ocaml issue.

Your stanza could look something like this:

 (executable
  (name example)
  (public_name example)
  (package example)
+ (flags -cc clang++)
  (modules example)
  (libraries binaryen))

These flags likely won't work on other operating systems, so you'll probably need to use dune-configurator to vary the flags per platform. You can see an example of this in our tests/.

MacOS DWARF & Compact unwind

When including this library in your dune MacOS executables, you might want to specify -cclib -Wl,-keep_dwarf_unwind -cclib -Wl,-no_compact_unwind in your (flags) stanza. If you don't include them, you'll probably see warnings like:

ld: warning: could not create compact unwind for _caml_start_program: dwarf uses DW_CFA_same_value
ld: warning: could not create compact unwind for _caml_raise_exn: stack subq instruction is too different from dwarf stack size
ld: warning: could not create compact unwind for _caml_raise_exception: stack subq instruction is too different from dwarf stack size

Your stanza could look something like this:

 (executable
  (name example)
  (public_name example)
  (package example)
+ (flags -cclib -Wl,-keep_dwarf_unwind -cclib -Wl,-no_compact_unwind)
  (modules example)
  (libraries binaryen))

These flags likely won't work on other operating systems, so you'll probably need to use dune-configurator to vary the flags per platform. You can see an example of this in our test/.

Static Linking

If you are planning to create portable binaries for Windows, it will try to find Cygwin/MinGW locations in your PATH. To avoid this, you probably want to add this to your (executable) stanzas:

 (executable
  (name example)
  (public_name example)
  (package example)
+ (flags (:standard -ccopt -- -ccopt -static))
  (modules example)
  (libraries binaryen))

These flags might not work on other operating systems (like MacOS), so you'll probably need to use dune-configurator to vary the flags per platform. You can see an example of this in our tests/.

Contributing

You'll need Node.js and esy to build this project. You should be able to use Opam if you are more comfortable with it, but the core team does all development using esy.

dune will take care of compiling Binaryen, so to build the project you'll only need to run:

esy

This will take a while. Once it's done, you can run the tests:

esy test