librime: the C++ core behind Rime input methods, and how to build it

What librime is, and the problem it removes

librime is the core library of the Rime Input Method Engine, written in cross-platform C++ and released under the 3-Clause BSD License. It is not an input method you install and start typing with. The README lists official frontends for three desktop platforms (ibus-rime on Linux, Squirrel on macOS, Weasel on Windows) and a long community list covering Android, iOS, Emacs, Vim, tmux, zsh, Readline and the web. Every one of those is a separate project that links against this library.

The problem it solves is the one every Chinese input method author hits: segmentation, dictionary lookup, candidate ranking, user history and conversion between Traditional and Simplified Chinese are the same work regardless of which window toolkit draws the candidate list. librime packages that work once. The README describes it as covering features found in a large variety of Chinese input methods, both shape-based and phonetic-based, so the same engine can back a Pinyin scheme and a Cangjie scheme without a rewrite.

It is aimed at people writing an input method or embedding one, not at end users. If you are choosing a keyboard for your desktop, you are looking at the wrong repository.

How the engine works: schemas, spelling algebra and the YAML DSL

The mechanism that matters most is the Rime input schema, which the README calls a DSL in YAML syntax for fast trying out innovative ideas of input method design. A schema is a data file, not code. It describes how keystrokes map to syllables, which dictionary to consult and how candidates are ordered. That means a new input method design can be tested by editing YAML rather than recompiling the engine.

Two supporting mechanisms sit under that. Spelling Algebra creates variant spellings, which the README singles out as especially useful for Chinese dialects: one syllable can be typed several ways and still resolve to the same lookup. Chord typing with a generic Qwerty keyboard is supported natively, so schemes that press several keys at once do not need a special driver. The related combo-pinyin work is described in the project wiki as an innovative chord-typing practice for Pinyin.

Conversion between Traditional Chinese, Simplified Chinese and other regional standards is delegated to OpenCC rather than implemented in the engine. That is a deliberate dependency choice: it keeps the conversion tables in a project that maintains them, and it means OpenCC appears in both the build and runtime dependency lists.

The repository layout reflects this split. include/ holds the public headers, src/ the engine, data/ and share/ the shipped data, plugins/ the optional modules, and sample/ a small CMake project with its own README, source, tests and tools directory. The sample directory is the most direct answer to how a host application is expected to link against the library.

Installing librime on Ubuntu and running the sample

The README gives the Linux path as two commands, and points macOS and Windows users at README-mac.md and README-windows.md instead, because those platforms need different setup.

make
sudo make install

The Makefile sets prefix to $(DESTDIR)/usr on Linux, so make install places the library under /usr unless you override prefix. Build dependencies are a C++17 compiler, cmake>=3.12, libboost>=1.74, libleveldb, libmarisa, libopencc>=1.0.2 and libyaml-cpp>=0.5. libglog and libgtest are marked optional, which means logging can be compiled out and the test suite is not required to build the library. The same dependencies reappear at runtime, so a binary built here will not run on a machine missing LevelDB, marisa-trie, OpenCC or yaml-cpp.

If you prefer to build in a container, the repository's Dockerfile shows the full sequence against Debian 12.1, including the package list and the plugin install step.

git clone https://github.com/rime/librime
cd librime
bash install-plugins.sh \
  rime/librime-charcode \
  hchunhui/librime-lua \
  lotem/librime-octagram \
  rime/librime-predict

install-plugins.sh pulls the plugin repositories listed as arguments. Three of those four are the ones the README documents under Plugins: librime-lua for Lua scripting, librime-octagram for the language model, and librime-predict for next-word prediction. The Dockerfile then configures with CMake, builds and runs ctest:

cmake -B build -G Ninja \
  -DCMAKE_BUILD_TYPE:STRING=Release \
  -DENABLE_LOGGING:BOOL=ON \
  -DBUILD_TEST:BOOL=ON \
  -DBUILD_STATIC:BOOL=OFF \
  -DBUILD_SHARED_LIBS:BOOL=ON
cmake --build build
cd build && ctest

Those flags are copied from the Dockerfile, not invented here. For a first real use, look at sample/ rather than at the engine internals: it is a self-contained CMake project with its own README and test directory, and it exists precisely to show how a host program consumes the library. The README does not walk through sample/ step by step, so expect to read its CMakeLists.txt to see which targets it links.

Plugins, including Lua, and what they cost you

The plugin list is where librime's extensibility becomes concrete. librime-lua adds Lua scripting, which is the usual way to add per-schema behaviour without touching C++. librime-octagram adds a language model, and librime-predict predicts the next word. Two entries are explicitly marked Deprecated: librime-charcode, which the README says depends on boost::locale and ICU, and librime-legacy, described as a legacy module with GPL-licensed code.

