diff options
Diffstat (limited to 'doc/BUILD_GUIDE.md')
| -rw-r--r-- | doc/BUILD_GUIDE.md | 62 |
1 files changed, 54 insertions, 8 deletions
diff --git a/doc/BUILD_GUIDE.md b/doc/BUILD_GUIDE.md index 089d63834..505ba4de6 100644 --- a/doc/BUILD_GUIDE.md +++ b/doc/BUILD_GUIDE.md @@ -39,22 +39,68 @@ If you have any problems building the firmware, you can try using a tool called ## 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. +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. +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. ## Customizing, Building, and Deploying Your Firmware -Note: Some keyboard folders have non-standard organizations, and may not even support specifying alternate keymaps. Until these get reorganized, you will need to edit their default keymaps directly. +### 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`. + +* 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>/` + +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). + * `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) +* `make all-keyboards-default` - builds all default keymaps for all keyboards and outputs status of each (use in root) +* `make all-keymaps [keyboard=<keyboard>]` - builds all of the keymaps for whatever keyboard folder you're in, or specified by `<keyboard>` + +Other, less useful functionality: + +* `make COLOR=false` - turns off color output +* `make SILENT=true` - turns off output besides errors/warnings +* `make VERBOSE=true` - outputs all of the avr-gcc stuff (not interesting) + +### The Makefile + +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 `config.h` file + +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. -1. Running the `make` command from your keyboard's folder will generate a .hex file based on the default keymap. All keymaps for a particular keyboard live in the `keymaps` folder in that keyboard's folder. To create your own keymap, duplicate the folder `keymaps/default`, and rename it with your name, for example `jack`. Or, if you don't care about the ability to share your keymap with the community via GitHub, you can just modify the default keymap itself. Details on how to program keymap files can be found in other guides. -2. To build a keymap other than the default, type `KEYMAP=<name>` after `make`. So if I've named my keymap `jack`, the full command would be `make KEYMAP=jack`. -3. How you deploy the firmware will depend on whether you are using a PCB or a Teensy. In both cases, you'll need to put the keyboard in bootloader mode, either by pressing a button on the PCB/Teensy or pressing the key with the `RESET` keycode. Then, if you're using a PCB, just run `make KEYMAP=<name> dfu` to both build and deploy the firmware. If you're using a Teensy, you'll probably need to take the <keyboardname>.hex file that make produces in the keyboard's folder, and deploy it using the [Teensy Loader.](https://www.pjrc.com/teensy/loader.html) ## Helpful Tips -1. On Linux or OS X, you can run `sleep 5; make KEYMAP=<name> 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. +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. ## Troubleshooting -1. Try running `make clean` if the make command fails. WIP |