diff options
79 files changed, 7318 insertions, 7711 deletions
diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 99f09f5f56..0000000000 --- a/.gitattributes +++ /dev/null @@ -1,2 +0,0 @@ -* text=auto -*.hex -diff
\ No newline at end of file @@ -38,13 +38,13 @@ You have access to a bunch of goodies! Check out the Makefile to enable/disable ### Customizing Makefile options on a per-keymap basis -If your keymap directory has a file called `makefile.mk` (note the lowercase filename, and the `.mk` extension), any Makefile options you set in that file will take precedence over other Makefile options (those set for Quantum as a whole or for your particular keyboard). +If your keymap directory has a file called `Makefile` (note the filename), any Makefile options you set in that file will take precedence over other Makefile options (those set for Quantum as a whole or for your particular keyboard). -So let's say your keyboard's makefile has `CONSOLE_ENABLE = yes` (or maybe doesn't even list the `CONSOLE_ENABLE` option, which would cause it to revert to the global Quantum default). You want your particular keymap to not have the debug console, so you make a file called `makefile.mk` and specify `CONSOLE_ENABLE = no`. +So let's say your keyboard's makefile has `CONSOLE_ENABLE = yes` (or maybe doesn't even list the `CONSOLE_ENABLE` option, which would cause it to revert to the global Quantum default). You want your particular keymap to not have the debug console, so you make a file called `Makefile` and specify `CONSOLE_ENABLE = no`. ### Customizing config.h on a per-keymap basis -If you use the ErgoDox EZ, you can make a `config_user.h` file in your keymap directory and use it to override any `config.h` settings you don't like. Anything you set there will take precedence over the global `config.h` for the ErgoDox EZ. To see an example of this, check out `keymaps/erez_experimental`. +You can also make a `config.h` file in your keymap directory and use it to override any `config.h` settings you don't like. Anything you set there will take precedence over the global `config.h` for the ErgoDox EZ. To see an example of this, check out `keymaps/erez_experimental`. ## Quick aliases to common actions @@ -134,12 +134,12 @@ Steve Losh [described](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) To use it, use `KC_LSPO` (Left Shift, Parens Open) for your left Shift on your keymap, and `KC_RSPC` (Right Shift, Parens Close) for your right Shift. -It's defaulted to work on US keyboards, but if your layout uses different keys for parenthesis, you can define those in your keymap like this: +It's defaulted to work on US keyboards, but if your layout uses different keys for parenthesis, you can define those in your `config.h` like this: #define LSPO_KEY KC_9 #define RSPC_KEY KC_0 -The only other thing you're going to want to do is create a `makefile.mk` in your keymap directory and set the following: +The only other thing you're going to want to do is create a `Makefile` in your keymap directory and set the following: ``` COMMAND_ENABLE = no # Commands for debug and configuration diff --git a/doc/BUILD_GUIDE.md b/doc/BUILD_GUIDE.md index d7a1e2935e..5636c65ea4 100644 --- a/doc/BUILD_GUIDE.md +++ b/doc/BUILD_GUIDE.md @@ -29,7 +29,7 @@ You can also try these instructions: ### Linux Install AVR GCC, AVR libc, and dfu-progammer with your favorite package manager. -Debian/Ubuntu example: +Debian/Ubuntu example: sudo apt-get update sudo apt-get install gcc-avr avr-libc dfu-programmer @@ -38,8 +38,8 @@ Debian/Ubuntu example: 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 file](VAGRANT_GUIDE.md). ## Verify Your Installation -1. If you haven't already, obtain this repository ([https://github.com/jackhumbert/qmk_firmware](https://github.com/jackhumbert/qmk_firmware)). You can either download it as a zip file and extract it, or clone it using the command line tool git or the Github Desktop application. -2. Open up a terminal or command prompt and navigate to the `qmk_firmware` folder using the `cd` command. The command prompt will typically open to your home directory. If, for example, you cloned the repository to your Documents folder, then you would type `cd Documents/qmk_firmware`. If you extracted the file from a zip, then it may be named `qmk_firmware-master` instead. +1. If you haven't already, obtain this repository ([https://github.com/jackhumbert/qmk_firmware](https://github.com/jackhumbert/qmk_firmware)). You can either download it as a zip file and extract it, or clone it using the command line tool git or the Github Desktop application. +2. Open up a terminal or command prompt and navigate to the `qmk_firmware` folder using the `cd` command. The command prompt will typically open to your home directory. If, for example, you cloned the repository to your Documents folder, then you would type `cd Documents/qmk_firmware`. If you extracted the file from a zip, then it may be named `qmk_firmware-master` instead. 3. To confirm that you're in the correct location, you can display the contents of your current folder using the `dir` command on Windows, or the `ls` command on Linux or Mac. You should see several files, including `README.md` and a `quantum` folder. From here, you need to navigate to the appropriate folder under `keyboard/`. For example, if you're building for a Planck, run `cd keyboard/planck`. 4. Once you're in the correct keyboard-specific folder, run the `make` command. This should output a lot of information about the build process. More information about the `make` command can be found below. @@ -48,20 +48,20 @@ If you have any problems building the firmware, you can try using a tool called ### The Make command The `make` command is how you compile the firmware into a .hex file, which can be loaded by a dfu programmer (like dfu-progammer via `make dfu`) or the [Teensy loader](https://www.pjrc.com/teensy/loader.html) (only used with Teensys). You can run `make` from the root (`/`), your keyboard folder (`/keyboard/<keyboard>/`), or your keymap folder (`/keyboard/<keyboard>/keymaps/<keymap>/`) if you have a `Makefile` there (see the example [here](/doc/keymap_makefile_example.mk)). - -By default, this will generate a <keyboard>_<keymap>.hex file in whichever folder you run make from. These files are ignored by git, so don't worry about deleting them when committing/creating pull requests. You .hex file will also be copied into your keymap folder as `compiled.hex`, which isn't ignore by git - this is included in case first-time users are having trouble compiling, and just want to flash a layout via `make dfu-no-build`. + +By default, this will generate a `<keyboard>_<keymap>.hex` file in whichever folder you run `make` from. These files are ignored by git, so don't worry about deleting them when committing/creating pull requests. Your .hex file will also be copied into your keymap folder as `compiled.hex`, which isn't ignored by git - this is included in case first-time users are having trouble compiling, and just want to flash a layout via `make dfu-no-build` or using the Teensy loader. * The "root" (`/`) folder is the qmk_firmware folder, in which are `doc`, `keyboard`, `quantum`, etc. -* The "keyboard" folder is any keyboard project's folder, like `/keyboard/<keyboard>` -* The "keymap" folder is any keymap's folder, like `/keyboard/<keyboard>/keymaps/<keymap>/` +* The "keyboard" folder is any keyboard project's folder, like `/keyboard/planck`. +* The "keymap" folder is any keymap's folder, like `/keyboard/planck/keymaps/default`. Below is a list of the useful `make` commands in QMK: * `make` - cleans automatically and builds your keyboard and keymap depending on which folder you're in. This defaults to the "default" layout (unless in a keymap folder), and Planck keyboard in the root folder * `make keyboard=<keyboard>` - specifies the keyboard (only to be used in root) * `make keymap=<keymap>` - specifies the keymap (only to be used in root and keyboard folder - not needed when in keymap folder) -* `make quick` - skips the clean step (only use when modifying .c code in the same project - at least one `make` is required) -* `make dfu` - (requires dfu-programmer) builds and flashes the keymap to your keyboard once placed in reset/dfu mode (button or press KC_RESET). +* `make quick` - skips the clean step (cannot be used immediately after modifying config.h or Makefiles) +* `make dfu` - (requires dfu-programmer) builds and flashes the keymap to your keyboard once placed in reset/dfu mode (button or press `KC_RESET`). This does not work for Teensy-based keyboards like the ErgoDox EZ. * `keyboard=` and `keymap=` are compatible with this * `make dfu-no-build` - (requires dfu-programmer) same as `make dfu`, but doesn't build and uses the included `compiled.hex` to flash the keyboard * `make all-keyboards` - builds all keymaps for all keyboards and outputs status of each (use in root) @@ -77,13 +77,13 @@ Other, less useful functionality: ### The Makefile -There are 3 different `make` and `Makefile` locations: +There are 3 different `make` and `Makefile` locations: * root (`/`) * keyboard (`/keyboard/<keyboard>/`) * keymap (`/keyboard/<keyboard>/keymaps/<keymap>/`) -The root contains all of the automatic keymap/keyboard stuff, is static, and shouldn't be modified. The keyboard one will contain the MCU set-up and default settings for your keyboard, and shouldn't be modified unless you are the producer of that keyboard. The keymap Makefile can be modified by users, and is optional. It is included automatically if it exists. You can see an example [here](/doc/keymap_makefile_example.mk) - the last few lines are the most important. The settings you set here will override any defaults set in the keyboard Makefile. It is required if you want to run `make` in the keymap folder. +The root contains the code used to automatically figure out which keymap or keymaps to compile based on your current directory and commandline arguments. It's considered stable, and shouldn't be modified. The keyboard one will contain the MCU set-up and default settings for your keyboard, and shouldn't be modified unless you are the producer of that keyboard. The keymap Makefile can be modified by users, and is optional. It is included automatically if it exists. You can see an example [here](/doc/keymap_makefile_example.mk) - the last few lines are the most important. The settings you set here will override any defaults set in the keyboard Makefile. **It is required if you want to run `make` in the keymap folder.** ### The `config.h` file @@ -92,16 +92,13 @@ There are 2 `config.h` locations: * keyboard (`/keyboard/<keyboard>/`) * keymap (`/keyboard/<keyboard>/keymaps/<keymap>/`) -The keyboard `config.h` is included only if the keymap one doesn't exist. It's possible to included both by using this code at the top of your keymap's `config.h`: - - #include "../../config.h" - -You can then overwrite any settings, rather than having to copy and paste the whole thing. You may need to `undefine` things to prevent warnings. - +The keyboard `config.h` is included only if the keymap one doesn't exist. The format to use for your custom one [is here](/doc/keymap_config_h_example.h). If you want to override a setting from the parent `config.h` file, you need to do this: -## Helpful Tips -1. On Linux or OS X, you can run `sleep 5; make keymap=<keymap> dfu` to delay building/deploying the firmware until for 5 seconds, giving you a chance to put the firmware into bootloader mode. You can change the 5 to any number of seconds. +``` +#undef MY_SETTING +#define MY_SETTING 4 +```c -## Troubleshooting +For a value of `4` for this imaginary setting. So we `undef` it first, then `define` it. - WIP +You can then override any settings, rather than having to copy and paste the whole thing. diff --git a/doc/keymap_config_h_example.h b/doc/keymap_config_h_example.h new file mode 100644 index 0000000000..8893d122e0 --- /dev/null +++ b/doc/keymap_config_h_example.h @@ -0,0 +1,8 @@ +#ifndef CONFIG_USER_H +#define CONFIG_USER_H + +#include "../../config.h" + +// place overrides here + +#endif diff --git a/doc/keymap_makefile_example.mk b/doc/keymap_makefile_example.mk index 5eb73246fa..f4671a9d11 100644 --- a/doc/keymap_makefile_example.mk +++ b/doc/keymap_makefile_example.mk @@ -1,5 +1,5 @@ # Build Options -# change to "no" to disable the options, or define them in the makefile.mk in +# change to "no" to disable the options, or define them in the Makefile in # the appropriate keymap folder that will get included automatically # BOOTMAGIC_ENABLE = no # Virtual DIP switch configuration(+1000) diff --git a/keyboard/alps64/Makefile b/keyboard/alps64/Makefile index 8259e4d08d..d8325e6c89 100644 --- a/keyboard/alps64/Makefile +++ b/keyboard/alps64/Makefile @@ -1,42 +1,4 @@ -#---------------------------------------------------------------------------- -# On command line: -# -# make all = Make software. -# -# make clean = Clean out built project files. -# -# make coff = Convert ELF to AVR COFF. -# -# make extcoff = Convert ELF to AVR Extended COFF. -# -# make program = Download the hex file to the device. -# Please customize your programmer settings(PROGRAM_CMD) -# -# make teensy = Download the hex file to the device, using teensy_loader_cli. -# (must have teensy_loader_cli installed). -# -# make dfu = Download the hex file to the device, using dfu-programmer (must -# have dfu-programmer installed). -# -# make flip = Download the hex file to the device, using Atmel FLIP (must -# have Atmel FLIP installed). -# -# make dfu-ee = Download the eeprom file to the device, using dfu-programmer -# (must have dfu-programmer installed). -# -# make flip-ee = Download the eeprom file to the device, using Atmel FLIP -# (must have Atmel FLIP installed). -# -# make debug = Start either simulavr or avarice as specified for debugging, -# with avr-gdb or avr-insight as the front end for debugging. -# -# make filename.s = Just compile filename.c into the assembler code only. -# -# make filename.i = Create a preprocessed source file for use in submitting -# bug reports to the GCC project. -# -# To rebuild project do "make clean" then "make all". -#---------------------------------------------------------------------------- + # Target file name (without extension). diff --git a/keyboard/arrow_pad/Makefile b/keyboard/arrow_pad/Makefile index 931eb3a16d..09fcf3e7a0 100644 --- a/keyboard/arrow_pad/Makefile +++ b/keyboard/arrow_pad/Makefile @@ -1,42 +1,4 @@ -#---------------------------------------------------------------------------- -# On command line: -# -# make all = Make software. -# -# make clean = Clean out built project files. -# -# make coff = Convert ELF to AVR COFF. -# -# make extcoff = Convert ELF to AVR Extended COFF. -# -# make program = Download the hex file to the device. -# Please customize your programmer settings(PROGRAM_CMD) -# -# make teensy = Download the hex file to the device, using teensy_loader_cli. -# (must have teensy_loader_cli installed). -# -# make dfu = Download the hex file to the device, using dfu-programmer (must -# have dfu-programmer installed). -# -# make flip = Download the hex file to the device, using Atmel FLIP (must -# have Atmel FLIP installed). -# -# make dfu-ee = Download the eeprom file to the device, using dfu-programmer -# (must have dfu-programmer installed). -# -# make flip-ee = Download the eeprom file to the device, using Atmel FLIP -# (must have Atmel FLIP installed). -# -# make debug = Start either simulavr or avarice as specified for debugging, -# with avr-gdb or avr-insight as the front end for debugging. -# -# make filename.s = Just compile filename.c into the assembler code only. -# -# make filename.i = Create a preprocessed source file for use in submitting -# bug reports to the GCC project. -# -# To rebuild project do "make clean" then "make all". -#---------------------------------------------------------------------------- + # MCU name #MCU = at90usb1287 diff --git a/keyboard/atomic/Makefile b/keyboard/atomic/Makefile index 0940d8f277..08e9205cbf 100644 --- a/keyboard/atomic/Makefile +++ b/keyboard/atomic/Makefile @@ -1,42 +1,4 @@ -#---------------------------------------------------------------------------- -# On command line: -# -# make all = Make software. -# -# make clean = Clean out built project files. -# -# make coff = Convert ELF to AVR COFF. -# -# make extcoff = Convert ELF to AVR Extended COFF. -# -# make program = Download the hex file to the device. -# Please customize your programmer settings(PROGRAM_CMD) -# -# make teensy = Download the hex file to the device, using teensy_loader_cli. -# (must have teensy_loader_cli installed). -# -# make dfu = Download the hex file to the device, using dfu-programmer (must -# have dfu-programmer installed). -# -# make flip = Download the hex file to the device, using Atmel FLIP (must -# have Atmel FLIP installed). -# -# make dfu-ee = Download the eeprom file to the device, using dfu-programmer -# (must have dfu-programmer installed). -# -# make flip-ee = Download the eeprom file to the device, using Atmel FLIP -# (must have Atmel FLIP installed). -# -# make debug = Start either simulavr or avarice as specified for debugging, -# with avr-gdb or avr-insight as the front end for debugging. -# -# make filename.s = Just compile filename.c into the assembler code only. -# -# make filename.i = Create a preprocessed source file for use in submitting -# bug reports to the GCC project. -# -# To rebuild project do "make clean" then "make all". -#---------------------------------------------------------------------------- + # MCU name #M |