Installation

Requirements

ICU	ICU's common library, libicuuc, version 52 or newer, found at load time. Only libicuuc is used, not libicui18n.
Lisp	SBCL
Lisp libraries	cl-ffi, uiop (plus parachute for the tests); cl-ffi is not in Quicklisp: with stift, cl-icu's stiftfile brings it in; without, clone it
C toolchain	none: no headers, no groveller, no compiler.

cl-icu does not care which ICU version it finds: it looks up ICU's versioned function names at load time (see ICU versions and saved images).

Linux

Install ICU's runtime library. Distributions name the package after the ICU version, so the simplest portable choice is the development package, which pulls in whichever version the distribution has:

Distribution	Package
Debian, Ubuntu	libicu-dev (or the runtime package itself: libicu76, libicu74, …)
Fedora	libicu
Arch	icu

cl-icu loads libicuuc.so if present (the development symlink), else the newest libicuuc.so.N it finds, trying N from 99 down to 50.

macOS

cl-icu looks for libicuuc.dylib, then libicuuc.N.dylib. macOS's own ICU (libicucore) is private and not used. Install ICU with Homebrew (brew install icu4c). Homebrew installs it keg-only, outside the default search path, so have the dynamic linker search it: start the Lisp with that directory, the output of brew --prefix icu4c plus lib/, in DYLD_FALLBACK_LIBRARY_PATH, such as DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/opt/icu4c/lib.

macOS is not tested in CI.

Windows

There is nothing to install. cl-icu uses the icu.dll that ships with Windows 10 version 1903 and later. That DLL combines libicuuc and libicui18n and exports the plain, unversioned function names. Its ICU and Unicode versions are whatever the installed Windows provides; icu-version and unicode-version report them.

When ICU cannot be found

Loading cl-icu signals an icu-error that says what to install:

cl-icu could not load ICU: Could not load the foreign library CL-ICU/FFI:LIBICUUC.
  libicuuc.so: …
  …
Install ICU's common library: on Debian or Ubuntu, libicu-dev or a versioned runtime package such as libicu76.

On Windows the advice is to update Windows. ICU versions and saved images lists the other errors loading can meet.

Loading

cl-icu is not in Quicklisp. Clone it where ASDF finds it (for example ~/common-lisp/ or ~/quicklisp/local-projects/):

git clone https://fakehacker.cc/dxtr/cl-icu.git

(asdf:load-system :cl-icu)

With stift, require it in your project's stiftfile, which then pins cl-ffi too:

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

Checking it works

(cl-icu:icu-version)       ; => "78.3"
(cl-icu:unicode-version)   ; => "17.0"

The packages:

Package	Use
cl-icu	everything in this wiki unless stated otherwise
cl-icu/ffi	the raw layer, see FFI layer

The packages have no global nicknames. The examples in this wiki are written in a package that gives cl-icu the local nickname icu, and cl-harfbuzz the nickname hb where it appears:

(defpackage #:example
  (:use #:cl)
  (:local-nicknames (#:icu #:cl-icu) (#:hb #:cl-harfbuzz)))
(in-package #:example)