# Linux km-config

Code for `km-config` is in [linux/keyman-config](../../linux/keyman-config/).

## Preparing to run

### Install Dependencies

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.1 dconf-cli \
    python3-setuptools python3-pip python3-dbus ibus libglib2.0-bin liblocale-gettext-perl \
    python3-build python3-fonttools python3-sentry-sdk
```

Newer Ubuntu versions (>= 24.04) don't allow to modify the environment and directly
install non-Debian-packaged Python packages. Instead you'll have to
run the commands in a virtual environment.

This requires the installation of some additional dependencies:

```bash
sudo apt install python3-venv libglib2.0-dev libdbus-1-dev pkg-config
libcairo2-dev libgirepository-2.0-dev
```

Then create the virtual environment with `python3 -m venv km-venv` and activate
it with `source km-venv/bin/activate`.

### Prepare code

Run `linux/keyman-config/build.sh build` to prepare the code.

### Installation

You can install the files with `linux/keyman-config/build.sh install`.
This will install the files into `/usr/local`.

To uninstall you can run `linux/keyman-config/build.sh uninstall`.

## Manually installing

If you prefer to manually copy the files you'll still have to run the
build step above. In addition you'll have to copy the GSettings schema:

### GSettings schema

Copy and compile the GSettings schema:

```bash
sudo cp linux/keyman-config/resources/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 `build.sh build`.

## 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`).

This command is run automatically when installing a keyboard package to create
the necessary files for the onboard onscreen keyboard.

## Building the Debian package

See the [packaging.md](https://github.com/keymanapp/keyman/blob/master/docs/linux/packaging.md#L26)
document.

## 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
TEXTDOMAINDIR=./locale LANGUAGE=de ./km-config
```

## Testing that all strings are localizable

To test that all strings can be translated, you can run the following
command. This will create and compile a TEST.po file
which shows all localizable strings in uppercase, and then run
km-config with the TEST.po file.

```bash
make test-po
```

## 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", "*_tests.py"
  ],
  "python.testing.unittestEnabled": true,
  ```

* The tests will show up in the _Test Explorer_ in VSCode and can be debugged there