I’ve developed a custom variant within a project and it is working well.
Within the project directory I have
/boards/mycustomvariant.json
/custom_variants/STM32F2xx/F207V(C-E-F-G)T_F217V(E-G)T/
…mycustomvariant_clock.c
…variant_mycustomvariant.h and
…variant_mycustomvariant.cpp
I am at the stage where I’d like to share this with my team and make it as easy as possible for them to create new projects using this board. Accordingly, I have created a boards directory in the .platformio directory and put mycustomvariant.json in there.
I have also copied mycustomvariant_clock.c, variant_mycustomvariant.h and variant_mycustomvariant.cpp into the .platformio\packages\framework-arduinoststm32\variants\STM32F2xx\F207V(C-E-F-G)T_F217V(E-G)T directory.
With these changes, pio boards will now show mycustomvariant and my team can select this board when creating a new project.
.platformio/boards/ won’t get overwritten with a platformio update but .platformio\packages\framework-arduinoststm32\variants\STM32F2xx\F207V(C-E-F-G)T_F217V(E-G)T will.
Should I remove the variant files and place them in a directory like .platformio/custom-variants/? If so, is there a way to automatically add the needed board_build.variants_dir = ... to platform.ini when the user creates the project? Is there a better way to do this?
First, they could all copy your boards and custom_variants folder in their project the same as you. I.e., duplicating your files and config into their project. Not very handy when you’d like to push an update to any of those those board files, tedious.
Second, in your project you create a script which sneakily copies the new variant files and board definitions into the internal PlatformIO folders. Marlin does this. While it does have the advantage that, once the copy to those internal folders is done, subsequent projects do not need to have these board files in their project folder or manually copy them, I would not recommend this, for the same reasons outlined above.
Third, and this is the best solution in my view, is that you create a fork of https://github.com/platformio/platform-ststm32/. This is where all the board definitions and the package.json that describes the used packages (such as framework-arduinoststm32). The thought here is, that in your fork, you can freely add your board definition (json) files in the boards/ folder. Further, you can change the package.json in regards to the source of framework-arduinoststm32, being able to point it at another git repository (that you of course control). Meaning you can the current state of your framework-arduinoststm32 folder (technicality: delete the .piopm file in it after uploading), upload it to some new git repository (or better: directly forked from the source) and reference the git link in the package.json as the version field of the framework-arduinoststm32 package.
That has the advantages that:
Users which want to use your custom boards in however many projects they like, just need to set platform = <link to your platform-ststm32 fork here> in the platformio.ini and can reference your custom board = ... right away with no further options.
You have a central point in which you can apply updates and patches that users can easily update to in the PlatformIO Home GUI ( → Platforms → STM32 <hash> → Update).
The only disadvantage is that it requires the forks and one-time setups.
We’ve split the team into two “access” levels. At the package dev level, we use our custom framework from a git cloned folder using the symlink method so that the custom platform package can be developed: