1Load Extension Plugin
2=====================
3
4Beets uses an SQLite database to store and query library information, which
5has support for extensions to extend its functionality. The ``loadext`` plugin
6lets you enable these SQLite extensions within beets.
7
8One of the primary uses of this within beets is with the `"ICU" extension`_,
9which adds support for case insensitive querying of non-ASCII characters.
10
11.. _"ICU" extension: https://www.sqlite.org/src/dir?ci=7461d2e120f21493&name=ext/icu
12
13Configuration
14-------------
15
16To configure the plugin, make a ``loadext`` section in your configuration
17file. The section must consist of a list of paths to extensions to load, which
18looks like this:
19
20.. code-block:: yaml
21
22    loadext:
23      - libicu
24
25If a relative path is specified, it is resolved relative to the beets
26configuration directory.
27
28If no file extension is specified, the default dynamic library extension for
29the current platform will be used.
30
31Building the ICU extension
32--------------------------
33This section is for **advanced** users only, and is not an in-depth guide on
34building the extension.
35
36To compile the ICU extension, you will need a few dependencies:
37
38 - gcc
39 - icu-devtools
40 - libicu
41 - libicu-dev
42 - libsqlite3-dev
43
44Here's roughly how to download, build and install the extension (although the
45specifics may vary from system to system):
46
47.. code-block:: shell
48
49    $ wget https://sqlite.org/2019/sqlite-src-3280000.zip
50    $ unzip sqlite-src-3280000.zip
51    $ cd sqlite-src-3280000/ext/icu
52    $ gcc -shared -fPIC icu.c `icu-config --ldflags` -o libicu.so
53    $ cp libicu.so ~/.config/beets
54