1page.title=Validate Keymaps Tool
2@jd:body
3
4<!--
5    Copyright 2015 The Android Open Source Project
6
7    Licensed under the Apache License, Version 2.0 (the "License");
8    you may not use this file except in compliance with the License.
9    You may obtain a copy of the License at
10
11        http://www.apache.org/licenses/LICENSE-2.0
12
13    Unless required by applicable law or agreed to in writing, software
14    distributed under the License is distributed on an "AS IS" BASIS,
15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16    See the License for the specific language governing permissions and
17    limitations under the License.
18-->
19<div id="qv-wrapper">
20  <div id="qv">
21    <h2>In this document</h2>
22    <ol id="auto-toc">
23    </ol>
24  </div>
25</div>
26
27<p>The Android framework has a small tool called <code>validatekeymaps</code> to validate the
28syntax of input device configuration files, key layout files, key character
29maps files and virtual key definition files.</p>
30<h2 id="compilation">Compilation</h2>
31<p>To compile <code>validatekeymaps</code>, set up the development environment, download
32the Android source tree, compile it, then run:</p>
33<pre><code>$ mmm frameworks/base/tools/validatekeymaps
34</code></pre>
35<p>This command should compile a host tool called validatekeymaps into the
36<code>out/host/&lt;os&gt;/bin</code> directory.</p>
37<h2 id="usage">Usage</h2>
38<p>If you ran <code>envsetup.sh</code> to set up your development environment, then the
39<code>validatekeymaps</code> tool should already be on your path.  You can verify
40this by running <code>validatekeymaps</code>.</p>
41<pre><code>$ validatekeymaps
42
43Keymap Validation Tool
44
45Usage:
46 validatekeymaps [*.kl] [*.kcm] [*.idc] [virtualkeys.*] [...]
47   Validates the specified key layouts, key character maps,
48   input device configurations, or virtual key definitions.
49</code></pre>
50<p>Then all you need to do is run <code>validatekeymaps</code> an give it the path of
51one or more files to validate.</p>
52<pre><code>$ validatekeymaps frameworks/base/data/keyboards/Generic.kl
53
54Validating file 'frameworks/base/data/keyboards/Generic.kl'...
55No errors.
56
57Success.
58</code></pre>
59<p>And if there is an error...</p>
60<pre><code>$ validatekeymaps Bad.kl
61
62Validating file 'Bad.kl'...
63E/KeyLayoutMap(87688): Bad.kl:24: Expected keyword, got 'ke'.
64Error -22 parsing key layout file.
65
66Failed!
67</code></pre>
68<h2 id="automation">Automation</h2>
69<p>It is a <em>very</em> good idea to run <code>validatekeymaps</code> on all configuration files
70before installing them on a device.</p>
71<p>The process can easily be automated as part of the build system by using a
72script or a makefile.</p>
73<p>The following sample makefile is based on the contents of
74<code>frameworks/base/data/keyboards/Android.mk</code>.</p>
75<pre><code># This makefile performs build time validation of framework keymap files.
76
77LOCAL_PATH := $(call my-dir)
78
79# Validate all key maps.
80include $(CLEAR_VARS)
81
82validatekeymaps := $(HOST_OUT_EXECUTABLES)/validatekeymaps$(HOST_EXECUTABLE_SUFFIX)
83files := MyKeyboard.kl MyKeyboard.kcm MyTouchScreen.idc
84
85LOCAL_MODULE := validate_framework_keymaps
86LOCAL_MODULE_TAGS := optional
87LOCAL_REQUIRED_MODULES := validatekeymaps
88
89validate_framework_keymaps: $(files)
90    $(hide) $(validatekeymaps) $(files)
91
92include $(BUILD_PHONY_PACKAGE)
93</code></pre>
94