11.2 Controlling source file character encoding

Starting with ASDF 2.21, components accept a :encoding option so authors may specify which character encoding should be used to read and evaluate their source code. When left unspecified, the encoding is inherited from the parent module or system; if no encoding is specified at any point, or if nil is explicitly specified, an extensible protocol described below is followed, that ultimately defaults to :utf-8 since ASDF 3.

The protocol to determine the encoding is to call the function detect-encoding, which itself, if provided a valid file, calls the function specified by *encoding-detection-hook*, or else defaults to the *default-encoding*. The *encoding-detection-hook* is by default bound to function always-default-encoding, that always returns the contents of *default-encoding*. *default-encoding* is bound to :utf-8 by default (before ASDF 3, the default was :default).

Whichever encoding is returned must be a portable keyword, that will be translated to an implementation-specific external-format designator by function encoding-external-format, which itself simply calls the function specified *encoding-external-format-hook*; that function by default is default-encoding-external-format, that only recognizes :utf-8 and :default, and translates the former to the implementation-dependent *utf-8-external-format*, and the latter to itself (that itself is portable but has an implementation-dependent meaning).

In other words, there now are plenty of extension hooks, but by default ASDF enforces the previous de facto standard behaviour of using :utf-8, independently from whatever configuration the user may be using. Thus, system authors can now rely on :utf-8 being used while compiling their files, even if the user is currently using :koi8-r or :euc-jp as their interactive encoding. (Before ASDF 3, there was no such guarantee, :default was used, and only plain ASCII was safe to include in source code.)

Some legacy implementations only support 8-bit characters, and some implementations provide 8-bit only variants. On these implementations, the *utf-8-external-format* gracefully falls back to :default, and Unicode characters will be read as multi-character mojibake. To detect such situations, UIOP will push the :asdf-unicode feature on implementations that support Unicode, and you can use reader-conditionalization to protect any :encoding encoding statement, as in #+asdf-unicode :encoding #+asdf-unicode :utf-8. We recommend that you avoid using unprotected :encoding specifications until after ASDF 2.21 or later becomes widespread. As of May 2016, all maintained implementations provide ASDF 3.1, so you may prudently start using this and other features without such protection.

While it offers plenty of hooks for extension, and one such extension is available (see asdf-encodings below), ASDF itself only recognizes one encoding beside :default, and that is :utf-8, which is the de facto standard, already used by the vast majority of libraries that use more than ASCII. On implementations that do not support unicode, the feature :asdf-unicode is absent, and the :default external-format is used to read even source files declared as :utf-8. On these implementations, non-ASCII characters intended to be read as one CL character may thus end up being read as multiple CL characters. In most cases, this shouldn’t affect the software’s semantics: comments will be skipped just the same, strings with be read and printed with slightly different lengths, symbol names will be accordingly longer, but none of it should matter. But a few systems that actually depend on unicode characters may fail to work properly, or may work in a subtly different way. See for instance lambda-reader.

We invite you to embrace UTF-8 as the encoding for non-ASCII characters starting today, even without any explicit specification in your .asd files. Indeed, on some implementations and configurations, UTF-8 is already the :default, and loading your code may cause errors if it is encoded in anything but UTF-8. Therefore, even with the legacy behaviour, non-UTF-8 is guaranteed to break for some users, whereas UTF-8 is pretty much guaranteed not to break anywhere (provided you do not use a BOM), although it might be read incorrectly on some implementations. :utf-8 has been the default value of *default-encoding* since ASDF 3.

If you need non-standard character encodings for your source code, use the extension system asdf-encodings, by specifying :defsystem-depends-on ("asdf-encodings") in your defsystem. This extension system will register support for more encodings using the *encoding-external-format-hook* facility, so you can explicitly specify :encoding :latin1 in your .asd file. Using the *encoding-detection-hook* it will also eventually implement some autodetection of a file’s encoding from an emacs-style -*- mode: lisp ; coding: latin1 -*- declaration, or otherwise based on an analysis of octet patterns in the file. At this point, asdf-encoding only supports the encodings that are supported as part of your implementation. Since the list varies depending on implementations, we still recommend you use :utf-8 everywhere, which is the most portable (next to it is :latin1).

Recent versions of Quicklisp include asdf-encodings; if you’re not using it, you may get this extension using git: git clone https://gitlab.common-lisp.net/asdf/asdf-encodings.git or git clone git@gitlab.common-lisp.net:asdf/asdf-encodings.git. You can also browse the repository on https://gitlab.common-lisp.net/asdf/asdf-encodings.

When you use asdf-encodings, any .asd file loaded will use the autodetection algorithm to determine its encoding. If you depend on this detection happening, you should explicitly load asdf-encodings early in your build. Note that :defsystem-depends-on cannot be used here: by the time the :defsystem-depends-on is loaded, the enclosing defsystem form has already been read.

In practice, this means that the *default-encoding* is usually used for .asd files. Currently, this defaults to :utf-8, and you should be safe using Unicode characters in those files. This might matter, for instance, in meta-data about author’s names. Otherwise, the main data in these files is component (path)names, and we don’t recommend using non-ASCII characters for these, for the result probably isn’t very portable.