-# Layouts: Using a keymap with multiple keyboards
+# Layouts: Using a Keymap with Multiple Keyboards
-The `layouts/` folder contains different physical key layouts that can apply to different keyboards.
+The `layouts/` folder contains different physical key layouts that can apply to different keyboards.
```
layouts/
| + ...
```
-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.
+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 repositories 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:
New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue.
-## Supporting a layout
+## 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):
+For a keyboard to support a layout, the variable must be defined in it's `<keyboard>.h`, and match the number of arguments/keys (and preferably the physical layout):
#define LAYOUT_60_ansi KEYMAP_ANSI
+The name of the layout must match this regex: `[a-z0-9_]+`
+
The folder name must be added to the keyboard's `rules.mk`:
LAYOUTS = 60_ansi
-`LAYOUTS` can be appended in the subproject's `rules.mk`:
+`LAYOUTS` can be set in any keyboard folder level's `rules.mk`:
- LAYOUTS += 60_iso
+ LAYOUTS = 60_iso
-but the `LAYOUT_<layout>` variable must be defined in `<subproject>.h` as well.
+but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well.
-## Tips for making layouts keyboard-agnostic
+## Building a Keymap
-Instead of using `#include "planck.h"`, you can use this line to include whatever `<keyboard>.h` (`<subproject>.h` should not be included here) file that is being compiled:
+You should be able to build the keyboard keymap with a command in this format:
- #include QMK_KEYBOARD_H
+ make <keyboard>:<layout>
+
+### Conflicting layouts
+When a keyboard supports multiple layout options,
-In your config.h, you can also use this variable to include the keyboard's `config.h`:
+ LAYOUTS = ortho_4x4 ortho_4x12
+
+And a layout exists for both options,
+```
+layouts/
++ community/
+| + ortho_4x4/
+| | + <layout>/
+| | | + ...
+| + ortho_4x12/
+| | + <layout>/
+| | | + ...
+| + ...
+```
- #include QMK_KEYBOARD_CONFIG_H
+The FORCE_LAYOUT argument can be used to specify which layout to build
+
+ make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4
+ make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12
+
+## Tips for Making Layouts Keyboard-Agnostic
+
+### Includes
+
+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
If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement:
-* `KEYBOARD_<keyboard>`
-* `SUBPROJECT_<subproject>`
+* `KEYBOARD_<folder1>_<folder2>`
For example:
```c
#ifdef KEYBOARD_planck
- #ifdef SUBPROJECT_rev4
+ #ifdef KEYBOARD_planck_rev4
planck_rev4_function();
#endif
#endif
```
-Note that the names are lowercase and match the folder/file names for the keyboard/subproject exactly.
\ No newline at end of file
+Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.
+
+### Keymaps
+
+In order to support both split and non-split keyboards with the same layout, you need to use the keyboard agnostic `LAYOUT_<layout name>` macro in your keymap. For instance, in order for a Let's Split and Planck to share the same layout file, you need to use `LAYOUT_ortho_4x12` instead of `LAYOUT_planck_grid` or just `{}` for a C array.
projects / qmk_firmware.git / blobdiff