marco/qmk

Arialdo Martini 32bb8f6b8a Improvements to documentation (#1919 )

* Typo: Github => GitHub

* Typo: windows => Windows, docker => Docker, and some punctuations

* "QMK Introduction" links to the right file

* "Unix" rather than "UNIX", which is a trademark

* Directory name is "keyboards", not "keyboard"

* "handwired" is a subdirectory of "keyboards"

* Punctuation and minor fixes

* macOS rather than Mac

* Punctuation and other minor fixes

* Vagrant Guide links to an existing file

* Jun Wako referenced with his name rather than his nickname

* Saxon genitive 's outside the link

2017-11-01 11:21:54 -04:00

2.3 KiB

Raw Blame History

Introduction

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.

Basic QMK structure

QMK is a fork of Jun Wako's 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.

Keyboard project structure

Within the folder keyboards and its subfolder handwired is a directory for each keyboard project, for example qmk_firmware/keyboards/clueboard. Within it you'll find the following structure:

keymaps/: Different keymaps that can be built
rules.mk: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific Makefile
config.h: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific config.h.

Keymap structure

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.

config.h: the options to configure your keymap
keymap.c: all of your keymap code, required
rules.mk: the features of QMK that are enabled
readme.md: a description of your keymap, how others might use it, and explanations of features. Please upload images to a service like imgur.

The `config.h` file

There are 2 config.h locations:

keyboard (/keyboards/<keyboard>/config.h)
keymap (/keyboards/<keyboard>/keymaps/<keymap>/config.h)

If the keymap config.h exists, that file is included by the build system and the keyboard config.h is not included. If you wish to override settings in your keymap's config.h you will need to include some glue code:

#ifndef CONFIG_USER_H
#define CONFIG_USER_H

#include "../../config.h"

If you want to override a setting from the parent config.h file, you need to #undef and then #define the setting again, like this:

#undef MY_SETTING
#define MY_SETTING 4

2.3 KiB Raw Blame History