summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorJack Humbert <jack.humb@gmail.com>2017-10-14 11:32:19 -1000
committerGitHub <noreply@github.com>2017-10-14 11:32:19 -1000
commit800ec55dfca06b4630acf62cbb5f130c4031e4f1 (patch)
tree718e43d976bc71627558b5f9e1b657e8a64e4131 /docs
parente5dc2253e26a105a11e0fad3e4e39c306e49cc92 (diff)
Make arguments redo, subproject elimination (#1784)
* redo make args to use colons, better folder structuring system [skip ci] * don't put spaces after statements - hard lessons in makefile development * fix-up some other rules.mk * give travis a chance * reset KEYMAPS variable * start converting keyboards to new system * try making all with travis * redo make args to use colons, better folder structuring system [skip ci] * don't put spaces after statements - hard lessons in makefile development * fix-up some other rules.mk * give travis a chance * reset KEYMAPS variable * start converting keyboards to new system * try making all with travis * start to update readmes and keyboards * look in keyboard directories for board.mk * update visualizer rules * fix up some other keyboards/keymaps * fix arm board ld includes * fix board rules * fix up remaining keyboards * reset layout variable * reset keyboard_layouts * fix remainging keymaps/boards * update readmes, docs * add note to makefile error * update readmes * remove planck keymap warnings * update references and docs * test out tarvis build stages * don't use stages for now * don't use stages for now
Diffstat (limited to 'docs')
-rw-r--r--docs/README.md6
-rw-r--r--docs/adding_a_keyboard_to_qmk.md2
-rw-r--r--docs/config_options.md18
-rw-r--r--docs/contributing.md6
-rw-r--r--docs/documentation_templates.md2
-rw-r--r--docs/faq_build.md2
-rw-r--r--docs/feature_layouts.md15
-rw-r--r--docs/getting_started_build_tools.md4
-rw-r--r--docs/getting_started_make_guide.md27
-rw-r--r--docs/hand_wire.md2
-rw-r--r--docs/unit_testing.md2
11 files changed, 40 insertions, 46 deletions
diff --git a/docs/README.md b/docs/README.md
index 515ddb7783..065263edbc 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,11 +14,11 @@ Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk
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:
- make planck-rev4-default
+ make planck/rev4:default
-This would build the `rev4` revision of the `planck` with the `default` keymap. Not all keyboards have revisions (also called subprojects), in which case, it can be omitted:
+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:
- make preonic-default
+ make preonic:default
## How to customize {#how-to-customize}
diff --git a/docs/adding_a_keyboard_to_qmk.md b/docs/adding_a_keyboard_to_qmk.md
index c8b76c1b9f..5ee2c8ccae 100644
--- a/docs/adding_a_keyboard_to_qmk.md
+++ b/docs/adding_a_keyboard_to_qmk.md
@@ -4,7 +4,7 @@ We welcome all keyboard projects into QMK, but ask that you try to stick to a co
## Naming your directory/project
-All names should be lowercase alphanumeric, and separated by an underscore (`_`), but not begin with one. Dashes (`-`) aren't allow by our build system, and will confuse it with keymaps/subprojects. Your directory and your `.h` and `.c` files should have exactly the same name. Subprojects/revision should follow the same format.
+All names should be lowercase alphanumeric, and separated by an underscore (`_`), but not begin with one. Your directory and your `.h` and `.c` files should have exactly the same name. All folders should follow the same format.
## `readme.md`
diff --git a/docs/config_options.md b/docs/config_options.md
index 13c8bdbbe8..b71dbb8ae9 100644
--- a/docs/config_options.md
+++ b/docs/config_options.md
@@ -12,29 +12,25 @@ This is a c header file that is one of the first things included, and will persi
// config options
-#ifdef SUBPROJECT_<subproject>
- #include "<subproject>/config.h"
-#endif
-
#endif
```
-This file contains config options that should apply to the whole keyboard, and won't change in subprojects, or most keymaps. The suproject block here only applies to keyboards with subprojects.
+This file contains config options that should apply to the whole keyboard, and won't change in revisions, or most keymaps. The revision block here only applies to keyboards with revisions.
-## Subproject
+## Revisions
```c
-#ifndef <subproject>_CONFIG_H
-#define <subproject>_CONFIG_H
+#ifndef <revision>_CONFIG_H
+#define <revision>_CONFIG_H
-#include "../config.h"
+#include "config_common.h"
// config options
#endif
```
-For keyboards that have subprojects, this file contains config options that should apply to only that subproject, and won't change in most keymaps.
+For keyboards that have revisions, this file contains config options that should apply to only that revisions, and won't change in most keymaps.
## Keymap
@@ -42,7 +38,7 @@ For keyboards that have subprojects, this file contains config options that shou
#ifndef CONFIG_USER_H
#define CONFIG_USER_H
-#include "../../config.h"
+#include "config_common.h"
// config options
diff --git a/docs/contributing.md b/docs/contributing.md
index b675f98b3f..755dd012f3 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -78,8 +78,8 @@ We have a few different types of changes in QMK, each requiring a different leve
* Separate PR's into logical units. For example, do not submit one PR covering two separate features, instead submit a separate PR for each feature.
* Check for unnecessary whitespace with `git diff --check` before committing.
* Make sure your code change actually compiles.
- * Keymaps: Make sure that `make keyboard-revision-your_new_keymap` does not return an error
- * Keyboards: Make sure that `make keyboard-all` does not return any errors
+ * Keymaps: Make sure that `make keyboard:your_new_keymap` does not return an error
+ * Keyboards: Make sure that `make keyboard:all` does not return any errors
* Core: Make sure that `make allkb` does not return any errors.
* Make sure commit messages are understandable on their own. You should put a short description (no more than 70 characters) on the first line, the second line should be empty, and on the 3rd and later lines you should describe your commit in detail, if required. Example:
@@ -128,7 +128,7 @@ Here are some things to keep in mind when working on your feature or bug fix.
* **Disabled by default** - memory is a pretty limited on most chips QMK supports, and it's important that current keymaps aren't broken, so please allow your feature to be turned **on**, rather than being turned off. If you think it should be on by default, or reduces the size of the code, please talk with us about it.
* **Compile locally before submitting** - hopefully this one is obvious, but things need to compile! Our Travis system will catch any issues, but it's generally faster for you to compile a few keyboards locally instead of waiting for the results to come back.
-* **Consider subprojects and different chip-bases** - there are several keyboards that have subprojects that allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled on platforms it doesn't work on.
+* **Consider revisions and different chip-bases** - there are several keyboards that have revisions that allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled on platforms it doesn't work on.
* **Explain your feature** - Document it in `docs/`, either as a new file or as part of an existing file. If you don't document it other people won't be able to benefit from your hard work.
We also ask that you follow these guidelines:
diff --git a/docs/documentation_templates.md b/docs/documentation_templates.md
index 856a131a65..18829ed0f0 100644
--- a/docs/documentation_templates.md
+++ b/docs/documentation_templates.md
@@ -34,7 +34,7 @@ Hardware Availability: [OLKB.com](https://olkb.com), [Massdrop](https://www.mass
Make example for this keyboard (after setting up your build environment):
- make planck-rev4-default
+ make planck/rev4:default
See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.
```
diff --git a/docs/faq_build.md b/docs/faq_build.md
index fe3aeeef61..3d732fa986 100644
--- a/docs/faq_build.md
+++ b/docs/faq_build.md
@@ -13,7 +13,7 @@ In short when your controller is ATMega32u4,
or just
- $ sudo make <keyboard>-<keymap>-dfu
+ $ sudo make <keyboard>:<keymap>:dfu
But to run `make` with root privilege is not good idea. Use former method if possible.
diff --git a/docs/feature_layouts.md b/docs/feature_layouts.md
index 4d75270dcd..5763b73806 100644
--- a/docs/feature_layouts.md
+++ b/docs/feature_layouts.md
@@ -43,15 +43,15 @@ The folder name must be added to the keyboard's `rules.mk`:
LAYOUTS = 60_ansi
-`LAYOUTS` can be appended in the subproject's `rules.mk`:
+`LAYOUTS` can be set in any keyboard folder level's `rules.mk`:
- LAYOUTS += 60_iso
+ LAYOUTS = 60_iso
-but the `LAYOUT_<layout>` variable must be defined in `<subproject>.h` as well.
+but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well.
## Tips for making layouts keyboard-agnostic
-Instead of using `#include "planck.h"`, you can use this line to include whatever `<keyboard>.h` (`<subproject>.h` should not be included here) file that is being compiled:
+Instead of using `#include "planck.h"`, you can use this line to include whatever `<keyboard>.h` (`<folder>.h` should not be included here) file that is being compiled:
#include QMK_KEYBOARD_H
@@ -61,17 +61,16 @@ In your config.h, you can also use this variable to include the keyboard's `conf
If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement:
-* `KEYBOARD_<keyboard>`
-* `SUBPROJECT_<subproject>`
+* `KEYBOARD_<folder1>_<folder2>`
For example:
```c
#ifdef KEYBOARD_planck
- #ifdef SUBPROJECT_rev4
+ #ifdef KEYBOARD_planck_rev4
planck_rev4_function();
#endif
#endif
```
-Note that the names are lowercase and match the folder/file names for the keyboard/subproject exactly. \ No newline at end of file
+Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly. \ No newline at end of file
diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md
index 0617252b2c..934617d852 100644
--- a/docs/getting_started_build_tools.md
+++ b/docs/getting_started_build_tools.md
@@ -121,10 +121,10 @@ If this is a bit complex for you, Docker might be the turn-key solution you need
# modify the keymap and keyboard assigment to compile what you want
# defaults are ergodox/default
-docker run -e keymap=gwen -e subproject=ez -e keyboard=ergodox --rm -v $('pwd'):/qmk:rw edasque/qmk_firmware
+docker run -e keymap=gwen -e keyboard=ergodox_ez --rm -v $('pwd'):/qmk:rw edasque/qmk_firmware
# 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
-docker run -e keymap=default -e subproject=ez -e keyboard=ergobox --rm -v D:/Users/Sacapuces/Documents/Repositories/qmk:/qmk:rw edasque/qmk_firmware
+docker run -e keymap=default -e keyboard=ergobox_ez --rm -v D:/Users/Sacapuces/Documents/Repositories/qmk:/qmk:rw edasque/qmk_firmware
```
diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md
index 97383d950a..b6f0f4ee27 100644
--- a/docs/getting_started_make_guide.md
+++ b/docs/getting_started_make_guide.md
@@ -1,22 +1,21 @@
# More detailed make instruction
-The full syntax of the `make` command is `<keyboard>-<subproject>-<keymap>-<target>`, where:
-
-* `<keyboard>` is the name of the keyboard, for example `planck`
- * Use `allkb` to compile all keyboards
-* `<subproject>` is the name of the subproject (revision or sub-model of the keyboard). For example, for Planck it can be `rev3` or `rev4`.
- * If the keyboard doesn't have any subprojects, it can be left out
- * To compile the default subproject, you can leave it out, or specify `defaultsp`
- * Use `allsp` to compile all subprojects
+The full syntax of the `make` command is `<keyboard_folder>:<keymap>:<target>`, where:
+
+* `<keyboard_folder>` is the path of the keyboard, for example `planck`
+ * Use `all` to compile all keyboards
+ * Specify the path to compile a revision, for example `planck/rev4` or `planck/rev3`
+ * If the keyboard doesn't have any folders, it can be left out
+ * To compile the default folder, you can leave it out
* `<keymap>` is the name of the keymap, for example `algernon`
- * Use `allkm` to compile all keymaps
+ * Use `all` to compile all keymaps
* `<target>` will be explained in more detail below.
The `<target>` means the following
* If no target is given, then it's the same as `all` below
-* `all` compiles as many keyboard/revision/keymap combinations as specified. For example, `make planck-rev4-default-all` will generate a single .hex, while `make planck-rev-all` will generate a hex for every keymap available to the planck.
+* `all` compiles as many keyboard/revision/keymap combinations as specified. For example, `make planck/rev4:default:all` will generate a single .hex, while `make planck/rev4:all` will generate a hex for every keymap available to the planck.
* `dfu`, `teensy` or `dfu-util`, compile and upload the firmware to the keyboard. If the compilation fails, then nothing will be uploaded. The programmer to use depends on the keyboard. For most keyboards it's `dfu`, but for ChibiOS keyboards you should use `dfu-util`, and `teensy` for standard Teensys. To find out which command you should use for your keyboard, check the keyboard specific readme.
- * **Note**: some operating systems need root access for these commands to work, so in that case you need to run for example `sudo make planck-rev4-default-dfu`.
+ * **Note**: some operating systems need root access for these commands to work, so in that case you need to run for example `sudo make planck/rev4:default:dfu`.
* `clean`, cleans the build output folders to make sure that everything is built from scratch. Run this before normal compilation if you have some unexplainable problems.
You can also add extra options at the end of the make command line, after the target
@@ -30,9 +29,9 @@ The make command itself also has some additional options, type `make --help` for
Here are some examples commands
-* `make allkb-allsp-allkm` builds everything (all keyboards, all subprojects, all keymaps). Running just `make` from the `root` will also run this.
-* `make ergodox-infinity-algernon-clean` will clean the build output of the Ergodox Infinity keyboard.
-* `make planck-rev4-default-dfu COLOR=false` builds and uploads the keymap without color output.
+* `make all:all` builds everything (all keyboard folders, all keymaps). Running just `make` from the `root` will also run this.
+* `make ergodox_infinity:algernon:clean` will clean the build output of the Ergodox Infinity keyboard.
+* `make planck/rev4:default:dfu COLOR=false` builds and uploads the keymap without color output.
## `rules.mk` options
diff --git a/docs/hand_wire.md b/docs/hand_wire.md
index 8f329daf8b..b5a5657141 100644
--- a/docs/hand_wire.md
+++ b/docs/hand_wire.md
@@ -273,7 +273,7 @@ Notice how the `k11` and `KC_NO` switched places to represent the wiring, and th
### keymaps/<variant>/default.c
-This is the actual keymap for your keyboard, and the main place you'll make changes as you perfect your layout. `default.c` is the file that gets pull by default when typing `make`, but you can make other files as well, and specify them by typing `make handwired-<keyboard>-<variant>`, which will pull `keymaps/<variant>/keymap.c`.
+This is the actual keymap for your keyboard, and the main place you'll make changes as you perfect your layout. `default.c` is the file that gets pull by default when typing `make`, but you can make other files as well, and specify them by typing `make handwired/<keyboard>:<variant>`, which will pull `keymaps/<variant>/keymap.c`.
The basis of a keymap is its layers - by default, layer 0 is active. You can activate other layers, the highest of which will be referenced first. Let's start with our base layer.
diff --git a/docs/unit_testing.md b/docs/unit_testing.md
index 3eac625097..81cfef79e9 100644
--- a/docs/unit_testing.md
+++ b/docs/unit_testing.md
@@ -36,7 +36,7 @@ Note how there's several different tests, each mocking out a separate part. Also
## Running the tests
-To run all the tests in the codebase, type `make test`. You can also run test matching a substring by typing `make test-matchingsubstring` Note that the tests are always compiled with the native compiler of your platform, so they are also run like any other program on your computer.
+To run all the tests in the codebase, type `make test`. You can also run test matching a substring by typing `make test:matchingsubstring` Note that the tests are always compiled with the native compiler of your platform, so they are also run like any other program on your computer.
## Debugging the tests