Dealing with foreign libraries¶
The OCaml programming language can interface with libraries written in foreign languages such as C. This section explains how to do this with Dune. Note that it does not cover how to write the C stubs themselves, this is covered by the OCaml manual.
More precisely, this section covers:
- how to add C/C++ stubs to an OCaml library;
- how to pass specific compilation flags for compiling the stubs;
- how to build a library with a foreign build system.
Note that in general Dune has limited support for building source files written in foreign languages. This support is suitable for most OCaml projects containing C stubs, but is too limited for building complex libraries written in C or other languages. For such cases, Dune can integrate a foreign build system into a normal Dune build.
Adding C/C++ stubs to an OCaml library¶
To add C stubs to an OCaml library, simply list the C files without
.c extension in the Foreign stubs field. For instance:
(library (name mylib) (foreign_stubs (language c) (names file1 file2)))
You can also add C++ stubs to an OCaml library by specifying
(language cxx) instead.
Dune is currently not flexible regarding the extension of the C/C++
source files. They have to be
.c for C files and
.cxx for C++ files. If you have source files with other
extensions and you want to build them with Dune, you need to rename
them first. Alternatively, you can use the
foreign build sandboxing method described
C/C++ source files may include header files in the same directory as the C/C++ source files or in the same directory group when using include_subdirs.
The header files must have the
Installing header files¶
It is sometimes desirable to install header files with the
library. For that you have two choices: install them explicitly with
an install stanza or use the
install_c_headers field of the
library stanza. This field takes a list of header files names
.h extension. When a library install header files,
these are made visible to users of the library via the include search
Foreign build sandboxing¶
When the build of a C library is too complicated to express in the Dune language, it is possible to simply sandbox a foreign build. Note that this method can be used to build other things, not just C libraries.
To do that, follow the following procedure:
- put all the foreign code in a sub-directory
- tell Dune not to interpret configuration files in this directory via an data_only_dirs stanza
- write a custom rule that:
- depends on this directory recursively via source_tree
- invokes the external build system
- attach the C archive files to an OCaml library via Foreign archives.
For instance, let’s assume that you want to build a C library
libfoo’s own build system and attach it to an
OCaml library called
The first step is to put the sources of
libfoo in your project,
for instance in
src/libfoo. Then tell dune to consider
src/libfoo as raw data by writing the following in
The next step is to setup the rule to build
libfoo. For this,
writing the following code
(rule (deps (source_tree libfoo)) (targets libfoo.a dllfoo.so) (action (no-infer (progn (chdir libfoo (run make)) (copy libfoo/libfoo.a libfoo.a) (copy libfoo/libfoo.so dllfoo.so)))))
We copy the resulting archive files to the top directory where they can be
targets. The build is done in a
no-infer action because
libfoo/libfoo.so are dependencies produced by
an external build system.
The last step is to attach these archives to an OCaml library as follows:
(library (name bar) (foreign_archives foo))
Then, whenever you use the
bar library, you will also be able to
use C functions from
When using the sandboxing method, the following limitations apply:
- the build of the foreign code will be sequential
- the build of the foreign code won’t be incremental
both these points could be improved. If you are interested in helping make this happen, please let the Dune team know and someone will guide you.