Working with the Keyman Cloud Keyboard Repository
We have many hundreds of keyboard layouts online at keyman.com that cover well over a thousand languages. These keyboard layouts work on Windows, the web, iPhones, iPads and Android phones and tablets. However, most of the layouts on the website are only available in compiled form, and in the past, the source code for these keyboards has not been consistently managed.
A large proportion of the keyboards on the site, including nearly all the keyboards that we have developed, are actually open source keyboards. We now have a single source for open source keyboards on github.com.
Previously, each keyboard had its source stored in different ways. Some just included the source files as an attachment to the compiled keyboards. Others had a web address from which the source could be downloaded. Over time, these web addresses tended to stagnate and not be kept up to date.
We are progressively moving all the open source keyboards in our database into the new repository. We have started with some of the most popular open layouts, including GFF Amharic, Thamizha Tamil99, and Sinhala Basic.
You are of course welcome to download the layouts yourself and improve them, and we hope you will contribute your own keyboards to this repository for all to use.
Get the source
I suggest forking the Tavultesoft keyboards repository in GitHub to start. Visit https://github.com/keymanapp/keyboards, and click the Fork button to create your own fork (you will need your own GitHub account, of course).
Once you have your own forked repository, pull a local copy onto your computer. Install git for Windows, and then create a keyboards parent folder to house your repository. I use
c:\tavultesoft, but you can use any folder.
From a command prompt, run the following steps:
cd /d your-keyboards-parent-folder git clone https://github.com/yourgithubname/keyboards.git
At this point, you should have a folder
c:\tavultesoft\keyboards (or wherever you decided to place the folder). This folder will contain the full set of keyboards.
You should also keep your fork in sync with the master repository; here’s how, continuing from the previous steps:
cd keyboards git remote add upstream https://github.com/keymanapp/keyboards.git
You can now get the latest changes to the master repository with the following commands, at any time:
git fetch upstream git merge upstream/master
All going well, you’ll have all the keyboards in the repository in ready to play with on your computer.
Keyman Developer has a powerful project feature that makes it easier to manage the keyboard projects. Each keyboard in the repository will have an associated Keyman Project .kpj file that can be built from the command line or from within the Keyman Developer IDE. This project file is the starting point for any work you do on a keyboard.
Make sure you have Keyman Developer 9.0.508.0 or later. You can download Keyman Developer Beta from http://keyman.com/developer.
Building keyboards in the IDE
.kpj file in Explorer to open the project in the Keyman Developer Integrated Development Environment (IDE). You can also open a project from the Project menu within the IDE. The project is automatically updated when you make changes, and changes specific to your computer are saved in a
.kpj.user file along with the
.kpj file. This
.kpj.user file can be deleted at any time, and should not be saved to the git repository.
In the Project screen, in either the Keyboards or the Packages tab, you can click Build all to build all the keyboard and package files listed in the project. If the project has dependencies on other projects, you will need to build them first: Keyman Developer does not resolve project dependencies at this time (see the command line details below for an automatic way to resolve this).
Building keyboards from the command line
build.cmd command script can be used to compile the keyboards and packages in the project. This script depends on the
%KeymanDeveloperPath% environment variable, which should be set to the path of
kmcomp.exe; this environment variable is normally set by the Keyman Developer installer.
The root folder in the repository also has a
build.cmd script you can use to build any or all of the keyboards in the subfolders. Each subfolder has its own
build.cmd script as well. Running the
build.cmd script without parameters will do a full build for that folder and subfolders. There are a number of additional parameters:
-c clean the folder (deletes all intermediate and output files, do this before committing with git) -d build with debug information -s build silently -t target build a specific file, target, which can be a .kmn or .kps file. -h get help on build.cmd
We do have a baseline for accepting contributed keyboards. While we can work with you on getting your keyboards ready, you can ease the process dramatically by following the guidelines we’ve already written.
These design patterns and requirements assume some knowledge of Keyman Developer and Keyman keyboard development. Keyman Developer is downloadable from http://keyman.com/developer, and the documentation is online at http://help.keyman.com/developer.
When first contributing keyboards, please place the keyboard's folder within the repo at
The keyboard folder's name should then match the keyboard's id. E.g, an "example" keyboard's base folder should reside within the repository structure at
Designing your keyboard layout
Use the documentation links above to learn how to create keyboard layouts; read the tutorials, our blog; the Keyboard Quality Whitepaper (desktop focused keyboards) will be helpful for learning how to develop your keyboards and documentation to a high standard.
You can create a single keyboard layout that targets both desktop/laptop computers and phone/tablet touch devices. We encourage you to develop new keyboard layouts that target all devices.
Use ASCII characters for keyboard base names
Each keyboard in the repository is stored in a folder with the same name as the base name of the keyboard. The base name of the keyboard may be comprised of the letters
a-z (lower case), digits
0-9, and underscore (
While you may see some existing keyboards which are not named according to this convention, new keyboards must follow the ASCII naming convention. This applies to the filename of the keyboard; the descriptive name (
store(&name)) is a Unicode string.
The keyboard name is used as a key for automatic updates on all platforms. Do not include the version of the keyboard in the filename, unless you want to make a new version a completely separate deployment because it has changed so substantially that users would not want to update to it automatically. In this situation, a new keyboard name is probably a wiser choice.
The keyboard name must also be unique in the repository. For less widely used languages, you may be able to get away with the name of the language, but for languages with a large number of speakers, there will probably be more than one keyboard layout, and you will need to be a bit more creative – “
tamil” is not going to be a good keyboard name.
One keyboard per folder
If you have a set of related keyboards, these can be deployed together on Windows in a single package. However, in the repository, each keyboard must be packaged on its own, and the combined package can be included as a separate target in the
packages top-level folder.
A regular folder structure
The folder structure for each keyboard has the following components:
- not stored in the repository; output files will go here
- other related files, e.g. Word documents, databases, experimental files
- keyboard source files, including any files that will be packaged in the build
- welcome.htm and any resources referenced from the welcome.htm file
- development documentation for the keyboard
- description of the keyboard, target languages, target devices, author, etc.
- details on major changes to the keyboards (repository commits covers detail)
- the open source license for the keyboard.
- the Keyman Developer project file for the keyboard
- Command line script for building the project.
- A metadata file detailing the keyboard's origin, version, requirements, and capabilities. This file greatly assists the process of making your keyboard readily available for public download. Please see the .keyboard_info section for more details.
These folders and files can be copied from the
template folder. You should always use the
build.cmd from the template folder, and you should not need to modify it; obviously, the other files will need to be filled with the content relevant to your contribution.
.kpj project file will contain references to the keyboard
.kps file and must set the output path to
$PROJECTPATH\build. Do not include the
.kpj.user file in the repository. The file should have the same base name as the folder/keyboard.
LICENSE.md should be filled with details relevant to your keyboard. These files use Markdown, an easy-to-read plain text format that can be converted to HTML.
Which files to include from your keyboard
The following files should be included for your keyboard in the
source folder. Some keyboards may have additional source files:
- The keyboard source file.
- The desktop on screen keyboard file (if it exists).
<keyboard>.ico (or .bmp)
- The keyboard icon.
- The touch keyboard definition.
- The package source file. See the Keyman Developer reference for what to include within the package source file, but remember that hen you reference any built files
within the package, make sure you reference them from your
Font and documentation files
- Any files you reference in the package source .kps file, such as fonts, documentation, should be included in the
- Metadata for KeymanWeb; this file is not technically required but is useful to include.
The following files should not be included, as they are generated at build time:
- The compiled keyboard file for Desktop.
- The compiled keyboard package file for Desktop.
- The compiled keyboard file for web and touch platforms.
Assigning an open source license
When you share your keyboard with the world, you will need to assign a specific open source license. There are hundreds of prewritten licenses, but for keyboards to be included in this repository, you must use the MIT license:
- MIT license
- A permissive license that is short and to the point. It lets people do anything with your code with proper attribution and without warranty.
The MIT license is explored in detail at choosealicense.com, from which the description above was taken.
Sharing the keyboard with us
Naturally, you will use GitHub to share your new keyboard or updates to an existing keyboard with us. We will review the changes you send us and when ready, merge them into the master repository. If appropriate, we will also at this time deploy compiled versions to KeymanWeb, Keyman for iOS, Keyman for Android, Keyman Desktop (Windows) and Keyman for Mac. These deployments are streamlined for non-technical users.
To share a keyboard with us, first you need to push it to your forked repository. From a command line prompt, in your keyboards folder, commit your changes:
git add . git commit -m "a message about your changes" git push origin master
Once you have pushed the changes to GitHub, you need to create a pull request. Open your browser, and navigate to your forked keyboards repository, probably at
https://github.com/yourgithubname/keyboards. On that page, you will find a link titled Pull Request. Click this to load a page showing all the changes that you have made, relative to the Tavultesoft master repository. When you are satisfied that the changes are correct, click the Create Pull Request button and you’re done. Learn more about pull requests.
At this point, we’ll receive a notification about your pull request and will work with you to integrate the changes into the master repository.
Refining the keyboard
We prefer initial contributions to be made within the 'experimental' section of the master repository, a workspace that allows incoming keyboards to be used with all of the Keyman platforms while further development on the keyboard proceeds.
From there, you can collaborate directly with some of our team members to enhance your keyboard's design and documentation for formal release. This is not a requirement, of course; it's quite possible to simply leave it available for us or for other interested parties to develop it further in the future, an action which is possible with the source code published to the 'experimental' section of our Github repository and permitted by the MIT license.
Experimental keyboards will be accessible during the development process by searching the "experimental" category of our keyboards library, making them available for use by interested parties, but will not be shown on the default "release" list.
As work on a keyboard proceeds and becomes high-quality, we will work with you to apply the final polishing necessary to relocate the keyboard from 'experimental' to 'release' so that it may join the hundreds of published, easily usable keyboards within the Keyman system.