From: simonmar Date: Tue, 31 Oct 2000 17:48:51 +0000 (+0000) Subject: [project @ 2000-10-31 17:48:51 by simonmar] X-Git-Tag: Approximately_9120_patches~3450 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=e4cc93bdfceaccbcae9b7cd2122284ac8cdff0b0;p=ghc-hetmet.git [project @ 2000-10-31 17:48:51 by simonmar] document hs2c --- diff --git a/ghc/docs/users_guide/utils.sgml b/ghc/docs/users_guide/utils.sgml index 67547c3..7aa4139 100644 --- a/ghc/docs/users_guide/utils.sgml +++ b/ghc/docs/users_guide/utils.sgml @@ -1,126 +1,383 @@ - -Other Haskell utility programs - - -utilities, Haskell - - -This section describes other program(s) which we distribute, that help -with the Great Haskell Programming Task. - - - -Emacs `TAGS' for Haskell: <Command>hstags</Command> - - - -hstags -TAGS for Haskell - - - -`Tags' is a facility for indexing the definitions of -programming-language things in a multi-file program, and then using -that index to jump around among these definitions. - - - -Rather than scratch your head, saying “Now where did we define -`foo'?”, you just do (in Emacs) M-. foo RET, and You're There! -Some people go wild over this stuff… - - - -GHC comes with a program hstags, which build Emacs-able TAGS files. The invocation syntax is: - - -hstags [GHC-options] file [files...] - + + Other Haskell utility programs + utilities, Haskell + + This section describes other program(s) which we distribute, + that help with the Great Haskell Programming Task. + + + + + “Yacc for Haskell”: <command>happy</command> + + Happy + Yacc for Haskell + parser generator for Haskell + + Andy Gill and Simon Marlow have written a parser-generator + for Haskell, called + happy.happy parser + generator Happy is to + Haskell what Yacc is to C. + + You can get happy from the Happy + Homepage. + + Happy is at its shining best when + compiled by GHC. + + + + + + + Writing Haskell interfaces to C code: + <command>hs2c</command> + hs2c + + + The hs2c command can be used to automate + some parts of the process of writing Haskell bindings to C code. + It reads an almost-Haskell source with embedded special + constructs, and outputs a real Haskell file with these constructs + processed, based on information taken from some C headers. The + extra constructs deal with accessing C data from Haskell. + + It may also output a C file which contains additional C + functions to be linked into the program, together with a C header + that gets included into the C code to which the Haskell module + will be compiled (when compiled via C) and into the C file. These + two files are created when the #def construct + is used. + + Actually hs2c does not output the Haskell + file directly. It creates a C program that includes the headers, + gets automatically compiled and run. That program outputs the + Haskell code. + + In the following, “Haskell file” is the main + output (usually a .hs file), “compiled + Haskell file” is the Haskell file after + ghc has compiled it to C (i.e. a + .hc file), “C program” is the + program that outputs the Haskell file, “C file” is the + optionally generated C file, and “C header” is its + header file. + + + Command line syntax + + glue-hsc takes input files as arguments, and flags that + modify its behavior: + + + + -t FILE or + --template=FILE + + The template file (see below). + + + + + --cc=PROG + + The C compiler to use (default: + ghc) + + + + + --ld=PROG + + The linker to use (default: + gcc). + + + + + --cflag=FLAG + + An extra flag to pass to the C compiler. + + + + + --lflag=FLAG + + An extra flag to pass to the linker. + + + + + --help + + Display a summary of the available flags. + + + + + The input file should end with .hsc. Output files get + names with the .hsc suffix replaced: + + + + + + .hs + Haskell file + + + _hsc.h + C header + + + _hsc.c + C file + + + + + + The C program is compiled using the Haskell compiler. This + provides the include path to HsFFI.h which + is automatically included into the C program. + + + Input syntax + + All special processing is triggered by the + # character. To output a literal + #, write it twice: ##. + + Otherwise # is followed by optional + spaces and tabs, an alphanumeric key that describes the kind of + processing, and its arguments. Arguments look like C expressions + and extend up to the nearest unmatched ), + ], or }, or to the end of + line outside any () [] {} '' "" /* */. Any + character may be preceded by a backslash and will not be treated + specially. + + Meanings of specific keys: + + + + + #include <file.h> + #include "file.h" + + The specified file gets included into the C program, + the compiled Haskell file, and the C + header. <HsFFI.h> is included + automatically. + + + + + #define name + #define name value + + Similar to #include. Note that + #includes and + #defines may be put in the same file + twice so they should not assume otherwise. + + + + + #option opt + + The specified Haskell compiler command-line option + is placed in the {-# OPTIONS #-} pragma + at the top of the Haskell file (see ). This is needed because + glue-hsc emits its own OPTIONS pragma, + and only one such pragma is interpreted by GHC. + + + + + #def C_definition + + The definition (of a function, variable, struct or + typedef) is written to the C file, and its prototype or + extern declaration to the C header. Inline functions are + handled correctly. struct definitions and typedefs are + written to the C program too. The + inline, struct or + typedef keyword must come just after + def. + + + + + #if condition + #ifdef name + #ifndef name + #elif condition + #else + #endif + + Conditional compilation directives are passed + unmodified to the C program, C file, and C header. Putting + them in the C program means that appropriate parts of the + Haskell file will be skipped. + + + + + #const C_expression + + The expression must be convertible to + long or unsigned + long. Its value (literal or negated literal) + will be output. + + + + + #const_str C_expression + + The expression must be convertible to const char + pointer. Its value (string literal) will be output. + + + + + #type C_type + + A Haskell equivalent of the C numeric type will be + output. It will be one of + {Int,Word}{8,16,32,64}, + Float, Double, + LDouble. + + + + + #peek struct_type, field + + A function that peeks a field of a C struct will be + output. It will have the type + Storable b => Ptr a -> IO b. + + The intention is that #peek and + #poke can be used for implementing the + operations of class Storable for a + given C struct (see ). + + + + + #poke struct_type, field + + Similarly for poke. It will have the type + Storable b => Ptr a -> b -> IO (). + + + + + #ptr struct_type, field + + Makes a pointer to a field struct. It will have the type + Ptr a -> Ptr b. + + + + + + + + Custom constructs + + #const, #type, + #peek, #poke and + #ptr are not hardwired into the + hs2c, but are defined in a C template that is + included in the C program: template-hsc.h. + Custom constructs and templates can be used too. Any + #-construct with unknown key is expected to + be handled by a C template. + + A C template should define a macro or function with name + prefixed by hsc_ that handles the construct + by emitting the expansion to stdout. See + template-hsc.h for examples. + + + + + +