Support for Library Development

This is an Idea im formulating for a while.

Here the Use Case / Story:
I have a Library developed in a Project. No i want to create a separate Project to upload the Library to github to share it across multiple projects and possibly for public use.
but at the point i move the lib into an individual project, i can not realy compile and run examples that easily without changing code.

So what Im imagining is like Switching Build Configurations in platform.ini i would like to select an example in the top level examples directory.
like this:

platform = espressif32
board = esp32-s3-devkitc-1 
example="example1" ; <-- this sets what example is compiled


platform = espressif32
board = esp32-s3-devkitc-1 
src_dir="examples/example1" ; <-- this sets where the src directory for compilation is found

This way i could easily switch between the examples and test them and i could also automatically recompile all examples after a change.

I don’t know if this is easily possible as you would switch where the main.cpp is found etc, but it would be very helpful to develop and maintain libraries.

To be honest I do not really understand what the problem is. So if you have what you consider library functionality and you extract it into its own project, you find it difficult to use it in the project you extracted that functionality from?

I am currently doing something similar and what I do is have the library be used directly (add a local folder to to lib_deps) or publish it to PlatformIO registry. I also think you could use different targets if it’s feasible - just name them differently.

So perhaps you could have env:EXAMPLE_1 and env:EXAMPLE_2? I haven’t tested this though.


Okay I’ll explain it in more detail:
So i have a Library that i want to maintain with MULTIPLE working examples that covert all functionality of the Library.
Currently, its not easy to compile through all the examples to easily check if after code changes the library still works on all examples.
The Solution i proposed here is, to allow setting the “src” folder for compilation to a given subpath to target individual examples.

so usually you have something like this in you project

            basic_example/ <-- examples src folder i want to target with a build config / env:XXX

src/ <-- default dir to look for main.cpp  ( setup() and loop() )

This is how I do it with the SinricPro library:
The library is hosted on GitHub.
All examples are located in the subdirectory “Examples
I use a GitHub workflow that compiles all examples as soon as a pull request is made.
This gives a nice report when something fails or when all examples have been successfully compiled.

Addendum: Documentation PlatformIO and Github actions

1 Like

Thanks for the informations, its similar but not quite what I’m looking for.
But I’ll save the information as i was also planing to use GitHub actions for continuous integration etc.

There I’m more about making a new workflow possible in PlatformIO (while working with Visual Studio Code)
I would like to toggle through the examples also while working on the examples.
The best way currently is to create multiple projects or #ifdef each main.cpp.

I use different env: build configurations to switch between different variants of a project, like the printer software marlin does, where you toggle between different boards.
Now to extend that system i would like to toggle through examples. This could also be generalized with test code that replaces the actual user code in PROJECT/src.

the rough framework for that also seems to already exist: HERE

This variant is more convenient when project is written as a library (when there are examples or testing code) as it has additional options for specifying extra libraries and boards from command line interface:

PLATFORMIO_CI_SRC: ${{ matrix.example }}

so this option just needs to be made available in platformio.ini

This is exactly what I use (GitHub Actions)

so this option just needs to be made available in platformio.ini

Since GitHub Actions is a functionality of GitHub, I don’t think it can be “integrated” (locally) into PlatformIO.

I could imagine keeping the library locally in a directory and using it with a symlink in the individual examples.

Maybe you could combine the examples in a single project and use src_filter. However, this is beyond my knowledge. Maybe @maxgerhardt has another idea here?

In the library, you can create a platformio.ini and a small extra script. This enables you to create one environment for each example, that will be compiled automatically from the examples/ folder without the need to copy it into src/, by using the build src filter. I’ve already shown that last year.

Of course, the other way is to have a small batch script that executes a few pio ci commands (this can also be done locally, not restricted to CI environments!) that will each test-compile one example. See documentation.

Im pretty sure that the github action just calls plaftormio core cli. plaformio basically uses input to construct a list of command line arguments calling compilers like gcc.
if you replace the filepath for search of source files in PROJECT/src with the root path of the example, its should work the same.

simlinks do not work on windows for example

thank @maxgerhardt, ill look into it. from first glance it looks close to what i described/looked for

In general, it would be useful to have this supported directly in platformio.ini, its basically just overwriting the folder path for the src directory. this would unlock more than just example compilation.

I opened this as a kind of feature request for the platformio core or at least an inspiration.
I don’t demand this to be implemented ofcourse. Just wanted to bring up that this might be a good idea to implement.

This is not how GitHub actions / workflows work. They are basically scripts that are executed in a virtual machine (ubuntu / Windows or MacOS) directly on Github. The best way to understand this is to read the documentation about github actions.

I think the way suggested by maxgerhard is the right one for a local solution without GitHub.

Hi max!

I have just tested this. That works great!
Many thanks for that! :slight_smile:

I think I can use this in the early stages of developing a library - before publishing to a GitHub repository and setting up all the workflows stuff.

Just found this:

src_dir = src2

to change the source dir, but it only is valid under [platformio] but not in [env:]
so it already is a feature, it’s just not enabled/implemented for individual [env:]

where can I officially suggest this feature/change