Creating Library

Managing components between the projects is a historical issue. A common code is duplicated between different projects that lead to project complexity. A good practice is to organize interdependent components as the separate libraries where other projects can depend on them.

PIO has a built-in Libraries where developers can declare project dependencies and PIO will automatically manage them (install, build, update). It doesn’t have any requirements for a library source code structure. The only requirement is a library manifest file - library.json, library.properties, or module.json. It must be located in the root of a library.

We highly recommend using library.json for better compatibility and avoiding any issues.

Structure

We recommend to use src folder for your C/C++ source files and include folder for your headers. You can also have nested sub-folders in src or include.

Example

├── examples
│   └── echo
├── include
│   └── HelloWorld.h
├── library.json
└── src
    └── HelloWorld.cpp

Manifest

A library package must contain a manifest. We recommend using library.json.

Example

{
  "name": "HelloWorld",
  "version": "1.0.0",
  "description": "A \"Hello world\" program is a computer program that outputs \"Hello World\" (or some variant) on a display device",
  "keywords": "planet, happiness, people",
  "repository":
  {
    "type": "git",
    "url": "https://github.com/username/hello-world.git"
  },
  "authors":
  [
    {
      "name": "John Smith",
      "email": "me@john-smith.com",
      "url": "https://www.john-smith/contact"
    },
    {
      "name": "Andrew Smith",
      "email": "me@andrew-smith.com",
      "url": "https://www.andrew-smith/contact",
      "maintainer": true
    }
  ],
  "license": "MIT",
  "homepage": "https://www.helloworld.org/",
  "dependencies": {
    "ownername/print": "~1.3.0"
  },
  "frameworks": "*",
  "platforms": "*"
}

Publishing

You can publish a library to the PIO Registry using pio pkg publish command. Every time when you modify a source code of a library you will need to increment the “version” field in library.json manifest and re-publish again.

If the published library has an issue and you would like to remove it from the PIO Registry, please use pio pkg unpublish command.

Examples

See the published libraries in PIO Registry.