X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Futils.sgml;h=ae5039131a70233a5238fac836a262c69de65c9e;hb=721713b5d825b893ba0f29dce1fc237c963ecc18;hp=4bd99a11911fb9622c422aa638589af8900ad6c6;hpb=7d55139b431f0ae67d041910812e7c2f38c0e09d;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/utils.sgml b/ghc/docs/users_guide/utils.sgml index 4bd99a1..ae50391 100644 --- a/ghc/docs/users_guide/utils.sgml +++ b/ghc/docs/users_guide/utils.sgml @@ -1,372 +1,445 @@ - -Other Haskell utility programs - - -utilities, Haskell - - -This section describes other program(s) which we distribute, that help -with the Great Haskell Programming Task. - - - -Makefile dependencies in Haskell: using <Command>mkdependHS</Command> - - - -mkdependHS -Makefile dependencies -dependencies in Makefiles - - - -You run mkdependHS like this: - - -mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...] - - -or - - -ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...] - - -To see mkdependHS's command-line flags, give it a duff flag, -e.g., mkdependHS -help. - - - -In general, if module A contains the line - - -import B ...blah... - - -then mkdependHS will generate a dependency line of the form: - - -A.o : B.hi - - -If module A contains the line - - -import {-# SOURCE #-} B ...blah... - - -then mkdependHS will generate a dependency line of the form: - - -A.o : B.hi-boot - - -(See for details of interface files.) -If A imports multiple modules, then there will be multiple lines with A.o as the -target. - - - -By default, mkdependHS generates all the dependencies, and then -concatenates them onto the end of -makefile (or Makefile if makefile doesn't exist) bracketed by -the lines "# DO NOT DELETE: Beginning of Haskell dependencies" and -"# DO NOT DELETE: End of Haskell dependencies". If these lines -already exist in the makefile, mkdependHS deletes the old -dependencies first. - - - -mkdependHS takes GHC options between -- brackets. -It understands the following ones. Any options between -- brackets -that it doesn't understand are simply ignored; this way you can feed your -Makefile's standard GHC options to mkdependHS un-filtered. - - - - - - -Run the C pre-processor over the input files. The -default is not to. - - - - - - - -A cpp ; usual meaning. - - - - - - - -Add <dirs> (colon-separated) to list of directories -to search for "import"ed modules. - - - - - - - -Add <dir> to list of directories to search for -.h files (i.e., usual meaning). - - - - - - - -This program uses this GHC system library; take -appropriate action (e.g., recognise when they are -"import"ing a module from that library). - - - - - - - -Here are the mkdependHS-specific options (not between --'s): - - - - - - -Be verbose. - - - - - - - -Be very verbose. - - - - - - - -Turn off warnings about interface file shadowing. - - - - - - - -Use blah as the makefile, rather than makefile -or Makefile. If blah doesn't exist, mkdependHS creates it. -We often use to put the dependencies in .depend and -then include the file .depend into Makefile. - - - - - - - -Use .<osuf> as the "target file" suffix ( default: o). -Multiple flags are permitted (GHC2.05 onwards). Thus "" -will generate dependencies for .hc and .o files. - - - - - - - -Make extra dependencies that declare that files with -suffix .<suf>_<osuf> depend on interface files with suffix .<suf>_hi, or -(for {-# SOURCE #-} imports) on .hi-boot. -Multiple flags are permitted. -For example, will -make dependencies for .hc on .hi, .a_hc on .a_hi, and .b_hc on .b_hi. -(Useful in conjunction with NoFib "ways".) - - - - - - - -Regard <file> as "stable"; i.e., exclude it from having -dependencies on it. - - - - - - - -same as - - - - - - - -Regard the colon-separated list of directories <dirs> as containing stable, -don't generate any dependencies on modules therein. - - - - - - - -same as . - - - - - - - -Regard <file> as not "stable"; i.e., generate dependencies -on it (if any). This option is normally used in conjunction -with the option. - - - - - - - -Regard prelude libraries as unstable, i.e., generate dependencies -on the prelude modules used (including Prelude). -This option is normally only used by the various system libraries. If -a option is used, dependencies will also be -generated on the library's interfaces. - - - - - - - - - -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>hsc2hs</command> + hsc2hs + + + The hsc2hs 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 (see below). + + Actually hsc2hs 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 + + hsc2hs 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. + + + + + -I DIR + + Passed to the C compiler. + + + + + --lflag=FLAG + + An extra flag to pass to the linker. + + + + + --include=FILE + + As if the appropriate #include + directive was placed in the source. + + + + + --help + + Display a summary of the available flags. + + + + + The input file should end with .hsc. Output files get + names with the *.hsc pattern replaced: + + + + + + *.hs + Haskell file + + + Hs*.h + C header + + + Hs*.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 # operator. To output + a literal #, write it twice: + ##. Inside string literals and comments + # characters are not processed. + + A # is followed by optional + spaces and tabs, an alphanumeric keyword that describes + the kind of processing, and its arguments. Arguments look + like C expressions separated by commas (they are not + written inside parens). They extend up to the nearest + unmatched ), ] or + }, or to the end of line if it occurs outside + any () [] {} '' "" /**/ and is not preceded + by a backslash. Backslash-newline pairs are stripped. + + In addition #{stuff} is equivalent + to #stuff except that it's self-delimited + and thus needs not to be placed at the end of line or in some + brackets. + + Meanings of specific keywords: + + + + + #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 + #undef name + + Similar to #include. Note that + #includes and + #defines may be put in the same file + twice so they should not assume otherwise. + + + + + #let name parameters = "definition" + + Defines a macro to be applied to the Haskell + source. Parameter names are comma-separated, not + inside parens. Such macro is invoked as other + #-constructs, starting with + #name. The definition will be + put in the C program inside parens as arguments of + printf. To refer to a parameter, + close the quote, put a parameter name and open the + quote again, to let C string literals concatenate. + Or use printf's format directives. + Values of arguments must be given as strings, unless the + macro stringifies them itself using the C preprocessor's + #parameter syntax. + + + + + #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 + #error message + #warning message + + 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. + + + + + #enum type, constructor, value, value, ... + + A shortcut for multiple definitions which use + #const. Each value + is a name of a C integer constant, e.g. enumeration value. + The name will be translated to Haskell by making each + letter following an underscore uppercase, making all the rest + lowercase, and removing underscores. You can supply a different + translation by writing hs_name = c_value + instead of a value, in which case + c_value may be an arbitrary expression. + The hs_name will be defined as having the + specified type. Its definition is the specified + constructor (which in fact may be an expression + or be empty) applied to the appropriate integer value. You can + have multiple #enum definitions with the same + type; this construct does not emit the type + definition itself. + + + + + + + + Custom constructs + + #const, #type, + #peek, #poke and + #ptr are not hardwired into the + hsc2hs, 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. + + Such macros can also be defined directly in the + source. They are useful for making a #let-like + macro whose expansion uses other #let macros. + Plain #let prepends hsc_ + to the macro name and wraps the defininition in a + printf call. + + + + + +