Skip to content

Commit

Permalink
Document precompiled .mpy files (#809)
Browse files Browse the repository at this point in the history
* Document precompiled .mpy files

---------

Co-authored-by: xs5871 <xs5871@qn-4.net>
  • Loading branch information
rrotter and xs5871 committed Oct 16, 2023
1 parent 5675a2e commit 69ad569
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 3 deletions.
23 changes: 23 additions & 0 deletions docs/en/Getting_Started.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,29 @@ Want to have fun features such as RGB, split keyboards and more? Check out what
You can also get ideas from the various [user examples](https://github.com/KMKfw/kmk_firmware/tree/master/user_keymaps) that we provide and dig into our [documentation](README.md).


### Pre-compiling KMK for faster boot times or microcontrollers with limited flash

There are two options:
1. To compile KMK yourself you'll need to download and install the [compatible mpy-cross](https://adafruit-circuit-python.s3.amazonaws.com/index.html?prefix=bin/mpy-cross/)
for your Operating System. Don't forget to add it to your PATH, test by running `mpy-cross` from a shell (Powershell, Bash, Fish, etc). Once that's set up, run either `make compile` (if you have `make`) or `python util/compile.py`to generate the `.mpy` versions of KMK files. Then copy the whole compiled `kmk/` directory to your keyboard.

There are even more compile and copy make targets.
Poweruser can compile KMK and additional libs, and then load the bytecode and keyboard code
onto a keyboard in one go:
```sh
make compile copy-compiled copy-board MPY_SOURCES='kmk/ lib/' BOARD='boards/someboard' MOUNTPOINT='/media/user/someboard'
```

2. To download a pre-compiled KMK go to [Actions > Build on the KMK GitHub project page](https://github.com/KMKfw/kmk_firmware/actions/workflows/compile.yml),
click on the latest build, and you'll find the download link at the bottom of the page under Artifacts. Unzip the download and place the contents in the `kmk/` directory on your keyboard.


On certain microcontrollers that will still not be enough of a size reduction to
fit all of KMK onto the flash (nice!nano for example).
You can remove any optional parts of KMK you aren't using.
Start by skipping `kmk/extensions`, `kmk/modules`, and `kmk/quickpin` and adding in only the files under those paths used in your keyboard (i.e. files that are imported in your `main.py` or `kb.py`).


## Additional help and support
> Roads? Where we're going we don't need roads.
Expand Down
5 changes: 2 additions & 3 deletions docs/en/Officially_Supported_Microcontrollers.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,8 @@ Downsides
- $25 USD per microcontroller at most retailers
- Not enough space to run KMK without compiling

### Pre-compiling KMK for nice!nano
As the nice!nano has limited flash memory you'll need to compile KMK. To do that you'll need to download and install the [compatible mpy-cross](https://adafruit-circuit-python.s3.amazonaws.com/index.html?prefix=bin/mpy-cross/) for your Operating System. Don't forget to add it to your PATH, test by running `mpy-cross` from a shell (Powershell, Bash, Fish, etc). Once that's set up, run either `make compile` (if you have `make`) or `python util/compile.py`to generate the `.mpy` versions of KMK files. Then copy the whole compiled `kmk/` directory to your keyboard.

### Pre-compiling KMK for nice!nano (or any other microcontroller with limited flash)
As the nice!nano has limited flash memory you'll need to use a [compiled KMK](Getting_Started.md#pre-compiling-kmk-for-faster-boot-times-or-microcontrollers-with-limited-flash).

Common Retailers
- [Boardsource](https://boardsource.xyz/store/5f4a1733bbaa5c635b83ed67)
Expand Down

0 comments on commit 69ad569

Please sign in to comment.