feat(docs): Added a page on module creation #2456
Conversation
Nick-Munnich
force-pushed
the
module-creation
branch
from
c7c0df8 to
d61d8e7
Compare
There was a problem hiding this comment.
I think it is worth considering dropping the vfx category from the initial version, since it seems unclear to me how they'd be implemented right now (let me know if I am missing something).
Looks good to me as a document overall and I agree with the implementation guidelines in general. There are some of the more subjective statements which I didn't review, like the first sentence.
That being said, will this wait until some sort of ZMK versioning is in place?
There was a problem hiding this comment.
There are some of the more subjective statements which I didn't review, like the first sentence.
Would be good to have a bit of discussion on those I think.
That being said, will this wait until some sort of ZMK versioning is in place?
The collection repo yes, but enough people seem to already be using the preview as a reference that I think it'd be worthwhile pushing through a trimmed down version of the page prior to versioning.
|
Something to ponder about: do you want to enforce a namespacing convention for headers? E.g., should modules be allowed to add new headers to For reference, zephyr does enforce namespacing of all headers:
|
Good point, thanks for raising it. I'd be on the side of following the Zephyr convention, personally. |
Nick-Munnich
force-pushed
the
module-creation
branch
3 times, most recently
from
68ea422 to
aadf93c
Compare
Co-authored-by: Cem Aksoylar <[email protected]>
Nick-Munnich
force-pushed
the
module-creation
branch
from
aadf93c to
2714b09
Compare
There was a problem hiding this comment.
I think this is good overall, but I feel the reader will wonder how to write the contents of the files mentioned and what they do in general. To some degree it is normal, we can't explain how to develop any feature for ZMK here. Do you think there are any resources we can link to? e.g. we can cross-link between new shield and behavior guides, especially if we module-ify the latter like suggested in #2511. Maybe Zephyr has a nice page that I haven't ever found? 😆
It might also be good to drop a link to https://docs.zephyrproject.org/3.5.0/develop/modules.html near the beginning.
| - Modules containing one or more keyboard-related definitions (boards, shields, interconnects, etc.) | ||
| - Modules containing behaviors & features | ||
| - Modules containing drivers | ||
| - Modules containing visual effects |
There was a problem hiding this comment.
I am still not a big fan of this classification, maybe we can say
| - Modules containing visual effects | |
| - Modules containing other features, such as visual effects |
|
|
||
| For each of these, you can use the singular or plural, i.e. `keyboard` and `keyboards` are both acceptable. Use your judgement to decide between the two. | ||
|
|
||
| `<description>` is your choice of name to describe the module. See the names of other modules of your chosen type in the `zmk-modules` repository for examples. |
There was a problem hiding this comment.
I think this repo will not be present if we merge this first, right?
| name: <your module name> | ||
| ``` | ||
|
|
||
| #### Build Options |
There was a problem hiding this comment.
| #### Build Options | |
| #### Build options |
Re-cased according to our internal convention
|
|
||
| - The `depends` child property is used to specify a list of modules which the module depends on. The dependencies are referred to by their [module name](#module-name). | ||
| - The `cmake` child property is used to identify a folder containing a `CMakeLists.txt` used to build the module. | ||
| - The `kconfig` child property is used to identify the `Kconfig` used to build the module. |
There was a problem hiding this comment.
| - The `kconfig` child property is used to identify the `Kconfig` used to build the module. | |
| - The `kconfig` child property is used to identify the `Kconfig` file that defines configuration settings used by the module. |
| Next, you need to define the options to build your module. These also go into `zephyr/module.yml`, as children of the `build` property. Commonly used options are: | ||
|
|
||
| - The `depends` child property is used to specify a list of modules which the module depends on. The dependencies are referred to by their [module name](#module-name). | ||
| - The `cmake` child property is used to identify a folder containing a `CMakeLists.txt` used to build the module. |
There was a problem hiding this comment.
| - The `cmake` child property is used to identify a folder containing a `CMakeLists.txt` used to build the module. | |
| - The `cmake` child property is used to identify a folder containing a `CMakeLists.txt` file that lists the CMake commands used to build source files. |
| - `settings` is a child property containing additional child properties, two of which are particularly relevant: | ||
| - `board_root` points to the parent directory of a `boards` directory, which contains additional board/shield definitions. | ||
| - `dts_root` points to the parent directory of a `dts` directory, which contains additional devicetree bindings. | ||
| - `snippet_root` points to the parent directory of a `snippets` directory, which contains [snippets](https://docs.zephyrproject.org/latest/build/snippets/index.html). |
There was a problem hiding this comment.
| - `snippet_root` points to the parent directory of a `snippets` directory, which contains [snippets](https://docs.zephyrproject.org/latest/build/snippets/index.html). | |
| - `snippet_root` points to the parent directory of a `snippets` directory, which contains [snippets](https://docs.zephyrproject.org/3.5.0/build/snippets/index.html). |
|
|
||
| ### Informational Files | ||
|
|
||
| Make sure to include a `README.md` file and a `LICENSE` file in your repository. Only modules with MIT-compatible licenses can be added to `zmk-modules`. |
There was a problem hiding this comment.
Here also, do we want to remove this remark in the short term?
|
|
||
| Note that the `include` and `src` folders are not mandated by the module system, and all of these can be positioned anywhere in your module's filetree if you adjust the `zephyr/module.yml` accordingly. The `west.yml` file is not commonly present in any of the types. | ||
|
|
||
| Modules should expose all provided header files with an include pathname beginning with the module-name. |
There was a problem hiding this comment.
| Modules should expose all provided header files with an include pathname beginning with the module-name. | |
| Modules should expose all provided header files with an include path name beginning with the module-name, for example at `include/zmk_<type>_<description>/<header>.h`. |
Replaced hyphens with underscores to fit C conventions.
Added a page on module creation, much nicer this time.
This page makes use of another repository,
zmk-module-template, which we should fork into the project if this approach is approved.This page also makes reference to a second repository,zmk-modules. Work regardingzmk-modulesis still in progress, but it is there to read and provide feedback on. If this is merged beforezmk-modulesis ready, then I suggest we comment out the parts onzmk-modulesfor the time being.