dxtr/cl-ft2
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Page: Installation
Pages
API Index Character Maps Cookbook Core Concepts Development Errors FFI Layer Face Dependents Font Variations Getting Started Glyph Objects and Strokers Glyphs and Metrics Home Installation Library and Faces Outlines Rendering and Bitmaps Scope and Limitations Sizes and Transforms
7 Installation
dxtr edited this page 2026-10-18 15:46:31 +02:00
Table of Contents

Installation

Requirements

  • FreeType 2.13.1 or newer, as a shared library. Only the library is needed at run time. cl-ft2 needs no headers and no C compiler, because its struct layouts are written by hand with cl-ffi's C-sized types (:long, :ushort, …). Those types follow the platform's data model, LP64 on Unix and LLP64 on Windows. On Windows, cl-ft2 carries its own FreeType, so there is nothing to install (see Windows).
  • SBCL.
  • ASDF dependencies: cl-ffi and uiop. cl-ffi is not in Quicklisp: with stift, cl-ft2's own stiftfile brings it in; without, clone it where ASDF finds it.

Installing FreeType:

Platform Package
Debian / Ubuntu apt install libfreetype6
Fedora dnf install freetype
Arch pacman -S freetype2
macOS (Homebrew) brew install freetype
Windows nothing: cl-ft2 carries native/windows-x64/freetype.dll

Finding the library

cl-ft2/ffi defines the foreign library libfreetype and loads it when the system loads:

OS Names tried, in order
Linux / Unix libfreetype.so.6, libfreetype.so
macOS libfreetype.6.dylib, libfreetype.dylib
Windows native\windows-x64\freetype.dll in cl-ft2's source tree, by its full path; then freetype.dll by name
other libfreetype

If no FreeType can be loaded, loading cl-ft2 signals a freetype-error named :cannot-open-resource (see Errors) that says how to get one: install FreeType 2.13.1 or newer (on Debian or Ubuntu, libfreetype6), or, on Windows, restore native\windows-x64\freetype.dll from the repository.

If FreeType is installed somewhere the dynamic linker does not search, such as Homebrew's prefix on Apple Silicon, have the linker search it: start the Lisp with that directory in DYLD_FALLBACK_LIBRARY_PATH, such as DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib. cl-ft2 names the library, and the system finds it. macOS is not tested.

Windows

Windows ships no FreeType, so cl-ft2 carries its own build, native/windows-x64/freetype.dll (FreeType 2.14.3, 64-bit), and loads it by its full path. Another freetype.dll on PATH, such as the one the JDK ships, is never picked up by mistake. The path is fixed when cl-ft2 is compiled, so it points into cl-ft2's source tree.

An application saved from an image runs without cl-ft2's source tree. It loads freetype.dll by name instead, and Windows looks next to the executable first, so ship the DLL there. When you ship it, include native/windows-x64/FTL.TXT too: FreeType's licence asks for credit in your documentation.

The bundled build has FreeType's own zlib and no other optional libraries, so it depends only on Windows' own DLLs. It lacks:

  • PNG glyph bitmaps, which CBDT/CBLC and sbix colour emoji fonts use
  • bzip2-compressed fonts
  • WOFF2 fonts

native/build-windows.sh rebuilds the DLL from FreeType's pinned, checksummed source with MinGW-w64, reproducibly, and native/build-windows.sh --check verifies that the committed DLL is what the source builds to. See Development.

Checking the version

To confirm which FreeType you got:

(ft2:with-library (lib)
  (ft2:library-version lib))
;; => 2, 14, 3

Loading cl-ft2

cl-ft2 is not in the Quicklisp distribution. Put the repository somewhere ASDF can find it, such as ~/common-lisp/ or ~/quicklisp/local-projects/:

git clone https://fakehacker.cc/dxtr/cl-ft2.git ~/common-lisp/cl-ft2

(ql:quickload :cl-ft2)        ; with cl-ffi cloned beside it
;; or
(asdf:load-system :cl-ft2)

With stift

In a project that uses stift, require it:

stift get https://fakehacker.cc/dxtr/cl-ft2.git

The stiftfile pins its commit, with cl-ffi, which cl-ft2 requires, as an indirect entry. Run stift update https://fakehacker.cc/dxtr/cl-ft2.git to move the pin to the newest commit of its branch.

Systems

System Contents
cl-ft2 Both packages, cl-ft2 and cl-ft2/ffi. Neither has a global nickname: give cl-ft2 a local one, as the examples' ft2.
cl-ft2/test The parachute test suite. (asdf:test-system :cl-ft2) runs it. See Development.

Fonts

cl-ft2 does not find fonts for you. It opens the path or octet vector you give it. To find installed fonts by family name, use fontconfig (fc-match "DejaVu Sans" --format '%{file}') or bundle the fonts with your application.

Next: Getting started.

cl-ft2

Start

Reference

Guides