Esperanto makes OCaml a build-once run-anywhere language, like itself, except it doesn't need an interpreter or virtual machine. Indeed, OCaml is able to produce a native executable which requires few libraries:
- a standard C library
libasmrun.a(the caml-runtime)- probably
libunix.aif you depend onunix.cmxa
Esperanto replaces the host's C library by Cosmopolitan. Then, it outputs a POSIX-approved polyglot format that runs on many platforms. For more details, please read the αcτµαlly pδrταblε εxεcµταblε.
You can install the project with OPAM:
$ opam pin add -y https://github.com/dinosaure/esperanto.gitLet's start to make a simple Hello World! example:
$ cat >main.ml <<EOF
let () = print_endline "Hello World!"
EOF
$ ocamlfind -toolchain esperanto opt main.ml
$ objcopy -S -O binary a.out
$ file a.out
a.out: DOS/MBR boot sector
$ sh -c "./a.out"
Hello World!You can take your favorite project and compile executables with the
Esperanto toolchain. You need to specify a new dune-workspace:
$ git clone https://github.com/dinosaure/hxd.git
$ cd hxd
$ cat >>bin/dune <<EOF
; A rule to properly strip everythings
(rule
(target xxd.com)
(enabled_if
(= %{context_name} esperanto))
(mode promote)
(deps xxd.exe)
(action (run objcopy -S -O binary %{deps} %{target})))
EOF
$ cat >dune-project<<EOF
(lang dune 2.0)
(context (default))
(context
(default
(name esperanto)
(toolchain esperanto)
(merlin)
(host default)))
EOFFinally, as a static program, you must fetch dependencies with opam monorepo and build your project with them:
$ opam monorepo lock
$ opam monorepo pull
$ dune build bin/xxd.com
$ ls bin/xxd.comNow, you have a portable/polyglot program. The user can assimilate the
program with the --assimilate option:
$ file bin/xxd.com
bin/xxd.com: DOS/MBR boot sector
$ sh -c "./bin/xxd.com --assimilate"
$ file bin/xxd.com
bin/xxd.com: ELF 64-bit LSB executableThe --assimilate option modify the executable itself to become really
native to your platform - in other words, the executable no longer becomes
polyglot!
The cosmopolitan toolchain (see toolchain/) provides a
special compiler and a special ld script which integrates options needed
to well-build the caml runtime with Cosmopolitan.
It puts into your OPAM 3 binaries:
arch-esperanto-none-static-ccthe compilerarch-esperanto-none-static-ldthe linkerarch-esperanto-none-static-objinfoa simple tool to mainly strip binaries
It installs few objects files:
cosmopolitan.athe Cosmopolitan librarycrt.o,ape.o,ape-no-modify-self.oandape.ldsstartup.owhich is a well-buildedcaml_startupfor your binaries which must be linked with-z caml-startupoptionstartup_unix.o/fake_unix.owhich initiates few constants needed bylibunix.aif you depend onunix.cmxa
From the toolchain, we are able to compile the OCaml compiler and its runtime
with Cosmopolitan (with few fixes). esperanto provides a new OCaml toolchain
which can be used by dune to "cross"-compile a project.
Such design comes from MirageOS and Solo5. For C stubs, we
provide the __ESPERANTO__ definition which permits to orchestrate your
compilation of C files according to the OCaml toolchain.
Currently, we support OCaml 4.13 & 4.14.
Currently, zsh < 5.9.0 does not support well Cosmopolitan/APE binaries.
However, the recent version fix the initial issue. In the case of you have
zsh < 5.9.0, you can use the --assimilate option to modify the executable
to a real native application:
$ zsh --version
zsh 5.8.1
$ zsh
$ ./a.out
zsh: exec format error: ./a.out
$ sh -c "./a.out --assimilate"
$ ./a.out
Hello World!However, as explained above, the binary no longer becomes polyglot!
An other issue on Linux is about binfmt_misc which wants to interpret the
binary as a Windows executable (due to the header of the Cosmopolitan binary).
A good explanation is available here: jart/cosmopolitan#2
The Cosmopolitan distribution (and specially the APE distribution) gives an
installer: https://justine.lol/apeloader/#binfmt_misc
This installer learns to binfmt_misc how to recognize and execute a
Cosmopolitan binary.
Cosmopolitan provides partially pthread (only mutex) and few functions which
can simulate threads (see spawn and join). Due to the partial
implementation of the pthread, we are not able to provide threads.cmxa from
the OCaml project. However, upstream wants to improve this situation and, in
the near future, Cosmopolitan will probably provide a full implementation of
pthread. In this future, we will be able to provide threads.cmxa and start
the support of OCaml 5.0.
The hard part of esperanto is when we need to compile C stubs with the Cosmopolitan C library. Indeed, the context is a bit different and your C code probably does not compile with Cosmopolitan. The usual mistake is about constants:
static int wait_flag_table[] = { WNOHANG, WUNTRACED };
value wait4(value flags, ...) {
int flags = caml_convert_flag_list(flags, wait_flag_table);
...
}type wait_flag = WNOHANG | WUNTRACED
external wait4 : wait_flag list -> ... = "wait4"Such code can not compile with Cosmopolitan due to the fact that WNOHANG
& WUNTRACED are not constants but values which are set at the beginning of
your program according to your platform.
Some others issues can remain but they are probably specific to you code. But Esperanto can not fit for every projects, so third-party libraries maintainers should be aware about "these details" if they want to support Esperanto.