I've started exploring PlatformIO and thought I'd set down my experiences so that others can get some quick answers to questions that they may have which may help navigate the copious documentation they will encounter on the Internet. First some important links:

PlatformIO: Open source professional collaborative platform for embedded development

PlatformIO project page on Hackaday, lots of links

Visual Studio Code: Coding IDE that provides an IDE for PlatformIO via an extension

What is it?

In short an IDE for enbedded development that is cross-platform and caters for multiple processors. It can fill the space that Arduino occupies and exceed it.

How to get it

First install Visual Studio Code (Vscode from now on) for your platform. Vscode is separate from PlatformIO but the latter leverages the former by an extension. On my Linux distro it was as easy as adding the Vscode repository to the software manager and then installing it as a package. You will get monthly updates. You can use it also as a code editor for your non-embedded projects BTW. It has tons of extensions, so many in fact that it can be hard to select, for various languages and environments.

Next fire up Vscode, find and install the PlatformIO extension. Starting a project in this will bring in the PlatformIO core. Installation is done in your own directories so no system privileges are required.

I actually took another path, I installed PlatformIO core from the command line using these instructions. It was probably unnecessary but it gave me insight to what was happening behind the scenes. Core is the CLI part of PlatformIO, and is written in Python, which allows it be easily cross-platform.

Depending on the parameters of the project you have created, other packages will be brought in. For instance I selected a STM8 platform on the blue breakout board, using the ST Standard Peripherals Library (SPL). This then pulled in various development packages based around SDCC, as well as support utilities like downloaders and debuggers. Note that this is separate to any other SDCC you may have installed on your computer, and will be stored in your private PlatformIO directories (~/.platformio on Linux).

How to run it

Fire up Vscode and look for PlatformIO in your installed extensions. Go to its home and start a project. You will see that it will create a project directory with a standard structure made popular by Ruby On Rails, Rust, Gradle, and other frameworks with subdirectories for source, includes, libraries, and build target directories which hold the generated objects.

You can also try to install an example project, blink for example. You will get a project directory in the standard structure populated from the PlatformIO repositories.

Wander around those directories and read the README files left there.

How to build projects

You can use the IDE for all actions, but I found it instructive to cd into the project and run commands using the PlatformIO CLI commands at the beginning. (You may need to add those commands to your shell's repertory by editing PATH or by making symlinks.) The main one is platformio, or the shorter pio. You can do things like:

pio run
pio run --target clean

 and others you can discover by pio -h.

You can actually do quite a bit of work from the CLI but for advanced operations like debugging, the IDE is the way to go.

You'll notice a file at the top directory of the project: platformio.ini This describes the build options. For example mine contained:

[env:stm8sblue]
platform = ststm8
board = stm8sblue
framework = spl

You can have multiple stanzas, you will end up with multiple products in .pio/build as a result. Many standard combinations are already in PlatformIO so you shouldn't have to create a new configuration if your platform is well established or PlatformIO is already supported by its manufacturer.

Where are the projects stored?

By default the projects directory is ~/Documents/PlatformIO/Projects on Linux and probably similar paths on the Mac and Windows. I didn't like this, I don't consider projects documents so I used these commands to change it:

pio settings get
# to see what they are
pio settings set projects_dir ~/work/uC/platformio
# where I store projects even though work is play now

Actually I go a bit further, after a project is created I move it into a MCU specific directory and put a symlink to the actual path in the projects_dir. But this is just me.

Have fun!

Well that should get you started. I'll be exploring PlatformIO with the STM8 breakout board, and when that arrives later, a RISC-V dev board, and hope to write up those experiences.