mirror of
https://github.com/keymanapp/keyman.git
synced 2026-10-06 14:07:32 +00:00
Merge pull request #10842 from keymanapp/docs/developer/10207-package-READMEs
docs(developer): npm package readme files 📚
This commit is contained in:
Marc Durdin
GitHub
commit
e2908262f5
8 changed files with 226 additions and 75 deletions
11
developer/src/kmc-analyze/README.md
Normal file
11
developer/src/kmc-analyze/README.md
Normal file
|
|
@ -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)
|
||||
10
developer/src/kmc-keyboard-info/README.md
Normal file
10
developer/src/kmc-keyboard-info/README.md
Normal file
|
|
@ -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)
|
||||
9
developer/src/kmc-kmn/README.md
Normal file
9
developer/src/kmc-kmn/README.md
Normal file
|
|
@ -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)
|
||||
9
developer/src/kmc-ldml/README.md
Normal file
9
developer/src/kmc-ldml/README.md
Normal file
|
|
@ -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)
|
||||
10
developer/src/kmc-model-info/README.md
Normal file
10
developer/src/kmc-model-info/README.md
Normal file
|
|
@ -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)
|
||||
7
developer/src/kmc-model/README.md
Normal file
7
developer/src/kmc-model/README.md
Normal file
|
|
@ -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)
|
||||
9
developer/src/kmc-package/README.md
Normal file
9
developer/src/kmc-package/README.md
Normal file
|
|
@ -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)
|
||||
|
|
@ -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
|
||||
|
||||
<!-- TODO: THIS SECTION NEEDS REWRITE ONCE `kmc generate` lands in 18.0. -->
|
||||
|
||||
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 <folder>` 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 <temp_path>
|
||||
```shell
|
||||
./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.
|
||||
|
||||
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.
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue