Awesome
fak-config
FAK user configuration repository.
Features
- QMK-like folder structure with
keyboards
andkeymaps
- All-in-one
fak
command for flashing, compiling, etc. - The latest release is automatically updated every push with ready-to-flash firmware for all your keyboards and keymaps
- Ready-to-use dev container for easy remote development via GitHub Codespaces or VS Code
- Globally shared Nickel files in
shared/lib
for code reuse across keyboards and keymaps
Setup
GitHub Codespace
The quickest and easiest way to get started is using GitHub Codespaces. You don't have to go through the trouble of setting up the development environment. Everything is remote, comes preloaded, and it just works.
- Fork this repo
- Create a new codespace
- Wait for the environment to be loaded in the terminal until you can enter commands
The only thing that won't work from a remote setup is, of course, flashing. You'll have to do that locally with wchisp
. Thankfully, wchisp
provides prebuilt binaries so getting that set up on your local machine is very easy.
- In your codespace,
fak compile -kb [keyboard] -km [keymap]
. It will print the path(s) where it put the firmware. - Download the
.ihx
file(s) located in the printed path(s). - In your local machine,
wchisp flash [keyboard].[keymap].central.ihx
. - And then if you have a split,
wchisp flash [keyboard].[keymap].peripheral.ihx
.
Alternatively, you can push your changes, wait a bit, then you will find all ready-to-flash .ihx
files in the latest release. From there, download the ones you need, then flash with wchisp
.
If, for whatever reason, you're getting fak: command not found
, enter nix develop
then you should be back up.
Nix
If you have Nix installed on your system, a Nix flake is provided.
- Fork and clone this repo
nix develop
(or if you havedirenv
, justdirenv allow
)
Manual setup
Requirements:
With manual setup, the fak
command isn't included. Use python fak.py
in place of fak
(e.g., fak clean
becomes python fak.py clean
). Alternatively, you may make a shell alias for fak
if you wish.
Commands
Now that you have your development environment set up and ready, compiling is as easy as fak compile -kb [keyboard] -km [keymap]
. You may omit -km [keymap]
if keymap is "default" (e.g., fak compile -kb [keyboard]
). This will also print the path(s) where it put the firmware files in, which is helpful in a remote setup.
If you're using a local setup, you can flash directly with fak flash -kb [keyboard] -km [keymap]
. Then if you have a split, flash the peripheral side with fak flash_p -kb [keyboard] -km [keymap]
. Likewise, you may omit -km [keymap]
if keymap is "default".
If something's off, wrong, or not working, cleaning your build files might help with fak clean
.
To compile every keyboard with its every keymap, enter fak compile_all
. Whenever you push, this is what GitHub Actions actually does behind the scenes to update the latest release with all ready-to-flash .ihx
files.
Included Nickel paths
All Nickel files are evaluated with two include paths:
ncl
directory infak
. This makesimport "fak/somefile.ncl"
possible.shared
directory in this repo. This makesimport "lib/somefile.ncl"
possible.
We do this so you don't have to do something like import ../../../subprojects/fak/ncl/fak/somefile.ncl
. Yeah. Horrible.
Migrating from FAK forks
If you're one of the OGs who use FAK before user config repos existed and you want to migrate:
- Fork and clone this repo.
- Copy over your keyboards and keymaps in
keyboards
while respecting the file structure. - Replace all those (horrible) relative
fak
imports withimport "fak/somefile.ncl"
.
Switching versions
- (Optional) To use a different FAK repo, like your own fork, change the
url
insubprojects/fak.wrap
. - To use a different version, change the
revision
insubprojects/fak.wrap
. This can be a commit hash (recommended) or a tag. fak update
.
⚠️ This affects all your keyboards and keymaps, so if there's a breaking change in the version and/or repo you're switching to, you'll have to fix that in all your Nickel files.