From d8183c52492557fdc8f35cec67c70170bae55efa Mon Sep 17 00:00:00 2001 From: Manna Harbour <51143715+manna-harbour@users.noreply.github.com> Date: Thu, 27 Oct 2022 23:50:32 +1100 Subject: [Keymap] Update Miryoku (#18773) * [miryoku] Revert "[Keymap] manna-harbour_miryoku RESET to QK_BOOT (#18755)" This reverts commit 89dbc181617e69a5b4d91d9d772724daa2d387bb. * [miryoku] Add keyboardio/model01 * [miryoku] Add handwired/dactyl_manuform/4x6 * [miryoku] Update BT keycodes - Update BT keycodes on Media inner index: - Move OUT_AUTO to bottom row - Move RGB_TOG in vi to pinkie column to match other TOG keycodes, and rotate row * [miryoku] Add Extra and Tap layers * [miryoku] Rename config workflow option to custom_config * [miryoku] Update custom_config.h and custom_rules.mk behaviour * [miryoku] Make mapping macro customisable globally and per layer * [miryoku] Add layer lock * [miryoku] Update RGB order in media-l-invertedt * [miryoku] Change mouse button order * [miryoku] Change to X macros for layer list - Supports adding and removing layers from custom_config.h - Add "U_" prefix to layer names - Add layer name strings - Populate keymaps array from X macro - Populate layers enum from X macro - Move layers enum to manna-harbour_miryoku.h - Rename miryoku_alternatives.h to miryoku_layer_alternatives.h - Rename miryoku_layer.h to miryoku_layer_selection.h - Remove miryoku_layer_names.h - Add miryoku_layer_list.h * [miryoku] Reformat split_3x6_3 mapping * [miryoku] Add merge field to workflows * [miryoku] Update thumb combos with new layer names * [miryoku] Update cover image * [miryoku] Add satt/vision * [miryoku] Update Branches and Building docs * [miryoku] Update reset keycode * [miryoku] Add xmk * [miryoku] Add boardsource/lulu * [miryoku] Fix keyboardio/model01 --- users/manna-harbour_miryoku/readme.org | 156 ++++++++++++++++++++++++++++----- 1 file changed, 136 insertions(+), 20 deletions(-) (limited to 'users/manna-harbour_miryoku/readme.org') diff --git a/users/manna-harbour_miryoku/readme.org b/users/manna-harbour_miryoku/readme.org index 9e3e587240..0adc414e36 100644 --- a/users/manna-harbour_miryoku/readme.org +++ b/users/manna-harbour_miryoku/readme.org @@ -3,36 +3,41 @@ * Miryoku QMK [[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/logos/miryoku-roa-32.png]] -[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/cover/miryoku-kle-cover.png]] +[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/cover/miryoku-kle-cover-miryoku_qmk.png]] [[https://github.com/manna-harbour/miryoku/][Miryoku]] is an ergonomic, minimal, orthogonal, and universal keyboard layout. [[https://github.com/manna-harbour/miryoku_qmk/tree/miryoku/users/manna-harbour_miryoku][Miryoku QMK]] is the Miryoku implementation for [[https://qmk.fm][QMK]]. + ** Branches *** QMK master -Miryoku QMK is periodically merged upstream into QMK master and it is generally recommended to build directly from QMK master. +QMK master is the current version of QMK, but usually does not contain the current version of Miryoku QMK. -QMK master is at https://github.com/qmk/qmk_firmware/tree/master, and the corresponding Miryoku QMK readme is at https://github.com/qmk/qmk_firmware/tree/master/users/manna-harbour_miryoku. +QMK master is at https://github.com/qmk/qmk_firmware/tree/master. The corresponding Miryoku QMK readme is at https://github.com/qmk/qmk_firmware/tree/master/users/manna-harbour_miryoku and describes the version of Miryoku QMK in QMK master. *** Miryoku QMK development branch -The Miryoku QMK development branch is ~miryoku~ and may contain new commits not yet merged into QMK master. +The Miryoku QMK development branch is the current version of Miryoku QMK, but usually does not contain the current version of QMK. -~miryoku~ is at https://github.com/manna-harbour/miryoku_qmk/tree/miryoku, and the corresponding Miryoku QMK readme is at https://github.com/manna-harbour/miryoku_qmk/tree/miryoku/users/manna-harbour_miryoku. +The Miryoku QMK development branch is named ~miryoku~ and is at https://github.com/manna-harbour/miryoku_qmk/tree/miryoku. The corresponding Miryoku QMK readme is at https://github.com/manna-harbour/miryoku_qmk/tree/miryoku/users/manna-harbour_miryoku. -New commits can be seen at the top of the [[https://github.com/manna-harbour/miryoku_qmk/commits/miryoku][history]] with commit messages beginning ~[miryoku]~. After the new commits are squashed and merged upstream into QMK master by pull request the ~miryoku~ branch is renamed and a new ~miryoku~ branch is created from QMK master. +New commits can be seen at the top of the [[https://github.com/manna-harbour/miryoku_qmk/commits/miryoku][history]] with commit messages beginning ~[miryoku]~ or ~[miryoku-github]~ -To checkout the ~miryoku~ branch in your existing QMK build environment: -#+BEGIN_SRC sh :tangle no -git remote add miryoku_qmk git@github.com:manna-harbour/miryoku_qmk.git # if using SSH -git remote add miryoku_qmk https://github.com/manna-harbour/miryoku_qmk.git # if using HTTPS -git fetch miryoku_qmk -git checkout --track miryoku_qmk/miryoku -#+END_SRC +Periodically, the ~[miryoku]~ commits are squashed and merged upstream into QMK master by pull request, the ~miryoku~ branch is renamed, and a new ~miryoku~ branch is created from QMK master. + + +**** Merge + +To use both the current versions of QMK and Miryoku QMK together, the QMK master and ~miryoku~ branches need to be merged. +The ~[miryoku-github]~ commits relate to GitHub specific functions of the Miryoku QMK repository and forks, such as workflows. Directly merging ~miryoku~ with a branch based on QMK master will lead to conflicts due to those commits. To avoid conflicts, first drop or revert all ~[miryoku-github]~ commits from ~miryoku~ before merging. + +Merging branches can be performed automatically at build time for [[#workflow-builds][workflow builds]] using the ~merge~ option, which will automatically revert all ~[miryoku-github]~ commits before merging. For local builds, see [[#checkout-update-and-merge][Checkout, Update, and Merge]] below. + +Any local changes to existing workflow files should be made independently in commits with messages starting ~[miryoku-github]~ so that they can also be automatically excluded in workflow builds. ** Building @@ -41,7 +46,52 @@ git checkout --track miryoku_qmk/miryoku First [[https://docs.qmk.fm/#/newbs_getting_started][set up the QMK build environment and build the default keymap for your keyboard]]. -Build with ~manna-harbour_miryoku~ as the keymap name. Customised defaults for [[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#alternative-layouts][alternative layout]] options can be set in [[#userspace][custom_rules.mk]]. Options can also be set or overridden at build time. +Next choose the [[#branches][branch]]. If using ~miryoku~, [[#checkout-update-and-merge][checkout, update, or merge]] as needed. + +Build with ~manna-harbour_miryoku~ as the keymap name. Personalised defaults for [[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#alternative-layouts][alternative layout]] options can be set in [[#userspace][custom_rules.mk]]. Options can also be set or overridden at build time. Build with [[#qmk][qmk]] or [[#make][make]]. + + +**** Checkout, Update, and Merge + +All of the following examples operate in your existing QMK build environment. +#+BEGIN_SRC sh :tangle no +cd qmk_firmware +#+END_SRC + +To checkout the ~miryoku~ branch from Miryoku QMK: +#+BEGIN_SRC sh :tangle no +git remote add miryoku_qmk git@github.com:manna-harbour/miryoku_qmk.git # if using SSH +git remote add miryoku_qmk https://github.com/manna-harbour/miryoku_qmk.git # if using HTTPS +git fetch miryoku_qmk +git checkout --track miryoku_qmk/miryoku +make git-submodule +#+END_SRC + +To update the ~miryoku~ branch from Miryoku QMK: +#+BEGIN_SRC sh :tangle no +git checkout miryoku +git fetch miryoku_qmk +git merge miryoku_qmk/miryoku +#+END_SRC + +If a new ~miryoku~ branch has been created in Miryoku QMK you will see ~(forced update)~ after the fetch. To rename the existing ~miryoku~ branch and create a new ~miryoku~ branch from Miryoku QMK: +#+BEGIN_SRC sh :tangle no +git checkout miryoku +git branch -m miryoku-`whoami`-`date --rfc-3339=date` +git fetch miryoku_qmk +git checkout --track miryoku_qmk/miryoku +make git-submodule +#+END_SRC + +To [[#merge][merge]] the ~miryoku~ branch with QMK master: +#+BEGIN_SRC sh :tangle no +git checkout miryoku +git checkout -b miryoku-merge-master +git revert --no-edit `git log --grep='^\[miryoku-github\]' --pretty='format:%H' | tr '\n' ' '` +git fetch origin +git merge origin/master +make git-submodule +#+END_SRC **** qmk @@ -51,7 +101,13 @@ Build with the ~qmk~ command. E.g. #+BEGIN_SRC sh :tangle no qmk compile -c -kb crkbd -km manna-harbour_miryoku # build for crkbd qmk flash -c -kb crkbd -km manna-harbour_miryoku # build for crkbd and flash -qmk compile -c -kb crkbd -km manna-harbour_miryoku -e MIRYOKU_ALPHAS=QWERTY -e MIRYOKU_NAV=INVERTEDT -e MIRYOKU_CLIPBOARD=WIN -e MIRYOKU_LAYERS=FLIP # build for crkbd with alternative layouts +qmk compile -c -kb crkbd -km manna-harbour_miryoku \ + -e MIRYOKU_ALPHAS=QWERTY \ + -e MIRYOKU_EXTRA=COLEMAKDH \ + -e MIRYOKU_TAP=QWERTY \ + -e MIRYOKU_NAV=INVERTEDT \ + -e MIRYOKU_CLIPBOARD=WIN \ + -e MIRYOKU_LAYERS=FLIP # build for crkbd with alternative layouts #+END_SRC @@ -62,7 +118,13 @@ First ~cd~ to the repository root. Then build with ~make~. E.g. #+BEGIN_SRC sh :tangle no make clean crkbd:manna-harbour_miryoku # build for crkbd make clean crkbd:manna-harbour_miryoku:flash # build for crkbd and flash -make clean crkbd:manna-harbour_miryoku MIRYOKU_ALPHAS=QWERTY MIRYOKU_NAV=INVERTEDT MIRYOKU_CLIPBOARD=WIN MIRYOKU_LAYERS=FLIP # build for crkbd with alternative layouts +make clean crkbd:manna-harbour_miryoku \ + MIRYOKU_ALPHAS=QWERTY \ + MIRYOKU_EXTRA=COLEMAKDH \ + MIRYOKU_TAP=QWERTY \ + MIRYOKU_NAV=INVERTEDT \ + MIRYOKU_CLIPBOARD=WIN \ + MIRYOKU_LAYERS=FLIP # build for crkbd with alternative layouts #+END_SRC @@ -70,13 +132,22 @@ make clean crkbd:manna-harbour_miryoku MIRYOKU_ALPHAS=QWERTY MIRYOKU_NAV=INVERTE Firmware can be built via GitHub Actions workflows without use of a local build environment. Local tools are still required for [[https://docs.qmk.fm/#/newbs_flashing][flashing]]. -First log in to GitHub, fork the [[#miryoku-qmk-development-branch][Miryoku QMK development branch]] repository, and enable workflows. +First [[#fork-or-sync][fork the Miryoku QMK repository or sync the ~miryoku~ branch]]. Then use the [[#build-examples][Build Examples]] or [[#build-inputs][Build Inputs]] workflows. To access a workflow, visit the Actions tab and select the workflow. To download the firmware from a workflow run, select the workflow, select the workflow run, select the desired Artifacts, and unzip the downloaded zip file. Workflow files are in [[../../.github/workflows]]. +**** Fork or Sync + +If you don't have a fork, first [[https://github.com/signup][create a GitHub account]], [[https://github.com/login][login to GitHub]], [[https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository][fork]] https://github.com/manna-harbour/miryoku_qmk, and visit the Actions tab and enable workflows. + +If you already have a fork, [[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork#syncing-a-fork-branch-from-the-web-ui][sync]] the ~miryoku~ branch. + +If a new ~miryoku~ branch has been created in Miryoku QMK, there will be a warning about conflicts when trying to sync. If you have local changes, first create a copy of the branch by [[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#creating-a-branch][creating a new branch]] and specifying the ~miryoku~ branch in your fork as the source, then sync the ~miryoku~ branch again. Accept the prompt to discard commits. + + **** Build Examples Copy one of the included Build Example workflow files, edit the ~name~ value, and edit and add options and values as desired. Select Run workflow, select the Branch if desired, and activate Run workflow. @@ -91,7 +162,9 @@ The ~keyboard~ option specifies the keyboard and is required. All other options The ~alphas~, ~nav~, ~clipboard~, and ~layers~ options correspond to the [[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#alternative-layouts][alternative layout]] options. The ~mapping~ option corresponds to the alternative [[#subset-mapping][mapping]] options. Alternative layout and mapping options are given in the documentation in the form ~MIRYOKU_OPTION=VALUE~. To use here, convert to the form specified above. Use ~default~ to represent the default value. Values for these five options are case-insensitive. See the [[../../.github/workflows/test-all-configs.yml][Test All Configs workflow file]] for all supported values. -The ~rules~ and ~config~ options can be used to specify values to be appended to ~custom_rules.mk~ and ~custom_config.h~, respectively. Separate multiple lines with ~\n~. +The ~rules~ and ~custom_config~ options can be used to specify values to be appended to ~custom_rules.mk~ and ~custom_config.h~, respectively. Separate multiple lines with ~\n~. + +The ~merge~ option can be used to merge branches at build time. Branches are specified in the form ~//~. E.g. QMK ~master~ and ~develop~ would be specified as ~qmk/qmk_firmware/master~ and ~qmk/qmk_firmware/develop~ respectively. Multiple space separated branches can be specified. For no merges, leave as ~default~. **** Build Inputs @@ -106,6 +179,8 @@ The ~Miryoku Alphas~, ~Miryoku Nav~, ~Miryoku Clipboard~, and ~Miryoku Layers~ o The ~custom_rules.mk~ and ~custom_config.h~ options can be used to specify values to be appended to the corresponding files. Join multiple lines with ~\n~. +The ~Merge QMK Branches~ option can be used to merge branches at build time. Branches are specified in the form ~//~. E.g. QMK ~master~ and ~develop~ would be specified as ~qmk/qmk_firmware/master~ and ~qmk/qmk_firmware/develop~ respectively. Multiple space separated branches can be specified. For no merges, leave as ~default~. + ** Subset Mapping @@ -122,13 +197,13 @@ thumb keys. - [[./rules.mk]] :: Build options. Automatically included. -- [[./custom_rules.mk]] :: Custom ~make~ options including customised defaults for alternative layout options, for local builds. Included from ~rules.mk~. +- [[./custom_rules.mk]] :: Custom ~make~ options including customised defaults for alternative layout and mapping options. Included from ~rules.mk~. - [[./post_rules.mk]] :: Handles Miryoku ~make~ options. Included from ~rules.mk~. - [[./config.h]] :: Config options. Automatically included. -- [[./custom_config.h]] :: Custom config options for local builds. Included from ~config.h~. +- [[./custom_config.h]] :: Custom config options. Included from ~config.h~. - [[./manna-harbour_miryoku.h]] :: Keymap-related definitions. Included from ~manna-harbour_miryoku.c~. Layer data is generated by [[https://github.com/manna-harbour/miryoku_babel][Miryoku Babel]] and is included from files in the [[miryoku_babel]] directory. @@ -500,6 +575,17 @@ make handwired/dactyl_manuform/4x5:manna-harbour_miryoku:flash #+END_SRC +**** handwired/dactyl_manuform/4x6 + +Only the main 5x3 alphas and the main 3 thumb keys are used. + +To build for this keyboard, + +#+BEGIN_SRC sh :tangle no +make handwired/dactyl_manuform/4x6:manna-harbour_miryoku:flash +#+END_SRC + + **** handwired/dactyl_manuform/5x6 Only the main 5x3 alphas and the main 3 thumb keys are used. @@ -542,6 +628,17 @@ make keyboardio/atreus:manna-harbour_miryoku:flash #+END_SRC +**** keyboardio/model01 + +Only the main 5x3 alphas and the inner 3 thumb keys are used. + +To build for this keyboard, + +#+BEGIN_SRC sh :tangle no +make keyboardio/model01:manna-harbour_miryoku:flash +#+END_SRC + + **** lily58 Only the main 5x3 alphas and the inner 3 thumb keys are used. @@ -588,6 +685,15 @@ make redox_w:manna-harbour_miryoku:flash #+END_SRC +**** satt/vision + +To build for this keyboard, + +#+BEGIN_SRC sh :tangle no +make satt/vision:manna-harbour_miryoku:flash +#+END_SRC + + **** sofle To build for this keyboard, @@ -647,6 +753,16 @@ Combo the primary and secondary thumb keys to emulate the tertiary thumb key. C - [[https://github.com/manna-harbour/qmk_firmware/issues/33][Retro Shift]] +*** 𝑥MK + +Use Miryoku QMK with any keyboard with [[https://github.com/manna-harbour/xmk][𝑥MK]]. + +For [[#local-builds][local builds]], merge https://github.com/manna-harbour/qmk_firmware/tree/xmk and build for keyboard ~converter/xmk~. + +For [[#workflow-builds][workflow builds]], use the Build Inputs workflow and build with keyboard ~converter/xmk~ and merge ~manna-harbour/qmk_firmware/xmk~, or use the Build Example 𝑥MK workflow. + +Also see [[https://github.com/manna-harbour/miryoku_kmonad][Miryoku KMonad]]. + ** [[https://github.com/manna-harbour][https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/logos/manna-harbour-boa-32.png]] -- cgit v1.2.3