@keymanapp/kmc

Keyman Developer - Command Line Compiler

This package provides a command-line interface to the Keyman Developer compiler toolchain, kmc.

Install kmc

kmc is available as:

• a part of Keyman Developer (Windows only)
• an npm package, and
• a zip download

Hint: Unlike previous versions of Keyman Developer, version 17 of kmc does not require WINE to run the command line tools on Linux or macOS.

Keyman Developer integration (Windows only)

kmc is included with a default installation of Keyman Developer, including a runtime of node.js, and will be on the system path by default. No additional configuration or installation is required.

npm (Windows, macOS, and Linux)

kmc is also available as an npm package, @keymanapp/kmc.

You'll need node.js, version 20.0 or later.

npm install -g @keymanapp/kmc

Zip download (Windows, macOS, and Linux)

kmc is also available as a zip download from keyman.com/developer/download, or can be installed from the command line (curl and unzip required):

# To build keyboards and packages:
mkdir kmc
cd kmc
# hint: the download is currently called 'kmcomp', although the
#       compiler is now called 'kmc'.
curl -L https://keyman.com/go/download/kmcomp -o kmc.zip
unzip kmc.zip
# Optionally, add kmc to your PATH

The five minute quick start

1. Download a sample keyboard project

We'll download a sample project from GitHub for Khmer. If you do not have the command-line git tools installed, you can visit the repository website and download it as a zip file instead.

git clone https://github.com/keyman-keyboards/khmer_angkor

This will have created a new folder called khmer_angkor/.

2. Build the project

Now, we'll build our keyboard project with kmc.

cd khmer_angkor
kmc build .

And... that's it! We'll now have a compiled keyboard and package in the build/ subfolder. The file build/khmer_angkor.kmp can be installed into any of the Keyman apps, and build/khmer_angkor.js can be added to KeymanWeb.

3. Install the keyboard

Windows: we can install this keyboard using kmshell:

"%ProgramFiles(x86)%\Keyman\Keyman Desktop\kmshell" -i build\khmer_angkor.kmp -s

Alternatively you can double-click the .kmp package file in Windows Explorer to install it.

Linux: we'd use the following km-package-install command:

km-package-install -f build/khmer_angkor.kmp

macOS: open Keyman Configuration and drop the package khmer_angkor.kmp file onto the Keyman Configuration window.

Android: send khmer_angkor.kmp to your Android device, and install it from the hamburger menu in the Keyman app.

iOS: send khmer_angkor.kmp to your iOS device, and install it from the hamburger menu in the Keyman app.

Web: copy khmer_angkor.js to your website, then load it with KeymanWeb:

keyman.addKeyboards({
  id:'khmer_angkor',        // The keyboard's unique identification code.
  name:'Khmer Angkor',      // The keyboard's user-readable name.
  language:{
    id:'km',                // A BCP 47 code uniquely identifying the language.
    name:'Khmer'            // The language's name.
  },
  filename:'./khmer_angkor.js',
});

File layout

See file layout for details on the standard source file layout that Keyman Developer works best with.

Reference and Examples

kmc - command line compiler

kmc is the command line compiler. You can use it to compile all Keyman files.

The most common command will be kmc build:

kmc build project.kpj : Compile all components of a keyboard or model project named project.kpj KMComp will respect the path settings within the project file. This is the recommended way to build, as it will build keyboards, models and packages all in one step. You can also call kmc build <folder> to build the project in the referenced folder, e.g. kmc build ..

• kmc reference

---

Working with the source

Building kmc

Run build.sh:

./build.sh configure build

Once you have run configure once, you should not normally need to do it again unless dependencies change or you clean the build folder. ./build.sh without parameters will do the default action, which is build.

Testing kmc

./build.sh test

Bundling for installation

./build.sh bundle --build-path <temp_path>

The temp_path must be a path outside the repository to avoid npm getting confused by the root package.json. This is called by inst/download.in.mak normally when building the Keyman Developer installer.

Publishing to NPM

./build.sh publish [--dry-run]

Publishes the current release to NPM. This should only be run from CI.