# libffi: A binding to libffi

[ bsd3, foreign, library ] [ Propose Tags ]

A binding to libffi, allowing C functions of types only known at runtime to be called from Haskell.

## Modules

[Index] [Quick Jump]

## Flags

Automatic Flags
NameDescriptionDefault
ghc-bundled-libffi

When GHC is configured without --with-system-libffi, it will bundle its own copies of libffi, one of them statically linked and the other dynamically linked. This flag will force linking against the static copy of libffi that GHC bundles. This avoids a GHC bug (https:/gitlab.haskell.orgghcghc-issues15397) that can arise when the linker confuses the system's dynamic libffi with GHC's own dynamic libffi. Note that this flag only works when GHC is configured without the --with-system-libffi option. This is the case for most GHC binary distributions, such as those provided by ghcup. If you are using a GHC that was configured with --with-system-libffi, however, you will need to disable this option and link against the system's version of libffi instead.

Enabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

#### Maintainer's Corner

For package maintainers and hackage trustees

Candidates

• No Candidates
Versions [RSS] 0.1, 0.2, 0.2.1 CHANGELOG.md base (>=3 && <5), bytestring [details] BSD-3-Clause Remi Turk 2008-2009 Remi Turk remi.turk@gmail.com Foreign http://haskell.org/haskellwiki/Library/libffi head: git clone https://github.com/remiturk/libffi by ryanglscott at 2022-09-24T17:07:35Z Arch:0.2.1, Fedora:0.1, LTSHaskell:0.1, NixOS:0.1, Stackage:0.2.1 17941 total (75 in the last 30 days) 2.0 (votes: 1) [estimated by Bayesian average] λ λ λ Docs uploaded by userBuild status unknown

[back to package description]

# libffi

A binding to libffi, allowing C functions of types only known at runtime to be called from Haskell.

# Notes on GHC's bundling of libffi

This library makes a somewhat unusual choice: by default, it does not explicitly declare a dependency against the libffi C library. This is because most binary distributions of GHC—that is, GHCs configured without the --with-system-libffi option—bundle their own copies of libffi. One of these copies is statically linked, and another of these copies is dynamically linked. Moreover, whenever GHC compiles an executable, it will always pass the necessary flags to link against its static copy of libffi, as the GHC runtime system depends on it.

When GHC bundles its own copies of libffi, if you were to declare, say, an extra-libraries: ffi dependency, then it would not behave in the way that you would expect. This is because:

1. The linker flags to link against GHC's static copy of libffi always come first in the final linking step when compiling an executable. As a result, declaring an extra-libraries: ffi dependency won't make much of a difference, since GHC will always statically link against its own copy of libffi anyway due to the order of linker flags.

2. Moreover, declaring an extra-libraries: ffi dependency can have the unfortunate side effect of declaring an unused dynamic dependency against libffi. Even worse is the fact that the version of dynamically linked libffi that comes with your operating system may differ from the version of dynamically linked libffi that GHC bundles. When the version numbers differ, this can lead to the compiled executable failing at runtime with mysterious errors such as:

error while loading shared libraries: libffi.so.7: cannot open shared object file: No such file or directory


Observation (2) means that when GHC is configured with --with-system-libffi, it is inherently fragile to use extra-libraries: ffi. This is an unfortunate situation, but there is not much that one can do about this short of fixing GHC#15397 upstream. A workaround would be to configure GHC with --with-system-libffi, but practically speaking, the vast majority of GHC binary distributions do not configure this way. This includes all versions of GHC that ghcup distributes, so unless we want to exclude most GHC users, we need some kind of workaround for this issue.
Our workaround is to rely on observation (1). That is, because GHC always passes flags to the linker to link against its own static copy of libffi, we can always assume that GHC will handle the libffi dependency for us. As a result, the default behavior for this library is to enable the +ghc-bundled-libffi flag, which means that the library will not declare an external dependency on libffi at all. This is rather unusual, but then again, GHC bundling its own copies of libffi is also unusual. (To our knowledge, this is the only C library that GHC bundles in this fashion.)
We have tested out +ghc-bundled-libffi on Windows, macOS, and Linux, and it works as expected. If you encounter any linking oddities with +ghc-bundled-libffi, please file an issue.
It is worth re-emphasizing that +ghc-bundled-libffi will only work if you are using a binary distribution of GHC that was not configured with the --with-system-libffi option. If you are using such a GHC, then you will need to use -ghc-bundle-libffi (note the minus sign) to disable the flag and link against your operating system's copy of libffi. Unfortunately, cabal does not provide a way to detect whether GHC was configured with --with-system-libffi or not, so the burden is on users to enable or disable ghc-bundle-libffi as appropriate.