Advanced Deployment

Quick integration (CMake / qmake): Deployment. QML API after deploy: Quick Start.

Package contents

The release archive contains:

LNVK/
├── bin/
│   └── lndict-compiler      (dictionary compiler utility)
├── include/lnvk/
│   └── lnvk.h              (#include <lnvk>)
├── integration/
│   ├── LNVKConfig.cmake
│   └── lnvirtualkeyboard.pri
├── qml/Ln/VirtualKeyboard/
│   ├── liblnvirtualkeyboardplugin.so
│   └── qmldir
├── share/lnvirtualkeyboard/dictionaries/
│   ├── layouts.lnlay   (all keyboard layouts + input profiles — required)
│   ├── themes.lntheme  (bundled dark/light themes — required)
│   ├── *.trie          # IME dictionaries
│   ├── *.pred          # word prediction
│   ├── *.bigram        # bigram language models
│   ├── *.prism         # Pinyin prism
│   └── *.mtx           # connection cost matrix
├── share/lnvirtualkeyboard/fonts/
│   ├── Inter-Variable.ttf
│   ├── NotoSans*.ttf
│   └── NotoSansCJK*.otf
└── share/lnvirtualkeyboard/licenses/
    ├── OFL.txt
    ├── fonts-NOTICE.md
    ├── dictionaries-NOTICE.md
    └── (other third-party license texts)

Install footprint

On-disk sizes for a Release build. Dictionary files are memory-mapped at runtime; they do not add to the keyboard's heap footprint while idle.

Pass LANGUAGES to ln_virtual_keyboard_deploy or LNVK_LANGUAGES in qmake to ship only the dictionaries each active language needs (see Selecting languages). layouts.lnlay and themes.lntheme are always included when a language list is specified. Per-language profile and file lists: Languages.

Layouts and themes load from share/lnvirtualkeyboard/dictionaries/ at runtime (same path search as other dictionary files). QML keyboard components ship inside the plugin binary. Bundled keyboard fonts are optional: they ship as separate .ttf / .otf files under share/lnvirtualkeyboard/fonts/ and are registered at plugin load when that directory is present. The keyboard runs without them and falls back to fonts you provide.

Third-party licensing

The release bundles third-party fonts (share/lnvirtualkeyboard/fonts/) and dictionary data (share/lnvirtualkeyboard/dictionaries/). Full license texts and attribution NOTICEs ship under share/lnvirtualkeyboard/licenses/. If you redistribute the bundled fonts or dictionaries, ship those license files alongside them.

Fonts (optional)

Bundled fonts are a convenience, not a requirement. If FontPaths finds no font directory at plugin load, registration is skipped and the keyboard continues normally; there is no startup error.

When present, the plugin registers them with QFontDatabase::addApplicationFont during plugin initialization.

Using your own fonts instead of bundled discovery: call FontPaths::setHostFontFiles before engine.load().

#include <lnvk>

lnvk::qt::FontPaths::setHostFontFiles({
    "/opt/myapp/fonts/Inter-Variable.ttf",
    "/opt/myapp/fonts/NotoSansArabic-Regular.ttf",
    "/opt/myapp/fonts/NotoSansCJKsc-Regular.otf",
});

When setHostFontFiles is called, bundled directory discovery (LNVK_FONTS_DIR, install prefix, etc.) is not used: the host list is the sole source.

QML binds the resolved family read-only: font.family: Lnvk.effectiveFontFamily.

Font family resolution order:

1. Per-script Noto/Inter family for the active language if that family is registered
2. Inter for Latin if available
3. QGuiApplication::font() if it covers the active writing system
4. Empty string → Qt platform default

If you redistribute the bundled font files, include OFL.txt and fonts-NOTICE.md.

Dictionary data

Compiled dictionaries derive from the open data sources below. Per-artifact attribution is in dictionaries-NOTICE.md.

Dictionary data files that incorporate CC BY-SA inputs are distributed under CC BY-SA 4.0. This applies only to the data files, not to the plugin code or to applications that load the dictionaries at runtime.

Building custom prediction dictionaries

The package includes bin/lndict-compiler so you can generate .pred files without rebuilding the project.

# From your LNVK package root
./bin/lndict-compiler --flat my-words.txt prediction-en-custom.pred

--flat accepts one-word-per-line text files or TSV with explicit frequency (word<TAB>word<TAB>frequency).

Deploy resulting .pred files into share/lnvirtualkeyboard/dictionaries/ and configure custom prediction mode in your app. See the Configuration guide.

Install layout

Deploy helpers copy QML and data under an install root. The plugin locates assets relative to QCoreApplication::applicationDirPath() (the directory containing your executable).

Install prefix (default)

Use when the binary lives in a bin/ subdirectory. This is the default for ln_virtual_keyboard_deploy() and lnvirtualkeyboard.pri.

<prefix>/
├── bin/myapp                 ← executable
├── qml/Ln/VirtualKeyboard/   ← plugin + qmldir
└── share/lnvirtualkeyboard/
    ├── dictionaries/         ← layouts.lnlay, themes.lntheme, *.pred, …
    ├── fonts/                ← optional
    └── licenses/             ← OFL, NOTICEs, upstream license texts

Runtime lookup (dictionaries): <app_dir>/../share/lnvirtualkeyboard/dictionaries/
QML import path: applicationDirPath() + "/../qml"

set_target_properties(myapp PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
ln_virtual_keyboard_deploy(myapp LANGUAGES en fr FONTS)

Flat prefix

Use when the binary sits directly under the install root (no bin/).

<prefix>/
├── myapp                     ← executable
├── qml/Ln/VirtualKeyboard/
└── share/lnvirtualkeyboard/
    ├── dictionaries/
    ├── fonts/                ← optional
    └── licenses/

Runtime lookup (dictionaries): <app_dir>/share/lnvirtualkeyboard/dictionaries/
QML import path: applicationDirPath() + "/qml"

ln_virtual_keyboard_deploy(myapp PREFIX "$<TARGET_FILE_DIR:myapp>" LANGUAGES en fr FONTS)

qmake: set LNVK_DEPLOY_PREFIX = $$OUT_PWD before including lnvirtualkeyboard.pri.

Custom locations

If your tree does not match either layout, set absolute paths at runtime or in the environment:

See Manual deployment for search order details.

CMake options

Full CMake example (same as the quick guide, with optional knobs):

cmake_minimum_required(VERSION 3.16)
project(MyApp LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Quick)
set(LNVK_DIR "/path/to/LNVK/integration")
find_package(LNVK REQUIRED CONFIG)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE Qt6::Quick)

set_target_properties(myapp PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
ln_virtual_keyboard_deploy(myapp LANGUAGES en fr FONTS)

In C++, add the QML import path before engine.load() (install-prefix layout):

engine.addImportPath(QCoreApplication::applicationDirPath() + QStringLiteral("/../qml"));

For a flat prefix, use "/qml" instead, or pass PREFIX "$<TARGET_FILE_DIR:myapp>" to ln_virtual_keyboard_deploy.

cmake -B build -DCMAKE_PREFIX_PATH="/path/to/LNVK"
cmake --build build

Selecting languages

By default all dictionaries are deployed. Deploy only specific languages:

ln_virtual_keyboard_deploy(myapp LANGUAGES en fr)

This always copies layouts.lnlay (~208 KiB, all keyboard layouts and bundled input profiles), themes.lntheme (dark/light theme data), and the full share/lnvirtualkeyboard/licenses/ tree in addition to per-language dictionary files. License files are not read at runtime but are required if you redistribute bundled fonts or dictionary data (see Third-party licensing).

Missing either layouts.lnlay or themes.lntheme causes startup errors such as Failed to load layout "en" or Failed to load theme "dark", and profile configuration may be sanitized (setActiveProfileIds: active profile ids were corrected).

qmake options

Include the .pri file from your .pro:

include(/path/to/LNVK/integration/lnvirtualkeyboard.pri)

This copies the QML plugin and dictionaries to the build output directory.

To deploy only specific languages:

LNVK_LANGUAGES = en fr
include(/path/to/LNVK/integration/lnvirtualkeyboard.pri)

Optional bundled fonts:

LNVK_DEPLOY_FONTS = 1
include(/path/to/LNVK/integration/lnvirtualkeyboard.pri)

Otherwise register fonts from C++ with FontPaths::setHostFontFiles.

Manual deployment

Plugin files

Copy Ln/VirtualKeyboard/ so the QML engine can find it:

• Qt's QML import path: copy Ln/ into your Qt installation's qml/ directory.
• Custom location: place Ln/ anywhere and point QML2_IMPORT_PATH to its parent:

export QML2_IMPORT_PATH=/opt/myapp/lib/qml
# Plugin must be at /opt/myapp/lib/qml/Ln/VirtualKeyboard/

Dictionary files

The plugin resolves the dictionaries directory (must contain layouts.lnlay) in order:

1. LNVK_DICT_DIR environment variable
2. Compile-time LNVK_DICT_DIR set when the plugin is built/installed with a fixed prefix
3. <app_dir>/share/lnvirtualkeyboard/dictionaries/ — flat prefix
4. <app_dir>/../share/lnvirtualkeyboard/dictionaries/ — install prefix (default)
5. <app_dir>/../data/dictionaries/
6. <app_dir>/data/dictionaries/
7. Walk up from <app_dir> looking for data/dictionaries/ containing layouts.lnlay

Individual dictionary files (for example prediction-en.pred) are opened inside that directory.

Font files (optional)

If you use the bundled fonts, copy share/lnvirtualkeyboard/fonts/ next to your app (same layout as dictionaries):

<app_dir>/../share/lnvirtualkeyboard/fonts/
    Inter-Variable.ttf
    NotoSans*.ttf
    NotoSansCJK*.otf

Or point LNVK_FONTS_DIR at any directory containing those files. FontPaths search order when auto-locating bundled fonts:

1. LNVK_FONTS_DIR environment variable (absolute path to the fonts directory)
2. Compile-time LNVK_FONTS_DIR
3. <app_dir>/share/lnvirtualkeyboard/fonts/ — flat prefix
4. <app_dir>/../share/lnvirtualkeyboard/fonts/ — install prefix
5. <app_dir>/../fonts/
6. <app_dir>/fonts/
7. Walk up from <app_dir> looking for a fonts/ directory that contains Inter-Variable.ttf

To use application fonts instead, skip this directory and call FontPaths::setHostFontFiles with your font file paths before plugin init. Font files should use the same Qt family names as the bundled set (Noto/Inter) so per-script resolution works automatically.

Embedded deployment

Use the install prefix or flat prefix layout on the device. Example (install prefix):

/opt/myapp/bin/myapp
/opt/myapp/qml/Ln/VirtualKeyboard/
/opt/myapp/share/lnvirtualkeyboard/dictionaries/
/opt/myapp/share/lnvirtualkeyboard/fonts/   (optional)
/opt/myapp/share/lnvirtualkeyboard/licenses/

Set LNVK_FONTS_DIR only when using bundled fonts from a non-standard path.

Available language codes

Pass these codes to LANGUAGES (CMake) or LNVK_LANGUAGES (qmake) to ship only the dictionaries you need:

Qt version compatibility

The plugin is compatible with Qt 5.15 and Qt 6.x. Use the release matching your Qt major version.