Added tutorial for writing C module

[romanchyla]

Following discussion in #1017, I'd like to submit the tutorial on how to write a C module for Lua. I was not sure where to place it in the navigation tree (and didn't want to make big changes)

ie: i didn't find how to do this:

- Building the firmware: 'en/build.md'
     - Writing C module: 'en/build/cmodule.md'

mkdocs allows (only?) this variant, which is ugly

- Building the firmware: 
     - 'Building the firmware': 'en/build.md'
     - Writing C module: 'en/build/cmodule.md'

[romanchyla]

If you tell me which is the essential information, I'll happily include it - the fact is, besides the sources I've listed, I didn't find better source (besides the source code). So, please add your comments, links and resources, and I'll incorporate them - or use this to bootstrap your edits :)

[TerryE]

I think that we are folding a couple of usecases and I feel that there are valid reasons why we should treat them as distinct.

• The first is the situation where an application developer wants some computationally intensive or time critical processing that merits being implemented in C and so needs to add a private library extension to her or his own firmware build.
• The second is where the extension is proposed as a standard addition to the core distribution.

In the fist case the developer is quite free to do whatever is needed. If the implementation works in their application, great. Here a simple guide might be useful. The second is quite different in that the bar is higher, as any flaws or inefficiencies will impact a large number of developers and we have some support responsibility; also to minimise an future support issues, it also makes sense that we try to standardise on a consistent programming style, etc..

[romanchyla]

I've always had the first case in mind (a developer writing his own private extension). At first, I didn't even include the link in the navigation - however, the mkdocs will not generate the documentation if the page is not included in the mkdocs.yml. So I was forced to do that.

But even for this use case, a documentation is extremely important - experts often can't imagine the difficulties newcomers face. And this tutorial, even though not all-encompassing, shows how to write a C module, which sections of the PIL to read and how to use that C extension from a lua module. It is a step in the right direction will get the ball rolling and should be made available. I'm happy to improve it further, incorporate comments etc.

So, a question: if I update the text and make it very clear that this is for 'private extensions' (and we find a better, less official way of including this text somewhere in docs) will that be 'good enough'?

[TerryE]

@romanchyla @DesperateProgrammer @pjsg, I've been thinking about this and I have a suggestion. You may have read my Unofficial FAQ. This getting a bit long and rambling and needs updating, but it is also currently aimed at the Lua applications programmer, rather than a programmer who wishes to develop a C module. As Roman proposes we could really use a set of articles which provide a deeper level of detail than the current FAQ for this second category.

My own view is that the current Github PR / 3rd party approval mechanism is great for controlled publishing of new content, but it is inflexible and a pain for working collaboration on new draft content. My suggestion is that we use a shared wiki to work on a working copy of this module developer FAQ, and from time to time snap an agreed version into this repo.

Does anyone think that this is a workable idea?

[romanchyla]

I think the wiki needs a dedicated person who would take care of keeping it organized, it is actually a hard work [it might depend on the wiki, but still...and the mkdocs]. There is too many projects out there with good intentions and terrible [outdated] wikis....

A workable solution that has both features (ie flexibility and control) could be a separate git repo and 'git submodule'. Before you raise your voice in protest, hear me out: git submodule is similar to symbolic link in linux (or SVN reference), the repository can point to a specific commit in another repository. Master can point to a specific commit. And from time to time, the link would be changed to a different commit [that is what Terry calls the 'snap' of the wiki]

That is less work for everyone. From the perspective of nodemcu-firmware nothing would change (git fetch, mkdocs serve). The latest version of the wiki would be browsable [by virtue of it being a Github repo]. And from the perspective of committers to the docu-wiki, it has all the nice features of version control (but follows faster PR policy).

But I think somebody would have to play with the mkdocs - it doesn't allow for generation of nested sections. And so it forces one to make weird hoops. [I can do that, if there was a consensus]

[TerryE]

I was thinking of the wiki as a temporary collaboration tool, but a lightweight git repo will be workable. Setting up mkdocs in my dev VM was trivial: a couple of bash lines and an extra NAT mapping. The master repo for project docs is this repo. We have no guarantee that if you, say, host the submodule that you don't subsequently delete it. So 👎 to using submodules for this usecase; IMO, the working version should be regarded as an ephemeral shared repo with the working contributors to the document having direct commit access, and even that is a tedious overhead IMO.

To be clear I am talking about a rapid drafting cycle with the aim of establishing consensus versions to snap into this repo by the normal project PR practice.

[romanchyla]

I tried to say that it should be nodemcu repository (ie: nodemcu/nodemcu-wiki) - then you have all the guarantees/control - and can give merge permissions to users who would not be able to commit into the master nodemcu

afaik, the github wiki is very good tool for edits - the power is in the simplicity [people don't have to make PR's, they can edit directly - yet their edits can be reviewed/reverted/vetted]

try to reconsider it in the light of this new information, but sure if there is somebody who wants to go ahead and maintain the wiki (and the markdown, plus resulting mkdocs generated content), I'll contribute with edits :)

add: mkdocs - convincing it to generate nested navigation is not so trivial (but I gave it only few minutes, I could be wrong)

[TerryE]

@marcelstoer Marcel, comments?

[marcelstoer]

So, finally...my 2 cents.

• 👍 on the proposal to add a page about how to write a C module.
• It should IMO be placed before all the modules in mkdocs.yml.
• Yes Terry, I agree it's important to distinguish the two use cases. At the top/end of this page it should be clearly stated what the intent and audience for the presented content is. It should also link to your new FAQ pages and to CONTRIBUTING.md.
• 👍 on collaborating on the content in a temporary wiki page in here. A very light-weight and pragmatic approach might also have been to use Google Docs but wiki is definitely the way to go.

Shall we close this PR and @romanchyla creates a now one when everything has been sorted out or shall it stay open (my preference) until the changes are committed to the existing branch and force pushed?

[TerryE]

I also vote for closing this PR, but my only perturbation would be to include this content in the Extension Developer FAQ.

[marcelstoer]

@romanchyla @DesperateProgrammer @pjsg @TerryE

I just created https://github.com/nodemcu/nodemcu-firmware/wiki/%5BDRAFT%5D-How-to-write-a-C-module as temporary collaboration space until we're happy to PR this.