Commit | Line | Data |
---|---|---|
ca01d940 JH |
1 | # Quantum Mechanical Keyboard Firmware |
2 | ||
9e567665 | 3 | [![Current Version](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags) |
4 | [![Build Status](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware) | |
5 | [![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh) | |
6 | [![Docs Status](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm) | |
7 | [![GitHub contributors](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly) | |
8 | [![GitHub forks](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/) | |
9 | ||
10 | ## What is QMK Firmware? | |
ca01d940 | 11 | |
6ba73e0e | 12 | QMK (*Quantum Mechanical Keyboard*) is an open source community that maintains QMK Firmware, QMK Toolbox, qmk.fm, and these docs. QMK Firmware is a keyboard firmware based on the [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) with some useful features for Atmel AVR controllers, and more specifically, the [OLKB product line](http://olkb.com), the [ErgoDox EZ](http://www.ergodox-ez.com) keyboard, and the [Clueboard product line](http://clueboard.co/). It has also been ported to ARM chips using ChibiOS. You can use it to power your own hand-wired or custom keyboard PCB. |
ca01d940 | 13 | |
9e567665 | 14 | ## How to Get It |
ca01d940 | 15 | |
391eae97 | 16 | If you plan on contributing a keymap, keyboard, or features to QMK, the easiest thing to do is [fork the repo through Github](https://github.com/qmk/qmk_firmware#fork-destination-box), and clone your repo locally to make your changes, push them, then open a [Pull Request](https://github.com/qmk/qmk_firmware/pulls) from your fork. |
ca01d940 | 17 | |
391eae97 | 18 | Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), or clone it via git (`git@github.com:qmk/qmk_firmware.git`), or https (`https://github.com/qmk/qmk_firmware.git`). |
ca01d940 | 19 | |
9e567665 | 20 | ## How to Compile |
ca01d940 | 21 | |
73ddb764 | 22 | Before you are able to compile, you'll need to [install an environment](getting_started_build_tools.md) for AVR or/and ARM development. Once that is complete, you'll use the `make` command to build a keyboard and keymap with the following notation: |
ca01d940 | 23 | |
800ec55d | 24 | make planck/rev4:default |
ca01d940 | 25 | |
800ec55d | 26 | This would build the `rev4` revision of the `planck` with the `default` keymap. Not all keyboards have revisions (also called subprojects or folders), in which case, it can be omitted: |
ca01d940 | 27 | |
800ec55d | 28 | make preonic:default |
ca01d940 | 29 | |
9e567665 | 30 | ## How to Customize |
ca01d940 | 31 | |
73ddb764 | 32 | QMK has lots of [features](features.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md). |