qmk

Unnamed repository; edit this file 'description' to name the repository.
git clone git://git.z3bra.org/qmk.git
Log | Files | Refs | Submodules | LICENSE

commit 32bb8f6b8af104c4a64b029820a4c7014eaf825d
parent 1683d3a5592cb7ece371d45c85f531ffcff55934
Author: Arialdo Martini <arialdomartini@gmail.com>
Date:   Wed,  1 Nov 2017 16:21:54 +0100

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

Diffstat:
docs/faq_general.md | 2+-
docs/getting_started_build_tools.md | 19+++++++++++--------
docs/getting_started_instroduction.md | 47-----------------------------------------------
docs/getting_started_introduction.md | 47+++++++++++++++++++++++++++++++++++++++++++++++
readme.md | 2+-
5 files changed, 60 insertions(+), 57 deletions(-)

diff --git a/docs/faq_general.md b/docs/faq_general.md @@ -10,7 +10,7 @@ ## What Differences Are There Between QMK and TMK? -TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert's](https://github.com/jackhumbert) fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK. +TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert](https://github.com/jackhumbert)'s fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK. From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Keycodes](keycodes.md). diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md @@ -1,6 +1,6 @@ # Installing Build Tools -This page describes setting up the build environment for QMK. These instructions cover AVR processors (such as the atmega32u4.) +This page describes setting up the build environment for QMK. These instructions cover AVR processors (such as the atmega32u4). <!-- FIXME: We should have ARM instructions somewhere. --> @@ -44,7 +44,7 @@ By default, this will download compilers for both AVR and ARM. If you don't need nix-shell --arg arm false -## Mac +## macOS If you're using [homebrew,](http://brew.sh/) you can use the following commands: brew tap osx-cross/avr @@ -58,10 +58,10 @@ This is the recommended method. If you don't have homebrew, [install it!](http:/ ## Windows with msys2 (recommended) -The best environment to use, for Windows Vista through any later version (tested on 7 and 10,) is [msys2](http://www.msys2.org). +The best environment to use, for Windows Vista through any later version (tested on 7 and 10), is [msys2](http://www.msys2.org). -* Install msys2 by downloading and following the instructions here: http://www.msys2.org -* Open the "MSYS2 MingGW 64-bit" shortcut +* Install msys2 by downloading it and following the instructions here: http://www.msys2.org +* Open the ``MSYS2 MingGW 64-bit`` shortcut * Navigate to your qmk checkout. For example, if it's in the root of your c drive: * `$ cd /c/qmk_firmware` * Run `util/msys2_install.sh` and follow the prompts @@ -80,7 +80,7 @@ If you already have cloned the repository on your Windows file system you can ig You will need to clone the repository to your Windows file system using the normal Git for Windows and **not** the WSL Git. So if you haven't installed Git before, [download](https://git-scm.com/download/win) and install it. Then [set it up](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup), it's important that you setup the e-mail and user name, especially if you are planning to contribute. -Once Git is installed, open the Git bash command and change the directory to where you want to clone QMK, note that you have to use forward slashes, and that your c drive is accessed like this `/c/path/to/where/you/want/to/go`. Then run `git clone --recurse-submodules https://github.com/qmk/qmk_firmware`, this will create a new folder `qmk_firmware` as a subfolder of the current one. +Once Git is installed, open the Git Bash command and change the directory to where you want to clone QMK; note that you have to use forward slashes, and that your c drive is accessed like this `/c/path/to/where/you/want/to/go`. Then run `git clone --recurse-submodules https://github.com/qmk/qmk_firmware`, this will create a new folder `qmk_firmware` as a subfolder of the current one. ### Toolchain setup The Toolchain setup is done through the Windows Subsystem for Linux, and the process is fully automated. If you want to do everything manually, there are no other instructions than the scripts themselves, but you can always open issues and ask for more information. @@ -122,8 +122,11 @@ If this is a bit complex for you, Docker might be the turn-key solution you need # defaults are ergodox/default docker run -e keymap=gwen -e keyboard=ergodox_ez --rm -v $('pwd'):/qmk:rw edasque/qmk_firmware +``` + +On Windows Docker seems to have issues with the VOLUME tag in Dockerfile, and `$('pwd')` won't print a Windows compliant path; use full path instead, like this: -# On windows docker seems to have issue with VOLUME tag in Dockerfile, and $('pwd') won't print a windows compliant path, use full path instead like this +```bash docker run -e keymap=default -e keyboard=ergobox_ez --rm -v D:/Users/Sacapuces/Documents/Repositories/qmk:/qmk:rw edasque/qmk_firmware ``` @@ -131,4 +134,4 @@ docker run -e keymap=default -e keyboard=ergobox_ez --rm -v D:/Users/Sacapuces/D This will compile the targeted keyboard/keymap and leave it in your QMK directory for you to flash. ## Vagrant -If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [vagrant guide](vagrant_guide.md). +If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [vagrant guide](getting_started_vagrant.md). diff --git a/docs/getting_started_instroduction.md b/docs/getting_started_instroduction.md @@ -1,47 +0,0 @@ -# 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 -``` diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md @@ -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 [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. + +### 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: + +```c +#undef MY_SETTING +#define MY_SETTING 4 +``` diff --git a/readme.md b/readme.md @@ -29,4 +29,4 @@ QMK is developed and maintained by Jack Humbert of OLKB with contributions from ## Documentation -[https://docs.qmk.fm](https://docs.qmk.fm) is hosted on [Gitbook](https://www.gitbook.com/book/qmk/firmware/details) and [Github](/docs/) (they are synced). You can request changes by making a fork and [pull request](https://github.com/qmk/qmk_firmware/pulls), or by clicking the "suggest an edit" link on any page of the Docs. +[https://docs.qmk.fm](https://docs.qmk.fm) is hosted on [Gitbook](https://www.gitbook.com/book/qmk/firmware/details) and [GitHub](/docs/) (they are synced). You can request changes by making a fork and [pull request](https://github.com/qmk/qmk_firmware/pulls), or by clicking the "suggest an edit" link on any page of the Docs.