X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Futils.sgml;h=a0769b78670a94fa111742f16937db2a8d480836;hb=ebeb534bad20646923b4f59085f9cf22ba93fb46;hp=7aa413965c9c8fc1b3e7f6f97441fceabdf4940f;hpb=e4cc93bdfceaccbcae9b7cd2122284ac8cdff0b0;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/utils.sgml b/ghc/docs/users_guide/utils.sgml index 7aa4139..a0769b7 100644 --- a/ghc/docs/users_guide/utils.sgml +++ b/ghc/docs/users_guide/utils.sgml @@ -5,6 +5,50 @@ This section describes other program(s) which we distribute, that help with the Great Haskell Programming Task. + + + + Ctags and Etags for Haskell: <command>hasktags</command> + hasktags + CTAGS for Haskell + + hasktags is a very simple Haskell program that produces ctags "tags" and etags "TAGS" files for Haskell programs. + + When loaded into an editor such an NEdit, Vim, or Emacs, this allows one to easily navigate around a multi-file program, finding definitions of functions, types, and constructors. + + Invocation Syntax: + + +hasktags files + + +This will read all the files listed in and produce a ctags "tags" file and an etags "TAGS" file in the current directory. + + Example usage + + +find -name \*.\*hs | xargs hasktags + + +This will find all haskell source files in the current directory and below, and create tags files indexing them in the current directory. + + hasktags is a simple program that uses simple + parsing rules to find definitions of functions, constructors, and types. It isn't guranteed to find everything, and will sometimes create false index entries, but it usually gets the job done fairly well. In particular, at present, functions are only indexed if a type signature is given for them. + + Before hasktags, there used to be fptags and hstags, which did essentially the same job, however neither of these seem to be maintained any more. + + +Using tags with your editor + +With NEdit, load the "tags" file using "File/Load Tags File". Use "Ctrl-D" to search for a tag. + +With XEmacs, load the "TAGS" file using "visit-tags-table". Use "M-." to search for a tag. + + + + + + - + Writing Haskell interfaces to C code: - <command>hs2c</command> - hs2c + hsc2hs + hsc2hs - The hs2c command can be used to automate + 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 @@ -116,9 +160,9 @@ tags: 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. + is used (see below). - Actually hs2c does not output the Haskell + 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. @@ -135,20 +179,29 @@ tags: Command line syntax - glue-hsc takes input files as arguments, and flags that - modify its behavior: + hsc2hs takes input files as arguments, + and flags that modify its behavior: + -o FILE or + ––output=FILE + + Name of the Haskell file. + + + + -t FILE or - --template=FILE + ––template=FILE The template file (see below). - --cc=PROG + -c PROG or + ––cc=PROG The C compiler to use (default: ghc) @@ -156,7 +209,8 @@ tags: - --ld=PROG + -l PROG or + ––ld=PROG The linker to use (default: gcc). @@ -164,29 +218,74 @@ tags: - --cflag=FLAG + -C FLAG or + ––cflag=FLAG An extra flag to pass to the C compiler. - --lflag=FLAG + -I DIR + + Passed to the C compiler. + + + + + -L FLAG or + ––lflag=FLAG An extra flag to pass to the linker. - --help + -i FILE or + ––include=FILE + + As if the appropriate #include + directive was placed in the source. + + + + + -D NAME[=VALUE] or + ––define=NAME[=VALUE] + + As if the appropriate #define + directive was placed in the source. + + + + + ––no-compile + + Stop after writing out the intermediate C program to disk. + The file name for the intermediate C program is the input file name + with .hsc replaced with _hsc_make.c. + + + + + -? or ––help - Display a summary of the available flags. + Display a summary of the available flags and exit successfully. + + + + + -V or ––version + + Output version information and exit successfully. - The input file should end with .hsc. Output files get - names with the .hsc suffix replaced: + The input file should end with .hsc (it should be plain + Haskell source only; literate Haskell is not supported at the + moment). Output files by default get names with the + .hsc suffix replaced: @@ -214,20 +313,28 @@ tags: 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: + 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: @@ -236,8 +343,8 @@ tags: #include "file.h" The specified file gets included into the C program, - the compiled Haskell file, and the C - header. <HsFFI.h> is included + the compiled Haskell file, and the C header. + <HsFFI.h> is included automatically. @@ -245,6 +352,7 @@ tags: #define name #define name value + #undef name Similar to #include. Note that #includes and @@ -254,14 +362,21 @@ tags: - #option opt + #let name parameters = "definition" - 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. + 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. @@ -286,6 +401,8 @@ tags: #elif condition #else #endif + #error message + #warning message Conditional compilation directives are passed unmodified to the C program, C file, and C header. Putting @@ -327,20 +444,22 @@ tags: #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. + 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 ). + given C struct (see the + Foreign.Storable module in the library + documentation). #poke struct_type, field - Similarly for poke. It will have the type + Similarly for poke. It will have the type Storable b => Ptr a -> b -> IO (). @@ -352,6 +471,47 @@ tags: Ptr a -> Ptr b. + + + #offset struct_type, field + + Computes the offset, in bytes, of + field in + struct_type. It will have type + Int. + + + + + #size struct_type + + Computes the size, in bytes, of + struct_type. It will have type + Int. + + + + + #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. + + @@ -362,7 +522,7 @@ tags: #const, #type, #peek, #poke and #ptr are not hardwired into the - hs2c, but are defined in a C template that is + 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 @@ -373,6 +533,13 @@ tags: 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. +