ExtUnix OCaml library
A collection of thin bindings to various low-level system API.
Our motto: "Be to Unix, what extlib is to stdlib"
- Implement thin C bindings that directly map to underlying system API.
- Provide common consistent ocaml interface: naming convention, exceptions.
- Simple to build - no extra dependencies.
Most of the system API don't deserve fully fledged library.
The ExtUnix project aims to collect these in one place. Read the "ExtUnix integration requirements" to know what kind of system API we can integrate.
- OCaml, Dune, ppxlib for build and installation
- (optional) oUnit2 for tests, odoc for documentation
Build and install:
make make install
Alternatively use the underlying Dune build system directly (plain ocaml, no sh and make needed):
dune build @install
$ ocaml # #use "topfind";; # #require "extunix";; # module U = ExtUnix.Specific;; # U.ttyname Unix.stdout;; - : string = "/dev/pts/8"
Run unit tests:
For OCaml programming style, we follow Unix module:
- Values and types should be named by the name of the underlying C function
Unix_erroron runtime errors
- Uniformly raise
Not_availableexception for functions not available on the current platform
- Be MT friendly by default - i.e. release runtime lock for blocking operations, (FIXME) optionally provide ST variants
- No shell scripting for build and install (think windows :) )
- Write portable C code (use compiler options to catch compatibility issues), NB: msvc doesn't support C99.
- Provide module (
ExtUnix.Specific) exposing only functions available on the platform where library is built - i.e. guaranteed to not throw
discoveris used to discover available functions during configure step.
config.hdescribes "features" discovered - it is responsible for inclusion of system-specific headers - this ensures coherent result at configure and build steps.
config.mldescribes the same features for the ocaml syntax extension
ppx_have, which preprocesses
src/extUnix.pp.mland generates two modules:
ExtUnix.Allwhere bindings to missing functions are rewritten to raise exception and
ExtUnix.Specificwhich drops bindings to missing functions.
ExtUnix integration requirements
We can integrate into ExtUnix:
- Official POSIX calls not in Unix module.
- Drafted POSIX calls which are at least present on two systems among: Linux, *BSD, MacOS X.
- System specific calls, as long as they don't need additional library, that they are marked as such in the documentation and that we have an automatic configure system test for them.
We should avoid system calls that are complex and would deserve a library on their own. For example, a family of more than 10 functions and datatypes should deserve its own library. If an external library already exists and works, like for inotify system call, we also won't consider it for integration.
Regarding Win32 portability: If there is a sane default to create a portable equivalent of the function on Windows, we can consider it. And we will mark it as such in the documentation.
Checklist for adding new bindings
- Add the C code to
src(follow the code style of existing bindings)
- Add the required checks to
- Add the name of the C bindings to
- Add the OCaml code to
HAVE ... END
- Add some tests to
- Add note to
Checklist for release
git logand update
- Increase VERSION in Makefile
Many people contribute to extunix. Please submit your patches and/or feature requests to the project bugtracker at https://github.com/ygrek/extunix/issues.
The current maintainer is reachable at mailto:firstname.lastname@example.org.