Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for multiple configuration to deduplicate examples #1118

Draft
wants to merge 17 commits into
base: develop
Choose a base branch
from

Conversation

salkinium
Copy link
Member

@salkinium salkinium commented Jan 6, 2024

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
    • Blink
    • Fiber
    • USB serial and MSC
    • USB FATFS and Flash programming
    • FLASH programming
    • ITM output
    • RTT communication
    • 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)
    • Don't try to compile example folder that don't exist
  • Adapt workflow lists

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

@salkinium
Copy link
Member Author

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
Copy link
Member Author

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 salkinium force-pushed the feature/dedup_examples branch 4 times, most recently from 2afca50 to 87a6802 Compare January 13, 2024 00:04
@salkinium
Copy link
Member Author

salkinium commented Apr 7, 2024

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
Copy link
Member

rleh commented Apr 7, 2024

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
Copy link
Member Author

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

@salkinium
Copy link
Member Author

salkinium commented Apr 7, 2024

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
Copy link
Member

rleh commented Apr 7, 2024

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
Copy link
Member

rleh commented Apr 7, 2024

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
Copy link
Member Author

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
Copy link
Member

rleh commented Apr 7, 2024

(deleted)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Development

Successfully merging this pull request may close these issues.

2 participants