Editing Foreign Function Interface (section)

== Linking ==

There are several ways for GHC to find the foreign code to link with:
* Static linking: the foreign code binary object is merged with the Haskell one to form the final executable
* Dynamic linking: the generated binary uses libraries (e.g. .dll or .so) that are automatically linked when the binary is executed
* Explicit dynamic linking: the Haskell code explicitly loads libraries, finds symbols in them and makes calls to them

The first two modes are well described in GHC and Cabal manuals. For the last one, you need to use platform dependent methods:
* on UNIX, you can use [http://hackage.haskell.org/package/unix/docs/System-Posix-DynamicLinker.html System.Posix.DynamicLinker]

Explicit dynamic linking helps you obtaining [https://hackage.haskell.org/package/base/docs/Foreign-Ptr.html#g:2 function pointers (FunPtr)]. You need to write "dynamic" wrappers to call the functions from Haskell.

=== Dynamic linker template ===

[https://hackage.haskell.org/package/dynamic-linker-template dynamic-linker-template] is a package that uses template Haskell to automatically generate "dynamic" wrappers for explicit dynamic linking (only supporting Unix for now).

The idea is that a library is like a record containing functions, hence it is easy to generate the code that load symbols from a library and store them into a Haskell record.

In the following code, the record matching library symbols is the data type MyLib. The generated code will apply "myModifier" to each field name of the record to find corresponding symbols in the library. myModifier should often be "id" but it is sometimes useful when symbols are not pretty. Here in the foreign code "_v2" is appended at the end of each symbol to avoid symbol clashes with the first version of the library.

The package supports optional symbols: functions that may or may not be present in the library. These optional functions are represented by encapsulating the function type into Maybe.

The `libHandle` field is mandatory and contains a pointer to the loaded library. You can use it to unload the library.

A function called `loadMyLib` is generated to load symbols from a library, wrap them using "dynamic" wrappers and store them into a MyLib value that is returned.

<haskell>
    {-# LANGUAGE TemplateHaskell, ForeignFunctionInterface #-}
    
    import System.Posix.DynamicLinker.Template
    
    data MyLib = MyLib {
        libHandle :: DL,
        thing1 :: Double -> IO Int,         -- Mandatory symbol
        thing2 :: Maybe (Int -> Int -> Int) -- Optional symbol
    }
    
    myModifier :: String -> String
    myModifier = (++ "_v2")
    
    $(makeDynamicLinker ''MyLib CCall 'myModifier)
    
    -- Load your library with:
    -- loadMyLib :: FilePath -> [RTLDFlags] -> IO MyLib
</haskell>