Vitepress conversion of docs. (#23795)
This commit is contained in:
Nick Brassel
GitHub
parent
395766657f
commit
6ef9717288
357 changed files with 3611 additions and 24208 deletions
|
|
@ -1,8 +1,10 @@
|
|||
# Building QMK with GitHub Userspace
|
||||
|
||||
This is an intermediate QMK tutorial to setup an out-of-tree build environment with a personal GitHub repository. It avoids using a fork of the QMK firmware to store and build your keymap within its source tree. Keymap files will instead be stored in your own personal GitHub repository, in [Userspace](https://docs.qmk.fm/#/feature_userspace) format, and built with an action workflow. Unlike the [default tutorial](https://docs.qmk.fm/#/newbs), this guide requires some familiarity with using Git.
|
||||
This is an intermediate QMK tutorial to setup an out-of-tree build environment with a personal GitHub repository. It avoids using a fork of the QMK firmware to store and build your keymap within its source tree. Keymap files will instead be stored in your own personal GitHub repository, in [Userspace](feature_userspace) format, and built with an action workflow. Unlike the [default tutorial](newbs), this guide requires some familiarity with using Git.
|
||||
|
||||
?> **Is This Guide For Me?**<br>
|
||||
::: tip
|
||||
**Is This Guide For Me?**<br>
|
||||
:::
|
||||
This is a lean setup to avoid space-consuming local build environment in your computer. Troubleshooting compile-time errors will be slower with commit uploads to GitHub for the compiler workflow.
|
||||
|
||||
|
||||
|
|
@ -12,7 +14,7 @@ The following are required to get started:
|
|||
|
||||
* [GitHub Account](https://github.com/new)
|
||||
* A working account is required to setup and host your repository for GitHub Actions to build QMK firmware.
|
||||
* [Text editor](newbs_learn_more_resources.md#text-editor-resources)
|
||||
* [Text editor](newbs_learn_more_resources#text-editor-resources)
|
||||
* 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.
|
||||
* [Toolbox](https://github.com/qmk/qmk_toolbox)
|
||||
* A graphical program for Windows and macOS that allows you to both program and debug your custom keyboard.
|
||||
|
|
@ -20,23 +22,25 @@ The following are required to get started:
|
|||
|
||||
## Environment Setup
|
||||
|
||||
?> If you are familiar with using [github.dev](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor), you can skip to [step 2](#_2-create-github-repository) and commit the code files that follows directly on GitHub using the web-based VSCode editor.
|
||||
::: tip
|
||||
If you are familiar with using [github.dev](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor), you can skip to [step 2](#_2-create-github-repository) and commit the code files that follows directly on GitHub using the web-based VSCode editor.
|
||||
:::
|
||||
|
||||
### 1. Install Git
|
||||
|
||||
A working Git client is required for your local operating system to commit and push changes to GitHub.
|
||||
|
||||
<!-- tabs:start -->
|
||||
::::tabs
|
||||
|
||||
### ** Windows **
|
||||
=== Windows
|
||||
|
||||
QMK maintains a bundle of MSYS2, the CLI and all necessary dependencies including Git. Install [QMK MSYS](https://msys.qmk.fm/) with the latest release [here](https://github.com/qmk/qmk_distro_msys/releases/latest). Git will be part of the bundle.
|
||||
|
||||
### ** macOS **
|
||||
=== macOS
|
||||
|
||||
Install Homebrew following the instructions on https://brew.sh. Git will be part of the bundle.
|
||||
|
||||
### ** Linux/WSL **
|
||||
=== Linux/WSL
|
||||
|
||||
It's very likely that you already have Git installed. If not, use one of the following commands:
|
||||
|
||||
|
|
@ -48,7 +52,7 @@ It's very likely that you already have Git installed. If not, use one of the fol
|
|||
* Sabayon: `sudo equo install dev-vcs/git`
|
||||
* Gentoo: `sudo emerge dev-vcs/git`
|
||||
|
||||
<!-- tabs:end -->
|
||||
::::
|
||||
|
||||
### 2. GitHub authentication
|
||||
|
||||
|
|
@ -74,7 +78,9 @@ echo "SRC += source.c" > ~/qmk_keymap/rules.mk
|
|||
echo "#include QMK_KEYBOARD_H" > ~/qmk_keymap/source.c
|
||||
```
|
||||
|
||||
?> For Windows user running MSYS, those commands will create the folder `qmk_keymap/` and its content in the `C:\Users\<windows_username>\qmk_keymap\` path location.
|
||||
::: tip
|
||||
For Windows user running MSYS, those commands will create the folder `qmk_keymap/` and its content in the `C:\Users\<windows_username>\qmk_keymap\` path location.
|
||||
:::
|
||||
|
||||
### Add a JSON keymap
|
||||
|
||||
|
|
@ -85,11 +91,13 @@ Visit the [QMK Configurator](https://config.qmk.fm/#/) to create a keymap file:
|
|||
3. Customise the key layout according to your preference.
|
||||
4. Select download next to **KEYMAP.JSON** and save the JSON file into the `~/qmk_keymap/` folder.
|
||||
|
||||
!> **Important:** Make sure that the GitHub username you use in step 2 is correct. If it is not, the build process will fail to locate your files in the right folder.
|
||||
::: warning
|
||||
**Important:** Make sure that the GitHub username you use in step 2 is correct. If it is not, the build process will fail to locate your files in the right folder.
|
||||
:::
|
||||
|
||||
### Add a GitHub Action workflow
|
||||
|
||||
Open the file `~/qmk_keymap/.github/workflows/build.yml` with your favorite [text editor](newbs_learn_more_resources.md#text-editor-resources), paste the following workflow content, and save it:
|
||||
Open the file `~/qmk_keymap/.github/workflows/build.yml` with your favorite [text editor](newbs_learn_more_resources#text-editor-resources), paste the following workflow content, and save it:
|
||||
```yml
|
||||
name: Build QMK firmware
|
||||
on: [push, workflow_dispatch]
|
||||
|
|
@ -137,7 +145,9 @@ jobs:
|
|||
```
|
||||
Replace `username.json` with the JSON file name that was downloaded from [QMK Configurator](https://config.qmk.fm/#/) in the previous step.
|
||||
|
||||
!> Do note that the `build.yml` file requires ***proper indentation*** for every line. Incorrect spacing will trigger workflow syntax errors.
|
||||
::: warning
|
||||
Do note that the `build.yml` file requires ***proper indentation*** for every line. Incorrect spacing will trigger workflow syntax errors.
|
||||
:::
|
||||
|
||||
### Commit files to GitHub
|
||||
|
||||
|
|
@ -162,7 +172,9 @@ git branch -M main
|
|||
git remote add origin https://github.com/gh-username/qmk_keymap.git
|
||||
git push -u origin main
|
||||
```
|
||||
?> Use your GitHub personal access token at the password prompt. If you have setup SSH access, replace `https://github.com/gh-username/qmk_keymap.git` with `git@github.com:gh-username/qmk_keymap.git` in the remote origin command above.
|
||||
::: tip
|
||||
Use your GitHub personal access token at the password prompt. If you have setup SSH access, replace `https://github.com/gh-username/qmk_keymap.git` with `git@github.com:gh-username/qmk_keymap.git` in the remote origin command above.
|
||||
:::
|
||||
|
||||
### Review workflow output
|
||||
|
||||
|
|
@ -173,12 +185,12 @@ Files committed to GitHub in the previous step will automatically trigger the wo
|
|||
4. Successfully compiled firmware will be under the "**Artifacts**" section.
|
||||
5. If there are build errors, review the job log for details.
|
||||
|
||||
Download and flash the firmware file into your keyboard using [QMK Toolbox](https://docs.qmk.fm/#/newbs_flashing?id=flashing-your-keyboard-with-qmk-toolbox).
|
||||
Download and flash the firmware file into your keyboard using [QMK Toolbox](newbs_flashing#flashing-your-keyboard-with-qmk-toolbox).
|
||||
|
||||
|
||||
## Customising your keymap
|
||||
|
||||
This setup and workflow relies on the QMK [Userspace](https://docs.qmk.fm/#/feature_userspace) feature. The build process will copy the QMK source codes and clone your repository into its `users/` folder in a container. You must adhere to the following guidelines when customising your keymaps:
|
||||
This setup and workflow relies on the QMK [Userspace](feature_userspace) feature. The build process will copy the QMK source codes and clone your repository into its `users/` folder in a container. You must adhere to the following guidelines when customising your keymaps:
|
||||
|
||||
* Keymap layout files must be retained in JSON format and cannot be converted to `keymap.c`.
|
||||
* User callback and functions (e.g. `process_record_user()`) can be placed in the `source.c` file.
|
||||
|
|
@ -191,4 +203,6 @@ This setup and workflow relies on the QMK [Userspace](https://docs.qmk.fm/#/feat
|
|||
* Code changes will require Git commit into GitHub to trigger the build workflow.
|
||||
|
||||
|
||||
?> See [GitHub Actions guide](https://docs.github.com/en/actions/learn-github-actions) to learn more about development workflow.
|
||||
::: tip
|
||||
See [GitHub Actions guide](https://docs.github.com/en/actions/learn-github-actions) to learn more about development workflow.
|
||||
:::
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue