Library Development HowTo

I’m trying to develop a library, and I am using core to do my development. I can easily make sketches, and define their dependencies, and I’ve seen the documentation on library.json. What I’m missing is a howto on building the library during development.

I want to make my library similar to how it would be published. Something with a src/ examples/ and library files. I want to work on the examples, and have their dependencies all worked out, and I want to kick off the builds of the examples and occasionally upload them to the target platform (esp32).

Am I missing this information in the documentation somewhere?

Thanks, Jeff

1 Like
  1. Create a new folder/project for a library. Place source code to src folder
  2. In a separate project you can use lib_extra_dirs and specify path to a folder where project/library’s directory is located.

Also, take a look at Redirecting... and NOTE block.

Rather than start a new topic, I thought I’d revive this old thread to propose an alternative strategy for library development in case anyone else happens to be searching through the forum for a solution to this problem. The challenge I struggled with was building an example project within a local PlatformIO library without any special platformio.ini settings.

While developing a library, I formed a working project in a fashion similar to that described in @ivankravets response. However, when I changed the structure of my library to make it compatible with the Library Manager, it became incompatible with the lib_extra_dirs approach because the directory structures are different; my source was now in a src subdirectory, not in the root of a directory named for the library as required by lib_extra_dirs.

I found the simplest solution to be the following. Unfortunately, this will only work on a Linux OS:

  1. In the pio global storage directory, create a symlink to the library directory named for the library. In my case, something like this:
    ln -s "/home/user/repository/library_directory/" /home/user/.platformio/lib/CustomLibraryName
  2. Add the library dependency to the project environment:
    lib_deps = CustomLibraryName

Changes to the library source code will immediately be available during PlatformIO build and allow rapid library development. The example can be easily modified and kept up to date during development. Be careful not to accidentally install or update an older version of your library from the Library Manager server; this will happen if you run a library update and don’t have version set in library.json.

I apologize if this is an obvious solution, but I didn’t encounter any such strategy in the documentation or in this forum and thought it might benefit any others trying to develop publicly available libraries. If there is a better solution for development of a library using its example sketches, I’d love to hear it!

1 Like

Hard and symbolic links are also possible on Windows, so it’s not limited to Linux. Maybe a Mac user can chime in if it’s possible also?

But hey, nice workaround :slight_smile: I suppose faking the src directory as the main library directory in the lib_extra_dirs would look a bit silly, wouldn’t it…

Oh, I didn’t know Windows could do that! :+1:

I tried to fake the src directory but didn’t have success. I assumed that was because I didn’t have all source files in sub directories, but I was simultaneously dealing with linker issues, so I’m not sure.

It seems like you could organize the library source in such a way that adding the src directory to lib_extra_dirs and then specify a source filter in library.json so that the project builds successfully both ways, but that would still require a change to platform.ini. I’m lazy and forgetful, so I like not having to modify the example depending on whether I’m developing the library or pushing a new release version.

1 Like

I’m with you there… if it needs changing when pushing the release version… it’s likely to get missed… (yes, I’m looking at you library manifest files! :laughing: ).

If you want to find out how to do file system links on Windoze, this is a good guide on the native support via the command line:

And for a useful helper shell extension (which looks to be maintined, so should still work nicely):

1 Like