diff --git a/developer/src/kmc-analyze/README.md b/developer/src/kmc-analyze/README.md new file mode 100644 index 0000000000..ed7729771f --- /dev/null +++ b/developer/src/kmc-analyze/README.md @@ -0,0 +1,11 @@ +# Keyman Developer - kmc-analyze + +This package provides Keyman keyboard analysis tools. It can be used from the +command line with [@keymanapp/kmc](https://npmjs.com/package/@keymanapp/kmc). + +Currently, the primary function of this package is to work with Keyman's +[`&displayMap` store](https://help.keyman.com/developer/language/reference/displaymap) for +rewriting the On Screen Keyboard with PUA characters, for consistent display of +diacritics and combining marks across all platforms. + +* [API Reference](https://help.keyman.com/developer/current-version/reference/api/kmc-analyze) diff --git a/developer/src/kmc-keyboard-info/README.md b/developer/src/kmc-keyboard-info/README.md new file mode 100644 index 0000000000..18e6cfcfe6 --- /dev/null +++ b/developer/src/kmc-keyboard-info/README.md @@ -0,0 +1,10 @@ +# Keyman Developer - kmc-keyboard-info + +This package builds a .keyboard_info file from a Keyman keyboard project. It can +be used from the command line with +[@keymanapp/kmc](https://npmjs.com/package/@keymanapp/kmc). + +This package is used only for preparing metadata files for deployment of +keyboards to the Keyman Cloud Keyboard Repository. + +* [API Reference](https://help.keyman.com/developer/current-version/reference/api/kmc-keyboard-info) diff --git a/developer/src/kmc-kmn/README.md b/developer/src/kmc-kmn/README.md new file mode 100644 index 0000000000..a74e4d004a --- /dev/null +++ b/developer/src/kmc-kmn/README.md @@ -0,0 +1,9 @@ +# Keyman Developer - kmc-kmn + +This package compiles .kmn keyboards into .kmx binary keyboard files. It can be +used from the command line with +[@keymanapp/kmc](https://npmjs.com/package/@keymanapp/kmc). + +Note: this package requires WASM support. + +* [API Reference](https://help.keyman.com/developer/current-version/reference/api/kmc-kmn) diff --git a/developer/src/kmc-ldml/README.md b/developer/src/kmc-ldml/README.md new file mode 100644 index 0000000000..a584354854 --- /dev/null +++ b/developer/src/kmc-ldml/README.md @@ -0,0 +1,9 @@ +# Keyman Developer - kmc-ldml + +This package compiles LDML .xml keyboards into Keyman .kmx binary keyboard +files. It can be used from the command line with +[@keymanapp/kmc](https://npmjs.com/package/@keymanapp/kmc). + +Note: this package requires WASM support (for the uset parser). + +* [API Reference](https://help.keyman.com/developer/current-version/reference/api/kmc-ldml) diff --git a/developer/src/kmc-model-info/README.md b/developer/src/kmc-model-info/README.md new file mode 100644 index 0000000000..cd6e80704a --- /dev/null +++ b/developer/src/kmc-model-info/README.md @@ -0,0 +1,10 @@ +# Keyman Developer - kmc-model-info + +This package builds a .model_info file from a Keyman lexical model project. It +can be used from the command line with +[@keymanapp/kmc](https://npmjs.com/package/@keymanapp/kmc). + +This package is used only for preparing metadata files for deployment of +lexical models to the Keyman Cloud Lexical Model Repository. + +* [API Reference](https://help.keyman.com/developer/current-version/reference/api/kmc-model-info) diff --git a/developer/src/kmc-model/README.md b/developer/src/kmc-model/README.md new file mode 100644 index 0000000000..66334cf3d7 --- /dev/null +++ b/developer/src/kmc-model/README.md @@ -0,0 +1,7 @@ +# Keyman Developer - kmc-model + +This package compiles .model.ts lexical models into .model.js files. It can be +used from the command line with +[@keymanapp/kmc](https://npmjs.com/package/@keymanapp/kmc). + +* [API Reference](https://help.keyman.com/developer/current-version/reference/api/kmc-model) diff --git a/developer/src/kmc-package/README.md b/developer/src/kmc-package/README.md new file mode 100644 index 0000000000..f60f18e9a8 --- /dev/null +++ b/developer/src/kmc-package/README.md @@ -0,0 +1,9 @@ +# Keyman Developer - kmc-package + +This package compiles .kps Keyman package source files into binary .kmp Keyman +package files. It can be used from the command line with +[@keymanapp/kmc](https://npmjs.com/package/@keymanapp/kmc). + +Note: .kmp files are .zip files internally. + +* [API Reference](https://help.keyman.com/developer/current-version/reference/api/kmc-package) diff --git a/developer/src/kmc/README.md b/developer/src/kmc/README.md index 31022383d0..5e5183bff5 100644 --- a/developer/src/kmc/README.md +++ b/developer/src/kmc/README.md @@ -1,105 +1,191 @@ -Keyman Developer - Next Generation Compiler +Keyman Developer - Command Line Compiler ================ -This package provides the following Keyman **command line tools**: +This package provides a command-line interface to the Keyman Developer compiler +toolchain, `kmc`. - - `kmc` — takes **LDML Keyboard .xml sources** and compiles them in to a - KMXPlus **.kmx** file. - - `kmlmc` — takes **lexical model sources** and compiles them in to a **.js** - file. - - `kmlmp` — uses a `.model.kmp` file to generate a redistributable **lexical - model package**. +## Install kmc -`kmlmc` is intended to be used standalone, or as part of a build system. `kmlmp` -is used only by command line tools. +`kmc` is available as: +* a part of Keyman Developer (Windows only) +* an npm package, and +* a zip download -Note: `kmc` will in the future replace `kmlmc` and `kmlmp`. +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. -In order to build [lexical models][], these tools must be built and compiled. +### Keyman Developer integration (Windows only) -[lexical models]: https://github.com/keymanapp/lexical-models +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) -Install -------- +kmc is also available as an npm package, +[@keymanapp/kmc](https://npmjs.com/package/@keymanapp/kmc). -Install `kmc` globally: +You'll need [node.js](https://nodejs.org/), version 18.0 or later. - npm install -g @keymanapp/kmc - -kmc Usage ---------- - -To compile an LDML keyboard from its `.xml` source, use `kmc`: - - kmc build my-keyboard.xml --outFile my-keyboard.kmx - -To see more command line options by using the `--help` option: - - kmc --help - ---- - -To compile a lexical model from its `.model.ts` source, use `kmc`: - - kmc build my-lexical-model.model.ts --outFile my-lexical-model.model.js - -To see more command line options by using the `--help` option: - - kmc --help - ---- - -kmc can now build package installers for Windows. Example usage (Bash on -Windows, using 'node .' instead of 'kmc' to run the local build): - -``` -node . build windows-package-installer \ - $KEYMAN_ROOT/developer/src/kmc-package/test/fixtures/khmer_angkor/source/khmer_angkor.kps \ - --msi /c/Program\ Files\ \(x86\)/Common\ Files/Keyman/Cached\ Installer\ Files/keymandesktop.msi \ - --exe $KEYMAN_ROOT/windows/bin/desktop/setup-redist.exe \ - --license $KEYMAN_ROOT/LICENSE.md \ - --out-file ./khmer.exe +```shell +npm install -g @keymanapp/kmc ``` -How to build from source ------------------------- +### Zip download (Windows, macOS, and Linux) + +kmc is also available as a zip download from +[keyman.com/developer/download](https://keyman.com/developer/download), +or can be installed from the command line (`curl` and `unzip` required): + +```shell +# 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](https://github.com/keyman-keyboards/khmer_angkor) and download it as a +zip file instead. + +```shell +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. + +```shell +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`][windows-install-keyboard]: + +```cmd +"%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`][linux-install-keyboard] +command: + +```shell +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](https://help.keyman.com/products/android/current-version/basic/installing-custom-packages) 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][load-keymanweb-keyboard]: + +```js +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][file-layout] for details on the standard source file layout +that Keyman Developer works best with. + +## Reference and Examples + +### kmc - command line compiler + +[kmc][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 ` to build the project in the +referenced folder, e.g. `kmc build .`. + +* [kmc reference][kmc] + +----- + +# Working with the source + +## Building kmc Run `build.sh`: - ./build.sh configure build +```shell +./build.sh configure build +``` -or (less preferably -- build.sh is more efficient): - - nmake configure build - -Once you have `configure`d once, you should not normally need to do it again +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`. -TODO: Note that kmc currently depends on kmc-* to have been configured; while -the build of kmc will do the typescript component of the build, it will not be -able to do any other build steps, so you may wish to build each of the -components separately, one time. +## Testing kmc -How to run the tests --------------------- +```shell +./build.sh test +``` - ./build.sh test +## Bundling for installation - -How to prepare bundling for installation ----------------------------------------- - - ./build.sh bundle --build-path +```shell +./build.sh bundle --build-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. -How to publish to NPM ---------------------- +## Publishing to NPM - ./build.sh publish [--dry-run] +```shell +./build.sh publish [--dry-run] +``` -Publishes the current release to NPM. This should only be run from CI. \ No newline at end of file +Publishes the current release to NPM. This should only be run from CI. + + +[kmc]: https://help.keyman.com/developer/current-version/reference/kmc/cli +[file-layout]: https://help.keyman.com/developer/current-version/reference/file-layout +[load-keymanweb-keyboard]: https://help.keyman.com/developer/engine/web/current-version/guide/adding-keyboards +[linux-install-keyboard]: https://help.keyman.com/products/linux/current-version/reference/km-package-install +[windows-install-keyboard]: https://help.keyman.com/knowledge-base/98