newbs_building_firmware_workflow.md (8449B)
1 # Building QMK with GitHub Userspace 2 3 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. 4 5 ::: tip Is This Guide For Me? 6 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. 7 ::: 8 9 ## Prerequisites 10 11 The following are required to get started: 12 13 * [GitHub Account](https://github.com/new) 14 * A working account is required to setup and host your repository for GitHub Actions to build QMK firmware. 15 * [Text editor](newbs_learn_more_resources#text-editor-resources) 16 * 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. 17 * [Toolbox](https://github.com/qmk/qmk_toolbox) 18 * A graphical program for Windows and macOS that allows you to both program and debug your custom keyboard. 19 20 21 ## Environment Setup 22 23 ::: tip 24 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. 25 ::: 26 27 ### 1. Install Git 28 29 A working Git client is required for your local operating system to commit and push changes to GitHub. 30 31 ::::tabs 32 33 === Windows 34 35 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. 36 37 === macOS 38 39 Install Homebrew following the instructions on https://brew.sh. Git will be part of the bundle. 40 41 === Linux/WSL 42 43 It's very likely that you already have Git installed. If not, use one of the following commands: 44 45 * Debian / Ubuntu / Devuan: `sudo apt install -y git` 46 * Fedora / Red Hat / CentOS: `sudo yum -y install git` 47 * Arch / Manjaro: `sudo pacman --needed --noconfirm -S git` 48 * Void: `sudo xbps-install -y git` 49 * Solus: `sudo eopkg -y install git` 50 * Sabayon: `sudo equo install dev-vcs/git` 51 * Gentoo: `sudo emerge dev-vcs/git` 52 53 :::: 54 55 ### 2. GitHub authentication 56 57 If your GitHub account is not configured for [authenticated Git operations](https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/), you will need to setup at least one of the following: 58 * [Personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) 59 * [Connecting with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) 60 61 ### 3. Create a repository 62 63 You will need a personal GitHub repository to host your QMK code. Follow [this guide](https://docs.github.com/en/get-started/quickstart/create-a-repo#create-a-repository) to create one named `qmk_keymap`. Do not proceed to commit any files just yet. 64 65 66 ## Initial Code Commit 67 68 ### Create template files 69 70 Run the following commands in your computer to create a folder with a few template files: 71 ``` 72 mkdir -p ~/qmk_keymap/.github/workflows 73 touch ~/qmk_keymap/.github/workflows/build.yml 74 touch ~/qmk_keymap/config.h 75 echo "SRC += source.c" > ~/qmk_keymap/rules.mk 76 echo "#include QMK_KEYBOARD_H" > ~/qmk_keymap/source.c 77 ``` 78 79 ::: tip 80 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. 81 ::: 82 83 ### Add a JSON keymap 84 85 Visit the [QMK Configurator](https://config.qmk.fm/#/) to create a keymap file: 86 87 1. Select your keyboard from the drop-down list (and choose a layout if required). 88 2. Use your GitHub username for the **Keymap Name** field. 89 3. Customise the key layout according to your preference. 90 4. Select download next to **KEYMAP.JSON** and save the JSON file into the `~/qmk_keymap/` folder. 91 92 ::: warning 93 **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. 94 ::: 95 96 ### Add a GitHub Action workflow 97 98 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: 99 ```yml 100 name: Build QMK firmware 101 on: [push, workflow_dispatch] 102 103 jobs: 104 build: 105 runs-on: ubuntu-latest 106 container: ghcr.io/qmk/qmk_cli 107 strategy: 108 fail-fast: false 109 matrix: 110 # List of keymap json files to build 111 file: 112 - username.json 113 # End of json file list 114 115 steps: 116 117 - name: Disable git safe directory checks 118 run : git config --global --add safe.directory '*' 119 120 - name: Checkout QMK 121 uses: actions/checkout@v3 122 with: 123 repository: qmk/qmk_firmware 124 submodules: recursive 125 126 - name: Checkout userspace 127 uses: actions/checkout@v3 128 with: 129 path: users/${{ github.actor }} 130 131 - name: Build firmware 132 run: qmk compile "users/${{ github.actor }}/${{ matrix.file }}" 133 134 - name: Archive firmware 135 uses: actions/upload-artifact@v3 136 continue-on-error: true 137 with: 138 name: ${{ matrix.file }}_${{ github.actor }} 139 path: | 140 *.hex 141 *.bin 142 *.uf2 143 ``` 144 Replace `username.json` with the JSON file name that was downloaded from [QMK Configurator](https://config.qmk.fm/#/) in the previous step. 145 146 ::: warning 147 Do note that the `build.yml` file requires ***proper indentation*** for every line. Incorrect spacing will trigger workflow syntax errors. 148 ::: 149 150 ### Commit files to GitHub 151 152 If you have completed all steps correctly, the folder `qmk_keymap/` will contain the following files: 153 ``` 154 ├── .github 155 │ └── workflows 156 │ └── build.yml 157 ├── rules.mk 158 ├── config.h 159 ├── source.c 160 └── username.json 161 ``` 162 163 To commit and push them into GitHub, run the following commands (replacing `gh-username` with your GitHub user name): 164 ``` 165 cd ~/qmk_keymap 166 git init 167 git add -A 168 git commit -m "Initial QMK keymap commit" 169 git branch -M main 170 git remote add origin https://github.com/gh-username/qmk_keymap.git 171 git push -u origin main 172 ``` 173 ::: tip 174 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. 175 ::: 176 177 ### Review workflow output 178 179 Files committed to GitHub in the previous step will automatically trigger the workflow to build the JSON file listed in `build.yml`. To review its output: 180 1. Visit your "**qmk_keymap**" repository page on [GitHub](https://github.com/). 181 2. Select **Actions** tab to display the "**Build QMK Firmware**" workflow. 182 3. Select that workflow to display its run from the last commit. 183 4. Successfully compiled firmware will be under the "**Artifacts**" section. 184 5. If there are build errors, review the job log for details. 185 186 Download and flash the firmware file into your keyboard using [QMK Toolbox](newbs_flashing#flashing-your-keyboard-with-qmk-toolbox). 187 188 189 ## Customising your keymap 190 191 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: 192 193 * Keymap layout files must be retained in JSON format and cannot be converted to `keymap.c`. 194 * User callback and functions (e.g. `process_record_user()`) can be placed in the `source.c` file. 195 * Multiple keymap JSON files can be built in the same workflow. List them under `matrix.file:`, e.g.: 196 ```yml 197 file: 198 - planck.json 199 - crkbd.json 200 ``` 201 * Code changes will require Git commit into GitHub to trigger the build workflow. 202 203 204 ::: tip 205 See [GitHub Actions guide](https://docs.github.com/en/actions/learn-github-actions) to learn more about development workflow. 206 :::