1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
ExtUnix OCaml library
=====================
[](https://travis-ci.org/ygrek/extunix)
[](https://ci.appveyor.com/project/ygrek/extunix/branch/master)
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.
Homepage: http://extunix.forge.ocamlcore.org/
Why?
----
Currently, everybody writes his own bindings to fulfil particular needs. 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.
Installation
------------
Dependencies :
* ocaml and ocamlfind for build and installation
* (optional) oUnit for tests (configure with `--enable-tests`)
Build and install :
./configure
make
make install
Alternatively use the underlying OASIS build system directly (plain ocaml,
no sh and make needed) :
ocaml setup.ml -configure
ocaml setup.ml -build
ocaml setup.ml -install
See other available targets :
ocaml setup.ml -help
Usage example :
$ ocaml
# #use "topfind";;
# #require "extunix";;
# module U = ExtUnix.Specific;;
# U.ttyname Unix.stdout;;
- : string = "/dev/pts/8"
Run unit tests :
./configure --enable-tests
make test
Guidelines
----------
For OCaml programming style, we follow Unix module:
* Values and types should be named by the name of the underlying C function
* Raise `Unix_error` on runtime errors
* Uniformly raise `Not_available` exception 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
Portability:
* 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
Not_available exception (experimental).
Build infrastructure:
* src/discover.ml is used to discover available functions during configure
step.
* Generated config.h describes "features" discovered - it is responsible for
inclusion of system-specific headers - this ensures coherent result at
configure and build steps.
* Generated config.ml describes the same features for the ocaml syntax
extension src/pa_have.ml, which preprocesses src/extUnix.mlpp and generates
two modules : `ExtUnixAll` where bindings to missing functions are rewritten
to raise exception and `ExtUnixSpecific` which 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 src/discover.ml
* Add the path to C bindings to _oasis CSources and run `oasis setup`
* Add the OCaml code to src/extUnix.mlpp guarded with HAVE ... END
* Add some tests to test/test.ml
* Add note to CHANGES.txt
* Run `./configure && make`
Checklist for release
---------------------
* Review `git log` and update CHANGES.txt
* Update version in _oasis and do `oasis setup`
* Commit
* `make release`
* Upload tarball and update download links on web page
* Update opam
Development
-----------
Many people contribute to extunix. Please submit your patches and/or feature requests
to project bugtracker at
https://github.com/ygrek/extunix/issues
Current maintainer is reachable at :
* mailto:ygrek@autistici.org
* xmpp:ygrek@jabber.kiev.ua
----
|
