Difference between revisions of "FFI imports packaging utility"

From HaskellWiki
Jump to: navigation, search
Line 1: Line 1:
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. [mailto:golubovsky@gmail.com Dimitry Golubovsky]
 
  +
== Abstract ==
 
 
== Benefits of Packaging FFI Imports ==
== The FFI Packaging Utility ==
 
  +
== Purpose ==
 
  +
== Command Line Options ==
=== Abstract ===
+
=== Synopsis ===
+
=== Package Naming and Versioning ===
This document contains user manual for the FFI Packaging Utility ('''ffipkg''') which is an extension to [http://hsffig.sourceforge.net HSFFIG].
+
=== Location of Libraries and Include Files ===
+
=== External Programs ===
It is expected that readers of this document first make themselves familiar with the following Wiki pages:
+
=== Compatibility ===
+
=== Other Options ===
* [http://www.haskell.oeg/hawiki/HsffigTutorial HSFFIG Tutorial]
+
== Creating a FFI Import Package ==
* [http://www.haskell.org/hawiki/HsffigLinkageOptimization HSFFIG Linkage Optimization]
+
=== Preparatory Steps ===
+
=== Creating Haskell Sources, Makefile, Cabal File ===
=== Why Package FFI Imports ===
+
=== Configuring a Package ===
+
=== Building a Package ===
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.
+
=== Package Installation ===
+
== Examples ==
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.
+
=== Hello, World ===
+
=== Berkeley DB Binding ===
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.
+
=== X11 Transport Protocol ===
 
The [http://www.haskell.org/cabal 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 ===
 
<pre>
 
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
 
</pre>
 
=== 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 <code>Makefile</code>, and the <code>Setup.hs</code> 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 (<code>-p FPKG</code> command line option was given). Names of packages created by '''ffipkg''' are always uppercased, so even <code>-p fPkG</code> would result in the same.
 
 
==== Preprocessing Header Files ====
 
 
A small include file is created, containing <code>#include</code> statements for all the files listed on the '''ffipkg''' command line. Name of this header file is composed of the string <code>hs_</code>, lowercased package name, and the <code>.h</code> suffix. In our example, this will be <code>hs_fpkg.h</code>.
 
 
The '''C''' preprocessor is invoked with command line options <code>-E -dD</code> 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 <code>.hsc</code> file generated. As with standalone '''hsffig''', this file would be named <code>HS_FPKG_H.hsc</code>.
 
 
==== Splitting Haskell Sources ====
 
 
==== Building Package Libraries ====
 
 
==== Integration with Cabal ====
 
 
=== Working Examples ===
 
 
==== Hello World ====
 
 
==== Berkeley DB ====
 
 
==== X11 Transport Protocol ====
 
 
=== Conclusion ===
 

Revision as of 03:33, 1 February 2006

Abstract

Benefits of Packaging FFI Imports

Purpose

Command Line Options

Synopsis

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