doc-gen "make" fails

[gen2thomas]

For my recent project, I really wanted to test TinyGo and have searched many hours, which MCU is supported for BT and/or WiFi. The documentation seems to be a little bit outdated. After I have managed my project in a few days with nRF52840 based chip - many thanks to the TinyGo-developers - I would like to give something back by improve and add some content for the documentation site.

I like to contribute a matrix for the supported hardware to save some time for other developers. First I write it manually, but than I found the code for the generation of machine and microcontrollers reference pages.

Unfortunately it is not working any more caused by some undefined symbols. It stops here:

src/machine/machine_atsamd21.go:1742:6: undefined: arm.DisableInterrupts
exit status 1

Also, this prevents building for all follow up pages, although there would be no such error.

My suggestions is (besides fix the originated problem):

• skip erroneous "pages" and generate all output which is not affected
• split the main.go a little bit (e.g. for PWM part, different sites) to make it better to maintain

@aykevl , @deadprogram , @soypat what do you think about?

[soypat]

Have you tried running make gen-device before make (inside your tinygo repository, if you build from source) ?

[gen2thomas]

I have not built from source but installed by unpack a development build on one machine (gentoo, amd64, intel) and by deb on another one (Debian 12, arm64, Tinkerboard 2). The tinygo repository was cloned on both machines.

Now I have done make gen-device before, but with the same result on both machines.

Next try would be on the Debian machine to uninstall the deb installation and install it from source.

Any other ideas?

[gen2thomas]

This workflow also leads to the same result:

• install tinygo from source
• make gen-dev
• switch to doc-gen folder and run make

[gen2thomas]

I have modified the code a little bit to print the error with the preamble "sanity check failed: " and continue with the next tinygo-target. Than other errors will be printed, which are maybe more helpful to catch the originated problem, e.g.:

sanity check failed: /home/<user>/.cache/tinygo/goroot-52976b6bee5da5f00e08d40051e652037e2eebb7a54b7f4003df55700c805798/src/machine/machine_rp2040_flash.go:101:11: f.eraseBlocks undefined (type flashBlockDevice has no field or method eraseBlocks, but does have EraseBlocks)

[gen2thomas]

@soypat a question, just to be sure: This doc-gen is not run automatically on each build of the page and it is only used to update the content manually from time to time?

[soypat]

@gen2thomas I'm actually not sure- never run doc-gen

[gen2thomas]

Ok, thanks! But who can answer this question? It seems @deadprogram has introduced this generator.

[gen2thomas]

The #385 is now ready to review. Besides a huge improvement of the doc-generator, many pages where fixed and improved also. So please have a look and make your suggestions.

Thanks Thomas

[aykevl]

I have fixed doc-gen here: #397
The fix was relatively simple: I just skip all type errors. That should be mostly harmless when generating documentation (it mostly fails with CGo).

This doc-gen is not run automatically on each build of the page and it is only used to update the content manually from time to time?

Correct. Usually after a TinyGo release but we haven't done that in a while (in part because it was broken).

It seems @deadprogram has introduced this generator.

That was me actually :)

[deadprogram]

Now closing since this has been corrected. Thanks @gen2thomas for reporting and to @aykevl for the fix.