Enable painless embedding of C code in Haskell code. If you're interested in how to use the library, skip to the "Inline C" section. To build, read the first two sections.

This module is intended to be imported qualified:

import qualified Language.C.Inline as C 

Each module that uses at least one of the TH functions in this module gets a C file associated to it, where the filename of said file will be the same as the module but with a `.c` extension. This C file must be built after the Haskell code and linked appropriately. If you use cabal, all you have to do is declare each associated C file in the .cabal file.

For example:

executable foo main-is: Main.hs, Foo.hs, Bar.hs hs-source-dirs: src -- Here the corresponding C sources must be listed for every module -- that uses C code. In this example, Main.hs and Bar.hs do, but -- Foo.hs does not. c-sources: src/Main.c, src/Bar.c -- These flags will be passed to the C compiler cc-options: -Wall -O2 -- Libraries to link the code with. extra-libraries: -lm ... 

Note that currently cabal repl is not supported, because the C code is not compiled and linked appropriately.

If we were to compile the above manually, we could:

$ ghc -c Main.hs $ cc -c Main.c -o Main_c.o $ ghc Foo.hs $ ghc Bar.hs $ cc -c Bar.c -o Bar_c.o $ ghc Main.o Foo.o Bar.o Main_c.o Bar_c.o -lm -o Main 

The quasiquoters below are the main interface to this library, for inlining C code into Haskell source files.

In general, quasiquoters are used like so:

[C.XXX| int { <C code> } |] 

Where C.XXX is one of the quasi-quoters defined in this section.

This syntax stands for a piece of typed C, decorated with a type:

• The first type to appear (int in the example) is the type of said C code.
• The syntax of the <C code> depends on on the quasi-quoter used, and the anti-quoters available. The exp quasi-quoter expects a C expression. The block quasi-quoter expects a list of statements, like the body of a function. Just like a C function, a block has a return type, matching the type of any values in any return statements appearing in the block.

See also the README.md file for more documentation.

Anti-quoters

Haskell variables can be captured using anti-quoters. inline-c provides a basic anti-quoting mechanism extensible with user-defined anti-quoters (see Language.C.Inline.Context). The basic anti-quoter lets you capture Haskell variables, for example we might say

let x = pi / 3 in [exp| double { cos($(double x)) } |] 

Which would capture the Haskell variable x of type CDouble.

In C expressions the $ character is denoted using $$.

Variable capture and the typing relation

The Haskell type of the inlined expression is determined by the specified C return type. The relation between the C type and the Haskell type is defined in the current Context -- see convertCType. C pointers and arrays are both converted to Haskell Ptrs, and function pointers are converted to FunPtrs. Sized arrays are not supported.

Similarly, when capturing Haskell variables using anti-quoting, their type is assumed to be of the Haskell type corresponding to the C type provided. For example, if we capture variable x using double x in the parameter list, the code will expect a variable x of type CDouble in Haskell (when using baseCtx).

Purity

The exp and block quasi-quotes denote computations in the IO monad. pure denotes a pure value, expressed as a C expression.

Safe and unsafe calls

unsafe variants of the quasi-quoters are provided in Language.C.Inline.Unsafe to call the C code unsafely, in the sense that the C code will block the RTS, but with the advantage of a faster call to the foreign code. See https://www.haskell.org/onlinereport/haskell2010/haskellch8.html#x15-1590008.4.3.

Examples

Inline C expression

{-# LANGUAGE QuasiQuotes #-} import qualified Language.C.Inline as C import qualified Language.C.Inline.Unsafe as CU import Foreign.C.Types C.include "<math.h>" c_cos :: CDouble -> IO CDouble c_cos x = [C.exp| double { cos($(double x)) } |] faster_c_cos :: CDouble -> IO CDouble faster_c_cos x = [CU.exp| double { cos($(double x)) } |] 

Inline C statements

{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE TemplateHaskell #-} import qualified Data.Vector.Storable.Mutable as V import qualified Language.C.Inline as C import Foreign.C.Types C.include "<stdio.h>" parseVector :: CInt -> IO (V.IOVector CDouble) parseVector len = do vec <- V.new $ fromIntegral len0 V.unsafeWith vec $ \ptr -> [C.block| void { int i; for (i = 0; i < $(int len); i++) { scanf("%lf ", &$(double *ptr)[i]); } } |] return vec