Starting with ASDF 2.21, components accept a
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,
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
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
that always returns the contents of *default-encoding*.
*default-encoding* is bound to
:utf-8 by default
(before ASDF 3, the default was
Whichever encoding is returned must be a portable keyword,
that will be translated to an implementation-specific external-format designator
which itself simply calls the function specified *encoding-external-format-hook*;
that function by default is
that only recognizes
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
:utf-8, independently from
whatever configuration the user may be using.
Thus, system authors can now rely on
being used while compiling their files,
even if the user is currently using
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
and Unicode characters will be read as multi-character mojibake.
To detect such situations, UIOP will push the
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
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 itself only recognizes one encoding beside
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,
:asdf-unicode is absent, and
:default external-format is used
to read even source files declared as
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
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
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
This extension system will register support for more encodings using the
so you can explicitly specify
in your .asd file.
*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
which is the most portable (next to it is
Recent versions of Quicklisp include
if you’re not using it, you may get this extension using git:
git clone https://gitlab.common-lisp.net/asdf/asdf-encodings.git
git clone email@example.com:asdf/asdf-encodings.git.
You can also browse the repository on
When you use
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.
:defsystem-depends-on cannot be used here: by the time
:defsystem-depends-on is loaded, the enclosing
defsystem form has already been read.
In practice, this means that the
is usually used for .asd files.
Currently, this defaults to
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.