Add support for multiple configuration to deduplicate examples

[salkinium]

This adds a simple project.xml syntax to generate and compile examples with multiple configurations.

This copies the example folder for every configuration inside the project.xml into the build folder and then lbuilds and compiles the example. The project.xml syntax is based on XML comments so that the example remains usable manually and should be self-explanatory for anyone using the example.

The targets are just any <extends>.*?</extends> in the project.xml. To support additional configurations that some devices need (see the USB example), any <option name="...">...</option>, <module>...</module>, <collect name="...">...</collect>, with a comment on top containing the config string will be added to the command line.

This is very simple and allows us to "flip" the example matrix from "target -> use case" to "use case -> target", which should also help focus the examples on truly shared APIs.

• [ ] Deduplicate more examples
  • [x] Blink
  • [x] Fiber
  • [x] USB serial and MSC
  • [x] USB FATFS and Flash programming
  • [x] FLASH programming
  • [x] ITM output
  • [x] RTT communication
  • [x] FreeRTOS
• [ ] Better Syntax Documentation
  • Do we need negative filters? no
  • [ ] Do we want config globbing support?
• [ ] Adapt example_check.py:
  • [ ] Don't miss new configs in examples folder (cos it's a silent failure)
  • [x] Don't try to compile example folder that don't exist
• [x] Adapt workflow lists

cc @rleh @chris-durand: What do you think?

[salkinium]

Ok, so in order to deduplicate more examples we need Board interfaces for setting up a default I2C and SPI connection similar to Board::initializeUsbFs() and the LEDs and Button. Then it should also be much easier to anyone to test any sensor example on the hardware they have at hand instead of having to port examples to their board first.

[salkinium]

I've prototyped this for some NUCLEO-32 boards, I think it's a good idea to deduplicate all the I2C/SPI examples too.

[salkinium]

ok, so I think the deduplication is a good thing, but I don't like the idea of putting everything into the example/generic folder. Here is the new structure, which basically flips the example on the head: first use-case, then board. What do you think about this, @rleh @chris-durand ?

• core
  • custom_allocator
  • delay
  • exceptions_rtti
  • fiber
  • flash
  • hard_fault
  • itm
  • multi-core
  • resumable
  • rtt
  • threadsafe_statics
  • tlsf_allocator
  • unaligned_access
  • vector_table_ram
• gpio
  • blinky
  • exti
  • gpio
  • ports
• analog
  • adc_dma
  • comp
  • dac
• timer
  • encoder_input
  • pwm
  • timer
• logging
  • logger
  • printf
  • uart
• ui
  • game_of_life
  • graphics
  • lvgl
• driver
  • can
  • i2c
  • single wire
  • spi
• communication
  • amnb
  • ethernet_freertos
  • nrf24
  • ros
  • sab
  • xpcc
• ext
  • cmsis_dsp
  • etl
  • freertos
  • nanopb
  • usb
  • usb_dfu
  • usbfatfs
• board
  • super custom board-specific examples
  • ideally we get rid of this section

[rleh]

What about a more flat structure? E.g. with the LIS3 driver/examples it would be nice to have lis3_spi/ and lis3_i2c/ examples located next to each other.

I would prefer no subdirectories over non-obvious subdirectories.

[salkinium]

it's flat like that, the second indentation is already the example folder. I just didn't list all the i2c drivers.

[salkinium]

ah, you mean completely flat? I think it's just too much, particularly because not everything can actually be deduplicated. I currently have 285 examples in this PR (down from 374 on develop), The analog examples can be fairly device specific, so they would be multiple ones like examples/analog/adc_f1, examples/analog/adc_f3, examples/analog/adc_h7 etc. I've now roughly used the same folder names as in src/modm to reflect the top-level use cases.

[rleh]

I think tags instead of categories are more useful for users (including me) to find an example. But that is not possible to implement using filesystem structures anyway, but we could generate a table of all examples inside examples/README.md with tag/keywords and maybe even a short description.

[rleh]

I'm also a bit skeptical about the impact of deduplication, use of scripting and undocumented magic XML comment syntax for new modm users. The examples are most users' first exposure to modm, and I find it unfavorable to add unnecessary complexity. The project.xml files of the examples are already special: The <repositories>…</repositories> block is missing and <extends>modm:some-configuration</extends> is used. From my experience, that makes the step from a functional modm-example to an own modm-project complicated for new users.

What do we think about generating the examples completely in a separate repo (e.g. https://github.com/modm-io/modm-examples) for all boards, including the modm repo as submodules and a project.xml file which would be at most similar to the one in a custom project?

[salkinium]

To get users started with their own projects, I created the modm-template repo once. Back then GitHub template repos didn't support submodules, but that has been fixed now. We should get that working, including how to setup multiple lbuild repos, CI for building, using our unit test system, documentation etc. We can document this in Readmes, which we can then also put onto the website like our other readmes.

I hope users are not even gonna notice that there's magic XML syntax in the project.xml (I'll document it, don't worry). It will look just like more documentation. This is mostly just an internal refactoring to make it more maintainable and not copy around blinky so much and to actually force us to design more APIs to be compatible across devices by actually testing it.

[rleh]

(deleted)