800ec55dfc
* redo make args to use colons, better folder structuring system [skip ci] * don't put spaces after statements - hard lessons in makefile development * fix-up some other rules.mk * give travis a chance * reset KEYMAPS variable * start converting keyboards to new system * try making all with travis * redo make args to use colons, better folder structuring system [skip ci] * don't put spaces after statements - hard lessons in makefile development * fix-up some other rules.mk * give travis a chance * reset KEYMAPS variable * start converting keyboards to new system * try making all with travis * start to update readmes and keyboards * look in keyboard directories for board.mk * update visualizer rules * fix up some other keyboards/keymaps * fix arm board ld includes * fix board rules * fix up remaining keyboards * reset layout variable * reset keyboard_layouts * fix remainging keymaps/boards * update readmes, docs * add note to makefile error * update readmes * remove planck keymap warnings * update references and docs * test out tarvis build stages * don't use stages for now * don't use stages for now
2.5 KiB
Layouts: Using a keymap with multiple keyboards
The layouts/ folder contains different physical key layouts that can apply to different keyboards.
layouts/
+ default/
| + 60_ansi/
| | + readme.md
| | + layout.json
| | + a_good_keymap/
| | | + keymap.c
| | | + readme.md
| | | + config.h
| | | + rules.mk
| | + <keymap folder>/
| | + ...
| + <layout folder>/
+ community/
| + <layout folder>/
| + ...
The layouts/default/ and layouts/community/ are two examples of layout "repositories" - currently default will contain all of the information concerning the layout, and one default keymap named default_<layout>, for users to use as a reference. community contains all of the community keymaps, with the eventual goal of being split-off into a separate repo for users to clone into layouts/. QMK searches through all folders in layouts/, so it's possible to have multiple reposistories here.
Each layout folder is named ([a-z0-9_]) after the physical aspects of the layout, in the most generic way possible, and contains a readme.md with the layout to be defined by the keyboard:
# 60_ansi
LAYOUT_60_ansi
New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue.
Supporting a layout
For a keyboard to support a layout, the variable ([a-z0-9_]) must be defined in it's <keyboard>.h, and match the number of arguments/keys (and preferrably the physical layout):
#define LAYOUT_60_ansi KEYMAP_ANSI
The folder name must be added to the keyboard's rules.mk:
LAYOUTS = 60_ansi
LAYOUTS can be set in any keyboard folder level's rules.mk:
LAYOUTS = 60_iso
but the LAYOUT_<layout> variable must be defined in <folder>.h as well.
Tips for making layouts keyboard-agnostic
Instead of using #include "planck.h", you can use this line to include whatever <keyboard>.h (<folder>.h should not be included here) file that is being compiled:
#include QMK_KEYBOARD_H
In your config.h, you can also use this variable to include the keyboard's config.h:
#include QMK_KEYBOARD_CONFIG_H
If you want to keep some keyboard-specific code, you can use these variables to escape it with an #ifdef statement:
KEYBOARD_<folder1>_<folder2>
For example:
#ifdef KEYBOARD_planck
#ifdef KEYBOARD_planck_rev4
planck_rev4_function();
#endif
#endif
Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.