A while back I created a fork of the Kaleidoscope repo blindly thinking that this would be where I did any keyboard customisation. Having returned to it to set up my build environment I realise that the changes I’m likely to want to make will be in the Model01-Firmware repo.
I was planning to fork this and replace the Model01-Firmware submodule in my Arduino-Boards repo with my forked copy.
Is this the best workflow for managing any changes that I wish to make?
I think the best way to work on your custom sketch is to first set your environment up as you would for use with the factory firmware. That is, follow the steps in the Model01-Firmware README. Then, fork that repo, and work from there. That’s about it. As Model01-Firmware is not a submodule of Arduino-Boards, you don’t need to replace it, either.
Once Kaleidoscope and supporting libraries are installed (in other words, Arduino-Boards is checked out into the right place), the Arduino tools, and the Kaleidoscope build system will find them, and you can have your sketch pretty much anywhere, independent from the rest.
If you wish to change any of the plugins, the best way for that is closer to what you described: fork the repo, but instead of replacing the submodule, I’d add a git remote instead. This way you can pull both upstream changes, and push your own, and don’t need to fiddle with keeping the parent Arduino-Boards repository synced, either.
I’ve been doing all my development for the past year or so this way, and it’s been working remarkably well. 
Thanks, makes perfect sense now.
That changed this week. It is, now.
The reason to do that is so that the Mode01-Firmware default sketch will show up as an example when you set things up with the Arduino Boards Manager.
You should never need to replace our version of the Model01-Firmware library in Arduino-Boards/libraries. It’s the only library for which that should be 100% true, since it doesn’t provide any library code, just the example sketch. (Well, it also has a Makefile. You might want that.)
Generally, I’d expect folks to either create their own repo for their own sketch OR to fork the Model01-Firmware repo. But you can just put that somewhere on disk you can get to. You don’t need to replace the copy in Arduino-Boards.
Also, IIRC, if you want to work with a variant of one of the core Kaleidoscope libraries, you’d just check out your version in the ‘libraries’ subdirectory of your Arduino sketchbook.
Aha, that was super not obvious to me. I followed the instructions in the Model01-Firmware readme and assumed that editing libraries in hardware/keyboardio/avr/libraries/Whatever would immediately take effect when I run make flash but it doesn’t seem to. I don’t really get what the model is here but I guess I need to make another submodule inside Model01-Firmware/libraries?
Nope, that doesn’t seem to work either. How do I get my changes to a plugin to take effect?
To be specific, running make flash in ~/Documents/Arduino/Model01-Firmware doesn’t seem to notice changes (eg, syntax errors) in ~/Documents/Arduino/hardware/keyboardio/avr/libraries/Kaleidoscope-LED-ActiveModColor.
Aha. Reading the Model01-Firmware Makefile, looks like it’s noticing that for a hot second I was using the Arduino.app’s “download some libraries” feature. Now I just have to figure out how to safely uninstall them…
Ah. Uninstalling through the board manager.
Thanks for sorting this out and adding a note to the readme! documenting use of third party plugins and code changes is a little ways down my list for the main docs repo, so it’s super useful to have some signposts out there for adventurous folks!
No problem! And thanks to you Jennifer for all your work on docs — it made a huge difference in my first day figuring out how to use my exciting new keyboard.
I believe that libraries installed inside libraries/ in the sketch directory should override libraries installed in Arduino/libraries
and libraries installed in Arduino/libraries should override libraries in the “hardware” directory.
But this is something that is buried in Arduino’s tooling and is non-obvious.
I would really, desperately, like to have a way for a user to customize a single library without having to uninstall the boards-manager version of our hardware definitions.
From my glance at it, at least on the mac, if it finds multiple copies of a library it takes the first one in $PATH, so talking folks through changing that should be doable on *nix. No idea for pc’s.
It also gives a compile time message to let the user know it found more than one.
I think I’m going to modify the docs to have folks compile (use the checkmark button in the IDE) prior to installing (the arrow button) to separate compile time issues from downloading issues. This will make compiler warnings more visible in the miniscule by default status window of the IDE.
It’s not that simple. God I wish it were. I don’t yet understand it well enough to explain it.
huh. interesting. I wish I could easily duplicate the system state I was in at the time, but I’ve ripped out and reinstalled so many times at this point I have no idea where I was when I saw that. What I know for certain was that I saw the compile time warning and it appeared to be possible to choose the other instance.
There are a couple different levels of searching. Or at least there are supposed to be.
Thanks for sorting this out. It’s on my mental to do list, but it’s enough steps down the ladder that I haven’t put any cycles on it. It will be great to have the process sketched out when I go to write user friendly docs.
One thing I noticed last week was that the Arduino code is not the latest. I specifically noticed that the “backslash-less” commit wasn’t present in the .ino. Not sure if you’ve updated since then, and I’m happy to know nothing about the process of registering things with Arduino, but if you’re poking at it anyway it might be worth pushing that change. reduces typo potential.
We’re being a little bit conservative about those pushes, because regressions will break things for a lot of folks, but point taken.
My goal was to push an update fixing some numpad issues before doing that next build
I wholeheartedly support keeping that as stable as possible!