qmk_firmware/assets/api_development_overview.md.CzbJJDNw.js

import { _ as _export_sfc, o as openBlock, c as createElementBlock, al as createStaticVNode } from "./chunks/framework.8zKZLKO7.js";
const __pageData = JSON.parse('{"title":"QMK Compiler Development Guide","description":"","frontmatter":{},"headers":[],"relativePath":"api_development_overview.md","filePath":"api_development_overview.md","lastUpdated":null}');
const _sfc_main = { name: "api_development_overview.md" };
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
  return openBlock(), createElementBlock("div", null, [..._cache[0] || (_cache[0] = [
    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 &quot;QMK Compiler Development Guide&quot;">​</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 &quot;Overview&quot;">​</a></h1><p>The QMK Compile API consists of a few moving 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 &quot;Workers&quot;">​</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 &quot;API Service&quot;">​</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(&#39;/v1/compile&#39;, methods=[&#39;POST&#39;]) <a class="header-anchor" href="#app-route-v1-compile-methods-post" aria-label="Permalink to &quot;@app.route(&#39;/v1/compile&#39;, methods=[&#39;POST&#39;])&quot;">​</a></h2><p>This is the main entrypoint for the API. A client&#39;s interaction starts here. The client POST&#39;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-lt-string-job-id-gt-methods-get" tabindex="-1">@app.route(&#39;/v1/compile/&lt;string:job_id&gt;&#39;, methods=[&#39;GET&#39;]) <a class="header-anchor" href="#app-route-v1-compile-lt-string-job-id-gt-methods-get" aria-label="Permalink to &quot;@app.route(&#39;/v1/compile/&amp;lt;string:job_id&amp;gt;&#39;, methods=[&#39;GET&#39;])&quot;">​</a></h2><p>This is the most frequently called endpoint. It pulls the job details from redis, if they&#39;re still available, or the cached job details on S3 if they&#39;re not.</p><h2 id="app-route-v1-compile-lt-string-job-id-gt-download-methods-get" tabindex="-1">@app.route(&#39;/v1/compile/&lt;string:job_id&gt;/download&#39;, methods=[&#39;GET&#39;]) <a class="header-anchor" href="#app-route-v1-compile-lt-string-job-id-gt-download-methods-get" aria-label="Permalink to &quot;@app.route(&#39;/v1/compile/&amp;lt;string:job_id&amp;gt;/download&#39;, methods=[&#39;GET&#39;])&quot;">​</a></h2><p>This method allows users to download the compiled firmware file.</p><h2 id="app-route-v1-compile-lt-string-job-id-gt-source-methods-get" tabindex="-1">@app.route(&#39;/v1/compile/&lt;string:job_id&gt;/source&#39;, methods=[&#39;GET&#39;]) <a class="header-anchor" href="#app-route-v1-compile-lt-string-job-id-gt-source-methods-get" aria-label="Permalink to &quot;@app.route(&#39;/v1/compile/&amp;lt;string:job_id&amp;gt;/source&#39;, methods=[&#39;GET&#39;])&quot;">​</a></h2><p>This method allows users to download the source for their firmware.</p>', 20)
  ])]);
}
const api_development_overview = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
export {
  __pageData,
  api_development_overview as default
};