qmk/qmk_firmware
1
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware.git synced 2026-10-01 06:19:16 +02:00
Code Issues Packages Projects Releases Wiki Activity

add docusaurus, convert notes/tips, ids

Browse Source
This commit is contained in:
Jack Humbert
2023-04-18 12:35:09 -04:00
parent e0a09ff728
commit 2cef3465e8
180 changed files with 15192 additions and 785 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/newbs_getting_started.md
+72 -24
View File
@@ -1,3 +1,6 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Setting Up Your QMK Environment
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.
@@ -11,15 +14,19 @@ There are a few pieces of software you'll need to get started.
* [Toolbox (optional)](https://github.com/qmk/qmk_toolbox)
* A graphical program for Windows and macOS that allows you to both program and debug your custom keyboard
?> 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.md#command-line-resources) will teach you enough to be able to work with QMK.
:::note
## 2. Prepare Your Build Environment :id=set-up-your-environment
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.md#command-line-resources) will teach you enough to be able to work with QMK.
:::
## 2. Prepare Your Build Environment {#set-up-your-environment}
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:start -->
<Tabs groupId="operating-systems">
### ** Windows **
<TabItem value="windows" label="Windows" default>
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.
@@ -30,7 +37,11 @@ You will need to install [QMK MSYS](https://msys.qmk.fm/). The latest release is
<details>
<summary>Advanced Users</summary>
!> <b style="font-size:150%">This process is not recommended for new users.</b>
:::caution
This process is not recommended for new users.
:::
If you'd like to manually install MSYS2, the following sections will walk you through the process.
@@ -38,7 +49,11 @@ If you'd like to manually install MSYS2, the following sections will walk you th
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.
!> **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.
:::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.
:::
#### Installation
@@ -48,7 +63,9 @@ Install the QMK CLI by running:
</details>
### ** macOS **
</TabItem>
<TabItem value="macOS" label="macOS">
QMK maintains a Homebrew tap and formula which will automatically install the CLI and all necessary dependencies.
@@ -56,7 +73,11 @@ QMK maintains a Homebrew tap and formula which will automatically install the CL
You will need to install Homebrew. Follow the instructions on https://brew.sh.
!> **NOTE:** If you are using Apple Silicon, such as the M1, you will need to install a rosetta compatible version of Homebrew. This version does not override the base Homebrew. This can be done by running `arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"`. See here: [Rosetta-compatible Homebrew](https://stackoverflow.com/questions/64882584/how-to-run-the-homebrew-installer-under-rosetta-2-on-m1-macbook)
:::note
If you are using Apple Silicon, such as the M1, you will need to install a rosetta compatible version of Homebrew. This version does not override the base Homebrew. This can be done by running `arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"`. See here: [Rosetta-compatible Homebrew](https://stackoverflow.com/questions/64882584/how-to-run-the-homebrew-installer-under-rosetta-2-on-m1-macbook)
:::
#### Installation
@@ -68,9 +89,15 @@ Install the QMK CLI on an Apple Silicon Mac by running:
arch -x86_64 brew install qmk/qmk/qmk
### ** Linux/WSL **
</TabItem>
?> **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).
<TabItem value="linux" label="Linux/WSL">
:::note 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).
:::
#### Prerequisites
@@ -102,7 +129,9 @@ You can also try the `qmk-git` package from AUR:
yay -S qmk-git
### ** FreeBSD **
</TabItem>
<TabItem value="freeBSD" label="FreeBSD">
#### Installation
@@ -112,13 +141,13 @@ Install the FreeBSD package for QMK CLI by running:
NOTE: remember to follow the instructions printed at the end of installation (use `pkg info -Dg "py*-qmk"` to show them again).
<!-- tabs:end -->
</TabItem>
</Tabs>
## 3. Run QMK Setup :id=set-up-qmk
## 3. Run QMK Setup {#set-up-qmk}
<!-- tabs:start -->
### ** Windows **
<Tabs groupId="operating-systems">
<TabItem value="windows" label="Windows" default>
After installing QMK you can set it up with this command:
@@ -126,7 +155,8 @@ After installing QMK you can set it up with this command:
In most situations you will want to answer `y` to all of the prompts.
### ** macOS **
</TabItem>
<TabItem value="macOS" label="macOS">
After installing QMK you can set it up with this command:
@@ -134,7 +164,8 @@ After installing QMK you can set it up with this command:
In most situations you will want to answer `y` to all of the prompts.
### ** Linux/WSL **
</TabItem>
<TabItem value="linux" label="Linux/WSL">
After installing QMK you can set it up with this command:
@@ -142,13 +173,17 @@ After installing QMK you can set it up with this command:
In most situations you will want to answer `y` to all of the prompts.
?>**Note on Debian, Ubuntu and their derivatives**:
:::note 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](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.
Sadly, Ubuntu reintroduced this bug and is [yet to fix it](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562).
Luckily, the fix is easy. Run this as your user: `echo 'PATH="$HOME/.local/bin:$PATH"' >> $HOME/.bashrc && source $HOME/.bashrc`
### ** FreeBSD **
:::
</TabItem>
<TabItem value="freeBSD" label="FreeBSD">
After installing QMK you can set it up with this command:
@@ -156,11 +191,20 @@ After installing QMK you can set it up with this command:
In most situations you will want to answer `y` to all of the prompts.
<!-- tabs:end -->
</TabItem>
</Tabs>
?> The qmk home folder can be specified at setup with `qmk setup -H <path>`, and modified afterwards using the [cli configuration](cli_configuration.md?id=single-key-example) and the variable `user.qmk_home`. For all available options run `qmk setup --help`.
:::info
?> If you already know how to use GitHub, [we recommend that you follow these instructions](getting_started_github.md) 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.
The qmk home folder can be specified at setup with `qmk setup -H <path>`, and modified afterwards using the [cli configuration](cli_configuration.md?id=single-key-example) and the variable `user.qmk_home`. For all available options run `qmk setup --help`.
:::
:::info
If you already know how to use GitHub, [we recommend that you follow these instructions](getting_started_github.md) 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.
:::
## 4. Test Your Build Environment
@@ -172,7 +216,11 @@ For example, to build a firmware for a Clueboard 66% you would use:
qmk compile -kb clueboard/66/rev3 -km default
?> 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`.
:::info
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: