Difference between revisions of "FFI imports packaging utility"
Jump to navigation
Jump to search
| Line 1: | Line 1: | ||
| + | == Abstract == |
||
| − | 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] |
||
| ⚫ | |||
| − | |||
| + | == Purpose == |
||
| ⚫ | |||
| ⚫ | |||
| − | |||
| − | === |
+ | === Synopsis === |
| + | === Package Naming and Versioning === |
||
| − | |||
| + | === Location of Libraries and Include Files === |
||
| − | This document contains user manual for the FFI Packaging Utility ('''ffipkg''') which is an extension to [http://hsffig.sourceforge.net HSFFIG]. |
||
| + | === External Programs === |
||
| − | |||
| + | === Compatibility === |
||
| − | It is expected that readers of this document first make themselves familiar with the following Wiki pages: |
||
| ⚫ | |||
| − | |||
| + | == Creating a FFI Import Package == |
||
| − | * [http://www.haskell.oeg/hawiki/HsffigTutorial HSFFIG Tutorial] |
||
| + | === Preparatory Steps === |
||
| − | * [http://www.haskell.org/hawiki/HsffigLinkageOptimization HSFFIG Linkage Optimization] |
||
| ⚫ | |||
| − | |||
| − | === |
+ | === Configuring a Package === |
| ⚫ | |||
| − | |||
| + | === Package Installation === |
||
| − | 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 [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. |
||
| − | |||
| ⚫ | |||
| − | <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> |
||
| ⚫ | |||
| − | |||
| − | 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>. |
||
| − | |||
| ⚫ | |||
| − | |||
| ⚫ | |||
| − | |||
| − | ==== Integration with Cabal ==== |
||
| − | |||
| ⚫ | |||
| − | |||
| ⚫ | |||
| − | |||
| ⚫ | |||
| − | |||
| ⚫ | |||
| − | |||
| − | === Conclusion === |
||