-
Notifications
You must be signed in to change notification settings - Fork 95
- How can I install ctypes?
- How should I install libffi on Mac OS X?
- How can I build ctypes with debug support?
- Does ctypes work on Windows?
- How can I print ctypes values in the toplevel?
- What's the build process for code that uses stub generation ?
- Why does stub generation use functors?
- Does stub generation support the "noalloc" and "float" flags?
- What's the purpose of the
-Wl,-no-as-neededflag?
- What's the best way to bind C functions that act on strings?
- How can I deal with null pointers?
- Does ctypes support bigarrays?
- How can I call variadic functions?
- How can I call C macros?
- How can I call compiler builtins?
- How can I bind to functions that set errno?
- How can I declare an incomplete type?
- How can I represent structures with bit-field members?
- How does ctypes handle struct layout?
- How can I represent packed structs?
- How can represent structs that use the "struct hack"?
- How can I attach finalisers to objects created by ctypes?
- When should I use finalisers?
- What do I need to know about the garbage collector?
- When does ctypes copy objects?
- What's the purpose of views?
- How can I cast between types?
- How can I access global C variables?
- How can I bind to C++ code?
- How can I expose OCaml code to C?
- How can I improve the performance of my ctypes code?
The easiest way to install ctypes is to use the OPAM package manager. You should first ensure that libffi is installed using your operating system's package manager, and then type
opam install ctypesIf you'd prefer not to use OPAM then you can obtain the source for ctypes from the releases page. In order to build the source you'll need libffi, findlib and a basic Unix-like environment with GNU Make. In order to run the tests you'll also need OUnit.
The default version of libffi on Mac OS X 10.8 is too old. Use Homebrew to install a later version.
Build one of the release packages or the trunk from source using the following command:
make DEBUG=true
Ctypes is written in OCaml and standard C, and is intended to work on all common platforms, including Windows. If you run into problems using ctypes on Windows, please give details on the issue tracker.
Use the ctypes.top package. Loading the package installs printers for various ctypes values. You can load the package using Findlib's #require directive:
# #use "topfind";;
- : unit = ()
Findlib has been successfully loaded. Additional directives:
#require "package";; to load a package
#list;; to list the available packages
#camlp4o;; to load camlp4 (standard syntax)
#camlp4r;; to load camlp4 (revised syntax)
#predicates "p,q,...";; to set these predicates
Topfind.reset();; to force that packages will be reloaded
#thread;; to enable threads
- : unit = ()
# #require "ctypes.top";;
$HOME/.opam/4.01.0/lib/ocaml/unix.cma: loaded
$HOME/.opam/4.01.0/lib/ocaml/bigarray.cma: loaded
$HOME/.opam/4.01.0/lib/ocaml/str.cma: loaded
$HOME/.opam/4.01.0/lib/ctypes: added to search path
$HOME/.opam/4.01.0/lib/ctypes/ctypes.cma: loaded
$HOME/.opam/4.01.0/lib/ctypes/ctypes-top.cma: loaded
# open Ctypes;;Once the package is loaded, the results of expressions that evaluate to C type descriptions are printed using C declaration syntax. For example, the type "array of 10 floats" is printed as float[10]:
# array 10 float;;
- : float carray typ = float[10]and the type "function accepting two ints and returning a pointer to an array of 10 chars" is printed as follows:
# int @-> int @-> returning (ptr (array 10 char));;
- : (int -> int -> char carray ptr) fn = char(*(int, int))[10]C values are also printed out, in a form similar to C's initializer syntax. Here's how ctypes prints an array of three floats:
# CArray.of_list float [1.0; 2.0; 3.0];;
- : float carray = { 1, 2, 3 }- There is a tutorial on the wiki
- Real World OCaml Chapter 19 has a more extensive tutorial.
- The API documentation describes each ctypes type and function.
- If you want to understand a particular feature the unit tests are often a useful starting point.
- The examples in the distribution show how to write larger-scale bindings to C code.
- A number of real-world examples of ctypes bindings are available: see Who is using ctypes?
There's a mailing list hosted on lists.ocaml.org and mirrored on gmane:
If you find a bug, or would like to propose or contribute a new feature, please visit the GitHub issue tracker
The ctypes OPAM page lists a number of packages that use ctypes.
Incomplete types are the closest thing C has to abstract types. The following declaration declares an incomplete type struct foo:
struct foo;If this is the only declaration in scope for struct foo then the C compiler will reject code that attempts to make use of the representation. For example, without a full declaration in scope there's no way to access members, depend on the size (whether directly as with sizeof, or indirectly as with pointer arithmetic), or allocate objects of type struct foo "on the stack".
The ctypes equivalent of the incomplete declaration above is a call to structure without a corresponding call to seal:
let foo = structure "foo"As in C, you won't be able to access members or compute the size of an incomplete type such as foo.