mirror of
https://github.com/keymanapp/keyman.git
synced 2026-10-06 14:07:32 +00:00
docs(linux): Move Linux documentation
This change moves the Linux developer documentation to the new location `docs/linux` as discussed in our planning meeting.
This commit is contained in:
Eberhard Beilharz
parent
f79e8f4f2a
commit
5cf88878da
7 changed files with 416 additions and 400 deletions
169
docs/linux/README.md
Normal file
169
docs/linux/README.md
Normal file
|
|
@ -0,0 +1,169 @@
|
|||
# Keyman for Linux
|
||||
|
||||
## Projects
|
||||
|
||||
- [keyman-config](../../linux/keyman-config) - km-config and some other tools to install, uninstall
|
||||
and view information about Keyman keyboard packages.
|
||||
- [ibus-keyman](../../linux/ibus-keyman) - IBUS integration to use .kmp Keyman keyboards
|
||||
- [core](../../core) - common keyboardprocessor library
|
||||
- [legacy/kmflcomp](../../linux/legacy/kmflcomp) - KMFL keyboard compiler
|
||||
- [legacy/libkmfl](../../linux/legacy/libkmfl) - older KMFL core library
|
||||
- [legacy/ibus-kmfl](../../linux/legacy/ibus-kmfl) - IBUS integration to use KMFL
|
||||
|
||||
See [license information](../../linux/LICENSE.md) about licensing.
|
||||
|
||||
## Linux Requirements/Setup
|
||||
|
||||
- It is helpful to be using the [packages.sil.org](http://packages.sil.org) repo
|
||||
|
||||
- Install packages required for building and developing Keyman for Linux
|
||||
|
||||
```bash
|
||||
sudo apt install cdbs debhelper libx11-dev autotools-dev build-essential \
|
||||
dh-autoreconf flex bison libibus-1.0-dev python3-setuptools meson \
|
||||
libjson-glib-dev libgtk-3-dev libxml2-utils help2man python3-lxml \
|
||||
python3-magic python3-numpy python3-pil python3-pip python3-qrcode \
|
||||
python3-requests python3-requests-cache python3 python3-gi dconf-cli \
|
||||
dconf-editor cargo python3-dbus gir1.2-webkit2-4.0 ibus libglib2.0-bin \
|
||||
liblocale-gettext-perl xvfb xserver-xephyr metacity mutter
|
||||
```
|
||||
|
||||
## Compiling from Command Line
|
||||
|
||||
### Build script
|
||||
|
||||
#### Installing for ibus to use ibus-keyman
|
||||
|
||||
- The process to build and install everything is:
|
||||
|
||||
- `make reconf` to create the build system and set the version
|
||||
- `make fullbuild` to configure and build
|
||||
- `sudo make install` to install to `/usr/local`
|
||||
|
||||
- Some of the files must be installed to `/usr/share/` so `make install` must be run as `sudo`.
|
||||
|
||||
To do this run `sudo make install`
|
||||
|
||||
- This will install to `/usr/local`
|
||||
- and `/usr/share/ibus/component/keyman.xml` and `/usr/share/keyman/icons`
|
||||
|
||||
- If you already have the ibus-keyman package installed then it will move the file `/usr/share/ibus/component/keyman.xml` to `/usr/share/doc/ibus-keyman/`
|
||||
|
||||
- run `sudo make uninstall` to uninstall everything and put it back again
|
||||
|
||||
#### Tmp install
|
||||
|
||||
Used by TC for validating PRs
|
||||
|
||||
Run `make tmpinstall` to build and install **keyboardprocessor** and **ibus-keyman** to `/tmp/keyman`
|
||||
|
||||
This is only for testing the build, not for running **ibus-keyman** in ibus
|
||||
|
||||
### Manually
|
||||
|
||||
- **ibus-keyman** requires headers and lib from **keyboardprocessor**
|
||||
|
||||
So
|
||||
|
||||
- **keyboardprocessor** must be built before **ibus-keyman**
|
||||
|
||||
For each project run `./configure && make && make install`.
|
||||
|
||||
You may prefer to create a different directory to build in and run configure from there e.g.
|
||||
|
||||
```bash
|
||||
mkdir ../build-ibus-keyman
|
||||
cd ../build-ibus-keyman
|
||||
../ibus-keyman/configure
|
||||
make
|
||||
make install
|
||||
```
|
||||
|
||||
## Continuous integration
|
||||
|
||||
Teamcity PR builds will run `make tmpinstall`
|
||||
|
||||
Master builds run `make tmpinstall` and create source packages
|
||||
|
||||
Nightly and release builds upload the most recent new master build to <https://downloads.keyman.com>
|
||||
|
||||
## Building packages
|
||||
|
||||
See [Linux packaging doc](packaging.md)
|
||||
for details on building Linux packages for Keyman.
|
||||
|
||||
## Testing
|
||||
|
||||
### keyman-config
|
||||
|
||||
The unit tests can be run with the following command:
|
||||
|
||||
```bash
|
||||
cd linux/keyman-config
|
||||
./run-tests.sh
|
||||
```
|
||||
|
||||
### ibus-keyman
|
||||
|
||||
If you want to run the ibus-keyman tests with Wayland, you'll have to
|
||||
have `mutter` installed (version >=40). Otherwise you'll only be able
|
||||
to run the tests with X11.
|
||||
|
||||
The tests can be run with the following command:
|
||||
|
||||
```bash
|
||||
cd linux/ibus-keyman/tests
|
||||
./run-tests
|
||||
```
|
||||
|
||||
The `run-tests` script accepts different arguments which can be seen with
|
||||
`./run-tests --help`.
|
||||
|
||||
## Running Keyman for Linux
|
||||
|
||||
### Setting up Ibus
|
||||
|
||||
Ibus should be running on a default install of Ubuntu
|
||||
|
||||
You may want to install extra packages to get other ibus input methods e.g **ibus-unikey** for VN
|
||||
|
||||
Run `ibus restart` after installing any of them
|
||||
|
||||
### Getting a Keyman keyboard
|
||||
|
||||
- After installing a Keyman keyboard usually ibus will be restarted automatically so that ibus will
|
||||
look for the new keyboard. If for whatever reason the keyboard doesn't show up in the system
|
||||
keyboard list, you can manually run `ibus restart`.
|
||||
|
||||
### Activating a Keyman keyboard
|
||||
|
||||
Keyman tries to activate the keyboard automatically. If you want to activate it for a different
|
||||
language, you can do so by following the steps below.
|
||||
|
||||
#### GNOME3 (focal and bionic default, also newer Ubuntu versions)
|
||||
|
||||
- Click the connection/sound/shutdown section in the top right. Then the tools icon for Settings.
|
||||
|
||||
- In `Language and Region` click `+` to add a keyboard.
|
||||
- Click the 3 dots expander then search for "Other" and click it
|
||||
- The Keyman keyboards should be listed here to choose
|
||||
|
||||
- Use `Win-space` to switch between keyboards.
|
||||
|
||||
#### Cinnamon (wasta default)
|
||||
|
||||
- Open `Menu` and find `IBus Keyboards` (`IBus Preferences`) and run it
|
||||
- Make sure `Show icon on system tray` is checked
|
||||
- Select the tab `Input Method`.
|
||||
- Click `Add` to add a keyman keyboard.
|
||||
- Click the 3 dots expander then search for "Other" and click it
|
||||
- The Keyman keyboards should be listed here to choose
|
||||
|
||||
#### MATE (alternative)
|
||||
|
||||
- Open `System-> Preferences -> Other -> IBus Preferences`.
|
||||
- Make sure `Show icon on system tray` is checked
|
||||
- Select the tab `Input Method`.
|
||||
- Click `Add` to add a keyman keyboard.
|
||||
- Click the 3 dots expander then search for "Other" and click it
|
||||
- The Keyman keyboards should be listed here to choose
|
||||
33
docs/linux/ibus-keyman.md
Normal file
33
docs/linux/ibus-keyman.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
# Keyman engine for IBus
|
||||
|
||||
All commands to be run in `linux/ibus-keyman`.
|
||||
|
||||
Source code for Keyman engine for IBus is in [linux/ibus-keyman](../../linux/ibus-keyman/).
|
||||
|
||||
## Requirements
|
||||
|
||||
You need autoconf, autopoint, gettext, automake and libtool to generate the build system.
|
||||
|
||||
Run `./autogen.sh` to run them.
|
||||
|
||||
## Building
|
||||
|
||||
```bash
|
||||
./autogen.sh
|
||||
./configure
|
||||
make
|
||||
sudo make install
|
||||
```
|
||||
|
||||
For a debug build:
|
||||
|
||||
```bash
|
||||
./configure CPPFLAGS=-DG_MESSAGES_DEBUG CFLAGS="-g -O0" CXXFLAGS="-g -O0"
|
||||
```
|
||||
|
||||
To use the header files from the source repo, you need to specify paths to the include files in core:
|
||||
|
||||
```bash
|
||||
./configure CPPFLAGS="-DG_MESSAGES_DEBUG -I../../core/build/arch/debug/include/ -I../../common/include/ -I../../core/include/" \
|
||||
CFLAGS="-g -O0" CXXFLAGS="-g -O0"
|
||||
```
|
||||
209
docs/linux/keyman-config.md
Normal file
209
docs/linux/keyman-config.md
Normal file
|
|
@ -0,0 +1,209 @@
|
|||
# Linux km-config
|
||||
|
||||
Code for `km-config` is in [linux/keyman-config](../../linux/keyman-config/).
|
||||
|
||||
## Preparing to run
|
||||
|
||||
If you are running from the repo or installing keyman-config manually rather than from a package
|
||||
then you will need to:
|
||||
|
||||
```bash
|
||||
sudo apt install python3-lxml python3-magic python3-numpy python3-qrcode python3-pil \
|
||||
python3-requests python3-requests-cache python3 python3-gi gir1.2-webkit2-4.0 dconf-cli \
|
||||
python3-setuptools python3-pip python3-dbus ibus libglib2.0-bin liblocale-gettext-perl
|
||||
```
|
||||
|
||||
Either `python3-raven` or `python3-sentry-sdk` (>= 1.4) is required as well. On Ubuntu 22.04 and later run:
|
||||
|
||||
```bash
|
||||
sudo apt install python3-sentry-sdk
|
||||
```
|
||||
|
||||
To install it on Ubuntu 18.04 and earlier run:
|
||||
|
||||
```bash
|
||||
sudo apt install python3-raven
|
||||
```
|
||||
|
||||
For Ubuntu versions that don't provide `python3-raven` but instead provide
|
||||
`python3-sentry-sdk` in a too old version (i.e. Ubuntu 20.04):
|
||||
Install `python3-sentry-sdk` from `packages.sil.org`,
|
||||
or install it with pip:
|
||||
|
||||
```bash
|
||||
pip3 install sentry-sdk
|
||||
```
|
||||
|
||||
Run the script `./createkeymandirs.sh` to create the directories for these programs to
|
||||
install the packages to.
|
||||
|
||||
Also copy and compile the GSettings schema:
|
||||
|
||||
```bash
|
||||
cd keyman_config
|
||||
sudo cp com.keyman.gschema.xml /usr/share/glib-2.0/schemas
|
||||
sudo glib-compile-schemas /usr/share/glib-2.0/schemas
|
||||
```
|
||||
|
||||
### Standards data file
|
||||
|
||||
Running `km-config` requires a language tag mapping file
|
||||
`keyman_config/standards/lang_tags_map.py`. This file gets generated during a package
|
||||
build, and also when running `make`.
|
||||
|
||||
## Installing manually from the repo
|
||||
|
||||
`make && sudo make install` will install locally to `/usr/local`.
|
||||
|
||||
`pip3 help install` will give you more install options.
|
||||
|
||||
To uninstall you can run `sudo make uninstall`.
|
||||
|
||||
## Things to run from the command line
|
||||
|
||||
### km-config
|
||||
|
||||
`./km-config`
|
||||
|
||||
This displays a configuration panel that shows the currently installed Keyman keyboard packages and can download and install additional keyboards.
|
||||
|
||||
#### Buttons
|
||||
|
||||
* `Uninstall` - uninstall selected keyboard
|
||||
* `About` - show information about selected keyboard
|
||||
* `Help` - display help documentation about selected keyboard
|
||||
* `Options` - display options.htm form for setting keyboard options
|
||||
|
||||
-----------------------------------
|
||||
|
||||
* `Refresh` - useful if you install or uninstall on the commandline while running km-config.
|
||||
* `Download` - runs `DownloadKmpWindow` (see below)
|
||||
* `Install` - opens a file choose dialog to choose a kmp file to install and bring up the `InstallKmpWindow` for more details and to confirm installing.
|
||||
* `Close` - close the configuration panel
|
||||
|
||||
#### Download window
|
||||
|
||||
This uses the keyman.com website to install kmps.
|
||||
|
||||
Search for a language or keyboard in the search box.
|
||||
Select a keyboard from the list.
|
||||
In 'Downloads for your device' there will be an 'Install keyboard' button for the keyboard for Linux.
|
||||
Click it to download the keyboard and bring up the `InstallKmpWindow` for more details and to confirm installing.
|
||||
|
||||
Secondary-click gives you a menu including 'Back' to go back a page.
|
||||
|
||||
### km-package-install
|
||||
|
||||
`km-package-install -p <keyboard package id>` install Keyman keyboard package from the keyman.com server
|
||||
|
||||
`km-package-install -f <kmp file>` install Keyman keyboard package from a local .kmp file
|
||||
|
||||
### km-package-uninstall
|
||||
|
||||
`km-package-uninstall <keyboard id>` uninstall Keyman keyboard package
|
||||
|
||||
`km-package-uninstall -s <keyboard id>` uninstall from shared area `/usr/local`
|
||||
|
||||
### km-package-list-installed
|
||||
|
||||
`km-package-list-installed` shows name, version, id, description of each installed keyboard
|
||||
|
||||
`km-package-list-installed -s` shows those installed in shared areas
|
||||
|
||||
`km-package-list-installed -os` shows those installed by the OS
|
||||
|
||||
`km-package-list-installed -u` shows those installed in user areas
|
||||
|
||||
### km-package-get
|
||||
|
||||
`km-package-get <keyboard id>` download Keyman keyboard package to `~/.cache/keyman`
|
||||
|
||||
### km-kvk2ldml
|
||||
|
||||
`km-kvk2ldml [-p] [-k] [-o LDMLFILE] <kvk file>` Convert a Keyman kvk on-screen keyboard file to an LDML file. Optionally print the details of the kvk file (`-p`) optionally with all keys (`-k`).
|
||||
|
||||
## Building the Debian package
|
||||
|
||||
You will need the build dependencies as well as the runtime dependencies above
|
||||
|
||||
`sudo apt install dh-python python3-all debhelper help2man`
|
||||
|
||||
Run `make deb`. This will build the Debian package in the `make_deb` directory.
|
||||
|
||||
## Internationalization
|
||||
|
||||
### Create or update i18n template file
|
||||
|
||||
Run
|
||||
|
||||
```bash
|
||||
make update-template
|
||||
```
|
||||
|
||||
This will create or update the file `locale/keyman-config.pot`.
|
||||
|
||||
### Add translations for a new language
|
||||
|
||||
To add translations for a new language run (replacing `de_DE` with the desired locale):
|
||||
|
||||
```bash
|
||||
cd locale
|
||||
msginit --locale=de_DE.UTF-8 --width=98 --input keyman-config.pot
|
||||
```
|
||||
|
||||
This will create the file `locale/de.po`.
|
||||
|
||||
**NOTE:** Specifying _UTF-8_ is important if any non-ASCII characters will be used in the
|
||||
translation, i.e. always.
|
||||
|
||||
**NOTE:** This step is not necessary when using Crowdin
|
||||
|
||||
### Update translations
|
||||
|
||||
After strings were added or modified the translated po files need to be updated. For this
|
||||
call, replacing `de` with the desired locale:
|
||||
|
||||
```bash
|
||||
make locale/de.po
|
||||
```
|
||||
|
||||
Alternatively you can also update all po files at once:
|
||||
|
||||
```bash
|
||||
make update-po
|
||||
```
|
||||
|
||||
**NOTE:** This step is not necessary when using Crowdin
|
||||
|
||||
### Compile translations
|
||||
|
||||
To create the binary files for the translations, run:
|
||||
|
||||
```bash
|
||||
make compile-po
|
||||
```
|
||||
|
||||
This will create `.mo` files, e.g. `locale/de/LC_MESSAGES/keyman-config.mo`.
|
||||
|
||||
### Testing localization
|
||||
|
||||
```bash
|
||||
LANGUAGE=de ./km-config
|
||||
```
|
||||
|
||||
## Debugging unit tests
|
||||
|
||||
* Add the following lines to your workspace settings file (`.vscode/settings`),
|
||||
or copy `docs/settings/linux/settings` to `.vscode/settings`)
|
||||
|
||||
```settings
|
||||
"python.envFile": "${workspaceFolder}/linux/keyman-config/tests/python.env",
|
||||
"python.testing.unittestArgs": [
|
||||
"-v",
|
||||
"-s", "linux/keyman-config/tests",
|
||||
"-p", "test_*.py"
|
||||
],
|
||||
"python.testing.unittestEnabled": true,
|
||||
```
|
||||
|
||||
* The tests will show up in the _Test Explorer_ in VSCode and can be debugged there
|
||||
|
|
@ -318,7 +318,7 @@ linux/scripts/upload-to-debian.sh -k $DEBSIGN_KEYID --push
|
|||
|
||||
## Reference
|
||||
|
||||
See the [Linux readme](https://github.com/keymanapp/keyman/blob/master/linux/README.md)
|
||||
See the [Linux readme](https://github.com/keymanapp/keyman/blob/master/docs/linux/README.md)
|
||||
for how to build Keyman on Linux etc.
|
||||
|
||||
### References for Debian packaging
|
||||
168
linux/README.md
168
linux/README.md
|
|
@ -1,169 +1,3 @@
|
|||
# Keyman for Linux
|
||||
|
||||
## Projects
|
||||
|
||||
- [keyman-config](./keyman-config) - km-config and some other tools to install, uninstall
|
||||
and view information about Keyman keyboard packages.
|
||||
- [ibus-keyman](./ibus-keyman) - IBUS integration to use .kmp Keyman keyboards
|
||||
- [core](../core) - common keyboardprocessor library
|
||||
- [legacy/kmflcomp](./legacy/kmflcomp) - KMFL keyboard compiler
|
||||
- [legacy/libkmfl](./legacy/libkmfl) - older KMFL core library
|
||||
- [legacy/ibus-kmfl](./legacy/ibus-kmfl) - IBUS integration to use KMFL
|
||||
|
||||
See [license information](./LICENSE.md) about licensing.
|
||||
|
||||
## Linux Requirements/Setup
|
||||
|
||||
- It is helpful to be using the [packages.sil.org](http://packages.sil.org) repo
|
||||
|
||||
- Install packages required for building and developing Keyman for Linux
|
||||
|
||||
```bash
|
||||
sudo apt install cdbs debhelper libx11-dev autotools-dev build-essential \
|
||||
dh-autoreconf flex bison libibus-1.0-dev python3-setuptools meson \
|
||||
libjson-glib-dev libgtk-3-dev libxml2-utils help2man python3-lxml \
|
||||
python3-magic python3-numpy python3-pil python3-pip python3-qrcode \
|
||||
python3-requests python3-requests-cache python3 python3-gi dconf-cli \
|
||||
dconf-editor cargo python3-dbus gir1.2-webkit2-4.0 ibus libglib2.0-bin \
|
||||
liblocale-gettext-perl xvfb xserver-xephyr metacity mutter
|
||||
```
|
||||
|
||||
## Compiling from Command Line
|
||||
|
||||
### Build script
|
||||
|
||||
#### Installing for ibus to use ibus-keyman
|
||||
|
||||
- The process to build and install everything is:
|
||||
|
||||
- `make reconf` to create the build system and set the version
|
||||
- `make fullbuild` to configure and build
|
||||
- `sudo make install` to install to `/usr/local`
|
||||
|
||||
- Some of the files must be installed to `/usr/share/` so `make install` must be run as `sudo`.
|
||||
|
||||
To do this run `sudo make install`
|
||||
|
||||
- This will install to `/usr/local`
|
||||
- and `/usr/share/ibus/component/keyman.xml` and `/usr/share/keyman/icons`
|
||||
|
||||
- If you already have the ibus-keyman package installed then it will move the file `/usr/share/ibus/component/keyman.xml` to `/usr/share/doc/ibus-keyman/`
|
||||
|
||||
- run `sudo make uninstall` to uninstall everything and put it back again
|
||||
|
||||
#### Tmp install
|
||||
|
||||
Used by TC for validating PRs
|
||||
|
||||
Run `make tmpinstall` to build and install **keyboardprocessor** and **ibus-keyman** to `/tmp/keyman`
|
||||
|
||||
This is only for testing the build, not for running **ibus-keyman** in ibus
|
||||
|
||||
### Manually
|
||||
|
||||
- **ibus-keyman** requires headers and lib from **keyboardprocessor**
|
||||
|
||||
So
|
||||
|
||||
- **keyboardprocessor** must be built before **ibus-keyman**
|
||||
|
||||
For each project run `./configure && make && make install`.
|
||||
|
||||
You may prefer to create a different directory to build in and run configure from there e.g.
|
||||
|
||||
```bash
|
||||
mkdir ../build-ibus-keyman
|
||||
cd ../build-ibus-keyman
|
||||
../ibus-keyman/configure
|
||||
make
|
||||
make install
|
||||
```
|
||||
|
||||
## Continuous integration
|
||||
|
||||
Teamcity PR builds will run `make tmpinstall`
|
||||
|
||||
Master builds run `make tmpinstall` and create source packages
|
||||
|
||||
Nightly and release builds upload the most recent new master build to <https://downloads.keyman.com>
|
||||
|
||||
## Building packages
|
||||
|
||||
See [Linux packaging doc](../docs/linux-packaging.md)
|
||||
for details on building Linux packages for Keyman.
|
||||
|
||||
## Testing
|
||||
|
||||
### keyman-config
|
||||
|
||||
The unit tests can be run with the following command:
|
||||
|
||||
```bash
|
||||
cd linux/keyman-config
|
||||
./run-tests.sh
|
||||
```
|
||||
|
||||
### ibus-keyman
|
||||
|
||||
If you want to run the ibus-keyman tests with Wayland, you'll have to
|
||||
have `mutter` installed (version >=40). Otherwise you'll only be able
|
||||
to run the tests with X11.
|
||||
|
||||
The tests can be run with the following command:
|
||||
|
||||
```bash
|
||||
cd linux/ibus-keyman/tests
|
||||
./run-tests
|
||||
```
|
||||
|
||||
The `run-tests` script accepts different arguments which can be seen with
|
||||
`./run-tests --help`.
|
||||
|
||||
## Running Keyman for Linux
|
||||
|
||||
### Setting up Ibus
|
||||
|
||||
Ibus should be running on a default install of Ubuntu
|
||||
|
||||
You may want to install extra packages to get other ibus input methods e.g **ibus-unikey** for VN
|
||||
|
||||
Run `ibus restart` after installing any of them
|
||||
|
||||
### Getting a Keyman keyboard
|
||||
|
||||
- After installing a Keyman keyboard usually ibus will be restarted automatically so that ibus will
|
||||
look for the new keyboard. If for whatever reason the keyboard doesn't show up in the system
|
||||
keyboard list, you can manually run `ibus restart`.
|
||||
|
||||
### Activating a Keyman keyboard
|
||||
|
||||
Keyman tries to activate the keyboard automatically. If you want to activate it for a different
|
||||
language, you can do so by following the steps below.
|
||||
|
||||
#### GNOME3 (focal and bionic default, also newer Ubuntu versions)
|
||||
|
||||
- Click the connection/sound/shutdown section in the top right. Then the tools icon for Settings.
|
||||
|
||||
- In `Language and Region` click `+` to add a keyboard.
|
||||
- Click the 3 dots expander then search for "Other" and click it
|
||||
- The Keyman keyboards should be listed here to choose
|
||||
|
||||
- Use `Win-space` to switch between keyboards.
|
||||
|
||||
#### Cinnamon (wasta default)
|
||||
|
||||
- Open `Menu` and find `IBus Keyboards` (`IBus Preferences`) and run it
|
||||
- Make sure `Show icon on system tray` is checked
|
||||
- Select the tab `Input Method`.
|
||||
- Click `Add` to add a keyman keyboard.
|
||||
- Click the 3 dots expander then search for "Other" and click it
|
||||
- The Keyman keyboards should be listed here to choose
|
||||
|
||||
#### MATE (alternative)
|
||||
|
||||
- Open `System-> Preferences -> Other -> IBus Preferences`.
|
||||
- Make sure `Show icon on system tray` is checked
|
||||
- Select the tab `Input Method`.
|
||||
- Click `Add` to add a keyman keyboard.
|
||||
- Click the 3 dots expander then search for "Other" and click it
|
||||
- The Keyman keyboards should be listed here to choose
|
||||
See [/docs/linux/README.md](../docs/linux/README.md) for documentation.
|
||||
|
|
|
|||
|
|
@ -1,29 +1,4 @@
|
|||
# Keyman engine for IBus
|
||||
|
||||
## Requirements
|
||||
|
||||
You need autoconf, autopoint, gettext, automake and libtool to generate the build system.
|
||||
|
||||
Run `./autogen.sh` to run them.
|
||||
|
||||
## Building
|
||||
|
||||
```bash
|
||||
./autogen.sh
|
||||
./configure
|
||||
make
|
||||
sudo make install
|
||||
```
|
||||
|
||||
For a debug build:
|
||||
|
||||
```bash
|
||||
./configure CPPFLAGS=-DG_MESSAGES_DEBUG CFLAGS="-g -O0" CXXFLAGS="-g -O0"
|
||||
```
|
||||
|
||||
To use the header files from the source repo, you need to specify paths to the include files in core:
|
||||
|
||||
```bash
|
||||
./configure CPPFLAGS="-DG_MESSAGES_DEBUG -I../../core/build/arch/debug/include/ -I../../common/include/ -I../../core/include/" \
|
||||
CFLAGS="-g -O0" CXXFLAGS="-g -O0"
|
||||
```
|
||||
See [ibus-keyman.md](../../docs/linux/ibus-keyman.md) for documentation
|
||||
how to build Keyman engine for IBus.
|
||||
|
|
|
|||
|
|
@ -1,207 +1,3 @@
|
|||
# Linux km-config
|
||||
|
||||
## Preparing to run
|
||||
|
||||
If you are running from the repo or installing keyman-config manually rather than from a package
|
||||
then you will need to:
|
||||
|
||||
```bash
|
||||
sudo apt install python3-lxml python3-magic python3-numpy python3-qrcode python3-pil \
|
||||
python3-requests python3-requests-cache python3 python3-gi gir1.2-webkit2-4.0 dconf-cli \
|
||||
python3-setuptools python3-pip python3-dbus ibus libglib2.0-bin liblocale-gettext-perl
|
||||
```
|
||||
|
||||
Either `python3-raven` or `python3-sentry-sdk` (>= 1.4) is required as well. On Ubuntu 22.04 and later run:
|
||||
|
||||
```bash
|
||||
sudo apt install python3-sentry-sdk
|
||||
```
|
||||
|
||||
To install it on Ubuntu 18.04 and earlier run:
|
||||
|
||||
```bash
|
||||
sudo apt install python3-raven
|
||||
```
|
||||
|
||||
For Ubuntu versions that don't provide `python3-raven` but instead provide
|
||||
`python3-sentry-sdk` in a too old version (i.e. Ubuntu 20.04):
|
||||
Install `python3-sentry-sdk` from `packages.sil.org`,
|
||||
or install it with pip:
|
||||
|
||||
```bash
|
||||
pip3 install sentry-sdk
|
||||
```
|
||||
|
||||
Run the script `./createkeymandirs.sh` to create the directories for these programs to
|
||||
install the packages to.
|
||||
|
||||
Also copy and compile the GSettings schema:
|
||||
|
||||
```bash
|
||||
cd keyman_config
|
||||
sudo cp com.keyman.gschema.xml /usr/share/glib-2.0/schemas
|
||||
sudo glib-compile-schemas /usr/share/glib-2.0/schemas
|
||||
```
|
||||
|
||||
### Standards data file
|
||||
|
||||
Running `km-config` requires a language tag mapping file
|
||||
`keyman_config/standards/lang_tags_map.py`. This file gets generated during a package
|
||||
build, and also when running `make`.
|
||||
|
||||
## Installing manually from the repo
|
||||
|
||||
`make && sudo make install` will install locally to `/usr/local`.
|
||||
|
||||
`pip3 help install` will give you more install options.
|
||||
|
||||
To uninstall you can run `sudo make uninstall`.
|
||||
|
||||
## Things to run from the command line
|
||||
|
||||
### km-config
|
||||
|
||||
`./km-config`
|
||||
|
||||
This displays a configuration panel that shows the currently installed Keyman keyboard packages and can download and install additional keyboards.
|
||||
|
||||
#### Buttons
|
||||
|
||||
* `Uninstall` - uninstall selected keyboard
|
||||
* `About` - show information about selected keyboard
|
||||
* `Help` - display help documentation about selected keyboard
|
||||
* `Options` - display options.htm form for setting keyboard options
|
||||
|
||||
-----------------------------------
|
||||
|
||||
* `Refresh` - useful if you install or uninstall on the commandline while running km-config.
|
||||
* `Download` - runs `DownloadKmpWindow` (see below)
|
||||
* `Install` - opens a file choose dialog to choose a kmp file to install and bring up the `InstallKmpWindow` for more details and to confirm installing.
|
||||
* `Close` - close the configuration panel
|
||||
|
||||
#### Download window
|
||||
|
||||
This uses the keyman.com website to install kmps.
|
||||
|
||||
Search for a language or keyboard in the search box.
|
||||
Select a keyboard from the list.
|
||||
In 'Downloads for your device' there will be an 'Install keyboard' button for the keyboard for Linux.
|
||||
Click it to download the keyboard and bring up the `InstallKmpWindow` for more details and to confirm installing.
|
||||
|
||||
Secondary-click gives you a menu including 'Back' to go back a page.
|
||||
|
||||
### km-package-install
|
||||
|
||||
`km-package-install -p <keyboard package id>` install Keyman keyboard package from the keyman.com server
|
||||
|
||||
`km-package-install -f <kmp file>` install Keyman keyboard package from a local .kmp file
|
||||
|
||||
### km-package-uninstall
|
||||
|
||||
`km-package-uninstall <keyboard id>` uninstall Keyman keyboard package
|
||||
|
||||
`km-package-uninstall -s <keyboard id>` uninstall from shared area `/usr/local`
|
||||
|
||||
### km-package-list-installed
|
||||
|
||||
`km-package-list-installed` shows name, version, id, description of each installed keyboard
|
||||
|
||||
`km-package-list-installed -s` shows those installed in shared areas
|
||||
|
||||
`km-package-list-installed -os` shows those installed by the OS
|
||||
|
||||
`km-package-list-installed -u` shows those installed in user areas
|
||||
|
||||
### km-package-get
|
||||
|
||||
`km-package-get <keyboard id>` download Keyman keyboard package to `~/.cache/keyman`
|
||||
|
||||
### km-kvk2ldml
|
||||
|
||||
`km-kvk2ldml [-p] [-k] [-o LDMLFILE] <kvk file>` Convert a Keyman kvk on-screen keyboard file to an LDML file. Optionally print the details of the kvk file (`-p`) optionally with all keys (`-k`).
|
||||
|
||||
## Building the Debian package
|
||||
|
||||
You will need the build dependencies as well as the runtime dependencies above
|
||||
|
||||
`sudo apt install dh-python python3-all debhelper help2man`
|
||||
|
||||
Run `make deb`. This will build the Debian package in the `make_deb` directory.
|
||||
|
||||
## Internationalization
|
||||
|
||||
### Create or update i18n template file
|
||||
|
||||
Run
|
||||
|
||||
```bash
|
||||
make update-template
|
||||
```
|
||||
|
||||
This will create or update the file `locale/keyman-config.pot`.
|
||||
|
||||
### Add translations for a new language
|
||||
|
||||
To add translations for a new language run (replacing `de_DE` with the desired locale):
|
||||
|
||||
```bash
|
||||
cd locale
|
||||
msginit --locale=de_DE.UTF-8 --width=98 --input keyman-config.pot
|
||||
```
|
||||
|
||||
This will create the file `locale/de.po`.
|
||||
|
||||
**NOTE:** Specifying _UTF-8_ is important if any non-ASCII characters will be used in the
|
||||
translation, i.e. always.
|
||||
|
||||
**NOTE:** This step is not necessary when using Crowdin
|
||||
|
||||
### Update translations
|
||||
|
||||
After strings were added or modified the translated po files need to be updated. For this
|
||||
call, replacing `de` with the desired locale:
|
||||
|
||||
```bash
|
||||
make locale/de.po
|
||||
```
|
||||
|
||||
Alternatively you can also update all po files at once:
|
||||
|
||||
```bash
|
||||
make update-po
|
||||
```
|
||||
|
||||
**NOTE:** This step is not necessary when using Crowdin
|
||||
|
||||
### Compile translations
|
||||
|
||||
To create the binary files for the translations, run:
|
||||
|
||||
```bash
|
||||
make compile-po
|
||||
```
|
||||
|
||||
This will create `.mo` files, e.g. `locale/de/LC_MESSAGES/keyman-config.mo`.
|
||||
|
||||
### Testing localization
|
||||
|
||||
```bash
|
||||
LANGUAGE=de ./km-config
|
||||
```
|
||||
|
||||
## Debugging unit tests
|
||||
|
||||
* Add the following lines to your workspace settings file (`.vscode/settings`),
|
||||
or copy `docs/settings/linux/settings` to `.vscode/settings`)
|
||||
|
||||
```settings
|
||||
"python.envFile": "${workspaceFolder}/linux/keyman-config/tests/python.env",
|
||||
"python.testing.unittestArgs": [
|
||||
"-v",
|
||||
"-s", "linux/keyman-config/tests",
|
||||
"-p", "test_*.py"
|
||||
],
|
||||
"python.testing.unittestEnabled": true,
|
||||
```
|
||||
|
||||
* The tests will show up in the _Test Explorer_ in VSCode and can be debugged there
|
||||
See [keyman-config.md](../../docs/linux/keyman-config.md) for documentation.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue