Commit | Line | Data |
---|---|---|
e6c638be | 1 | # Introduction |
2 | ||
32bb8f6b | 3 | This page attempts to explain the basic information you need to know to work with the QMK project. It assumes that you are familiar with navigating a Unix shell, but does not assume you are familiar with C or with compiling using make. |
e6c638be | 4 | |
7b0356d1 | 5 | ## Basic QMK Structure |
e6c638be | 6 | |
32bb8f6b | 7 | QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders. |
e6c638be | 8 | |
3d7bfae2 ET |
9 | ### Userspace Structure |
10 | ||
11 | Within the folder `users` is a directory for each user. This is a place for users to put code that they might use between keyboards. See the docs for [Userspace feature](feature_userspace.md) for more information. | |
12 | ||
7b0356d1 | 13 | ### Keyboard Project Structure |
e6c638be | 14 | |
d3317a8a | 15 | Within the folder `keyboards`, its subfolder `handwired` and its vendor and manufacture subdirectories e.g. `clueboard` is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard/2x1800`. Within it, you'll find the following structure: |
e6c638be | 16 | |
17 | * `keymaps/`: Different keymaps that can be built | |
b4f45766 | 18 | * `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `rules.mk`. |
e6c638be | 19 | * `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`. |
d3317a8a EP |
20 | * `info.json`: The file used for setting layout for QMK Configurator. See [Configurator Support](reference_configurator_support.md) for more information. |
21 | * `readme.md`: A brief overview of the keyboard. | |
22 | * `<keyboardName>.h`: This file is where the keyboard layout is defined against the keyboard's switch matrix. | |
23 | * `<keyboardName>.c`: This file is where you can find custom code for the keyboard. | |
24 | ||
25 | For more information on project structure, see [QMK Keyboard Guidelines](hardware_keyboard_guidelines.md). | |
e6c638be | 26 | |
7b0356d1 | 27 | ### Keymap Structure |
e6c638be | 28 | |
32bb8f6b | 29 | In every keymap folder, the following files may be found. Only `keymap.c` is required, and if the rest of the files are not found the default options will be chosen. |
e6c638be | 30 | |
31 | * `config.h`: the options to configure your keymap | |
32 | * `keymap.c`: all of your keymap code, required | |
33 | * `rules.mk`: the features of QMK that are enabled | |
34 | * `readme.md`: a description of your keymap, how others might use it, and explanations of features. Please upload images to a service like imgur. | |
35 | ||
7b0356d1 | 36 | # The `config.h` File |
e6c638be | 37 | |
b666921e | 38 | There are 3 possible `config.h` locations: |
e6c638be | 39 | |
40 | * keyboard (`/keyboards/<keyboard>/config.h`) | |
b666921e | 41 | * userspace (`/users/<user>/config.h`) |
e6c638be | 42 | * keymap (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`) |
43 | ||
c5c112ae | 44 | The build system automatically picks up the config files in the above order. If you wish to override any setting set by a previous `config.h` you will need to first include some boilerplate code for the settings you wish to change. |
e6c638be | 45 | |
46 | ``` | |
c5c112ae | 47 | #pragma once |
e6c638be | 48 | ``` |
49 | ||
b666921e ET |
50 | Then to override a setting from the previous `config.h` file you must `#undef` and then `#define` the setting again. |
51 | ||
52 | The boilerplate code and setting look like this together: | |
e6c638be | 53 | |
b666921e | 54 | ``` |
c5c112ae | 55 | #pragma once |
b666921e ET |
56 | |
57 | // overrides go here! | |
e6c638be | 58 | #undef MY_SETTING |
59 | #define MY_SETTING 4 | |
60 | ``` |