docs/faq_build.md

   1 # Frequently Asked Build Questions
   2
   3 This page covers questions about building QMK. If you haven't yet done so, you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](getting_started_make_guide.md) guides.
   4
   5 ## Can't Program on Linux
   6 You will need proper permissions to operate a device. For Linux users, see the instructions regarding `udev` rules, below. If you have issues with `udev`, a work-around is to use the `sudo` command. If you are not familiar with this command, check its manual with `man sudo` or [see this webpage](https://linux.die.net/man/8/sudo).
   7
   8 An example of using `sudo`, when your controller is ATMega32u4:
   9
  10     $ sudo dfu-programmer atmega32u4 erase --force
  11     $ sudo dfu-programmer atmega32u4 flash your.hex
  12     $ sudo dfu-programmer atmega32u4 reset
  13
  14 or just:
  15
  16     $ sudo make <keyboard>:<keymap>:dfu
  17
  18 Note that running `make` with `sudo` is generally *not* a good idea, and you should use one of the former methods, if possible.
  19
  20 ## Linux `udev` Rules
  21 On Linux, you'll need proper privileges to access the MCU. You can either use
  22 `sudo` when flashing firmware, or place these files in `/etc/udev/rules.d/`.
  23
  24 **/etc/udev/rules.d/50-atmel-dfu.rules:**
  25 ```
  26 # Atmel ATMega32U4
  27 SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666"
  28 # Atmel USBKEY AT90USB1287
  29 SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666"
  30 # Atmel ATMega32U2
  31 SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666"
  32 ```
  33
  34 **/etc/udev/rules.d/52-tmk-keyboard.rules:**
  35 ```
  36 # tmk keyboard products     https://github.com/tmk/tmk_keyboard
  37 SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
  38 ```
  39
  40 ## WINAVR is Obsolete
  41 It is no longer recommended and may cause some problem.
  42 See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
  43
  44 ## USB VID and PID
  45 You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product.
  46
  47 Most boards in QMK use `0xFEED` as the vendor ID. You should look through other keyboards to make sure you pick a unique Product ID.
  48
  49 Also see this.
  50 https://github.com/tmk/tmk_keyboard/issues/150
  51
  52 You can buy a really unique VID:PID here. I don't think you need this for personal use.
  53 - http://www.obdev.at/products/vusb/license.html
  54 - http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
  55
  56 ## Cortex: `cstddef: No such file or directory`
  57 GCC 4.8 of Ubuntu 14.04 had this problem and had to update to 4.9 with this PPA.
  58 https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded
  59
  60 https://github.com/tmk/tmk_keyboard/issues/212
  61 https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef
  62 https://developer.mbed.org/forum/mbed/topic/5205/
  63
  64 ## `clock_prescale_set` and `clock_div_1` Not Available
  65 Your toolchain is too old to support the MCU. For example WinAVR 20100110 doesn't support ATMega32u2.
  66
  67 ```
  68 Compiling C: ../../tmk_core/protocol/lufa/lufa.c
  69 avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8  -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d  ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o
  70 ../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu':
  71 ../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set'
  72 ../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function)
  73 ../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once
  74 ../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.)
  75 make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1
  76 ```
  77
  78
  79 ## BOOTLOADER_SIZE for AVR
  80 Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong comment.
  81
  82 ```
  83 # Boot Section Size in *bytes*
  84 #   Teensy halfKay   512
  85 #   Teensy++ halfKay 2048
  86 #   Atmel DFU loader 4096       (TMK Alt Controller)
  87 #   LUFA bootloader  4096
  88 #   USBaspLoader     2048
  89 OPT_DEFS += -DBOOTLOADER_SIZE=2048
  90 ```
  91
  92 ## `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` on MacOS
  93 This is an issue with updating on brew, causing symlinks that avr-gcc depend on getting mangled.
  94
  95 The solution is to remove and reinstall all affected modules.
  96
  97 ```
  98 brew rm avr-gcc
  99 brew rm dfu-programmer
 100 brew rm gcc-arm-none-eabi
 101 brew rm avrdude
 102 brew install avr-gcc
 103 brew install dfu-programmer
 104 brew install gcc-arm-none-eabi
 105 brew install avrdude
 106 ```
 107
 108 ### avr-gcc 8.1 and LUFA
 109
 110 If you updated your avr-gcc to above 7 you may see errors involving LUFA. For example:
 111
 112 `lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
 113
 114 For now, you need to rollback avr-gcc to 7 in brew.
 115
 116 ```
 117 brew uninstall --force avr-gcc
 118 brew install avr-gcc@7
 119 brew link avr-gcc@7
 120 ```