Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document precompiled .mpy files #809

Merged
merged 3 commits into from
Aug 19, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading