>
Invoking Green CardThe general syntax for invoking Green Card is:
green-card [options] [filename] |
Green Card reads from standard input if no filename is given. The options can be any of those:
Print a usage message listing all available options, then exit successfully.
Print the version number, then exit successfully.
Print more information while processing the input.
Output extra debug information.
Search the directories named in the colon (:) separated list for imported files. The directories will be searched in a left to right order.
When searching, use colon separated list of source file suffixes (standard: no suffix or .gc)
Generate Haskell code for a particular system. Targets currently supported: ghc, hugs, nhc, and ffi. You're encouraged to use the ffi target, since the Haskell output it generates can be used with all Haskell systems that support the common FFI (as of June 2001, all of them).
Generates code that can use callbacks to Haskell (GHC only.) This makes the generated code slower (but safer!). See Section 7.2 for details.
Put C code in a separate file (GHC target only.)
Generate Haskell 1.4 compatible instead of Haskell 98.
Control how you mangle external names into Haskell ones. Schemes currently supported: std and classic. The default is std mangling, which will just change the casing of the first character:
A_STD_EXAMPLE ==> a_STD_EXAMPLE (variable case) ==> A_STD_EXAMPLE (datacon case) |
The classic name mangling scheme removes underscores and upper-cases each word, i.e.:
A_CLASSIC_EXAMPLE ==> aClassicExample (variable case) ==> AClassicExample (datacon case) |
Include debugging code in generated code.
Generate ``foreign imports'' to dynamic library DLL (FFI backend only).
Use specific calling convention (stdcall or ccall).
Green Card will create one or more output files when running. The following options control where the output goes:
where to put generated Haskell file.
where to put generated C file (if any header files are generated, they'll go in (dropSuffix file ++ ".h").
Use <prefix> as stem when generating output filenames that haven't been specificed directly, i.e., using -p Right, the Haskell and C output will be output in Right.hs and Right.c, respectively.
If none of the above output options are used, the name of the output files are constructed from the name of the input file. The filename suffix is dropped and the appropriate suffix is appended, e.g., running Green Card on foo.gc will create a Haskell file called foo.hs.
ToDo: add more debugging tips.
When working with GHC, a commonly occurring problem for Green Card generated code is that of functions being called unsafely when they should have been called safely. The manifestation of this is as an almighty crash. To help debug this, Green Card supports the option --stub-debug which will emit debug code into the generated code. For instance, for the following procedure specification:
%fun Foo :: Int -> IO Int %code Foo(arg1) |
It will generate something like this:
foo :: Int -> IO Int foo arg1 = _casm_ ``do {int arg1;int res1; arg1 = %0; __current_fun__ = "foo"; do { Foo(arg1); %r = (int)(res1);} while(0);} while(0);'' arg1 >>= \ res1 -> (return (res1)) |
On top of the normal boilerplate gubbins, the variable __current_fun__ is assigned (Green Card doesn't define this variable, so you'll have to define it yourself.) Using __current_fun__, it is possible to catch unsafe calls that really should have been safe. Here's how a Win32 library catches this condition in the (C wrapper) for its Haskell callback:
char* __current_fun__ = NULL; ... #if defined(DEBUG) extern int inCCallGC; if (inCCallGC == 0) { fprintf(stderr, "Warning: unsafe ccall %s invokes Haskell callback\n", __current_fun__); } #endif |
The variable inCCallGC is defined by the GHC RTS, and its value is equal to the number of safe calls currently executing. (PS: The above code doesn't catch all erroneous cases.)