6.1 Interfacing with C header files

One of HaskellDirect's front-ends support DCE IDL, which is syntactically extremely close to C prototype and type declarations in the sense that a C header file can be viewed as low-quality IDL input.

HaskellDirect supports the reading of header files together with a number of mechanisms to help you improve on the information that header file declaration conveys. To elucidate how HaskellDirect can be used, here's a set of steps you will commonly have to go through to import into Haskell the functionality specified in a header file.

• Create a wrapper IDL module which simply includes the header file, i.e.,

  module CoolAPI {
  #include "CoolAPI.h"
  };
  

• Compile the wrapper IDL with ihc, using the following options:

    ihc -fhs-to-c CoolAPI.idl -cpp -I/extra/include/path/needed
  

  i.e., stating that you're generating stubs that let's you call C functions from Haskell (-fhs-to-c), enable the use of the C pre-processor plus any configuration of the include search path that might be needed.
• If you want to use the generated stubs from Hugs, add --hugs to the command-line.

By following the above three steps, HaskellDirect should have generated CoolAPI.hs, which contains the necessary type and function stub definitions. However, more often than not, these stubs are less than satisfactory, for a number of reasons:

• Contains lot of defintions included from standard header files that you are not interested in. To avoid this, use the HaskellDirect option -fexclude-system-includes.
• The stubs aren't particularly useable from a Haskell programmer point-of-view. For example, from

  char* getenv(char*);
  

  HaskellDirect generates:

  getenv :: Ptr Char -> IO (Ptr Char)
  

  From reading the documentation of the function you know that the pointers in question are null-terminated character strings, but there's no way of informing HaskellDirect that this is the case, at least not via the header file. IDL does supply you with the capabilities to specify this, through its string attribute:

  [string]char* getenv([in,string]char *arg);
  

  but requiring the user to convert the header file to IDL is not a practical proposition in most cases. So, to support the user here, HaskellDirect has got support for Attribute Specification Files (ASFs), which let's you specify the attributes of a function separately from its prototype/declaration. For information on how ASFs lets you improve upon the quality of the generated stub code, see Section Off-line attribute specification.
• The generated output doesn't include defnitions for any of the #defines that the header file contained. There are no shrink-wrapped solutions to this one (at least not yet.) Current alternatives are:
  • Make use of GNU CPP's support for dumping the #defines it encountered while processing (i.e., -dM), to list them all. Convert this list into corresponding IDL const declarations, either through a simple script or by-hand.
  • Contact HaskellDirect's author for a patch to GNU CPP that adds support for converting #defines to const declarations. With that patch added, automatic conversion of #defines into equivalent Haskell defintions becomes possible. [It is my intention to forward this patch to the GNU CPP maintainers to have it considered for inclusion, as it serves a useful role outside our (small) sphere.]
• You're only interested in a subset of the functions declared in the header file, or not interested in all but a couple. To have HaskellDirect omit stubs for certain functions, use the option -fwinnow-defns or -fonly-remove-defns together with an ASF file. For instance, assuming your header file contains prototypes for functions f and g but you're only interested in f. To achieve this you supply an ASF (via the option --asf=) containing the following on-liner:

  f:
  

  and compile up the stubs using:

    ihc -fhs-to-c -cpp CoolAPI.idl --asf=CoolAPI.asf -fwinnow-defns
  

  Since g isn't mentioned in the ASF, it will be ignored since -fwinnow-defns will only generate stub code for definitions mentioned in the ASF file. Notice that if f uses any locally defined types, they will also be included in the generated output. In the cases where it is simpler to name the defintions you want to exclude from the set of generated Haskell stubs, -fonly-remove-defns is your friend. For the above example, you would then supply an ASF listing the functions you want to omit:

  g=
  

  and feed that one-line ASF to HaskellDirect along with -fonly-remove-defns.

As a parting remark, it is the author's experience that it is often easy to fall into the trap of spending lots of effort in trying to supply the set of IDL attributes that makes the generated stubs look just right to the Haskell programmer. If you find yourself in this situation, it may be worth considering whether you should instead shift some of the responsibility of providing a Haskell-friendly veneer to the external API into Haskell itself, i.e., write the impedance matching code yourself.