Terminology (plugin, module, project, etc.)

@algernon recently wrote about [Managing core and contributed Kaleidoscope plugins](his progress) on categorizing parts of the firmware.

It seems he is currently working on a grouping/categorization/modularization/git-submodulification of the existing parts of the firmware.

When I read his ideas about categories and the list of projects, it occurred to me that some of these projects, core and third party modules are not plugins in a strict sense.

Up to now everybody uses the term plugin typically when refering to a part of the firmware that is living in its own git repo. Mostly the names of such projects start with Kaleidoscope- .

The term plugin is commonly used for a piece of software that serves as a module for an existing software and inter-operates with it via a well defined API. Mostly this also requires the module to be run-time loadable (plug and unplug). The latter is not the case for the firmware as it is a monolith. So what we commonly call firmware plugins are, in my opinion, not plugins in a strict sense.

There are some projects - I use the term projects here for everything that lives in its own git repo - that do not provide firmware parts, or do not use the plugin-API or only provide headers (Kaleidoscope-Ranges) or do provide code that only interacts with the firmware (e.g. Kaleidoscope-Hardware-Virtual), but are not actually part of the (device-) firmware.

We should consider using more distinctive terms for those different types of projects, e.g.

  • plugin for everything that is linked into the firmware and uses the plugin-API.
  • module for everything that is linked into the firmware (including plugins).
  • project (or maybe a better suited term) for everything that is related to the firmware (including modules), but not necessarily compiled code.

What do you think?

2 Likes

I completely agree that terminology has been fuzzy, and Iā€™d like to see us decide on clearer definitions for terms that we use. I also like the idea of increasing the vocabulary to provide clear distinctions between things. Your definitions of ā€œmoduleā€ and ā€œpluginā€ are great, though ā€œprojectā€ is not one that I like much (I think ā€œprojectā€ is better for a description of the work that is done to make something, rather than the thing that is made). If I think of a better alternative, Iā€™ll let you know.

I also think it would be nice to have a term (or maybe two) for modules that are not plugins, so I can say ā€œKaleidoscope-Foo isnā€™t a plugin, itā€™s a wug.ā€ But Iā€™m also drawing a blank coming up with an idea for that termā€¦

1 Like

How about package as an alternative to project?

And component for a non-plugin module? Or maybe component becomes the general term (also covering plugins) and module becomes the specific term for the non-plugin thingy.

OTOH, wug sounds cromulent to me.

edited for clarity

2 Likes

Fair enough! Letā€™s call it wugā€¦ or ā€¦ maybe wugin?

3 Likes

For anyone unfamiliar, ā€œwugā€ is a famous nonce word from developmental psychology & cognitive science, used in the ā€œwug testā€ where a novel object is given to a very young test subject, who is told that the object is a ā€œwugā€, to see if they use the pluralization rule properly.

That word stole Jean Berko Gleasson from Barry Kripke!

1 Like

I agree that we should have a standard vocabulary. And Iā€™ve let everyone down by not having a written glossary from the get-go. This should include not just the names of chunks of code, but also of objects inside the system. (key, keyswitch, layer, layout, keymap, etc)

In my head:

  • Library or Arduino Library
    Some chunk of code packaged according to the Arduino Library definition. This includes every Kaleidoscope Plugin, as well as Kaleidoscope itself. Not every Library is a Plugin. This is a term already used in the Arduino ecosystem.
  • Plugin or Kaleidoscope Plugin
    An Arduino library that is designed to use the Kaleidoscope Plugin API. Every Plugin is a Library, but not vice-versa. It may be the case that Plugins use or wrap Libraries.
  • Hardware Definition or Hardware Plugin orā€¦I donā€™t have a good name for this
    An implementation of the Kaleidoscope Hardware API that lets Kaleidoscope talk to a specific keyboard or other device. This is an Arduino Library, but not really a Kaleidoscope Plugin, since it doesnā€™t use the plugin hooks.
  • Sketch
    This is the Arduino term for the main program someone runs on their keyboard. Itā€™s not the term Iā€™d pick if I were starting from scratch, but itā€™s widely used in the ecosystem, so I think weā€™re stuck with it.
  • Core
    This is the low-level implementation of the Arduino APIs for a given microcontroller implementation. Every Hardware Plugin runs on top of a core, but some may share the same core.

Iā€™m not a fan of ā€˜moduleā€™ or ā€˜projectā€™ for things that have official definitions. As I understand it, ā€˜modulesā€™ are a newish c++ core feature. And projects are things that people work on. Kaleidoscope is a project, each plugin is a project. Sometimes a personal firmware sketch is a project.

For naming things people build for Kaleidoscope that donā€™t use the Plugin API or the Hardware Plugin APIā€¦Iā€™m not sure yet. Happy to entertain suggestions. While ā€˜wugā€™ is a cromulent word, itā€™s probably not the right one here :wink:

Does that make sense?

2 Likes

8 posts were merged into an existing topic: Kaleidoscope-CMake

(A number of posts that are more related to Kaleidoscope-CMake were moved here. There is some overlap with terminology, but the bulk of it is off-topic in this thread.)