newbs_getting_started.md (7416B)
1 # Setting Up Your QMK Environment 2 3 Before you can build keymaps, you need to install some software and set up your build environment. This only has to be done once no matter how many keyboards you plan to compile firmware for. 4 5 ## 1. Prerequisites 6 7 There are a few pieces of software you'll need to get started. 8 9 * [Text editor](newbs_learn_more_resources#text-editor-resources) 10 * You’ll need a program that can edit and save plain text files. The default editor that comes with many OS's does not save plain text files, so you'll need to make sure that whatever editor you chose does. 11 * [Toolbox (optional)](https://github.com/qmk/qmk_toolbox) 12 * A graphical program for Windows and macOS that allows you to both program and debug your custom keyboard 13 14 ::: tip 15 If you haven't worked with the Linux/Unix command line before, there are a few basic concepts and commands you should learn. [These resources](newbs_learn_more_resources#command-line-resources) will teach you enough to be able to work with QMK. 16 ::: 17 18 ## 2. Prepare Your Build Environment {#set-up-your-environment} 19 20 We've tried to make QMK as easy to set up as possible. You only have to prepare your Linux or Unix environment, then let QMK install the rest. 21 22 :::::tabs 23 24 ==== Windows 25 26 QMK maintains a Bundle of MSYS2, the CLI and all necessary dependencies. It also provides a handy `QMK MSYS` terminal shortcut to boot you directly into the correct environment. 27 28 #### Prerequisites 29 30 You will need to install [QMK MSYS](https://msys.qmk.fm/). The latest release is available [here](https://github.com/qmk/qmk_distro_msys/releases/latest). 31 32 :::: details Advanced Users 33 34 ::: danger 35 <b style="font-size:150%">This process is not recommended for new users.</b> 36 ::: 37 38 If you'd like to manually install MSYS2, the following sections will walk you through the process. 39 40 #### Prerequisites 41 42 You will need to install [MSYS2](https://www.msys2.org). Once installed, close any open MSYS terminals (purple icon) and open a new MinGW 64-bit terminal (blue icon) from the Start Menu. 43 44 ::: warning 45 **NOTE:** The MinGW 64-bit terminal is *not* the same as the MSYS terminal that opens when installation is completed. Your prompt should say "MINGW64" in purple text, rather than "MSYS". See [this page](https://www.msys2.org/wiki/MSYS2-introduction/#subsystems) for more information on the differences. 46 ::: 47 48 #### Installation 49 50 Install the QMK CLI by running: 51 52 ```sh 53 curl -fsSL https://install.qmk.fm | sh 54 ``` 55 56 :::: 57 58 ==== macOS 59 60 #### Prerequisites 61 62 You will need to install Homebrew. Follow the instructions on https://brew.sh. 63 64 #### Installation 65 66 Install the QMK CLI by running: 67 68 ```sh 69 curl -fsSL https://install.qmk.fm | sh 70 ``` 71 72 ==== Linux/WSL 73 74 #### Installation 75 76 ::: info 77 Many Linux distributions are supported, but not all. Mainstream distributions will have best success -- if possible, choose either Debian or its derivatives (such as Ubuntu, or Mint), CentOS or its derivatives (such as Fedora, or Rocky Linux), and Arch or its derivatives (such as Manjaro, or CachyOS). 78 ::: 79 80 Install the QMK CLI by running: 81 82 ```sh 83 curl -fsSL https://install.qmk.fm | sh 84 ``` 85 86 ::: tip 87 **Note for WSL users**: By default, the installation process will clone the QMK repository into your WSL home directory, but if you have cloned manually, ensure that it is located inside the WSL instance instead of the Windows filesystem (ie. not in `/mnt`), as accessing it is currently [extremely slow](https://github.com/microsoft/WSL/issues/4197). 88 ::: 89 90 ::: warning 91 Any QMK packages provided by your distribution's package manager are almost certainly out of date. It is strongly suggested the installation script above is used instead. 92 ::: 93 94 ==== FreeBSD 95 96 #### Installation 97 98 ::: warning 99 FreeBSD support is provided on a best-effort basis by the community instead of the QMK maintainers. It is strongly suggested that you use either Windows, macOS, or a supported distribution of Linux instead. 100 ::: 101 102 Install the FreeBSD package for QMK CLI by running: 103 104 ```sh 105 pkg install -g "py*-qmk" 106 ``` 107 108 ::: info NOTE 109 Remember to follow the instructions printed at the end of installation (use `pkg info -Dg "py*-qmk"` to show them again). 110 ::: 111 112 ::::: 113 114 ## 3. Run QMK Setup {#set-up-qmk} 115 116 ::::tabs 117 118 === Windows 119 120 Open QMK MSYS and run the following command: 121 122 ```sh 123 qmk setup 124 ``` 125 126 In most situations you will want to answer `y` to all of the prompts. 127 128 === macOS 129 130 Open Terminal and run the following command: 131 132 ```sh 133 qmk setup 134 ``` 135 136 In most situations you will want to answer `y` to all of the prompts. 137 138 === Linux/WSL 139 140 Open your preferred terminal app and run the following command: 141 142 ```sh 143 qmk setup 144 ``` 145 146 In most situations you will want to answer `y` to all of the prompts. 147 148 ::: info Note on Debian, Ubuntu and their derivatives: 149 It's possible, that you will get an error saying something like: `bash: qmk: command not found`. 150 This is due to a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155) Debian introduced with their Bash 4.4 release, which removed `$HOME/.local/bin` from the PATH. This bug was later fixed on Debian and Ubuntu. 151 Sadly, Ubuntu reintroduced this bug and is [yet to fix it](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562). 152 Luckily, the fix is easy. Run this as your user: `echo 'PATH="$HOME/.local/bin:$PATH"' >> $HOME/.bashrc && source $HOME/.bashrc` 153 ::: 154 155 === FreeBSD 156 157 Open your preferred terminal app and run the following command: 158 159 ```sh 160 qmk setup 161 ``` 162 163 In most situations you will want to answer `y` to all of the prompts. 164 165 :::: 166 167 ::: tip 168 The qmk home folder can be specified at setup with `qmk setup -H <path>`, and modified afterwards using the [cli configuration](cli_configuration#single-key-example) and the variable `user.qmk_home`. For all available options run `qmk setup --help`. 169 ::: 170 171 ::: tip 172 If you already know how to use GitHub, [we recommend that you follow these instructions](getting_started_github) and use `qmk setup <github_username>/qmk_firmware` to clone your personal fork. If you don't know what that means you can safely ignore this message. 173 ::: 174 175 ## 4. Test Your Build Environment 176 177 Now that your QMK build environment is set up, you can build a firmware for your keyboard. Start by trying to build the keyboard's default keymap. You should be able to do that with a command in this format: 178 179 ```sh 180 qmk compile -kb <keyboard> -km default 181 ``` 182 183 For example, to build a firmware for a Clueboard 66% you would use: 184 185 ```sh 186 qmk compile -kb clueboard/66/rev3 -km default 187 ``` 188 189 ::: tip 190 The keyboard option is the path relative to the keyboard directory, the above example would be found in `qmk_firmware/keyboards/clueboard/66/rev3`. If you're unsure you can view a full list of supported keyboards with `qmk list-keyboards`. 191 ::: 192 193 When it is done you should have a lot of output that ends similar to this: 194 195 ``` 196 Linking: .build/clueboard_66_rev3_default.elf [OK] 197 Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK] 198 Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK] 199 Checking file size of clueboard_66_rev3_default.hex [OK] 200 * The firmware size is fine - 26356/28672 (2316 bytes free) 201 ``` 202 203 # Creating Your Keymap 204 205 You are now ready to create your own personal keymap! Move on to [Building Your First Firmware](newbs_building_firmware) for that.