mirror of
https://github.com/qmk/qmk_firmware.git
synced 2025-02-27 01:56:43 +00:00
16 lines
4.8 KiB
JavaScript
16 lines
4.8 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":"QMK Compiler Development Guide","description":"","frontmatter":{},"headers":[],"relativePath":"api_development_overview.md","filePath":"api_development_overview.md"}');
|
||
const _sfc_main = { name: "api_development_overview.md" };
|
||
const _hoisted_1 = /* @__PURE__ */ createStaticVNode('<h1 id="qmk-compiler-development-guide" tabindex="-1">QMK Compiler Development Guide <a class="header-anchor" href="#qmk-compiler-development-guide" aria-label="Permalink to "QMK Compiler Development Guide""></a></h1><p>This page attempts to introduce developers to the QMK Compiler. It does not go into nitty gritty details- for that you should read code. What this will give you is a framework to hang your understanding on as you read the code.</p><h1 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to "Overview""></a></h1><p>The QMK Compile API consists of a few movings parts:</p><p><img src="https://raw.githubusercontent.com/qmk/qmk_api/master/docs/architecture.svg" alt="Architecture Diagram"></p><p>API Clients interact exclusively with the API service. This is where they submit jobs, check status, and download results. The API service inserts compile jobs into <a href="https://python-rq.org" target="_blank" rel="noreferrer">Redis Queue</a> and checks both RQ and S3 for the results of those jobs.</p><p>Workers fetch new compile jobs from RQ, compile them, and then upload the source and the binary to an S3 compatible storage engine.</p><h1 id="workers" tabindex="-1">Workers <a class="header-anchor" href="#workers" aria-label="Permalink to "Workers""></a></h1><p>QMK Compiler Workers are responsible for doing the actual building. When a worker pulls a job from RQ it does several things to complete that job:</p><ul><li>Make a fresh qmk_firmware checkout</li><li>Use the supplied layers and keyboard metadata to build a <code>keymap.c</code></li><li>Build the firmware</li><li>Zip a copy of the source</li><li>Upload the firmware, source zip, and a metadata file to S3.</li><li>Report the status of the job to RQ</li></ul><h1 id="api-service" tabindex="-1">API Service <a class="header-anchor" href="#api-service" aria-label="Permalink to "API Service""></a></h1><p>The API service is a relatively simple Flask application. There are a few main views you should understand.</p><h2 id="app-route-v1-compile-methods-post" tabindex="-1">@app.route('/v1/compile', methods=['POST']) <a class="header-anchor" href="#app-route-v1-compile-methods-post" aria-label="Permalink to "@app.route('/v1/compile', methods=['POST'])""></a></h2><p>This is the main entrypoint for the API. A client's interaction starts here. The client POST's a JSON document describing their keyboard, and the API does some (very) basic validation of that JSON before submitting the compile job.</p><h2 id="app-route-v1-compile-string-job-id-methods-get" tabindex="-1">@app.route('/v1/compile/<string:job_id>', methods=['GET']) <a class="header-anchor" href="#app-route-v1-compile-string-job-id-methods-get" aria-label="Permalink to "@app.route('/v1/compile/&lt;string:job_id&gt;', methods=['GET'])""></a></h2><p>This is the most frequently called endpoint. It pulls the job details from redis, if they're still available, or the cached job details on S3 if they're not.</p><h2 id="app-route-v1-compile-string-job-id-download-methods-get" tabindex="-1">@app.route('/v1/compile/<string:job_id>/download', methods=['GET']) <a class="header-anchor" href="#app-route-v1-compile-string-job-id-download-methods-get" aria-label="Permalink to "@app.route('/v1/compile/&lt;string:job_id&gt;/download', methods=['GET'])""></a></h2><p>This method allows users to download the compiled firmware file.</p><h2 id="app-route-v1-compile-string-job-id-source-methods-get" tabindex="-1">@app.route('/v1/compile/<string:job_id>/source', methods=['GET']) <a class="header-anchor" href="#app-route-v1-compile-string-job-id-source-methods-get" aria-label="Permalink to "@app.route('/v1/compile/&lt;string:job_id&gt;/source', methods=['GET'])""></a></h2><p>This method allows users to download the source for their firmware.</p>', 20);
|
||
const _hoisted_21 = [
|
||
_hoisted_1
|
||
];
|
||
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
|
||
return openBlock(), createElementBlock("div", null, _hoisted_21);
|
||
}
|
||
const api_development_overview = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
|
||
export {
|
||
__pageData,
|
||
api_development_overview as default
|
||
};
|