mirror of
https://github.com/qmk/qmk_firmware.git
synced 2025-02-27 01:56:43 +00:00
16 lines
13 KiB
JavaScript
16 lines
13 KiB
JavaScript
import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode } from "./chunks/framework.DyMmIvSC.js";
|
||
const __pageData = JSON.parse('{"title":"External QMK Userspace","description":"","frontmatter":{},"headers":[],"relativePath":"newbs_external_userspace.md","filePath":"newbs_external_userspace.md"}');
|
||
const _sfc_main = { name: "newbs_external_userspace.md" };
|
||
const _hoisted_1 = /* @__PURE__ */ createStaticVNode('<h1 id="external-qmk-userspace" tabindex="-1">External QMK Userspace <a class="header-anchor" href="#external-qmk-userspace" aria-label="Permalink to "External QMK Userspace""></a></h1><p>QMK Firmware now officially supports storing user keymaps outside of the normal QMK Firmware repository, allowing users to maintain their own keymaps without having to fork, modify, and maintain a copy of QMK Firmware themselves.</p><p>External Userspace mirrors the structure of the main QMK Firmware repository, but only contains the keymaps that you wish to build. You can still use <code>keyboards/<my keyboard>/keymaps/<my keymap></code> to store your keymaps, or you can use the <code>layouts/<my layout>/<my keymap></code> system as before -- they're just stored external to QMK Firmware.</p><p>The build system will still honor the use of <code>users/<my keymap></code> if you rely on the traditional QMK Firmware <a href="./feature_userspace">userspace feature</a> -- it's now supported externally too, using the same location inside the External Userspace directory.</p><p>Additionally, there is first-class support for using GitHub Actions to build your keymaps, allowing you to automatically compile your keymaps whenever you push changes to your External Userspace repository.</p><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>External Userspace is new functionality and may have issues. Tighter integration with the <code>qmk</code> command will occur over time.</p></div><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>Historical keymap.json and GitHub-based firmware build instructions can be found <a href="./newbs_building_firmware_workflow">here</a>. This document supersedes those instructions, but they should still function correctly.</p></div><h2 id="setting-up-qmk-locally" tabindex="-1">Setting up QMK Locally <a class="header-anchor" href="#setting-up-qmk-locally" aria-label="Permalink to "Setting up QMK Locally""></a></h2><p>If you wish to build on your local machine, you will need to set up QMK locally. This is a one-time process, and is documented in the <a href="./newbs">newbs setup guide</a>.</p><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>If you wish to use any QMK CLI commands related to manipulating External Userspace definitions, you will currently need a copy of QMK Firmware as well.</p></div><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>Building locally has a much shorter turnaround time than waiting for GitHub Actions to complete.</p></div><h2 id="external-userspace-repository-setup-forked-on-github" tabindex="-1">External Userspace Repository Setup (forked on GitHub) <a class="header-anchor" href="#external-userspace-repository-setup-forked-on-github" aria-label="Permalink to "External Userspace Repository Setup (forked on GitHub)""></a></h2><p>A basic skeleton External Userspace repository can be found <a href="https://github.com/qmk/qmk_userspace" target="_blank" rel="noreferrer">here</a>. If you wish to keep your keymaps on GitHub (strongly recommended!), you can fork the repository and use it as a base:</p><p><img src="https://i.imgur.com/hcegguh.png" alt="Userspace Fork"></p><p>Going ahead with your fork will copy it to your account, at which point you can clone it to your local machine and begin adding your keymaps:</p><p><img src="https://i.imgur.com/CWYmsk8.png" alt="Userspace Clone"></p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> $HOME</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> clone</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/{myusername}/qmk_userspace.git</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> config</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> user.overlay_dir="$(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">realpath</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> qmk_userspace)"</span></span></code></pre></div><h2 id="external-userspace-setup-locally-stored-only" tabindex="-1">External Userspace Setup (locally stored only) <a class="header-anchor" href="#external-userspace-setup-locally-stored-only" aria-label="Permalink to "External Userspace Setup (locally stored only)""></a></h2><p>If you don't want to use GitHub and prefer to keep everything local, you can clone a copy of the default External Userspace locally instead:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> $HOME</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> clone</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/qmk/qmk_userspace.git</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> config</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> user.overlay_dir="$(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">realpath</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> qmk_userspace)"</span></span></code></pre></div><h2 id="adding-a-keymap" tabindex="-1">Adding a Keymap <a class="header-anchor" href="#adding-a-keymap" aria-label="Permalink to "Adding a Keymap""></a></h2><p><em>These instructions assume you have already set up QMK locally, and have a copy of the QMK Firmware repository on your machine.</em></p><p>Keymaps within External Userspace are defined in the same way as they are in the main QMK repository. You can either use the <code>qmk new-keymap</code> command to create a new keymap, or manually create a new directory in the <code>keyboards</code> directory.</p><p>Alternatively, you can use the <code>layouts</code> directory to store your keymaps, using the same layout system as the main QMK repository -- if you choose to do so you'll want to use the path <code>layouts/<layout name>/<keymap name>/keymap.*</code> to store your keymap files, where <code>layout name</code> matches an existing layout in QMK, such as <code>tkl_ansi</code>.</p><p>After creating your new keymap, building the keymap matches normal QMK usage:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> compile</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -kb</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">keyboar</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -km</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">keyma</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">p</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>The <code>qmk config user.overlay_dir=...</code> command must have been run when cloning the External Userspace repository for this to work correctly.</p></div><h2 id="adding-the-keymap-to-external-userspace-build-targets" tabindex="-1">Adding the keymap to External Userspace build targets <a class="header-anchor" href="#adding-the-keymap-to-external-userspace-build-targets" aria-label="Permalink to "Adding the keymap to External Userspace build targets""></a></h2><p>Once you have created your keymap, if you want to use GitHub Actions to build your firmware, you will need to add it to the External Userspace build targets. This is done using the <code>qmk userspace-add</code> command:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># for a keyboard/keymap combo:</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> userspace-add</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -kb</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">keyboar</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -km</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">keyma</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">p</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># or, for a json-based keymap (if kept "loose"):</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> userspace-add</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">relative/path/to/my/keymap.jso</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">n</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><p>This updates the <code>qmk.json</code> file in the root of your External Userspace directory. If you're using a git repository to store your keymaps, now is a great time to commit and push to your own fork.</p><h2 id="compiling-external-userspace-build-targets" tabindex="-1">Compiling External Userspace build targets <a class="header-anchor" href="#compiling-external-userspace-build-targets" aria-label="Permalink to "Compiling External Userspace build targets""></a></h2><p>Once you have added your keymaps to the External Userspace build targets, you can compile all of them at once using the <code>qmk userspace-compile</code> command:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> userspace-compile</span></span></code></pre></div><p>All firmware builds you've added to the External Userspace build targets will be built, and the resulting firmware files will be placed in the root of your External Userspace directory.</p><h2 id="using-github-actions" tabindex="-1">Using GitHub Actions <a class="header-anchor" href="#using-github-actions" aria-label="Permalink to "Using GitHub Actions""></a></h2><p>GitHub Actions can be used to automatically build your keymaps whenever you push changes to your External Userspace repository. If you have set up your list of build targets, this is as simple as enabling workflows in the GitHub repository settings:</p><p><img src="https://i.imgur.com/EVkxOt1.png" alt="Repo Settings"></p><p>Any push will result in compilation of all configured builds, and once completed a new release containing the newly-minted firmware files will be created on GitHub, which you can subsequently download and flash to your keyboard:</p><p><img src="https://i.imgur.com/zmwOL5P.png" alt="Releases"></p>', 40);
|
||
const _hoisted_41 = [
|
||
_hoisted_1
|
||
];
|
||
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
|
||
return openBlock(), createElementBlock("div", null, _hoisted_41);
|
||
}
|
||
const newbs_external_userspace = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
|
||
export {
|
||
__pageData,
|
||
newbs_external_userspace as default
|
||
};
|