https://wiki.archlinux.org/api.php?action=feedcontributions&user=Dbeattyspace&feedformat=atomArchWiki - User contributions [en]2024-03-29T05:19:55ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=ROS&diff=587486ROS2019-10-30T14:58:32Z<p>Dbeattyspace: /* Building from source */ Adding a note about how to download a specific version of ROS 2</p>
<hr />
<div>[[Category:Science]]<br />
[[ja:ROS]]<br />
[http://www.ros.org ROS] is an open-source, meta-operating system for your robot. It provides the services you would expect from an operating system, including hardware abstraction, low-level device control, implementation of commonly-used functionality, message-passing between processes, and package management.<br />
<br />
== Installation Instructions ==<br />
<br />
You can install any of the ROS distributions below since they are fully released on AUR.<br />
<br />
Melodic {{AUR|ros-melodic-desktop-full}}<br />
<br />
Lunar {{AUR|ros-lunar-desktop-full}}<br />
<br />
== Older Versions (Not fully working) ==<br />
<br />
=== Kinetic ===<br />
<br />
Kinetic packages on the AUR are a work in progress. There are [https://github.com/bchretien/arch-ros-stacks/issues/57#issuecomment-228612399 some issues regarding opencv3] that have not been fully resolved yet (installing {{AUR|ros-kinetic-opencv3}} works, but is somewhat inefficient since it rebuilds opencv3). Currently, installing a metapackage such as {{AUR|ros-kinetic-ros-core}} or {{AUR|ros-kinetic-robot}} should bring in all required dependencies (see [https://paste.xinu.at/YXIz/] for the correct order).<br />
<br />
Packages are being added on an as-needed basis. Please post any issues with the current packages in their respective AUR comments section.<br />
<br />
== catkin_make ==<br />
<br />
Note that catkin uses python2, and therefore catkin_make may fail unless it explicitly uses python2. To do so, add the following alias to ~/.bashrc:<br />
<br />
alias catkin_make="catkin_make -DPYTHON_EXECUTABLE=/usr/bin/python2 -DPYTHON_INCLUDE_DIR=/usr/include/python2.7 -DPYTHON_LIBRARY=/usr/lib/libpython2.7.so"<br />
<br />
Another way is to use {{AUR|python-catkin_tools}} and to configure it by running the following command in your Catkin workspace.<br />
catkin config --cmake-args -DPYTHON_EXECUTABLE=/usr/bin/python2<br />
<br />
=== Using Catkin/ROS with an IDE ===<br />
==== CLion ====<br />
To make {{AUR|CLion}} support ROS packages, you can change the {{ic|Exec}} parameter of its desktop file ({{ic| ~/.local/share/applications/jetbrains-clion.desktop}}) as follows.<br />
Exec=bash -i -c "source /home/[username]/catkin_ws/devel/setup.sh;/opt/clion/bin/clion.sh" %f<br />
However, {{ic|/home/[username]/catkin_ws}} must be exchanged with your Catkin workspace. You can now open a Catkin project without {{Pkg|cmake}} complaining about missing packages, hopefully.<br />
If desired or needed you can use Python 3 by adding {{ic|1=-DPYTHON_EXECUTABLE=/usr/bin/python3}} to the CMake options which can be found in the settings.<br />
<br />
== catkin build ==<br />
<br />
For configuring the systems using the {{ic|catkin build}} environment, one have to configure the catkin workspace as usual and issue a<br />
<br />
catkin config -DPYTHON_EXECUTABLE=/usr/bin/python2 -DPYTHON_INCLUDE_DIR=/usr/include/python2.7 -DPYTHON_LIBRARY=/usr/lib/libpython2.7.so<br />
<br />
Afterwards, use {{ic|catkin build}} as normal. Please remember to reconfigure your catkin whenever you delete the configuration files (i.e. the {{ic|catkin_ws}} directory)<br />
<br />
== Rebuild when shared libraries are updated ==<br />
<br />
When you update a library that ROS depends on (e.g. Boost), all packages that link to it must be rebuilt. Most AUR helpers will not detect this situation. The following script will generate a list of all packages that are linked to missing so files:<br />
<br />
https://seangreenslade.com/h/snippets/ros-find-outofdate.py<br />
<br />
(Note that the script requires {{pkg|pyalpm}} to be installed.)<br />
<br />
== ROS 2 ==<br />
=== Building from source ===<br />
<br />
Build instructions are available at https://index.ros.org/doc/ros2/Installation/Dashing/Linux-Development-Setup/.<br />
<br />
Install build dependencies: {{Pkg|wget}}, {{Pkg|python}}, {{Pkg|python-yaml}}, {{Pkg|python-setuptools}}, {{Pkg|sip}}, {{Pkg|python-sip}}, {{Pkg|python-pyqt5}}, {{Pkg|git}}, {{Pkg|cmake}}, {{Pkg|asio}}, {{Pkg|tinyxml}}, {{Pkg|tinyxml2}}, {{Pkg|eigen}}, {{Pkg|libxaw}}, {{Pkg|glu}}, {{Pkg|qt5-base}}, {{Pkg|opencv}}, {{Pkg|hdf5}}, {{Pkg|vtk}}, {{Pkg|glew}}, {{Pkg|poco}}, {{Pkg|python-nose}}, {{Pkg|python-numpy}}, {{Pkg|python-lark-parser}},{{Pkg|python-cryptography}}, {{Pkg|python-netifaces}},{{AUR|python-vcstool}}, {{AUR|python-empy}}, {{AUR|log4cxx}}, {{AUR|python-colcon-common-extensions}}, {{AUR|python-rosdep}}.<br />
<br />
Fetch the sources:<br />
<br />
$ mkdir -p ~/ros2_ws/src<br />
$ cd ~/ros2_ws<br />
$ wget https://raw.githubusercontent.com/ros2/ros2/master/ros2.repos<br />
$ vcs import src < ros2.repos<br />
<br />
Note: Replace "master" with whatever distribution is desired (e.g. "dashing").<br />
<br />
Presently some fixes are required:<br />
<br />
Edit {{ic|build/qt_gui_cpp/sip/qt_gui_cpp_sip/Makefile:12}}, replacing {{ic|$$[QT_INSTALL_LIBS]}} with {{ic|/usr/lib}}.<br />
[https://github.com/ros-visualization/rviz/issues/1382#issuecomment-507007580 Github issue]<br />
<br />
Now you can build the workspace:<br />
<br />
$ cd ~/ros2_ws<br />
$ colcon build --symlink-install<br />
<br />
Read https://github.com/ros2/ros1_bridge/blob/master/README.md#build-the-bridge-from-source regarding ROS 1 / ROS 2 interoperability.<br />
<br />
=== Usage Examples ===<br />
<br />
First source the workspace:<br />
<br />
$ . ~/ros2_ws/install/local_setup.bash<br />
<br />
Functionality comparable to {{ic|roscore}}, {{ic|rosnode}}, {{ic|rostopic}}, {{ic|rosmsg}}, {{ic|rospack}}, {{ic|rosrun}} and {{ic|rosservice}} is available via {{ic|ros2}}:<br />
<br />
$ ros2 -h<br />
usage: ros2 [-h] Call `ros2 <command> -h` for more detailed usage. ... <br />
<br />
ros2 is an extensible command-line tool for ROS 2.<br />
<br />
optional arguments:<br />
-h, --help show this help message and exit<br />
<br />
Commands:<br />
daemon Various daemon related sub-commands<br />
msg Various msg related sub-commands<br />
node Various node related sub-commands<br />
pkg Various package related sub-commands<br />
run Run a package specific executable<br />
security Various security related sub-commands<br />
service Various service related sub-commands<br />
srv Various srv related sub-commands<br />
topic Various topic related sub-commands<br />
<br />
Call `ros2 <command> -h` for more detailed usage.<br />
<br />
A typical "Hello World" example starts with running a publisher node:<br />
<br />
$ ros2 topic pub /chatter 'std_msgs/String' "data: 'Hello World'"<br />
<br />
Then, in another terminal, you can run a subscriber (Don't forget to source the workspace in every new terminal):<br />
<br />
$ ros2 topic echo /chatter<br />
<br />
List existing nodes:<br />
<br />
$ ros2 node list<br />
publisher_std_msgs_String<br />
<br />
List topics:<br />
<br />
$ ros2 topic list<br />
/chatter<br />
<br />
ROS 2's version of rviz is <br />
<br />
$ rviz2</div>Dbeattyspacehttps://wiki.archlinux.org/index.php?title=SageMath&diff=543563SageMath2018-09-25T20:43:58Z<p>Dbeattyspace: /* SageTeX */ File created is named doc.sagetex.sage when compiling</p>
<hr />
<div>[[Category:Mathematics and science]]<br />
[[ja:SageMath]]<br />
{{Related articles start}}<br />
{{Related|Matlab}}<br />
{{Related|Octave}}<br />
{{Related|Mathematica}}<br />
{{Related articles end}}<br />
<br />
[http://www.sagemath.org SageMath] (formerly '''Sage''') is a program for numerical and symbolic mathematical computation that uses [[Python]] as its main language. It is meant to provide an alternative for commercial programs such as Maple, Matlab, and Mathematica.<br />
<br />
SageMath provides support for the following:<br />
* '''Calculus''': using [[Wikipedia:Maxima (software)|Maxima]] and [[Wikipedia:SymPy|SymPy]].<br />
* '''Linear Algebra''': using the [[Wikipedia:GNU Scientific Library|GSL]], [[Wikipedia:SciPy|SciPy]] and [[Wikipedia:NumPy|NumPy]].<br />
* '''Statistics''': using [[Wikipedia:R (programming language)|R]] (through RPy) and SciPy.<br />
* '''Graphs''': using [[Wikipedia:matplotlib|matplotlib]].<br />
* An '''interactive shell''' using [[Wikipedia:IPython|IPython]].<br />
* Access to '''Python modules''' such as [[Wikipedia:Python Imaging Library|PIL]], [[Wikipedia:SQLAlchemy|SQLAlchemy]], etc.<br />
<br />
== Installation ==<br />
<br />
* {{Pkg|sagemath}} contains the command-line version;<br />
* {{Pkg|sagemath-doc}} for HTML documentation and inline help from the command line.<br />
* {{Pkg|sage-notebook}} includes the browser-based notebook interface.<br />
<br />
{{Note|Most of the [http://doc.sagemath.org/html/en/installation/standard_packages.html standard Sage packages] are available as [[pacman#Installing packages|optional dependencies]] of the {{pkg|sagemath}} package or in [[AUR]], therefore they have to be installed additionally as normal Arch packages in order to take advantage of their features. Note that there is no need to install them with {{ic|sage -i}}, in fact this command will not work if you installed SageMath with pacman.}}<br />
<br />
== Usage ==<br />
SageMath mainly uses Python as a scripting language with a few [http://doc.sagemath.org/html/en/tutorial/afterword.html#section-mathannoy modifications] to make it better suited for mathematical computations.<br />
<br />
=== SageMath command-line ===<br />
SageMath can be started from the command-line:<br />
$ sage<br />
<br />
For information on the SageMath command-line see [http://doc.sagemath.org/reference/repl/index.html this page].<br />
<br />
The command-line is based on the IPython shell so you can use all its [http://doc.sagemath.org/html/en/tutorial/interactive_shell.html tricks] with SageMath. For an extensive tutorial on IPython see the community maintained [http://wiki.ipython.org/Cookbook IPython Cookbook].<br />
<br />
Note, however, that it is not very comfortable for some uses such as plotting. When you try to plot something, for example:<br />
sage: plot(sin,(x,0,10))<br />
SageMath opens the plot in an external application.<br />
<br />
=== Sage Notebook ===<br />
{{Note|The SageMath Flask notebook is deprecated in favour of the Jupyter notebook. The Jupyter notebook is recommended for all new worksheets. You can use the {{pkg|sage-notebook-exporter}} application to convert your Flask notebooks to Jupyter}}<br />
<br />
A better suited interface for advanced usage in SageMath is the Notebook.<br />
To start the Notebook server from the command-line, execute:<br />
$ sage -n<br />
<br />
The notebook will be accessible in the browser from http://localhost:8080 and will require you to login. <br />
<br />
However, if you only run the server for personal use, and not across the internet, the login will be an annoyance. You can instead start the Notebook without requiring login, and have it automatically pop up in a browser, with the following command:<br />
$ sage -c "notebook(automatic_login=True)"<br />
<br />
For a more comprehensive tutorial on the Sage Notebook see the [http://doc.sagemath.org/html/en/reference/notebook/index.html Sage documentation]. For more information on the {{ic|notebook()}} command see [http://doc.sagemath.org/html/en/reference/notebook/sagenb/notebook/notebook.html this page].<br />
<br />
=== Jupyter Notebook ===<br />
SageMath also provides a kernel for the [https://jupyter.org/ Jupyter] notebook in the {{Pkg|sagemath-jupyter}} package. To use it, launch the notebook with the command<br />
$ jupyter notebook<br />
and choose "SageMath" in the drop-down "New..." menu. The SageMath Jupyter notebook supports [[LaTeX]] output via the {{ic|%display latex}} command and 3D plots if {{Pkg|jmol}} is installed.<br />
<br />
=== Cantor ===<br />
[http://edu.kde.org/applications/mathematics/cantor/ Cantor] is an application included in the KDE Edu Project. It acts as a front-end for various mathematical applications such as Maxima, SageMath, Octave, Scilab, etc. See the [http://wiki.sagemath.org/Cantor Cantor page] on the Sage wiki for more information on how to use it with SageMath.<br />
<br />
Cantor can be installed with the {{Pkg|cantor}} package or as part of the {{Grp|kde-applications}} or {{Grp|kdeedu}} groups, available in the [[official repositories]].<br />
<br />
== Optional additions ==<br />
=== SageTeX ===<br />
If you have [[TeX Live]] installed on your system, you may be interested in [http://doc.sagemath.org/html/en/tutorial/sagetex.html using SageTeX], a package that makes the inclusion of SageMath code in LaTeX files possible. TeX Live is made aware of SageTeX automatically so you can start using it straight away.<br />
<br />
As a simple example, here is how you include a Sage 2D plot in your TEX document (assuming you use {{ic|pdflatex}}):<br />
* include the {{ic|sagetex}} package in the preamble of your document with the usual<br />
\usepackage{sagetex}<br />
<br />
* create a {{ic|sagesilent}} environment in which you insert your code:<br />
\begin{sagesilent}<br />
dob(x) = sqrt(x^2 - 1) / (x * arctan(sqrt(x^2 - 1)))<br />
dpr(x) = sqrt(x^2 - 1) / (x * log( x + sqrt(x^2 - 1)))<br />
p1 = plot(dob,(x, 1, 10), color='blue')<br />
p2 = plot(dpr,(x, 1, 10), color='red')<br />
ptot = p1 + p2<br />
ptot.axes_labels(['$\\xi$','$\\frac{R_h}{\\max(a,b)}$'])<br />
\end{sagesilent}<br />
<br />
* create the plot, e.g. inside a {{ic|float}} environment:<br />
\begin{figure}<br />
\begin{center}<br />
\sageplot[width=\linewidth]{ptot}<br />
\end{center}<br />
\end{figure}<br />
<br />
* compile your document with the following procedure:<br />
$ pdflatex <doc.tex><br />
$ sage <doc.sagetex.sage><br />
$ pdflatex <doc.tex><br />
<br />
* you can have a look at your output document.<br />
<br />
The full documentation of SageTeX is available on [http://www.ctan.org/pkg/sagetex CTAN].<br />
<br />
== Troubleshooting ==<br />
=== TeX Live does not recognize SageTex ===<br />
If your TeX Live installation does not find the SageTex package, you can try the following procedure (as root or use a local folder):<br />
* Copy the files to the texmf directory:<br />
# cp /opt/sage/local/share/texmf/tex/* /usr/share/texmf/tex/<br />
* Refresh TeX Live:<br />
{{bc|<br />
# texhash /usr/share/texmf/<br />
texhash: Updating /usr/share/texmf/.//ls-R... <br />
texhash: Done.<br />
}}<br />
<br />
== See also ==<br />
* [http://www.sagemath.org/ Official Website]<br />
* [http://doc.sagemath.org/ SageMath Documentation]<br />
* [http://planet.sagemath.org/ Planet Sage]<br />
* [http://wiki.sagemath.org/ SageMath Wiki]<br />
* [http://www.sagemath.org/links-components.html Software Used by SageMath]</div>Dbeattyspacehttps://wiki.archlinux.org/index.php?title=X_keyboard_extension&diff=472709X keyboard extension2017-04-01T01:17:30Z<p>Dbeattyspace: "Simpliest" -> "Simplest"</p>
<hr />
<div>[[Category:X server]]<br />
[[Category:Keyboards]]<br />
[[ja:X KeyBoard extension]]<br />
X KeyBoard extension, or XKB, defines the way keyboards codes are handled in X,<br />
and provides access to internal translation tables.<br />
It is the basic mechanism that allows using multiple keyboard layouts in X.<br />
<br />
Learning about XKB can be hard without some hands-on experience.<br />
This page is intended to help users to start with XKB by doing some changes to their keymaps.<br />
It is not meant as a complete guide to all XKB features. Instead, it skips over gritty details<br />
and focuses on the most practical things first.<br />
<br />
If you ended up here looking for a simple way to configure your keyboard,<br />
be sure to check [[Keyboard configuration in Xorg]] first.<br />
<br />
== Precautions and preparations ==<br />
<br />
It is possible (and, in fact, easy) to end up disabling some keys on your keyboard for the current X session<br />
while working with XKB.<br />
This includes modifiers, cursor arrows and Enter key, as well as C-A-Backspace and C-A-Fx combinations.<br />
Make sure you have some way to terminate the session without using your keyboard.<br />
<br />
While it is rare, changing XKB configuration can sometimes hang or crash X server.<br />
Make sure you can handle it.<br />
Having some way to killall X or reboot the host remotely may be a good idea.<br />
<br />
Stop {{pkg|xxkb}}, or any other layout switching applications. xxkb actively changes XKB state.<br />
Debugging both at the same time is not a good idea.<br />
<br />
And finally, be warned: it is very easy to get used to custom layout.<br />
<br />
== Getting and setting XKB layout ==<br />
<br />
=== Using rules ===<br />
<br />
Look inside {{ic|/usr/share/X11/xkb/rules/}} for {{ic|*.lst}} files or the [http://www.x.org/wiki/XKB/ XKB Homepage] to get ideas on how to configure rules. Your own configurations can go in {{ic|/etc/X11/xorg.conf.d/}}.<br />
<br />
For example one may want to remap their {{ic|Caps Lock}} key to {{ic|Escape}}:<br />
<br />
{{hc|90-custom-kbd.conf|<br />
Section "InputClass"<br />
Identifier "keyboard defaults"<br />
MatchIsKeyboard "on"<br />
<br />
Option "XKbOptions" "caps:escape"<br />
EndSection<br />
}}<br />
<br />
=== Using keymap (deprecated) ===<br />
<br />
Use xkbcomp (package {{Pkg|xorg-xkbcomp}}) to manipulate XKB data. To get current configuration, run<br />
<br />
xkbcomp $DISPLAY output.xkb<br />
<br />
To upload the data back to the server, run<br />
<br />
xkbcomp input.xkb $DISPLAY<br />
<br />
Note that without {{ic|$DISPLAY}} argument xkbcomp will try to compile .xkb file into (mostly useless) .xkm<br />
file, without uploading anything to the server. It will, however, check the syntax and report errors.<br />
<br />
Once the layout is ready, save it as {{ic|~/.Xkeymap}} and make {{ic|~/.xinitrc}} load it on startup:<br />
<br />
test -f ~/.Xkeymap && xkbcomp ~/.Xkeymap $DISPLAY<br />
<br />
The actual file name is irrelevant. Note that unlike standard system-wide configuration via {{ic|xorg.conf}},<br />
this is a per-user keymap.<br />
Also, there is absolutely no problem changing XKB configuration while X is running.<br />
<br />
== Basic information on XKB ==<br />
<br />
The core XKB functionality is quite simple, and it's necessary to have a some ideas on<br />
how it works before starting working on the keymaps.<br />
<br />
=== Tools and values ===<br />
<br />
Use xev (package {{pkg|xorg-xev}}) to get keycodes and to check how your keymap works. Sample output:<br />
<br />
KeyPress event, serial 45, synthetic NO, window 0x2200001,<br />
root 0xad, subw 0x0, time 183176240, (796,109), root:(867,413),<br />
state 0x1, keycode 21 (keysym 0x2b, plus), same_screen YES,<br />
XLookupString gives 1 bytes: (2b) "+"<br />
XmbLookupString gives 1 bytes: (2b) "+"<br />
XFilterEvent returns: False<br />
<br />
Note keycode 21, state 0x1 and keysym 0x2b aka plus.<br />
Keycode 21 is what input device supplied to X, typically a physical key index of some sort.<br />
The state represents modifier keys, 0x01 is Shift.<br />
Keycode together with the state value is what X sends to the application in XKeyEvent(3) structure.<br />
Keysym and corresponding string is what the client obtained using XLookupString(3) and friends.<br />
<br />
The bits in the state field have pre-defined names: {{ic|Shift}}, {{ic|Lock}}, {{ic|Control}}, {{ic|Mod1}}, {{ic|Mod2}},<br />
{{ic|Mod3}}, {{ic|Mod4}} and {{ic|Mod5}},<br />
lowest to highest. Thus, {{ic|Ctrl+Shift}} is 0x05, and so on. Client applications typically only check the bits<br />
they need, so an application with normal keyboard input and {{ic|Ctrl+key}} shortcuts usually<br />
makes no distinction between {{ic|Control}} and {{ic|Control+Mod3}} states.<br />
<br />
Keysyms are numeric, too. A lot of them have names, declared in {{ic|/usr/include/X11/keysymdef.h}}<br />
with {{ic|KP_}} prefix. However, the number is what clients actually receive.<br />
Keysyms are only important when an application expects some particular values; typically<br />
that is keys like arrows, Enter, Backspace, F-keys, and various shortcuts.<br />
For the rest, the string is used.<br />
<br />
=== Keycode translation ===<br />
<br />
XKB works mostly at the XLookupString stage,<br />
transforming incoming keycode into keysym according to its own internal state, which is <br />
group and state values:<br />
<br />
(keycode, group, state) → keysym<br />
<br />
Group typically represents a "layout", as in US-English, French-AZERTY, Russian, Greek etc.<br />
There can be at most 4 groups.<br />
<br />
Internally, the translation involves additional steps:<br />
<br />
(keycode [, group]) → type<br />
(state, type) → level<br />
(keycode, group, level) → S[keycode][group][level]<br />
<br />
with {{ic|S}} being the translation table (actually called {{ic|xkb_symbols}}, see below).<br />
<br />
Types are used to tell which modifiers affect which keys; essentially it's a way to reduce the third dimension<br />
of {{ic|S}}. For example, typical alphanumeric key is only affected by {{ic|Shift}}; it's type is set to {{ic|TWO_LEVEL}}, and<br />
<br />
(state, TWO_LEVEL) → level = ((state >> 0) & 0x01) = state & 0x01<br />
<br />
which is either 0 or 1. Thus it's {{ic|S[keycode][0..4][0..1]}} instead of {{ic|S[keycode][0..4][0..256]}}.<br />
<br />
=== Keysyms and states ===<br />
<br />
In X terms, {{ic|a}} and {{ic|Ctrl+a}} means same keysym and different states,<br />
but {{ic|a}} and {{ic|A}} are different keysyms.<br />
<br />
Generally it is XKB task to provide different keysyms, but states are handled later<br />
by individual applications.<br />
<br />
Also, states in XKB have somewhat delayed effect, that is, you must have the state set<br />
prior to pressing a key.<br />
<br />
Example: {{ic|Ctrl+h}} can be configured to act as backspace in rxvt (application setting). This<br />
way rxvt will receive {{ic|h}} keysym with {{ic|Control}} bit set in the state value, and it will be clearly<br />
different from {{ic|Backspace}} keysym.<br />
Alternatively, XKB can be used to make {{ic|Ctrl+h}} combination generate {{ic|Backspace}} keysym with {{ic|Control}} bit set;<br />
in this case, rxvt will not see any difference between physical {{ic|Backspace}} key and {{ic|h}} key as<br />
long as {{ic|Ctrl}} key is pressed.<br />
Making {{ic|Ctrl+h}} combination generate {{ic|Backspace}} keysym with no {{ic|Control}} bit set is an XKB task, too,<br />
but it's much more difficult to implement than {{ic|Control+Backspace}}.<br />
<br />
=== Actions ===<br />
<br />
Keysym obtained from the table above can also trigger some action:<br />
<br />
(keysym, state) → action<br />
<br />
For XKB, setting or locking a modifier bit is an action, and so is any X server interaction<br />
like switching consoles, terminating the server, moving pointer etc.<br />
Actions do not generally affect keysyms, and generating a keysym is not an action.<br />
<br />
There is only one possible action for each (keysym, state) pair.<br />
<br />
== Editing the layout ==<br />
<br />
Start with whatever default configuration your server has. Whenever possible, make the changes<br />
gradually and test them.<br />
<br />
The .xkb file produced by xkbcomp is a simple text file.<br />
C++ style comments, // till the end of line, are allowed. <br />
Section names, as in xkb_keycodes "name-here", are irrelevant at this point and can be omited.<br />
<br />
=== xkb_keycodes ===<br />
<br />
Keycode definition. The rest of the file does not use numeric keycodes, only symbolic keylabels<br />
defined in this section.<br />
<br />
It's a good idea to leave only those keys the keyboard in question actually has here.<br />
<br />
The labels themselves are arbitrary. They are only used in xkb_symbols section later.<br />
<br />
=== xkb_types ===<br />
<br />
This section comes before xkb_symbols, so take a look, but try not to make changes yet.<br />
Standard types depend a lot on virtual modifiers, which will be explained later.<br />
For now, just find the types you need. <br />
Start with the following: ONE_LEVEL, TWO_LEVEL, ALPHABETIC.<br />
<br />
ONE_LEVEL keys are not affected by modifiers; typically it's Enter, Space, Escape, F keys,<br />
Shift/Alt/Ctrl keys and so on.<br />
TWO_LEVEL and ALPHABETIC keys produce different keysyms depending on Shift state. All<br />
alphanumeric keys are of these types. ALPHABETIC additionally respects CapsLock.<br />
<br />
Type description themselves are quite simple. The line<br />
<br />
modifiers= Shift+NumLock+LevelThree;<br />
<br />
means keys of this type are affected by Shift, NumLock and LevelThree bits only.<br />
Map lines like<br />
<br />
map[Shift+LevelThree]= Level4;<br />
<br />
define which combination corresponds to which level value. xkbcomp uses "LevelN"<br />
when dumping the data, but short and much more convenient "N" can be used as well.<br />
<br />
level_name lines are irrelevant and can be ignored.<br />
<br />
=== xkb_compatibility ===<br />
<br />
Action definitions ({{ic|interpret}}) and keyboard leds ({{ic|indicator}}) among other things.<br />
It is ok to remove stuff you do not have or do not use, like keypad actions, mouse<br />
control or extra modifiers.<br />
<br />
Note that {{ic|key+AnyOfOrNone(all)}} is equivalent to just {{ic|key}}, but {{ic|key}} is much easier<br />
to read.<br />
<br />
Check groups switching if you need it. {{ic|1=LockGroup(group=N)}} can be useful if you have<br />
four groups, otherwise {{ic|ISO_Next_Group}}/{{ic|ISO_Prev_Group}} are enough. {{ic|LatchGroup}} can be<br />
useful for unusual setups.<br />
<br />
=== xkb_symbols ===<br />
<br />
The main section that defines what each key does. Syntax:<br />
<br />
key <LABL> { [ G1L1, G1L2, G1L3, ... ], [ G2L1, G2L2, G2L3, ... ], ... }<br />
<br />
{{ic|<LABL>}} is keylabel from xkb_keycodes section, {{ic|GiLj}} is keysym for group i level j.<br />
The number of keysyms in each group must match the number of levels defined for this type<br />
({{ic|xkbcomp}} will warn you if it does not).<br />
<br />
Check {{ic|/usr/include/X11/keysymdef.h}} for the list of possible keysyms.<br />
Aside from those listed, you can also use {{ic|Unnnn}} for Unicode symbol with hex code nnnn, e.g.<br />
{{ic|U0301}} for combining acute accent. Note that {{ic|a}} and {{ic|U0061}} are treated differently (for instance,<br />
most applications expect {{ic|Ctrl+a}}, not {{ic|Ctrl+U0061}} because their numeric values are different.<br />
<br />
Key types are also specified here, either as<br />
<br />
key.type = "T1";<br />
key <...> { ... };<br />
key <...> { ... };<br />
key <...> { ... };<br />
key.type = "T2";<br />
key <...> { ... };<br />
key <...> { ... };<br />
<br />
or individually for each key:<br />
<br />
key <...> { type = "T", [ .... ], [ .... ] };<br />
<br />
Key type may be different in different groups. This is somewhat counter-intuitive, but<br />
actually has some useful applications. To set types for each group, use this:<br />
<br />
key <...> { type[1] = "T1", type[2] = "T2", [ ... ], [ ... ] };<br />
<br />
You can set labels for the groups using<br />
<br />
name[1] = "EN"; // group 1<br />
name[2] = "RU"; // group 2<br />
name[3] = "UA"; // group 3<br />
<br />
This is what xxkb will show if labels are enabled there.<br />
<br />
The section also contains {{ic|modifier_map}} lines. Leave them alone for now,<br />
or check Virtual Modifiers below.<br />
<br />
=== xkb_geometry ===<br />
<br />
A completely irrelevant section describing physical keyboard layout.<br />
Can be deleted without any consequences.<br />
<br />
== Basic examples ==<br />
<br />
Check your existing layout first, as it likely contains standard definition for many common keys.<br />
<br />
Thoughout the text, "xkb_keycodes { text }" means "text" should be added<br />
to xkb_keycodes section.<br />
Whenever it's clear from context, section names are omited.<br />
<br />
=== Simple key assignment ===<br />
<br />
Enabling additional (aka multimedia) keys:<br />
<br />
xkb_keycodes {<br />
<VOL-> = 122; // check with xev<br />
<VOL+> = 123;<br />
}<br />
<br />
xkb_symbols {<br />
key.type = "ONE_LEVEL";<br />
key <VOL-> { [ XF86AudioLowerVolume ] };<br />
key <VOL+> { [ XF86AudioRaiseVolume ] };<br />
}<br />
<br />
Escape on CapsLock, for vimers mostly:<br />
<br />
key.type = "ONE_LEVEL";<br />
key <CAPS> { [ Escape ] };<br />
<br />
Exchanging Ins and PrintScreen (in case they are reversed — happens on Dell laptop keyboards):<br />
<br />
key.type = "ONE_LEVEL";<br />
key <IN?> { [ Print ] };<br />
key <PRSC> { [ Insert ] };<br />
<br />
On some HP laptop keyboards, the above does not work. Instead, the keycodes themselves must be redefined:<br />
<br />
partial xkb_keycodes "insert" {<br />
alias <I118> = <IN?>;<br />
&lt;INS&gt; = 218;<br />
<I218> = 118;<br />
};<br />
<br />
Changing shift to a sticky key version:<br />
<br />
replace<br />
<br />
key <LFSH> { [ Shift_L ] };<br />
<br />
with<br />
<br />
key <LFSH> { [ ISO_Level2_Latch ] };<br />
<br />
=== Multiple layouts ===<br />
<br />
For regular alphanumeric keys, just add a second/third/fourth [ ] section to the key definition:<br />
<br />
key.type = "ALPHABETIC";<br />
key <AD01> { [ q, Q ], [ a, A ] }; // QWERTY-AZERTY<br />
<br />
key <AC02> { [ s, S ], // two cyrillic layouts<br />
[ U044B, U042B ],<br />
[ U0456, U0406 ] };<br />
<br />
Layout switching is done by triggering action LockGroup:<br />
<br />
interpret ISO_Next_Group { action = LockGroup(group=+1); };<br />
interpret ISO_Prev_Group { action = LockGroup(group=-1); };<br />
<br />
Typically this means placing ISO_Next_Group and ISO_Prev_Group<br />
keysyms in correct group/level positions. Note that groups wrap, so if you have two groups and hit<br />
ISO_Next_Group twice, you will return to the group you started with.<br />
<br />
Cyclic switching between two or more layouts with a dedicated key:<br />
<br />
key.type = "ONE_LEVEL";<br />
key <RWIN> { [ ISO_Next_Group ] }<br />
<br />
If you have more than two layouts and some keys to spare, it may be a better idea to have a dedicated<br />
key for each layout. Example for three layouts:<br />
<br />
key.type = "ONE_LEVEL";<br />
key <RCTL> { [ ISO_Next_Group ], // g1: switch to g2<br />
[ ISO_Prev_Group ], // g2: switch back to g1<br />
[ ISO_Prev_Group ] }; // g3: switch to g2<br />
<br />
key <MENU> { [ ISO_Prev_Group ], // g1: switch to g3<br />
[ ISO_Next_Group ], // g2: switch to g3<br />
[ ISO_Next_Group ] }; // g3: switch back to g1<br />
<br />
With four layouts, you will likely have to use ISO_First_Group and ISO_Last_Group.<br />
<br />
The same idea can be implemented with only one key by utilizing TWO_LEVEL type:<br />
<br />
key.type = "TWO_LEVEL";<br />
key <MENU> { [ ISO_Next_Group, ISO_Prev_Group ], <br />
[ ISO_Prev_Group, ISO_Next_Group ], <br />
[ ISO_Prev_Group, ISO_Next_Group ] }; <br />
<br />
This way it's Menu for group 2 and Shift-Menu for group 3. To use Ctrl or Alt instead of Shift,<br />
replace TWO_LEVEL with PC_CONTROL_LEVEL2 or PC_ALT_LEVEL2 types respectively.<br />
<br />
Switching using two modifier keys (Shift+Shift, Ctrl+Shift etc) can be done by using something other<br />
than ONE_LEVEL for these keys. Shift+Shift example:<br />
<br />
key.type = "TWO_LEVEL";<br />
key <LFSH> { [ Shift_L, ISO_Prev_Group ] };<br />
key <RTSH> { [ Shift_R, ISO_Next_Group ] };<br />
<br />
To latch a group (aka toggle; set for the time you hold the key only), use LatchGroup action typically<br />
bound to ISO_Group_Latch keysym:<br />
<br />
key <RCTL> { [ ISO_Group_Latch ] }<br />
<br />
Adjust ISO_Group_Latch definition in xkb_compatibility section to use the right group:<br />
<br />
interpret ISO_Group_Latch { action = LatchGroup(group=3); };<br />
<br />
Check /usr/share/X11/xkb/symbols/group for more standard examples.<br />
<br />
=== Additional symbols ===<br />
<br />
Typing more with the same keys.<br />
<br />
==== Compose key ====<br />
<br />
Easy to set up and extremely useful for entering common unicode characters.<br />
<br />
key <RALT> { [ Multi_key ] };<br />
<br />
==== Level3 ====<br />
<br />
The idea is similar to Alt or AltGr in their original meaning: alphanumeric keys<br />
get additional characters, activated by holding down some modifier key.<br />
<br />
First of all, setting up the modifier.<br />
<br />
xkb_symbols { <br />
key <LWIN> { [ISO_Level3_Shift ] };<br />
modifier_map Mod5 { ISO_Level3_Shift };<br />
}<br />
<br />
Also, the following should already be defined in the relevant sections, but in case it is not:<br />
<br />
xkb_compatibility {<br />
interpret ISO_Level3_Shift { action= SetMods(modifiers=Mod5); };<br />
}<br />
<br />
xkb_types {<br />
type "THREE_LEVEL" {<br />
modifiers= Shift+Mod5;<br />
map[Shift]= Level2;<br />
map[Mod5]= Level3;<br />
map[Shift+Mod5]= Level3;<br />
level_name[Level1]= "Base";<br />
level_name[Level2]= "Shift";<br />
level_name[Level3]= "Level3";<br />
};<br />
type "FOUR_LEVEL" {<br />
modifiers= Shift+LevelThree;<br />
map[Shift]= Level2;<br />
map[LevelThree]= Level3;<br />
map[Shift+LevelThree]= Level4;<br />
level_name[Level1]= "Base";<br />
level_name[Level2]= "Shift";<br />
level_name[Level3]= "Alt Base";<br />
level_name[Level4]= "Shift Alt";<br />
};<br />
}<br />
<br />
Note standard definitions have LevelThree instead of Mod5 in xkb_compatibility and xkb_types.<br />
As long as modifier_map above uses Mod5, there is no practical difference, you will end up using Mod5<br />
bit anyway.<br />
<br />
Now, the keys themselves, vi-style cursors in this case:<br />
<br />
key.type = "THREE_LEVEL";<br />
key <AC06> { [ h, H, Left ] };<br />
key <AC07> { [ j, J, Down ] };<br />
key <AC08> { [ k, K, Up ] };<br />
key <AC09> { [ l, L, Right ] };<br />
<br />
As you may find out using xev, this produces Mod5+Left instead of just Left. But that is ok as most<br />
appications ignore state bits they do not use. For an alternative solution, check Overlays below.<br />
<br />
=== Meta, Super and Hyper ===<br />
<br />
==== Real modifiers ====<br />
<br />
Some applications (notably emacs) allow meaningful use of higher state bits. It is usually assumed<br />
there are modifier keys called Meta, Super and Hyper on the keyboard beside standard Shift, Ctrl and Alt,<br />
which control these bits.<br />
<br />
From XKB point of view this means setting Mod2, Mod3, Mod4 and Mod5 modifier bits. Because all<br />
you need is the bits themselves, there is no need to edit types like in the Level3 example above.<br />
<br />
xkb_compatibility {<br />
interpret Super_L { action = SetMods(modifiers=Mod3); };<br />
}<br />
<br />
xkb_symbols {<br />
key <LWIN> { [ Super_L ] };<br />
modifier_map Mod3 { Super_L };<br />
}<br />
<br />
Standard definitions use Super modifier instead of Mod3 in {{ic|xkb_compatibility}}.<br />
You can keep that, just make sure {{ic|modifier_map}} line is in place.<br />
<br />
Keep in mind there is no strict correspondence between ModN and named modifiers like Super, Hyper or even Alt.<br />
Mod1 is the only one that is widely used; some applications call it Meta, some Alt. For the others,<br />
check how particular application treats state bits, and/or check Virtual modifiers below.<br />
<br />
==== Keysym tracking ====<br />
<br />
At least one application (openbox) is known to track KeyPress/KeyRelease events for Meta_[LR], Super_[LR]<br />
and Hyper_[LR] keysyms instead of relying on the state bits. In such case<br />
<br />
xkb_symbols {<br />
key <LWIN> { [ Super_L ] };<br />
}<br />
<br />
is enough and you can omit {{ic|interpret}} and {{ic|modifier_map}} lines.<br />
<br />
Speaking of openbox, note it actually allows both methods: "S-h" tracks Super_[LR] events<br />
while "Mod3-h" checks relevant state bit.<br />
<br />
== Preset configuration ==<br />
<br />
XKB is often configured by specifying XkbTypes/XkbCompat/XkbSymbols,<br />
or XkbModel/XkbLayout (+XkbVariant/XkbOptions), or XkbKeymap, typically in<br />
/etc/X11/xorg.conf or /etc/X11/xorg.conf.d/*.conf, like this:<br />
<br />
Option "XkbModel" "thinkpad60" <br />
Option "XkbLayout" "us,sk,de" <br />
Option "XkbVariant" "altgr-intl,qwerty," <br />
Option "XkbOptions" "grp:menu_toggle,grp_led:caps" <br />
<br />
These values define full XKB map (the one that can be dumped by xkbcomp) by combining<br />
several files from {{ic|/usr/share/X11/xkb}}. In fact, equivalent .xkb<br />
file for xkbcomp can be obtained using {{ic|setxkbmap -print}}:<br />
<br />
setxkbmap -model thinkpad60 -layout us,sk,de -variant altgr-intl,qwerty \<br />
-option -option grp:menu_toggle -option grp_led:caps -print<br />
<br />
Note include statements in the output. The files for each section are fetched from<br />
relevant subdirectories under {{ic|/usr/share/X11/xkb}}, i.e.<br />
<br />
xkb_types { include "complete" };<br />
<br />
means xkbcomp will look for {{ic|/usr/share/X11/xkb/types/complete}}. Plus signs mean<br />
concatenation, so<br />
<br />
xkb_keycodes { include "evdev+aliases(qwerty)" };<br />
<br />
means <br />
<br />
xkb_keycodes {<br />
include "evdev";<br />
include "aliases(qwerty)";<br />
};<br />
<br />
Parenthesis select named section from the file. Check<br />
{{ic|/usr/share/X11/xkb/keycodes/aliases}} and note<br />
<br />
xkb_keycodes "qwerty" { ... };<br />
<br />
this is the part {{ic|aliases(qwerty)}} refers to. Finally, colons allow shifting<br />
parts of layout to another group.<br />
<br />
Unlike XkbTypes/XkbCompat/XkbSymbols/XkbGeometry values, which define relevant<br />
.xkb file sections directly, XkbModel, XkbLayout and XkbRules refer to<br />
additional non-xkb files found under {{ic|/usr/share/X11/xkb/rules/}} that match model<br />
and layout values to specific symbols and geometry. XkbKeymap refers to complete<br />
keymaps. Check Ivan Pascal page for detailed description.<br />
<br />
Just like with xkbcomp approach, this kind of configuration can be done<br />
on the fly: use setxkbmap without -print option.<br />
<br />
The files from {{ic|/usr/share/X11/xkb}} are a good source of examples, especially when it<br />
comes to standard keyboard features with nontrivial XKB implementation<br />
(e.g. keypad/NumLock handling). Also, these are the files you have to edit to push<br />
your changes upstream. Check [http://www.freedesktop.org/wiki/Software/XKeyboardConfig/Rules X Keyboard Config Rules] before doing it though.<br />
<br />
=== xmodmap ===<br />
<br />
While sometimes used in conjunction with preset configuration,<br />
[[xmodmap]] is not directly related to XKB. This tool uses different (pre-XKB)<br />
ideas on how keycodes are processed within X; in particular, xmodmap lacks the notion<br />
of groups and types, so trying to set more than one keysym per key is not likely<br />
to work.<br />
<br />
Generally it is not recommended to use xmodmap, except maybe for the simplest tasks.<br />
XKB-compatible equivalent of xmodmap is xkbcomp; however,<br />
xkbcomp lacks -e option, so it is not that simple.<br />
Anyway, whenever possible, xkbcomp should be preferred.<br />
<br />
== Indicators ==<br />
<br />
As in "keyboard leds".<br />
Indicator names are used to match the to the physical LEDs in xkb_keycodes section.<br />
Otherwise, they are irrelevant. Indicators not matched to any LED are called "virtual";<br />
xkbvleds (package {{Pkg|xorg-xkbutils}}) can be used to check their state. Example:<br />
<br />
xkb_keycodes {<br />
indicator 1 = "LED1"; // first physical LED<br />
}<br />
<br />
Indicators always reflect specified part of XKB internal state. Two common modes is showing<br />
modifier state:<br />
<br />
xkb_compatibility {<br />
indicator "LED1" { modifiers = Lock; }; // CapsLock indicator<br />
}<br />
<br />
or current group:<br />
<br />
xkb_compatibility {<br />
indicator "LED1" { groups = 0x06; }; // "group 2 or group 3 is active"<br />
}<br />
<br />
The values are bitmasks. For groups, bit 1 is group 1, bit 2 is group 2 and so on.<br />
<br />
== Modifiers and types ==<br />
<br />
At some point it may become necessary to clean up types section, and/or to introduce<br />
unusual types.<br />
<br />
Types and modifiers are tightly connected, so it makes a lot of sense to start with<br />
the modifier bits first, before doing anything with the type descriptions.<br />
<br />
Decide which bits you will use. There are only eight of them, and of those,<br />
Shift, Control and Mod1 are widely used in applications, and Lock (aka CapsLock)<br />
has pre-defined meaning which also may be hard to override.<br />
The remaining four, however, are fair play.<br />
<br />
Warning: four standard types, ONE_LEVEL, TWO_LEVEL, ALPHABETIC and KEYPAD, receive<br />
special treatment in xkbcomp. They may work differently just because they are named<br />
this way. Avoid deleting them. If some changes do not work as expected, try adding a new<br />
type instead.<br />
<br />
=== Using real modifiers in standard types ===<br />
<br />
Depending of your base configuration, there may be a lot of unused standard types<br />
like EIGHT_LEVEL or PC_RCONTROL_LEVEL2.<br />
Remove them to avoid doing unnecessary work.<br />
<br />
Now, some standard types use virtual modifiers. If you decide to use them, check<br />
Virtual modifiers below and skip this section. Otherwise, it's a good idea<br />
to get rid of them completely. Check the types you need, and either replace them<br />
with corresponding real ones, or remove relevant definitions. Example:<br />
<br />
type "KEYPAD" {<br />
modifiers= Shift+NumLock;<br />
map[Shift]= Level2;<br />
map[NumLock]= Level2;<br />
level_name[Level1]= "Base";<br />
level_name[Level2]= "Number";<br />
};<br />
<br />
if you use Mod2 for NumLock, change the type to<br />
<br />
type "KEYPAD" {<br />
modifiers= Shift+Mod2;<br />
map[Shift]= Level2;<br />
map[Mod2]= Level2;<br />
level_name[Level1]= "Base";<br />
level_name[Level2]= "Number";<br />
};<br />
<br />
if you are not going to have NumLock modifier, change it to<br />
<br />
type "KEYPAD" {<br />
modifiers= Shift;<br />
map[Shift]= Level2;<br />
level_name[Level1]= "Base";<br />
level_name[Level2]= "Number";<br />
};<br />
<br />
Do the same in xkb_compatibility section too.<br />
Once it's done, you should be able to remove all "virtual_modifiers" lines in the file.<br />
<br />
=== Switching a single modifier bit ===<br />
<br />
Basically all you need is a keysym with a relevant interpretation entry.<br />
Example for Mod5 switching with {{ic|LWIN}} key, with {{ic|ISO_Level3_Shift}} for keysym:<br />
<br />
xkb_compatibility {<br />
interpret ISO_Level3_Shift { action = SetMods(modifiers=Mod5); };<br />
}<br />
<br />
xkb_symbols {<br />
key <LWIN> { [ISO_Level3_Shift ] };<br />
}<br />
<br />
Aside from {{ic|SetMods}}, you can also use {{ic|LockMods}} or {{ic|LatchMods}}.<br />
{{ic|SetMods}} makes a regular "on while pressed" modifier key.<br />
{{ic|LockMods}} makes an "on/off" switch like CapsLock or NumLock.<br />
{{ic|LatchMods}} means "on until next keypress" aka sticky modifier<br />
<br />
=== modifier_map ===<br />
<br />
Modifier map is a table that maps each of eight modifier bits to at most<br />
two keys:<br />
<br />
modifier_map Mod1 { Alt_L, Alt_R };<br />
<br />
In the core protocol, without XKB, it means more or less the same thing<br />
as<br />
<br />
interpret Alt_L { action = SetMods(modifiers=Mod1); };<br />
interpret Alt_R { action = SetMods(modifiers=Mod1); };<br />
<br />
XKB does not use modifier map in its original meaning. Within XKB, its<br />
only function is to map virtual modifiers (see below).<br />
<br />
However, the table is easily accessible by clients, and there is one<br />
counter-intuitive (but well-known) trick involving it:<br />
modifier map is used to tell which of ModX bits is Alt.<br />
Because of this, it is a good idea to have one modifier mapped<br />
to Alt_L or Alt_R as shown above. Unless you have very good reasons<br />
to do otherwise, it should be Mod1.<br />
<br />
== Multiple keyboards ==<br />
<br />
XKB allows setting keymap for a single connected physical keyboard only.<br />
This feature can be extremely useful for multi-keyboard setups when keyboards<br />
in question are different; consider a laptop with a full-size USB keyboard attached.<br />
<br />
First of all, use xinput (package {{Pkg|xorg-xinput}}) to get device IDs:<br />
<br />
AT Translated Set 2 keyboard id=11 [slave keyboard (3)]<br />
<br />
Now,<br />
<br />
xkbcomp -i 11 file.xkb $DISPLAY<br />
<br />
or<br />
setxkbmap -device 11 ...<br />
<br />
will set keymap for specified keyboard only. Dumping XKB configuration works too:<br />
<br />
xkbcomp -i 11 $DISPLAY file.xkb<br />
<br />
Note {{ic|xkbcomp -i11}} will not work and will not give a clear error message either. Make sure<br />
you have space after {{ic|-i}}.<br />
<br />
== Debugging XKB ==<br />
<br />
When keys do not work as expected, the first thing to check is XKB internal state:<br />
modifiers, effective group and control bits. All three can be used to drive leds;<br />
use xkbvleds to check them<br />
<br />
indicator "LED1" { modifiers = Lock; };<br />
indicator "LED2" { groups = 2; };<br />
indicator "LED3" { controls = audiblebell; };<br />
<br />
Additionally, xkbwatch shows all (real) modifiers together with their lock/latch status.<br />
Modifiers are also reported by xev. Xxkb can be used to monitor effective group, but<br />
make sure two_state mode is off.<br />
<br />
In case interpretations section does not work well, make sure to check for duplicated<br />
"interpret" blocks. Better yet, try commenting out anything related to specific keysym.<br />
See section 9.2 for explanation.<br />
<br />
It also makes sense to check what exactly the server got by downloading the keymap back with<br />
<br />
xkbcomp $DISPLAY out.xkb<br />
<br />
The results tend to be different from the input file. There is no known work-around for this.<br />
<br />
== Virtual Modifiers ==<br />
<br />
One of the most troublesome parts of XKB, virtual modifiers appear prominently<br />
in all standard keymaps, despite being a relatively minor and mostly useless feature.<br />
The term itself is grossly misleading, and most of the docs do not help much either.<br />
<br />
So, first of all: virtual modifiers are not modifiers in the same way real modifiers are.<br />
If anything, it is a way to name some of the real modifiers. They are not 16 more bits<br />
that can be used in level definitions. They are 16 possible names, each referring<br />
to one (or some, or none) of the 8 modifier bits.<br />
<br />
Real modifier bits are called Shift, Lock, Control and Mod1-Mod5. There are no<br />
Alt among them. Virtual modifiers were introduced to allow saying something like<br />
<br />
#define Alt Mod1<br />
<br />
to applications willing to use this information.<br />
<br />
It is possible to make a usable layout without defining virtual modifiers at all.<br />
Among standard modifiers, only Alt/Meta actually need such treatment, because<br />
Shift and Control are real modifiers anyway and NumLock is not normally used as a modifier.<br />
<br />
Also, unlike most of the keymap-related things that affect any application using<br />
basic Xlib functions, virtual modifiers must be queried explicitly using XKBlib<br />
calls. Not all applications actually do that.<br />
<br />
=== Defining virtual modifiers ===<br />
<br />
The mapping between virtual and real modifiers is defined in a rather weird way<br />
using keysyms as a medium. Refer to XKBproto for some reasons behind this.<br />
Real modifiers M are assigned to a key using<br />
<br />
modifier_map M { <keysym> };<br />
<br />
Virtual modifiers V can be assigned to a key using<br />
<br />
interpret <keysym> { virtualMod = V; };<br />
<br />
If a virtual modifier V shares at least one keysym with a real modifier M,<br />
it is bound to M.<br />
<br />
Note that virtual modifier names are not pre-defined and must be declared in <br />
xkb_compatibility and xkb_types sections before using them:<br />
<br />
xkb_compatibility "complete" {<br />
virtual_modifiers LevelThree,NumLock,Alt;<br />
}<br />
<br />
=== Keysym interpretation ===<br />
<br />
Virtual modifiers can be used in interpret <keysym> blocks as if they were<br />
defined to the respective real modifiers. For a virtual modifier V not bound<br />
to any real modifier, this means<br />
<br />
#define V<br />
<br />
type declaration, and <br />
<br />
interpret <key> { }<br />
interpret <key>+V { }<br />
<br />
blocks will be treated as duplicates. Only one of them, the last one in the file, will work.<br />
xkbcomp usually gives a warning in cases like this.<br />
<br />
=== Client side notes ===<br />
<br />
Handling XKB virtual modifiers on the client side requires some non-trivial server interaction.<br />
Most applications just do not bother, sticking with 8 real modifiers supplied in XKeyEvent.state.<br />
<br />
However, it is possible for an application to obtain virtual modifiers associated with a key press.<br />
Gtk, for instance, has [http://www.gtk.org/api/2.6/gdk/gdk-Keyboard-Handling.html#gdk-keymap-translate-keyboard-state gdk-keymap-translate-keyboard-state()]<br />
which may or may not be used in particular application.<br />
<br />
Some others may implement something that looks like virtual modifier support, but actually is not.<br />
Check openbox example in section 5.3.3.2. Regarding Alt handling, check section 8.3.<br />
<br />
== XKB control bits ==<br />
<br />
A bunch of bit flags affecting various aspects of XKB functionality.<br />
To control them, use {Set,Latch,Lock}Controls actions.<br />
<br />
=== Mouse control ===<br />
<br />
XKB allows controlling mouse pointer from keyboard. When set up properly, it can be extremely<br />
useful. However, its usability depends a lot on particular physical keyboard layout and on<br />
user's individual preferences.<br />
<br />
From XKB point of view it is relatively simple to implement, one should just trigger<br />
relevant actions. Fairly complete implementation can be found in<br />
{{ic|/usr/share/X11/xkb/compat/mousekeys}}.<br />
<br />
Note that the actions will not work unless {{ic|MouseKeys}} control bit is set:<br />
<br />
interpret Pointer_EnableKeys { action= LockControls(controls=MouseKeys); };<br />
<br />
Because most keyboards do not have dedicated mouse control keys, <br />
combining {{ic|MouseKeys}} and one of the {{ic|Overlay}} flags may be a good idea:<br />
<br />
interpret Pointer_EnableKeys { action= LockControls(controls=MouseKeys+Overlay1); };<br />
<br />
This allows moving pointer control keys to appropriate overlay block:<br />
<br />
xkb_keycodes {<br />
<MUP> = 218;<br />
<MDWN> = 212;<br />
<MLFT> = 214;<br />
<MRHT> = 216;<br />
}<br />
<br />
xkb_symbols {<br />
key <UP> { [ Up ], overlay1 = <MUP> };<br />
key <LEFT> { [ Left ], overlay1 = <MLFT> };<br />
key <RGHT> { [ Right ], overlay1 = <MRHT> };<br />
key <DOWN> { [ Down ], overlay1 = <MDWN> };<br />
<br />
key <MUP> { [ Pointer_Up ] };<br />
key <MDWN> { [ Pointer_Down ] };<br />
key <MLFT> { [ Pointer_Left ] };<br />
key <MRHT> { [ Pointer_Right ] };<br />
}<br />
<br />
This way it is possible to assign non-mouse actions to the keys used to control mouse,<br />
and thus, for example, use modifier keys to generate mouse buttons events.<br />
<br />
== Local XKB folder ==<br />
<br />
You can set an X keymap from a local file using the following command:<br />
<br />
$ xkbcomp keymap.xkb $DISPLAY<br />
<br />
where {{ic|keymap.xkb}} must have a structure like<br />
<br />
{{hc|keymap.xkb|<br />
xkb_keymap {<br />
xkb_keycodes { ... };<br />
xkb_types { ... };<br />
xkb_compat { ... };<br />
xkb_symbols { ... };<br />
<br />
// Geometry is completely optional.<br />
// xkb_geometry { include "pc(pc104)" };<br />
};<br />
}}<br />
<br />
You can use ''includes'' from this file, where the inclusion refer to a local folder instead of {{ic|/usr/share/X11/xkb}}. You need to use the {{ic|-I/path/}} parameter of xkbcomp for that. Full example:<br />
<br />
$ xkbcomp -I$HOME/.xkb $HOME/.keymap.xkb $DISPLAY<br />
<br />
{{hc|$HOME/.keymap.xkb|<br />
xkb_keymap {<br />
xkb_keycodes { include "evdev+aliases(qwerty)" };<br />
xkb_types { include "complete" };<br />
xkb_compat { include "complete" };<br />
xkb_symbols { include "pc+custom+inet(evdev)" };<br />
};<br />
}}<br />
<br />
The symbol file must have the same name as specified in the {{ic|xkb_symbols}} right above.<br />
{{hc|$HOME/.xkb/symbols/custom|<br />
partial alphanumeric_keys xkb_symbols "custom" { ... };<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== I have an USB keyboard and the settings get lost upon unplugging it ===<br />
<br />
Using [[#Using rules|rules]] instead of static keymap configuration will give you a more flexible and permanent key mapping that doesn't need to be reloaded manually (or by a script).<br />
<br />
== See Also ==<br />
<br />
http://www.x.org/wiki/XKB and links therein, especially:<br />
<br />
* [http://www.charvolant.org/~doug/xkb/html/index.html An Unreliable Guide To XKB Configuration]. Similar in scope to this page, with a bit different point of view. Recommended for a general picture.<br />
* [http://pascal.tsu.ru/en/xkb/ Ivan Pascal XKB docs]. One of the oldest and most well-known guides. Focuses a lot on details, and explains some of exotic XKB features.<br />
* [http://www.x.org/releases/current/doc/kbproto/xkbproto.pdf XKB protocol specification]. Comprehensive description of all XKB features. Extremely useful for understating how XKB works, includes a good description of virtual modifiers among other things. Some practice with xkbcomp is strongly recommended though, because the features are described on protocol level.</div>Dbeattyspace