docs/newbs_building_firmware.md

   1 # Building Your First Firmware
   2
   3 Now that you have setup your build environment you are ready to start building custom firmware. For this section of the guide we will bounce between 3 programs- your file manager, your text editor, and your terminal window. Keep all 3 open until you are done and happy with your keyboard firmware.
   4
   5 If you have closed and reopened your terminal window since following the first part of the guide, don't forget to `cd qmk_firmware` so that your terminal is in the correct directory.
   6
   7 ## Navigate To Your Keymaps Folder
   8
   9 Start by navigating to the `keymaps` folder for your keyboard.
  10
  11 {% hint style='info' %}
  12 If you are on macOS or Windows there are commands you can use to easily open the keymaps folder.
  13
  14 macOS:
  15
  16     open keyboards/<keyboard_folder>/keymaps
  17
  18 Windows:
  19
  20     start keyboards/<keyboard_folder>/keymaps
  21 {% endhint %}
  22
  23 ## Create a Copy Of The `default` Keymap
  24
  25 Once you have the `keymaps` folder open you will want to create a copy of the `default` folder. We highly recommend you name your folder the same as your GitHub username, but you can use any name you want as long as it contains only lower case letters, numbers, and the underscore character.
  26
  27 ## Open `keymap.c` In Your Favorite Text Editor
  28
  29 Open up your `keymap.c`. Inside this file you'll find the structure that controls how your keyboard behaves. At the top of `keymap.c` there may be some defines and enums that make the keymap easier to read. Farther down you'll find a line that looks like this:
  30
  31     const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
  32
  33 This line indicates the start of the list of Layers. Below that you'll find lines containing either `LAYOUT` or `KEYMAP`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a that particular layer.
  34
  35 {% hint style='warn' %}
  36 When editing your keymap file be careful not to add or remove any commas. If you do you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is.
  37 {% endhint %}
  38
  39 ## Customize The Layout To Your Liking
  40
  41 How to complete this step is entirely up to you. Make the one change that's been bugging you, or completely rework everything. You can remove layers if you don't need all of them, or add layers up to a total of 32. Check the following documentation to find out what you can define here:
  42
  43 * [Keycodes](keycodes.md)
  44 * [Features](features.md)
  45 * [FAQ](faq.md)
  46
  47 {% hint style='info' %}
  48 While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise.
  49 {% endhint %}
  50
  51 ## Build Your Firmware
  52
  53 When your changes to the keymap are complete you will need to build the firmware. To do so go back to your terminal window and run the build command:
  54
  55     make <my_keyboard>:<my_keymap>
  56
  57 For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
  58
  59     make planck/rev5:xyverz
  60
  61 While this compiles you will have a lot of output going to the screen informing you of what files are being compiled. It should end with output that looks similar to this:
  62
  63 ```
  64 Linking: .build/planck_rev5_xyverz.elf                                                              [OK]
  65 Creating load file for flashing: .build/planck_rev5_xyverz.hex                                      [OK]
  66 Copying planck_rev5_xyverz.hex to qmk_firmware folder                                               [OK]
  67 Checking file size of planck_rev5_xyverz.hex                                                        [OK]
  68  * File size is fine - 18392/28672
  69 ```
  70
  71 ## Flash Your Firmware
  72
  73 Move on to [Flashing Firmware](newbs_flashing.md) to learn how to write your new firmware to your keyboard.