Libchewing
libchewing - The intelligent phonetic input method library
Install / Use
/learn @chewing/LibchewingREADME
_ _
___| |__ _____ _(_)_ __ __ _
/ __| '_ \ / _ \ \ /\ / / | '_ \ / _` |
| (__| | | | __/\ V V /| | | | | (_| |
\___|_| |_|\___| \_/\_/ |_|_| |_|\__, |
|___/
https://chewing.im/
libchewing - The intelligent phonetic input method library
The Chewing (酷音) is an intelligent phonetic input method (Zhuyin/Bopomofo) and is one of the most popular choices for Traditional Chinese users. Chewing was inspired by other proprietary intelligent Zhuyin input methods on Microsoft Windows, namely Wang-Xin by Eten, Microsoft New Zhuyin, and Nature Zhuyin (aka Going). The Chewing developer maintains the project as a fully open-source effort, positioning it as a leading libre intelligent phonetic solution among major operating environments.
- Website: https://chewing.im/
- Issue tracker: https://github.com/chewing/libchewing/issues
- Mailing lists:
- Development: https://groups.google.com/group/chewing-devel
- General: https://groups.google.com/group/chewing
- Matrix:
- Development: https://matrix.to/#/#libchewing:matrix.org
- General: https://matrix.to/#/#chewing-users:matrix.org
- Build Status:
- Github Actions:
- Coverity Scan:
- Codecov:
- Github Actions:
libchewing releases can be verified with the following OpenPGP public key
083B3CAB64267E5BAB7159673EF0C673DADCC30C Libchewing Signing Key <release@chewing.im>
or the following minisign public key
RWRzJFnXiLZleAyCIv1talBjyRewelcy9gzYQq9pd3SKSFBPoy57sf5s
Status
1. System bridge integration
Chewing has been integrated into various input frameworks in Unix-like systems and even in Microsoft Windows and Android. On these systems, the Chewing package is typically divided into two parts: libchewing, which manages the actual character selection logic, and an input framework interface for display and preference settings.
- The active integration:
- The inactive one: SCIM, standalone Microsoft Windows 32/64-bit (windows-chewing), mozc, uim, ucimf, JMCCE, xcin, IIIMF, standalone MacOS X (SpaceChewing), Sun's Java Desktop System Input Method Framework, OpenVanilla Input Method Framework (previous than version 1.0), and OXIM.
2. Support phonetic keyboard layout
- DaChen (default)
- Hsu
- IBM
- Gin-Yieh
- Eten
- Eten 26 keys
- Dvorak
- Dvorak Hsu
- HanYu PinYin
- Taiwan Huayu Luomapinyin
- MPS2 Pinyin
- Colemak
- Colemak-DH ANSI
- Colemak-DH Ortholinear
- Workman
3. External and unmerged projects
libchewing provides a straightforward API and design, enabling third-party projects to deploy innovative features. Here are some examples:
- FreeArray: utilizing libchewing for selecting phrases of Array input method.
- CitC (Chewing in the Cloud): extending cloud services for real-time training and phrase selection based on Chewing IM.
- KindleChewing: Chewing IM for Kindle DX device
- NTNU-Master Input Method: A faster Chinese IM based on windows-chewing
Build and Installation
Prerequisites
The following tools are used to build libchewing. Not all tools are necessary during building. For example, if the compiler you used is clang, gcc & Visual Studio are not needed. The versions listed here is the minimal version known to build libchewing. If any tools you use below this version, libchewing might not be built.
- Build tools:
- cmake >= 3.21.0
- Toolchain / IDE:
- clang >= 3.2 OR gcc >= 4.6.3
- Rust >= 1.88
- Build Tools for Visual Studio 2022 for MSVC build
- Vcpkg for MSVC build
- Documentation tools:
- texinfo >= 4.8
Build via CMake
Use the default preset:
cmake --preset default --install-prefix /usr
cmake --build build
cmake --build build -t test
cmake --build build -t install
Build the rust implementation:
cmake --preset rust-release --install-prefix /usr
cmake --build build
cmake --build build -t test
cmake --build build -t install
Check other supported presets:
cmake --list-presets
Cross-build
Define a cmake-toolchains file to cross-compile.
Example cross-build instructions:
cmake --preset default --toolchain arm-none-linux-gnueabi.cmake
cmake --build build
Build on Windows with Build Tools for Visual Studio 2022
To build libchewing on Windows and link to other program build from MSVC, you need to use the MSVC toolchain. To install the build environment:
Open admin prompt cmd.exe
winget install Microsoft.VisualStudio.2022.BuildTools
winget install Ninja-build.Ninja
winget install Kitware.CMake
winget install Rustlang.Rustup
Optional development tools
winget install Git.Git
winget install VSCodium.VSCodium
Reboot, then open Visual Studio Installer and install C/C++ components.
Open x64 Native Tools Command Prompt for VS 2022
rustup default stable
cmake -G Ninja --preset rust
Now you have the build environment for libchewing. You can follow the installation steps to build with cmake.
Build on macOS
To build libchewing on macOS, you will need tools listed in the requirements. Since macOS does not ship with these tools, building them from source can be a tricky task.
A simple way to install these tools is through Homebrew, a package manager for macOS. Once Homebrew is installed, run the following commands to install the tools you need:
brew install cmake
brew install rustup
rustup default stable
Minimum Supported Rust Version
To ensure libchewing can be built on various Linux distributions, we use the minimum rust version available from major distributions' next release branch. Data source: https://repology.org/project/rust/versions
- Current MSRV: 1.88.0 (Debian unstable)
Usage
Chewing enables users to input Chinese by its pronunciation, using either [Bopomofo/Zhuyin][1] or [Hanyu pinyin][2]. It also supports Chinese punctuation marks, as well as both normal and full-shape numbers and the English alphabet.
The following sections are based on the assumption that you are using the default configuration. This includes the default/DaChen Bopomofo keyboard layout on an en_US keyboard, along with the default key-binding.
Glossary
Preedit Buffer: This is the area where your typing is stored before being sent to the applications (such as Firefox) you are using.
Mode: This determines how Chewing responds to keyboard input.
Editing mode
This mode facilitates the typing of normal Chinese characters and punctuation and is typically the default working mode.
In this mode, alphanumeric characters and punctuation marks are interpreted as Bopomofo symbols or punctuation marks. When these symbols form Chinese characters, the system chooses the most appropriate character based on the context in the preedit buffer.
Entering complete Chinese sentences is advantageous as it allows the system to perform auto-correction. To confirm the output, pressing Enter will commit the characters in the preedit buffer.
In case of errors, characters can be selected by moving the cursor with {Left} or {Right}, followed by pressing {Down} to enter Candidate Selection mode for word choice.
Auto-correction for a specific phrase can be overridden by pressing {Tab} at the end of the sentence.
Memorization of 2, 3, or 4-word phrases is possible by pressing {Ctrl-2}, {Ctrl-3}, or {Ctrl-4} at the phrase's end.
The behavior of the Shift key changes in this mode. Using Shift with an alphanumeric key outputs corresponding full-shape Chinese symbols if "Easy Symbol Input" is enabled, or outputs corresponding half-shape lowercase English alphabets if "Easy Symbol Input" is disabled.
For inputting Chinese symbols, aside from enabling "Easy Symbol Input" mode, pressing {Ctrl-1} or {`} opens a symbol selection dialog. After selecting the category, the {Down} key can be used to choose symbols as one would for characters.
Key binding API name Functionality
----------- -------- -------------
Caps Lock chewing_handle_Capslock Toggle Temporary English sub-mode
Down chewing_handle_Down Enter Candidate Selection mode
Shift-Space chewing_handle_ShiftSpace Toggle Half/Full Shape sub-mode
Enter chewing_handle_Enter Commit the content in preedit buffer
to active application window
Tab chewing_handle_Tab Break the auto-correction.
Ctrl-1 chewing_handle_CtrlNum O
