hLibsass is a low-level binding to LibSass. It provides basic types used by the library along with a FFI interface to the C API.
This is really a low-level library, if you want a high-level, more Haskell-friendly library, check out hSass.
It is available on Hackage.
A note from maintainer
Although it might seem like this package is dead - it is not. I am maintaining it (willing to maintain), it's just that I don't use it anymore and can't really detect bugs proactively. This also applies to LibSass updates - I am not monitoring it. If you want a bug fixed or LibSass version bumped, just open an issue and I will try to solve it! :)
This library is (mostly) 1-1 binding to LibSass. See LibSass wiki for documentation.
Static, shared or external version of LibSass?
hLibsass supports three different ways of linking with Libsass:
- Static, locally-built LibSass,
- Shared, locally-built LibSass, requires setting
- External (e.g. system package), requires setting
The first two options rely on the LibSass being distributed with the
hlibsass package and compiled during configure/build process. hLibsass is always distributed with LibSass version that is compatibile with the package.
Up until version
0.1.6.0, the first option was preferred, because LibSass has been distributed as a source package only. Development package of LibSass is now available in most Linux distributions and in Homebrew, so using it is equally good option
Using locally-built shared version of LibSass may require adjusting
LD_LIBRARY_PATH or putting
libsass.so somewhere in the
PATH, so this option is discouraged. However, if you really want to use it that way, you may use tools/libpath.sh to set
LD_LIBRARY_PATH (it extracts the library location using
externalLibsass flag has precedence over
hLibsass and LibSass version
hLibsass uses LibSass internally and therefore is quite tightly bound to LibSass. Every breaking change in LibSass C API will break hLibSass (either at compile-time or at runtime, depends on the change). For now, these combinations should work:
- hLibsass 0.1.5.x with LibSass 3.3.2 (distributed with) and 3.4.3 (not every function is reexported, but there were no changes that would break hLibSass),
- hLibsass 0.1.6.x with LibSass 3.4.3 (distributed with),
- hLibsass 0.1.7.x with LibSass 3.5.2 (distributed with)
- hLibsass 0.1.8.x with LibSass 3.5.5 (distributed with),
- hLibsass 0.1.9.x with LibSass 3.6.3 (distributed with),
- hLibsass 0.1.10.x with LibSass 3.6.4 (distributed with),
- LibSass 3.5.x WILL have breaking changes and will result in runtime failures of hLibSass versions prior to 0.1.7.0 (and probably compile-time failures too), see LibSass releases page for more details.
Building on Windows
hLibsass by default builds LibSass as part of it's build process. This means that it will require C & C++ compiler. On Linux that is not a problem most of the time since Clang/GCC is (almost) available on bare systems. On Windows it requires a little bit of additional packages.
The minimum that hLibsass requires is MinGW-w64. Installing it and compilig hLibsass using it's shell (so that
PATH is configured correctly) should be enough to get started.
Up until hLibsass 0.1.10, hLibsass required also
env binary. It is distributed as part of Cygwin/MSYS2. The easiest way to use that is to use Stack. It installs MSYS2 as part of their setup and compiles your packages inside POSIX-compatibile shell. You can follow instructrions on Stack documentation on how to install MinGW-w64 there.
Things to consider
Libsass is C++ library with C API, so in order to use it, it is necessary to provide C++ runtime. This library is linked against
libstdc++ (Windows & Linux)/
libc++ (macOS) automatically, so you don't have to deal with linking process.
GHCi not able to load hLibSass
GHC 7 is unable to load static version of native libraries (at least some of them) and therefore it rejects loading
libsass.a. On Linux, you can overcome this by switch to GHC 8 (tested with 8.0.2 with LTS Haskell 8.5) or by using shared or external (also shared) version of LibSass. On macOS, GHC 8 still rejects the library (it detects unresolver/duplicated symbols), so the only solution is to use shared/external LibSass (Homebrew version works).
Copyright (c) 2015-2020 Jakub Fijałkowski. See LICENSE for details.