search

keyboardio / Kaleidoscope

Firmware for Keyboardio keyboards and other keyboards with AVR or ARM MCUs.
http://keyboard.io
GNU General Public License v3.0
756 stars 259 forks source link

need documentation for installing third party plugins #235

Open aspiers opened 7 years ago

aspiers commented 7 years ago

As @Jennigma already observed, it would be really helpful to have a document guiding users on how to install third party plugins.

@cdisselkoen already wrote step-by-step installation instructions for MacrosOnTheFly in its README, and IMHO it would be worth extracting this info into a new wiki page so that it can be pointed to from any third party plugin and co-maintained by the whole community.

One thing I've observed from installing the awesome new DigitalRain plugin is that while it compiles fine from the Arduino IDE, if I try to compile from the CLI via make, I get:

BOARD_HARDWARE_PATH="/home/adam/.arduino15/packages/keyboardio/hardware/avr/1.19.0" /home/adam/.arduino15/packages/keyboardio/hardware/avr/1.19.0/libraries/Kaleidoscope/bin//kaleidoscope-builder build-all
Building output/Model01-Firmware/Model01-Firmware (0.0.0-gv1.13-81-ge197-dirty) ...                           
/home/adam/software/hardware/Arduino/Model01-Firmware/Model01-Firmware.ino:38:48: fatal error: Kaleidoscope-LEDEffect-DigitalRain.h: No such file or directory
 #include "Kaleidoscope-LEDEffect-DigitalRain.h"
                                                ^
compilation terminated.
exit status 1                                                                                                 
/home/adam/.arduino15/packages/keyboardio/hardware/avr/1.19.0/build-tools/makefiles//rules.mk:75: recipe for target 'build-all' failed
make: *** [build-all] Error 1

If that's expected behaviour then it would be worth documenting in the guide I'm suggesting ... or even better, documenting how to get it successfully compiling from the CLI too.

tremby commented 7 years ago

The plugin compiles fine with the makefile for me. I haven't used the IDE. So I'm not sure what might be going on there.

algernon commented 7 years ago

Whether the CLI works or not, depends largely on where you check out third-party libraries to.

cdisselkoen commented 7 years ago

My instructions explicitly help users find the right directory, so that the makefile should work. If not, sounds like a separate issue to file against Kaleidoscope and/or MacrosOnTheFly.

algernon commented 5 years ago

There are two major ways to install a third party plugin: into the standard Arduino library path, in which case it should Just Work (but one needs to figure out where the arduino libraries are); or into a custom location and augmenting kaleidoscope-builder. Both should be documented.

For the kaleidoscope-builder way, setting EXTRA_BUILDER_ARGS in .kaleidoscope-builder.conf will do the trick, as can be seen here.

gedankenexperimenter commented 5 years ago

I've always just put third-party plugins as subdirectories of the sketch, which works without any .kaleidoscope-builder.conf modifications.

noseglasses commented 5 years ago

And I am used to putting 3rd party plugins in the bundle's avr/library directory, which also does not require any modifications to .kaleidoscope-builder.conf.

noseglasses commented 5 years ago

My normal routine when working on a Kaleidoscope feature or plugin is the following (Linux):

1) generate and cd to a directory .../<name of feature>/hardware 2) recursively clone the bundle to .../<name of feature>/hardware/keyboardio 3) clone any additional 3rd party plugins to .../<name of feature>/hardware/keyboardio/avr/libraries 4) cd to .../<name of feature>/hardware/keyboardio/avr/libraries/Model01-Firmware 5) optionally check out a special firmware from a forked Model01-Firmware repo or copy a firmware there 6) enter make flash to build and flash the firmware

This approach is nice because I can use as many independent firmware builds. And they can easily be removed afterwards.