diff --git a/ReadMe.md b/ReadMe.md
new file mode 100644
--- /dev/null
+++ b/ReadMe.md
@@ -0,0 +1,111 @@
+## Installation
+
+Installation cannot be done fully automatically.
+It would require Cabal code that is bound to certain Cabal versions
+and is prone to fail.
+We give several non-automatic ways
+that also allow you to choose a particular LLVM version.
+
+First possibility is to point Cabal
+to the LLVM installation directories manually.
+It is recommended to add options to your global `.cabal/config`:
+
+~~~~
+extra-include-dirs: /usr/lib/llvm-21/include
+extra-lib-dirs: /usr/lib/llvm-21/lib
+~~~~
+
+This works for both `v1-build` and `v2-build`.
+The shown paths work for Debian and Ubuntu
+using the LLVM repositories at .
+You can obtain them with
+
+~~~~
+llvm-config-21 --includedir --libdir
+~~~~
+
+You can choose specific LLVM versions per project.
+For `v1-builds` it works like so:
+
+~~~~
+cabal install -fllvm1300 --extra-include-dirs=$(llvm-config-13 --includedir) --extra-lib-dirs=$(llvm-config-13 --libdir) yourpackage
+~~~~
+
+For Nix-style build you must add some options
+to the `cabal.project.local` file of your LLVM-related project:
+
+~~~~
+package llvm-ffi
+ flags: +llvm1300
+ extra-include-dirs: /usr/lib/llvm-13/include
+ extra-lib-dirs: /usr/lib/llvm-13/lib
+~~~~
+
+Alternatively, you may set environment variables globally or locally:
+
+~~~~
+export CPATH=/usr/lib/llvm-21/include:$CPATH
+export C_INCLUDE_PATH=/usr/lib/llvm-21/include:$C_INCLUDE_PATH
+export LD_LIBRARY_PATH=/usr/lib/llvm-21/lib:$LD_LIBRARY_PATH
+~~~~
+
+You can install and make LLVM library available
+in an elegant way using Nix:
+
+~~~~
+nix-shell -p llvmPackages_21.libllvm
+~~~~
+
+Though, for compatibility of GHC with LLVM and GLIBC
+you will need to use more packages from Nix
+and you better use a `shell.nix` file for bundling those:
+
+~~~~
+let
+ pkgs = import {};
+ llvmPkgs = pkgs.llvmPackages_21.libllvm;
+in
+pkgs.mkShell {
+ nativeBuildInputs = (with pkgs; [
+ gnumake
+ pkg-config
+ ghc
+ cabal-install
+ llvmPkgs
+ ]);
+ CPATH="${llvmPkgs.dev}/include";
+ C_INCLUDE_PATH="${llvmPkgs.dev}/include";
+ LD_LIBRARY_PATH="${llvmPkgs.lib}/lib";
+}
+~~~~
+
+The second way uses `pkg-config`.
+You can store above paths permanently in a `pkg-config` file like `llvm.pc`.
+The optimal way would be if LLVM installations or GNU/Linux distributions
+would contain such a file, but they don't.
+Instead, you may generate it using the `llvm-pkg-config` package
+or write one manually.
+Then you run
+
+~~~~
+cabal install -fpkgConfig
+~~~~
+
+Warning for inplace builds:
+Re-configuring the package using, say `-fllvm1600`,
+and re-buildung it might result in corrupt code.
+You must make sure that the stuff in `cbits` is re-compiled.
+Cabal or GHC may forget about that.
+You are safe if you run `cabal clean`.
+
+Caution: Nasty crashes can occur
+if you have configured paths for LLVM version X in `.cabal/config`
+and try to build `llvm-ffi` for a different LLVM version Y.
+Counterintuitively, global search paths have higher precedence
+[than local ones](https://github.com/haskell/cabal/issues/7782).
+But that does not simply mean
+that the local configuration is ignored completely.
+Instead the local library file is found,
+because its name libLLVM-Y.so is unique,
+whereas the include file names clash,
+thus the ones from the global include directory are used.
diff --git a/llvm-ffi.cabal b/llvm-ffi.cabal
--- a/llvm-ffi.cabal
+++ b/llvm-ffi.cabal
@@ -1,110 +1,19 @@
Cabal-Version: 2.2
Name: llvm-ffi
-Version: 21.0
+Version: 21.0.0.1
License: BSD-3-Clause
License-File: LICENSE
Synopsis: FFI bindings to the LLVM compiler toolkit.
Description:
FFI bindings to the LLVM compiler toolkit.
.
- Installation cannot be done fully automatically.
- It would require Cabal code that is bound to certain Cabal versions
- and is prone to fail.
- We give several non-automatic ways
- that also allow you to choose a particular LLVM version.
- .
- First possibility is to point Cabal
- to the LLVM installation directories manually.
- It is recommended to add options to your global @.cabal/config@:
- .
- > extra-include-dirs: /usr/lib/llvm-21/include
- > extra-lib-dirs: /usr/lib/llvm-21/lib
- .
- This works for both @v1-build@ and @v2-build@.
- The shown paths work for Debian and Ubuntu
- using the LLVM repositories at .
- You can obtain them with
- .
- > llvm-config-21 --includedir --libdir
- .
- You can choose specific LLVM versions per project.
- For @v1-builds@ it works like so:
- .
- > cabal install -fllvm1300 --extra-include-dirs=$(llvm-config-13 --includedir) --extra-lib-dirs=$(llvm-config-13 --libdir) yourpackage
- .
- For Nix-style build you must add some options
- to the @cabal.project.local@ file of your LLVM-related project:
- .
- > package llvm-ffi
- > flags: +llvm1300
- > extra-include-dirs: /usr/lib/llvm-13/include
- > extra-lib-dirs: /usr/lib/llvm-13/lib
- .
- Alternatively, you may set environment variables globally or locally:
- .
- > export CPATH=/usr/lib/llvm-21/include:$CPATH
- > export C_INCLUDE_PATH=/usr/lib/llvm-21/include:$C_INCLUDE_PATH
- > export LD_LIBRARY_PATH=/usr/lib/llvm-21/lib:$LD_LIBRARY_PATH
- .
- You can install and make LLVM library available
- in an elegant way using Nix:
- .
- > nix-shell -p llvmPackages_21.libllvm
- .
- Though, for compatibility of GHC with LLVM and GLIBC
- you will need to use more packages from Nix
- and you better use a @shell.nix@ file for bundling those:
- .
- > let
- > pkgs = import {};
- > llvmPkgs = pkgs.llvmPackages_21.libllvm;
- > in
- > pkgs.mkShell {
- > nativeBuildInputs = (with pkgs; [
- > gnumake
- > pkg-config
- > ghc
- > cabal-install
- > llvmPkgs
- > ]);
- > CPATH="${llvmPkgs.dev}/include";
- > C_INCLUDE_PATH="${llvmPkgs.dev}/include";
- > LD_LIBRARY_PATH="${llvmPkgs.lib}/lib";
- > }
- .
- The second way uses @pkg-config@.
- You can store above paths permanently in a @pkg-config@ file like @llvm.pc@.
- The optimal way would be if LLVM installations or GNU/Linux distributions
- would contain such a file, but they don't.
- Instead, you may generate it using the @llvm-pkg-config@ package
- or write one manually.
- Then you run
- .
- > cabal install -fpkgConfig
- .
We try to stay up to date with LLVM releases.
The current version of this package is compatible with LLVM 13-21.
Please understand that the package may or may not work
against older LLVM releases.
.
- Warning for inplace builds:
- Re-configuring the package using, say @-fllvm1600@,
- and re-buildung it might result in corrupt code.
- You must make sure that the stuff in @cbits@ is re-compiled.
- Cabal or GHC may forget about that.
- You are safe if you run @cabal clean@.
- .
- Caution: Ugly crashes can occur
- if you have configured paths for LLVM version X in @.cabal/config@
- and try to build @llvm-ffi@ for a different LLVM version Y.
- Counterintuitively, global search paths have higher precedence
- than local ones: .
- But that does not simply mean
- that the local configuration is ignored completely.
- Instead the local library file is found,
- because its name libLLVM-Y.so is unique,
- whereas the include file names clash,
- thus the ones from the global include directory are used.
+ Caution: In many cases installation cannot run fully automatic.
+ See ReadMe.md for the details.
Author: Henning Thielemann, Bryan O'Sullivan, Lennart Augustsson
Maintainer: Henning Thielemann
Homepage: http://haskell.org/haskellwiki/LLVM
@@ -122,6 +31,9 @@
flatpak/llvm-3.8.1.json
flatpak/llvm-3.9.1.json
+Extra-Doc-Files:
+ ReadMe.md
+
Flag developer
Description: developer mode - warnings let compilation fail
Manual: True
@@ -187,7 +99,7 @@
Location: https://hub.darcs.net/thielema/llvm-ffi/
Source-Repository this
- Tag: 21.0
+ Tag: 21.0.0.1
Type: darcs
Location: https://hub.darcs.net/thielema/llvm-ffi/