Difference between revisions of "FFI imports packaging utility"

From HaskellWiki
Jump to: navigation, search
Line 62: Line 62:
 
==== Generating FFI Imports ====
 
==== Generating FFI Imports ====
   
The code equivalent to the '''hsffig''' main program is executed in a forked process.
+
The code equivalent to the '''hsffig''' main program is executed in a forked process. This results in a <code>.hsc</code> file generated. As with standalone '''hsffig''', this file would be named <code>HS_FPKG_H.hsc</code>.
   
 
==== Splitting Haskell Sources ====
 
==== Splitting Haskell Sources ====

Revision as of 04:45, 28 January 2006

Note: This page contains a progressing draft of the documentation for an extension to HSFFIG to create Haskell packages for FFI imports. Once this page is complete this note will be removed. Dimitry Golubovsky

The FFI Packaging Utility

Abstract

This document contains user manual for the FFI Packaging Utility (ffipkg) which is an extension to HSFFIG.

It is expected that readers of this document first make themselves familiar with the following Wiki pages:

Why Package FFI Imports

Typically, when building a Haskell applications calling foreign functions from some library directly, certain things are taken into consideration such as location of the library header files and the library itself.

The hsffig tool automatically preprocesses library header files and generates FFI import statements for all foreign functions (with few exceptions like variadic functions and functions taking/returning structures) as well as function declarations to access members of C structures and unions.

As a result of such automatic FFI import generation, substantial amount of Haskell code is created which in turn results in subatantial time to compile it.

The Cabal tool assists in creation of packages. Usually Haskell packages contain reusable libraries of modules written in Haskell.

The ffipkg utility serves the purpose to bridge FFI imports and packaging. With FFI packages, locations of foreign libraries and header files need to be remembered only once, during package creation. The Haskell code created during the automated FFI import process needs to be compiled only once, thus reducing the time to compile applications using the foreign library.

Command Line Options

Usage: ffipkg [OPTION...] include-file...
  -v      --verbose              provide verbose output
  -s      --static               prefer static libraries
  -i      --header               stop after writing package include file
  -?, -h  --help                 print this help message
  -I                             include files location (may be multiple)
  -L                             library files location (may be multiple)
  -l                             library file to link (may be multiple)
  -V      --version              show version number
  -w 0.0  --package-version=0.0  specify version of the package
  -p      --package-name=        name the package (will be uppercased)
          --with-make=make       path to make
          --with-awk=awk         path to awk
          --with-ar=ar           path to ar
          --with-ghc=ghc         path to ghc
          --with-gcc=gcc         path to gcc
          --with-hsc2hs=hsc2hs   path to hsc2hs

How It Works

The ffipkg utility is a toplevel driver integrating functionality of hsffig and splitter (see the HSFFIG Tutorial), and also implementing the logic described in the HSFFIG Linkage Optimization notes. It accepts user's command line options and arguments, checks availability of the programs needed to build a package, converts C header files into Haskell FFI declarations, creates Makefile, and the Setup.hs file for integration with Cabal.

The following subsections describe this process in deeper details.

Naming conventions

In this section, we use FPKG as the name for our imaginary package (-p FPKG command line option was given). Names of packages created by ffipkg are always uppercased, so even -p fPkG would result in the same.

Preprocessing Header Files

A small include file is created, containing #include statements for all the files listed on the ffipkg command line. Name of this header file is composed of the string hs_, lowercased package name, and the .h suffix. In our example, this will be hs_fpkg.h.

The C preprocessor is invoked with command line options -E -dD to preprocess the include file mentioned in the previous paragraph.

Generating FFI Imports

The code equivalent to the hsffig main program is executed in a forked process. This results in a .hsc file generated. As with standalone hsffig, this file would be named HS_FPKG_H.hsc.

Splitting Haskell Sources

Building Package Libraries

Integration with Cabal

Working Examples

Hello World

Berkeley DB

X11 Transport Protocol

Conclusion