Community module support

[drashna]

Since community modules have landed in master, how long until all of these features get turned into modules ;)

For more information:

• https://docs.qmk.fm/features/community_modules

For examples:

• https://github.com/tzarc/qmk_modules
• https://github.com/drashna/qmk_modules

For active PR of new module:

• Add Super Alt-Tab macro example as module qmk/qmk_firmware#24970

[getreuer]

Yes, great to see Community Modules made it in for the Q1 release! Thanks for the Super Alt-Tab example, that's a nice one.

I've started work on porting this repo's features to modules. I have successfully drafted a couple as modules so far. For the most part, the Community Modules framework is straightforward to develop for. For users, Community Modules look great for reducing the friction of adding custom features to a keymap.

Before fully switching to modules, I am thinking about two things:

1. Community Modules are easier to use. However, I don't think most users use QMK external userspace or understand git submodules, so this may make the existing documentation intimidating to follow. (To be fair, the pre-modules process of coping C source files and editing rules.mk may be even more intimidating.) I've started an attempt at writing a user-friendly guide to modules. I'll submit a PR to bring this back to the docs once I have thought it through better.

2. Some users are on QMK forks that haven't yet merged Community Modules. I'm considering a transitional period of maintaining both "module" and "non-module" versions of a feature. Longer term, modules are clearly the right approach, and I'd like to eventually switch to modules only.

Random implementation question: Do you know, in qmk_module.json, is there a way to indicate that the module relies on one-shots being enabled? I haven't understood how exactly do the names in "features" correspond to C #defines and build options.

[drashna]

That's fair. I'm definitely an "early adopter" type here.

Do you know, in qmk_module.json, is there a way to indicate that the module relies on one-shots being enabled? I haven't understood how exactly do the names in "features" correspond to C #defines and build options.

I don't think there is any way to do that, other than maybe adding OPT_DEFS += -UNO_ACTION_ONESHOT to a post_rules.mk to ensure that it's not defined.

As for the features, it's the same as in the keyboard.json. Which is to say *_ENABLE = yes in makefile stuff (eg, OLED_ENABLE being oled in features. So for MOUSE_ENABLE = yes and CONSOLE_ENABLE = yes, you'd want:

    "features": {
        "console": true,
        "mouse": true
    }

[getreuer]

@drashna thanks for clearing that up. Also I appreciate the links you shared for your modules and @tzarc's modules. It's been helpful to look at some real, larger examples.

I converted my features to community modules in https://github.com/getreuer/qmk-modules. Overall, it's been great, modules are easy to develop and convenient to use.

Module	Description
Achordion	Customize the tap-hold decision.
Custom Shift Keys	Customize what keycode is produced when shifted.
Keycode String	Format QMK keycodes as human-readable strings.
Mouse Turbo Click	Click the mouse rapidly.
Orbital Mouse	A polar approach to mouse key control.
PaletteFx	Palette-based animated RGB matrix lighting effects.
Select Word	Convenient word and line selection.
Sentence Case	Automatically capitalize sentences.
SOCD Cleaner	SOCD filtering for fast gaming inputs.

I made getreuer/qmk-modules a git submodule of this repo, under modules/getreuer/. That works, but maybe I'm over-complicating things. Is there a better way to share a keymap + modules?

It would be great discuss the future of the modules framework and consider how it could be improved. Is there an active discussion thread somewhere? If not, I'm happy to open an issue in qmk/qmk_firmware and kick it off with some thoughts.

[tzarc]

Almost all discussion thus far has taken place on Discord.

That submodule setup is what I'm using for my own modules, kinda up to the user to figure out if they want anything more complex.

I'll also point out that in a couple of places you're doing things like #include "modules/getreuer/....." -- this shouldn't be necessary as each module should be placed on the search path. Seems I've forgotten to add that, so I'll make a PR to rectify it.

EDIT: $(VPATH) should already include the module, and should already be set up as include paths. Modules were specifically set up to be path-agnostic so that people could drop in, say, just socd_cleaner at modules root and it'd still work.

[getreuer]

Yes, that's right, #includes do work without qualifying the paths. This is both good and bad. It's good for the flexibility in where the module is placed. It's bad if there are multiple headers in the path of the same name, in which case the compiler selects the header that came first in its search path (IIUC), potentially including a different header than the one intended and producing confusing build errors.

I ran into this header name collision problem in my repo. Transitionally, I will provide both module and non-module implementations of the features (since e.g. the vial-qmk repo hasn't yet merged Community Module support). So in my repo, each header is duplicated between features/<name>.h and modules/getreuer/<name>/<name>.h.

While my repo's situation may be unusual, another situation where there may be headers name collision is when multiple users define modules of the same name. This seems likely to occur, since modules are easy to share, fork, and modify (which is otherwise a great thing). I see you and @drashna have converted several of my features modules there—that's very cool! =) This does mean though there could be problems if a user installs all three of our module repos:

<QMK_FIRMWARE or QMK_USERSPACE>
└── modules
    ├── drashna
    │   ├── custom_shift_keys
    │   │   └── custom_shift_keys.h
    │   └── ...
    ├── getreuer
    │   ├── custom_shift_keys
    │   │   └── custom_shift_keys.h
    │   ├── socd_cleaner
    │   │   └── socd_cleaner.h
    │   └── ...
    └── tzarc
        ├── socd_cleaner
        │   └── socd_cleaner.h
        └── ...

Considering this, it seems desirable that a module qualifies its include paths to encapsulate itself from whatever else the user might have installed in the searched paths. I'm open to other opinions.

[tzarc]

I’d argue the pathing is largely irrelevant; the module paths are only added to the build if and only if the keymap.json enables it. The issue described would only arise if someone were to enable both identically named modules at the same time… which you’d hope is obviously “wrong” from a user perspective.

Ultimately it’s code under your control; if you want to keep them that way it’s your choice. Others will either complain, or fork and modify, if installed to a different location.

[getreuer]

Ah, thanks for point out that only enabled modules are added to the search path! That's sophisticated. This solves the collision problem, like you say.

You've done awesome work making the modules framework. It works very well, especially considering this is just the initial release, and not to mention the limitations of the C language. It's amazing how well it works out.