That last point is the one to read twice. The engine itself is BSD-3-Clause, but the README states plainly that librime-legacy contains GPL-licensed code. Linking a GPL module into your build changes the terms you distribute under, and the README does not offer a compatibility analysis. If your product ships as a closed binary, the safe reading is to leave the deprecated legacy module out; the project gives you no statement to the contrary.

The plugin mechanism also has a build-order consequence. install-plugins.sh fetches plugin sources into plugins/ before the CMake configure step, which is why the Dockerfile runs it first. A plugin added after the build directory is configured will not appear until you re-run CMake. The README does not document a plugin discovery path at runtime, so the assumption is that plugins are compiled in.

Where librime is the wrong dependency

The clearest limitation is stated by the project's own structure: librime has no user interface. It does not draw candidates, does not own a global hotkey, and does not integrate with any desktop input method framework. If you need a working IME on a Linux desktop, ibus-rime or fcitx5-rime is the answer, and librime is a transitive dependency you never touch directly.

The second limitation is the dependency weight. Boost, LevelDB, marisa-trie, OpenCC and yaml-cpp appear in both the build and runtime lists. For a small application that only needs Pinyin-to-Hanzi conversion, that is a large footprint to carry for a feature you could get from a much smaller library. The engine is sized for people who want the whole input method pipeline, including user history and schema-driven customization.

The third is platform coverage. The README offers build instructions for macOS and Windows in separate files and a Makefile path for Linux, FreeBSD, OpenBSD and Termux. Anything else is on you. If your target is a platform without a maintained frontend, you are writing that frontend yourself, and the README does not describe what that involves beyond pointing at the sample project and the frontend list.

Finally, the release channel deserves attention. The most recent release listed is a nightly build dated 2026-08-26, with 1.17.0 dated 2026-06-06 and 1.16.1 dated 2026-01-20. The last push to master was 2026-08-26. Nightly builds are not a stability promise, and the README does not document a rollback or downgrade procedure if a nightly regresses.

Alternatives, and the actual difference in approach

The most instructive comparison is with the frontends librime already has, because it clarifies the split. ibus-rime is an IBus engine: it plugs into the IBus daemon that most GNOME and many other Linux desktops already run, and it handles the desktop integration, the candidate window and the session. librime supplies the conversion. Choosing ibus-rime means accepting IBus as your input framework; building on librime directly means writing that layer yourself.

Among libraries, the notable alternative in the same space is the input method framework that fcitx5 frontends use, fcitx5-rime, which the README lists alongside ibus-rime as an official frontend. The difference is not in the engine, since fcitx5-rime also uses librime, but in the surrounding framework: fcitx5 has its own module system and its own candidate rendering, and it supports a broader set of non-Chinese input methods in the same daemon. If you want one input framework for everything, that matters. If you only care about Rime schemas, both frontends reach the same engine.

For the narrower problem of scripted behaviour inside a schema, librime-lua is the alternative to writing C++ plugins, and it is the reason search interest clusters around Lua. It trades the compile step for an interpreter dependency, which the Dockerfile reflects by installing liblua5.4-dev.

Maintenance, upgrade cost and licence

The repository is not archived. The last push to master was 2026-08-26, and the most recent release listed is a nightly build of the same date, so the project is moving. That is a fact about activity, not a guarantee about stability, and the two stable tags listed (1.17.0 and 1.16.1) are the ones to pin against if you need reproducibility.

Upgrade cost is dominated by the ABI. librime is a C++ library, and the CMake options in the Dockerfile show that static and shared builds are both supported (BUILD_STATIC and BUILD_SHARED_LIBS). A shared build means your application is exposed to whatever the installed librime provides; a static build means you own the dependency graph, including Boost and OpenCC, inside your binary. Neither is free. The repository also ships a bump-version.sh script and a cliff.toml configuration, which suggests release notes are generated from commit history, so CHANGELOG.md is the place to check before upgrading.

On licensing: the project is BSD-3-Clause, which is permissive and generally compatible with closed-source distribution. The caveats are the dependencies and the deprecated plugins. marisa-trie is listed as BSD 2-Clause with LGPL 2.1, OpenCC as Apache 2.0, Boost under the Boost Software License, and yaml-cpp under MIT. librime-legacy is GPL-licensed per the README. This is a description of what the repository states, not legal advice; if you redistribute a binary, check each dependency against your own distribution model.

Editorial conclusion

Adopt librime if you are building an input method frontend or embedding Chinese text input into an application and you accept a C++17 toolchain plus Boost, LevelDB, marisa-trie, OpenCC and yaml-cpp as runtime dependencies. Do not adopt it if you want a working keyboard today: install ibus-rime, Squirrel or Weasel instead, since librime ships no user interface. Before committing, verify that your target platform is covered by README-mac.md or README-windows.md, that the schema you need exists, and that you are willing to track the nightly build channel, which is the most recent release listed.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes