[[project @ 2000-10-31 17:48:51 by simonmar]
simonmar**20001031174851
document hs2c
] {
hunk ./ghc/docs/users_guide/utils.sgml 1
-
-Other Haskell utility programs
-
+
+ Other Haskell utility programs
+ utilities, Haskell
hunk ./ghc/docs/users_guide/utils.sgml 5
-utilities, Haskell
+ This section describes other program(s) which we distribute,
+ that help with the Great Haskell Programming Task.
hunk ./ghc/docs/users_guide/utils.sgml 8
-
-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
+ generatorHappy 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.
+
+
hunk ./ghc/docs/users_guide/utils.sgml 268
-
+
+ #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.
+
+
hunk ./ghc/docs/users_guide/utils.sgml 282
-
-The only flags of its own are: to be verbose; to
-APPEND to the TAGS file, rather than write to it.
-
+
+ #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.
+
+
hunk ./ghc/docs/users_guide/utils.sgml 297
-
-Shortcomings: (1) Instance declarations don't get into the TAGS file
-(but the definitions inside them do); as instances aren't named, this
-is probably just as well. (2) Data-constructor definitions don't get
-in. Go for the corresponding type constructor instead.
-
+
+ #const C_expression
+
+ The expression must be convertible to
+ long or unsigned
+ long. Its value (literal or negated literal)
+ will be output.
+
+
hunk ./ghc/docs/users_guide/utils.sgml 307
-
-(Actually, GHC also comes with etags [for C], and perltags
-[for You Know What]. And—I cannot tell a lie—there is Denis
-Howe's fptags [for Haskell, etc.] in the ghc/CONTRIB
-section…)
-
+
+ #const_str C_expression
+
+ The expression must be convertible to const char
+ pointer. Its value (string literal) will be output.
+
+
hunk ./ghc/docs/users_guide/utils.sgml 315
-
+
+ #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.
+
+
hunk ./ghc/docs/users_guide/utils.sgml 326
-
-“Yacc for Haskell”: <Command>happy</Command>
-
+
+ #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.
hunk ./ghc/docs/users_guide/utils.sgml 333
-
-happy
-Yacc for Haskell
-parser generator for Haskell
-Andy Gill and Simon Marlow have written a parser-generator for
-Haskell, called happy.happy parser generatorHappy
-is to Haskell what Yacc is to C.
-
+ The intention is that #peek and
+ #poke can be used for implementing the
+ operations of class Storable for a
+ given C struct (see ).
+
+
hunk ./ghc/docs/users_guide/utils.sgml 340
-
-You can get happy from the Happy Homepage.
-
+
+ #poke struct_type, field
+
+ Similarly for poke. It will have the type
+ Storable b => Ptr a -> b -> IO ().
+
+
hunk ./ghc/docs/users_guide/utils.sgml 348
-
-Happy is at its shining best when compiled by GHC.
-
+
+ #ptr struct_type, field
+
+ Makes a pointer to a field struct. It will have the type
+ Ptr a -> Ptr b.
+
+
+
hunk ./ghc/docs/users_guide/utils.sgml 357
-
+
hunk ./ghc/docs/users_guide/utils.sgml 359
-
-Pretty-printing Haskell: <Command>pphs</Command>
-
+
+ Custom constructs
hunk ./ghc/docs/users_guide/utils.sgml 362
-
-pphs
-pretty-printing Haskell code
-
+ #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.
hunk ./ghc/docs/users_guide/utils.sgml 371
-
-Andrew Preece has written
-pphs,pphspretty-printing Haskell
-a utility to pretty-print Haskell code in LaTeX documents.
-Keywords in bolds, variables in italics—that sort of thing. It is
-good at lining up program clauses and equals signs, things that are
-very tiresome to do by hand.
-
+ 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.
hunk ./ghc/docs/users_guide/utils.sgml 376
-
-The code is distributed with GHC in ghc/CONTRIB/pphs.
-
+
hunk ./ghc/docs/users_guide/utils.sgml 378
-
+
hunk ./ghc/docs/users_guide/utils.sgml 380
-
+
}