drashna/qmk_firmware
1
0
Fork 0
Code Activity Actions

Overhaul the Getting Started section and add a FAQ section

Browse source
This commit is contained in:
skullY 2017-08-05 20:54:34 -07:00 • committed by Jack Humbert
parent 89bcdde927
commit e6c638bed1
11 changed files with 355 additions and 369 deletions
Download patch file Download diff file Expand all files Collapse all files

47
docs/getting_started_instroduction.md Normal file
View file

@ -0,0 +1,47 @@
# 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 @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.
### Keyboard project structure
Within the `handwired` and `keyboard` folders is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard`. Within 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, 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:
```c
#undef MY_SETTING
#define MY_SETTING 4
```