ghc.mk: Use the same conditional install logic from unlit
[hsc2hs.git] / README.rst
1 ``hsc2hs``: Haskell Pre-processor for C FFI bindings
2 ####################################################
3
4 The ``hsc2hs`` command can be used to automate some parts of the process
5 of writing Haskell bindings to C code. It reads an almost-Haskell source
6 with embedded special constructs, and outputs a real Haskell file with
7 these constructs processed, based on information taken from some C
8 headers. The extra constructs deal with accessing C data from Haskell.
9
10 It may also output a C file which contains additional C functions to be
11 linked into the program, together with a C header that gets included
12 into the C code to which the Haskell module will be compiled (when
13 compiled via C) and into the C file. These two files are created when
14 the ``#def`` construct is used (see below).
15
16 Actually ``hsc2hs`` does not output the Haskell file directly. It
17 creates a C program that includes the headers, gets automatically
18 compiled and run. That program outputs the Haskell code.
19
20 In the following, "Haskell file" is the main output (usually a ``.hs``
21 file), "compiled Haskell file" is the Haskell file after ``ghc`` has
22 compiled it to C (i.e. a ``.hc`` file), "C program" is the program that
23 outputs the Haskell file, "C file" is the optionally generated C file,
24 and "C header" is its header file.
25
26 .. contents::
27
28 Command line syntax
29 ~~~~~~~~~~~~~~~~~~~
30
31 ``hsc2hs`` takes input files as arguments, and flags that modify its
32 behavior:
33
34 ``-o FILE``, ``--output=FILE``
35     Name of the Haskell file.
36
37 ``-t FILE``, ``--template=FILE``
38     The template file (see below).
39
40 ``-c PROG``, ``--cc=PROG``
41     The C compiler to use (default: ``gcc``)
42
43 ``-l PROG``, ``--ld=PROG``
44     The linker to use (default: ``gcc``).
45
46 ``-C FLAG``, ``--cflag=FLAG``
47     An extra flag to pass to the C compiler.
48
49 ``-I DIR``
50     Passed to the C compiler.
51
52 ``-L FLAG``, ``--lflag=FLAG``
53     An extra flag to pass to the linker.
54
55 ``-i FILE``, ``--include=FILE``
56     As if the appropriate ``#include`` directive was placed in the
57     source.
58
59 ``-D NAME[=VALUE]``, ``--define=NAME[=VALUE]``
60     As if the appropriate ``#define`` directive was placed in the
61     source.
62
63 ``--no-compile``
64     Stop after writing out the intermediate C program to disk. The file
65     name for the intermediate C program is the input file name with
66     ``.hsc`` replaced with ``_hsc_make.c``.
67
68 ``-k``, ``--keep-files``
69     Proceed as normal, but do not delete any intermediate files.
70
71 ``-x``, ``--cross-compile``
72     Activate cross-compilation mode (see `cross-compilation`_).
73
74 ``--cross-safe``
75     Restrict the .hsc directives to those supported by the
76     ``--cross-compile`` mode (see `cross-compilation`_). This should be
77     useful if your ``.hsc`` files must be safely cross-compiled and you
78     wish to keep non-cross-compilable constructs from creeping into
79     them.
80
81 ``-?``, ``--help``
82     Display a summary of the available flags and exit successfully.
83
84 ``-V``, ``--version``
85     Output version information and exit successfully.
86
87 The input file should end with .hsc (it should be plain Haskell source
88 only; literate Haskell is not supported at the moment). Output files by
89 default get names with the ``.hsc`` suffix replaced:
90
91 +--------------+----------------+
92 | ``.hs``      | Haskell file   |
93 +--------------+----------------+
94 | ``_hsc.h``   | C header       |
95 +--------------+----------------+
96 | ``_hsc.c``   | C file         |
97 +--------------+----------------+
98
99 The C program is compiled using the Haskell compiler. This provides the
100 include path to ``HsFFI.h`` which is automatically included into the C
101 program.
102
103 Input syntax
104 ~~~~~~~~~~~~
105
106 All special processing is triggered by the ``#`` operator. To output a
107 literal ``#``, write it twice: ``##``. Inside string literals and
108 comments ``#`` characters are not processed.
109
110 A ``#`` is followed by optional spaces and tabs, an alphanumeric keyword
111 that describes the kind of processing, and its arguments. Arguments look
112 like C expressions separated by commas (they are not written inside
113 parens). They extend up to the nearest unmatched ``)``, ``]`` or ``}``,
114 or to the end of line if it occurs outside any ``() [] {} '' "" /**/``
115 and is not preceded by a backslash. Backslash-newline pairs are
116 stripped.
117
118 In addition ``#{stuff}`` is equivalent to ``#stuff`` except that it's
119 self-delimited and thus needs not to be placed at the end of line or in
120 some brackets.
121
122 Meanings of specific keywords:
123
124 ``#include <file.h>``, ``#include "file.h"``
125     The specified file gets included into the C program, the compiled
126     Haskell file, and the C header. ``<HsFFI.h>`` is included
127     automatically.
128
129 ``#define ⟨name⟩``, ``#define ⟨name ⟨value⟩``, ``#undef ⟨name⟩``
130     Similar to ``#include``. Note that ``#includes`` and ``#defines``
131     may be put in the same file twice so they should not assume
132     otherwise.
133
134 ``#let ⟨name⟩ ⟨parameters⟩ = "⟨definition⟩"``
135     Defines a macro to be applied to the Haskell source. Parameter names
136     are comma-separated, not inside parens. Such macro is invoked as
137     other ``#``-constructs, starting with ``#name``. The definition will
138     be put in the C program inside parens as arguments of ``printf``. To
139     refer to a parameter, close the quote, put a parameter name and open
140     the quote again, to let C string literals concatenate. Or use
141     ``printf``'s format directives. Values of arguments must be given as
142     strings, unless the macro stringifies them itself using the C
143     preprocessor's ``#parameter`` syntax.
144
145 ``#def ⟨C_definition⟩``
146     The definition (of a function, variable, struct or typedef) is
147     written to the C file, and its prototype or extern declaration to
148     the C header. Inline functions are handled correctly. struct
149     definitions and typedefs are written to the C program too. The
150     ``inline``, ``struct`` or ``typedef`` keyword must come just after
151     ``def``.
152
153 ``#if ⟨condition⟩``, ``#ifdef ⟨name⟩``, ``#ifndef ⟨name⟩``, ``#elif ⟨condition⟩``, ``#else``, ``#endif``, ``#error ⟨message⟩``, ``#warning ⟨message⟩``
154     Conditional compilation directives are passed unmodified to the C
155     program, C file, and C header. Putting them in the C program means
156     that appropriate parts of the Haskell file will be skipped.
157
158 ``#const ⟨C_expression⟩``
159     The expression must be convertible to ``long`` or ``unsigned long``.
160     Its value (literal or negated literal) will be output.
161
162 ``#const_str ⟨C_expression⟩``
163     The expression must be convertible to const char pointer. Its value
164     (string literal) will be output.
165
166 ``#type ⟨C_type⟩``
167     A Haskell equivalent of the C numeric type will be output. It will
168     be one of ``{Int,Word}{8,16,32,64}``, ``Float``, ``Double``,
169     ``LDouble``.
170
171 ``#peek ⟨struct_type⟩, ⟨field⟩``
172     A function that peeks a field of a C struct will be output. It will
173     have the type ``Storable b => Ptr a -> IO b``. The intention is that
174     ``#peek`` and ``#poke`` can be used for implementing the operations
175     of class ``Storable`` for a given C struct (see the
176     ``Foreign.Storable`` module in the library documentation).
177
178 ``#poke ⟨struct_type⟩, ⟨field⟩``
179     Similarly for poke. It will have the type
180     ``Storable b => Ptr a -> b -> IO ()``.
181
182 ``#ptr ⟨struct_type⟩, ⟨field⟩``
183     Makes a pointer to a field struct. It will have the type
184     ``Ptr a -> Ptr b``.
185
186 ``#offset ⟨struct_type⟩, ⟨field⟩``
187     Computes the offset, in bytes, of ``field`` in ``struct_type``. It
188     will have type ``Int``.
189
190 ``#size ⟨struct_type⟩``
191     Computes the size, in bytes, of ``struct_type``. It will have type
192     ``Int``.
193
194 ``#alignment ⟨struct_type⟩``
195     Computes the alignment, in bytes, of ``struct_type``. It will have type
196     ``Int``.
197
198 ``#enum ⟨type⟩, ⟨constructor⟩, ⟨value⟩, ⟨value⟩, ...``
199     A shortcut for multiple definitions which use ``#const``. Each
200     ``value`` is a name of a C integer constant, e.g. enumeration value.
201     The name will be translated to Haskell by making each letter
202     following an underscore uppercase, making all the rest lowercase,
203     and removing underscores. You can supply a different translation by
204     writing ``hs_name = c_value`` instead of a ``value``, in which case
205     ``c_value`` may be an arbitrary expression. The ``hs_name`` will be
206     defined as having the specified ``type``. Its definition is the
207     specified ``constructor`` (which in fact may be an expression or be
208     empty) applied to the appropriate integer value. You can have
209     multiple ``#enum`` definitions with the same ``type``; this
210     construct does not emit the type definition itself.
211
212 Custom constructs
213 ~~~~~~~~~~~~~~~~~
214
215 ``#const``, ``#type``, ``#peek``, ``#poke`` and ``#ptr`` are not
216 hardwired into the ``hsc2hs``, but are defined in a C template that is
217 included in the C program: ``template-hsc.h``. Custom constructs and
218 templates can be used too. Any ``#``\-construct with unknown key is
219 expected to be handled by a C template.
220
221 A C template should define a macro or function with name prefixed by
222 ``hsc_`` that handles the construct by emitting the expansion to stdout.
223 See ``template-hsc.h`` for examples.
224
225 Such macros can also be defined directly in the source. They are useful
226 for making a ``#let``\-like macro whose expansion uses other ``#let``
227 macros. Plain ``#let`` prepends ``hsc_`` to the macro name and wraps the
228 definition in a ``printf`` call.
229
230 .. _cross-compilation:
231
232 Cross-compilation
233 ~~~~~~~~~~~~~~~~~
234
235 ``hsc2hs`` normally operates by creating, compiling, and running a C
236 program. That approach doesn't work when cross-compiling — in this
237 case, the C compiler's generates code for the target machine, not the
238 host machine. For this situation, there's a special mode
239 ``hsc2hs --cross-compile`` which can generate the .hs by extracting
240 information from compilations only — specifically, whether or not
241 compilation fails.
242
243 Only a subset of ``.hsc`` syntax is supported by ``--cross-compile``.
244 The following are unsupported:
245
246 -  ``#{const_str}``
247 -  ``#{let}``
248 -  ``#{def}``
249 -  Custom constructs