docs/newbs_getting_started.md
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.
There are a few pieces of software you'll need to get started.
::: tip 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 will teach you enough to be able to work with QMK. :::
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.
:::::tabs
==== Windows
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.
You will need to install QMK MSYS. The latest release is available here.
:::: details Advanced Users
::: danger <b style="font-size:150%">This process is not recommended for new users.</b> :::
If you'd like to manually install MSYS2, the following sections will walk you through the process.
You will need to install MSYS2. Once installed, close any open MSYS terminals (purple icon) and open a new MinGW 64-bit terminal (blue icon) from the Start Menu.
::: warning 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 for more information on the differences. :::
Install the QMK CLI by running:
curl -fsSL https://install.qmk.fm | sh
::::
==== macOS
You will need to install Homebrew. Follow the instructions on https://brew.sh.
Install the QMK CLI by running:
curl -fsSL https://install.qmk.fm | sh
==== Linux/WSL
::: info 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). :::
Install the QMK CLI by running:
curl -fsSL https://install.qmk.fm | sh
::: tip
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.
:::
::: warning 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. :::
==== FreeBSD
::: warning 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. :::
Install the FreeBSD package for QMK CLI by running:
pkg install -g "py*-qmk"
::: info NOTE
Remember to follow the instructions printed at the end of installation (use pkg info -Dg "py*-qmk" to show them again).
:::
:::::
::::tabs
=== Windows
Open QMK MSYS and run the following command:
qmk setup
In most situations you will want to answer y to all of the prompts.
=== macOS
Open Terminal and run the following command:
qmk setup
In most situations you will want to answer y to all of the prompts.
=== Linux/WSL
Open your preferred terminal app and run the following command:
qmk setup
In most situations you will want to answer y to all of the prompts.
::: info Note on Debian, Ubuntu and their derivatives:
It's possible, that you will get an error saying something like: bash: qmk: command not found.
This is due to a bug 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.
Sadly, Ubuntu reintroduced this bug and is yet to fix it.
Luckily, the fix is easy. Run this as your user: echo 'PATH="$HOME/.local/bin:$PATH"' >> $HOME/.bashrc && source $HOME/.bashrc
:::
=== FreeBSD
Open your preferred terminal app and run the following command:
qmk setup
In most situations you will want to answer y to all of the prompts.
::::
::: tip
The qmk home folder can be specified at setup with qmk setup -H <path>, and modified afterwards using the cli configuration and the variable user.qmk_home. For all available options run qmk setup --help.
:::
::: tip
If you already know how to use GitHub, we recommend that you follow these instructions 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.
:::
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:
qmk compile -kb <keyboard> -km default
For example, to build a firmware for a Clueboard 66% you would use:
qmk compile -kb clueboard/66/rev3 -km default
::: tip
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.
:::
When it is done you should have a lot of output that ends similar to this:
Linking: .build/clueboard_66_rev3_default.elf [OK]
Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK]
Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK]
Checking file size of clueboard_66_rev3_default.hex [OK]
* The firmware size is fine - 26356/28672 (2316 bytes free)
You are now ready to create your own personal keymap! Move on to Building Your First Firmware for that.