Difference between revisions of "FFI imports packaging utility"

From HaskellWiki
Jump to: navigation, search
Line 8: Line 8:
   
 
== Purpose ==
 
== Purpose ==
The '''ffipkg''' utility accepts locations of '''C''' header and foreign library files as command line arguments and produces Haskell source files with FFI declarations, a Makefile, a Cabal package descriptor file, and a Setup.hs file suitable for running the Cabal package setup program. The utility acts as a driver running the '''C''' preprocessor, the equivalent of the '''hsffig''' program, and the source '''splitter'''. The Makefile created allows for compilation of Haskell source files into split object files: a feature of the GHC. This technique is discussed in [[#4|[4]]].
+
The '''ffipkg''' utility accepts locations of '''C''' header and foreign library files as command line arguments and produces Haskell source files with FFI declarations, a Makefile, a Cabal package descriptor file, and a Setup.hs file suitable for running the Cabal package setup program. The utility acts as a "driver" running the '''C''' preprocessor, the equivalent of the '''hsffig''' program, and the source '''splitter'''. The Makefile created allows for compilation of Haskell source files into split object files: a feature provided by GHC. This technique is discussed in [[#4|[4]]].
   
 
== Command Line Options ==
 
== Command Line Options ==
 
=== Synopsis ===
 
=== Synopsis ===
  +
Usage: ffipkg [OPTION...] include-file...
  +
-v --verbose provide verbose output
  +
-n --new-hooks use newer userHooks interface
  +
-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
  +
 
=== Package Naming and Versioning ===
 
=== Package Naming and Versioning ===
 
=== Location of Libraries and Include Files ===
 
=== Location of Libraries and Include Files ===

Revision as of 10:47, 1 February 2006

Abstract

The Haskell Cabal [1] is a framework which defines a common interface for authors to more easily build their applications in a portable way. The Haskell Foreign Functions Import Generator (hsffig) [3] is a tool to convert a C header file (.h) into Haskell code containing FFI [2] import statements for all entities whose declarations are found in the header file. The FFI Packaging Utility (ffipkg) is a tool that integrates the functionality of hsffig with the Cabal framework allowing for building and installation of packages entirely consisting of foreign functions imports.

It is recommended that readers of this document be familiar with the documents referred to as [3] and [4].

Benefits of Packaging FFI Imports

To build a Haskell application linked to a foreign library, it is necessary to specify the locations of certain files (C headers and static or shared library files) for the Haskell compiler, and this information must be remembered for every application using the library. Building a FFI package means that all such information is contained within the package descriptor, and all that needs to be remembered is just name of the package.

Purpose

The ffipkg utility accepts locations of C header and foreign library files as command line arguments and produces Haskell source files with FFI declarations, a Makefile, a Cabal package descriptor file, and a Setup.hs file suitable for running the Cabal package setup program. The utility acts as a "driver" running the C preprocessor, the equivalent of the hsffig program, and the source splitter. The Makefile created allows for compilation of Haskell source files into split object files: a feature provided by GHC. This technique is discussed in [4].

Command Line Options

Synopsis

Usage: ffipkg [OPTION...] include-file...

 -v      --verbose              provide verbose output
 -n      --new-hooks            use newer userHooks interface
 -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

Package Naming and Versioning

Location of Libraries and Include Files

External Programs

Compatibility

Other Options

Creating a FFI Import Package

Preparatory Steps

Creating Haskell Sources, Makefile, Cabal File

Configuring a Package

Building a Package

Package Installation

Examples

Hello, World

Berkeley DB Binding

X11 Transport Protocol

References