PlatformIO Community

Arduino Library creation

In any case I’d probably be interested in buying your book when it comes out



1 Like

Hi (again) - the structure is all good but for the life of me I can’t include an examples folder and get the source to compile.

I have included the examples in the ‘lib’ folder as per the README and each example.cpp file is in a folder of the same name.
I have also placed an include in the [env] section of the .ini file:

-I lib/RandomNumber/examples/example-01

example-01.cpp is not getting compiled however

Apologies if the question seems a bit simple - I’m not normally a C/C++ programmer

Screen Shot 2021-08-24 at 10.55.31 pm

Many thanks


It appears that you have the examples folder within lib\RandomNumber?

The example @maxgerhardt links above is a pure Arduino library, in the format that the Arduino IDE likes to have. The structure is of this format:


Within src, you just have the sources and headers for the library itself. Within examples (lower case is a necessity!) you have various sub-directories containing the *.ino files for each example.

PlatformIO can read and understand this directory structure when used with the Arduino framework. If you were to convert this to a dedicated PlatformIO library, then as @maxgerhardt indicated above, you would copy the src folder into lib and rename it to the name of your library. Then, obviously, remove the files from the original src directory.

If you intend to write a library for PlatformIO, which is not in the Arduino structure, this is exceedingly helpful! Creating Library — PlatformIO latest documentation.



A -I flag is for adding a path to the include search path, so that if a code does #include <some_file.h>, the compiler may find in one of the added paths. It does not add a file to the build-system. Refer to my post above as to what files are compiled in a PlatformIO project.

If you want to run the example, either copy the contents of example-01.cpp to the src/main.cpp file of your test project, or use a pio ci command on the console. This creates and compiles an example on-the-fly. Uploading is not possible though, it’s intended for a compilation check, as can e.g. be seen on the Continuous Integration page.

Example usage

pio ci --board=uno lib/MyTestLibrary/examples/example-01 --lib lib/MyTestLibrary

Would dynamically create a board = uno (with the default setting framework = arduino), using the source files in lib/MyTestLibrary/examples/example-01 while copying the contents of lib/MyTestLibrary into the newly-created project’s lib/ folder.

See GitHub - maxgerhardt/pio-arduino-lib-development-example.

I think its back to the drawing board. Whilst I appreciate both of your replies, I’m still in the dark as to where to put the examples and how to build them. I understand the structure of the Arduino library - that’s not the issue.

Anyway, I’ll post here again when (if) I make any progress. I don’t understand why something that should be trivially simple is so difficult to get right and why there is no decent instruction on it.

Anyway no worries


You’ve already put the examples in the correct location, and I’ve referenced two ways you can build them.

After a longer look I realised this once I’d seen your git repo. I didn’t know about the correct ‘pio’ command. The examples now compile - not sure why the example files aren’t built anywhere and also if it is possible to automate a distribution build but with what you’ve given me I can move forward

Many thanks


What do you define as a “distribution build”?

A distribution folder with the production build eg you would change all .cpp files to ino, add in docs or other files…etc Maven, grunt, webpack…etc

The file extension in the examples can be .ino, PIO will be able to build that too. The other stuff is not related to PIO builds.

I found an older post on here about someone running gulp. Also noticed the pre & post directives and the ability to get to ‘env’ to execute stuff. So I should be able to work it out from there


So, returning to this after a few days, I thought I had it sorted but realise I haven’t. I’ve got the structure and can compile individual files however I don’t get how to compile all the example src files in one go, neither do I understand how to set the build_dir explicitly. I’ve looked through the documentation for about an hour and it makes little sense to me though I feel what I’m doing should be trivial

The command I’m using is:
pio ci --board=uno lib/RandomNumber/examples/example-01 --lib lib/RandomNumber

I tried */ instead of examples/example-01 but that didn’t help

Neither am I totally sure of what the --lib flag is doing. I thought it was the source but it doesn’t seem to be compiling everything.

Those have to be individual commands. pio ci creates as said a dynamic project on the fly, and one final firmware should only contain one example, otherwise all the main functions (like setup() and loop()) will be conflicting. See e.g. this (uses pio run though instead of pio ci)

One can create a special PlatformIO project for this purpose by creating multiple enviornments with different src_filter settings, each of which only enables the compilation of one test. But it’s most common to just compile one example at a time (automated for all exampels of course in CI).

I must admit I’m on the verge of going back to the Arduino IDE - at least it works, is predictable and easy to use - even if it is a pain. I just don’t see how platformio is helping in anyway at all.

I can’t compile multiple examples at once
I can’t see errors in the editor until I compile
I can’t make head nor tail of the ‘documentation’

I feel like I’ve never coded in my life before using this product yet I have for decades.

Why do I have to create a ‘special PlatformIO project with multiple environments…’

You do this sort of thing in Java and node and Python in 5 minutes. Why is this so weird?

Found one of my issues - Having set the default parser to TagParser, all my real-time syntax checking no longer worked.
Changed this back to default and it works.
Finally some progress

Now I just need to figure out how to compile the library files all in one go

Hi @peetj,

is this any help: Writing Libraries - free eBook


Hi Norman

thanks although it isn’t the library structure that is difficult. It is simple to create a library. PlatformIO is the problem. Seems hard to do anything. It is also the C++ plugin for VS Code that I’m fighting with although I got it to syntax check and format correctly yesterday.

It seems I can’t compile all the examples at once which is my next issue. I might have to settle for copying and pasting each example into the src folder main.cpp file or issuing a separate pio ci command for each example manually.

There must be a way to automate this as I’d like to get unit tests if possible and a deploy target to productionize the build - however it is slow progress.

Which one? The Microsoft one is the only one that should be installed, others being installed at the same time cause problems and also do so for PlatformIO.


Its ok I figured out the config and it works fine.

One other thing is unit testing with my setup. I would like to write and run tests to test the library functions. I don’t mind manually running the tests. Have you done this before?


I’m afraid I hven’t started using the test system yet, it’s definitely on my todo list. There are some good blog posts on it though:

which I have bookmarked.