# Creating Library

PlatformIO Library Manager doesn’t have any requirements to a library source code structure. The only one requirement is library’s manifest file - library.json, library.properties or module.json. It can be located inside your library or in the another location where PlatformIO Library Registry Crawler will have HTTP access.

Updates to existing libraries are done every 24 hours. In case a more urgent update is required, you can post a request on PlatformIO community.

Contents

- Source Code Location

  - At GitHub

  - Under VCS (SVN/GIT)

  - Self-hosted

- Register

- Examples

## Source Code Location

There are a several ways how to share your library with the whole world (see examples).

You can hold a lot of libraries (split into separated folders) inside one of the repository/archive. In this case, you need to specify `include` option of export field to relative path to your library’s source code.

### At GitHub

Recommended

If a library source code is located at GitHub, then you need to specify only these fields in the library.json:

- name

- version (is not required, but highly recommended for new Library Manager)

- keywords

- description

- repository

PlatformIO Library Registry Crawler will populate the rest fields, like authors with an actual information from GitHub.

Example, DallasTemperature:

    {
      "name": "DallasTemperature",
      "keywords": "onewire, 1-wire, bus, sensor, temperature",
      "description": "Arduino Library for Dallas Temperature ICs (DS18B20, DS18S20, DS1822, DS1820)",
      "repository":
      {
        "type": "git",
        "url": "https://github.com/milesburton/Arduino-Temperature-Control-Library.git"
      },
      "authors":
      [
        {
          "name": "Miles Burton",
          "email": "miles@mnetcs.com",
          "url": "http://www.milesburton.com",
          "maintainer": true
        },
        {
          "name": "Tim Newsome",
          "email": "nuisance@casualhacker.net"
        },
        {
          "name": "Guil Barros",
          "email": "gfbarros@bappos.com"
        },
        {
          "name": "Rob Tillaart",
          "email": "rob.tillaart@gmail.com"
        }
      ],
      "dependencies": [
        {
          "name": "OneWire",
          "authors": "Paul Stoffregen",
          "frameworks": "arduino"
        }
      ],
      "version": "3.7.7",
      "frameworks": "arduino",
      "platforms": "*"
    }

### Under VCS (SVN/GIT)

PlatformIO Library Registry Crawler can operate with a library source code that is under VCS control. The list of required fields in the library.json will look like:

- name

- keywords

- description

- authors

- repository

Example:

    {
        "name": "XBee",
        "keywords": "xbee, protocol, radio",
        "description": "Arduino library for communicating with XBees in API mode",
        "authors":
        {
            "name": "Andrew Rapp",
            "email": "andrew.rapp@gmail.com",
            "url": "https://code.google.com/u/andrew.rapp@gmail.com/"
        },
        "repository":
        {
            "type": "git",
            "url": "https://code.google.com/p/xbee-arduino/"
        },
        "frameworks": "arduino",
        "platforms": "atmelavr"
    }

### Self-hosted

You can manually archive (Zip, Tar.Gz) your library source code and host it in the Internet. Then you should specify the additional fields, like version and downloadUrl. The final list of required fields in the library.json will look like:

- name

- keywords

- description

- authors

- version

- downloadUrl

    {
        "name": "OneWire",
        "keywords": "onewire, 1-wire, bus, sensor, temperature, ibutton",
        "description": "Control devices (from Dallas Semiconductor) that use the One Wire protocol (DS18S20, DS18B20, DS2408 and etc)",
        "authors":
        {
            "name": "Paul Stoffregen",
            "url": "http://www.pjrc.com/teensy/td_libs_OneWire.html"
        },
        "version": "2.2",
        "downloadUrl": "http://www.pjrc.com/teensy/arduino_libraries/OneWire.zip",
        "export": {
            "include": "OneWire"
        },
        "frameworks": "arduino",
        "platforms": "atmelavr"
    }

## Register

The registration requirements:

- A library must adhere to the library manifest specification - library.json, library.properties or module.json.

- There must be public HTTP access to the library manifest file.

Now, you can register your library and allow others to install it.

## Examples

Command:

    $ platformio lib register http://my.example.com/library.json
    $ platformio lib register http://my.example.com/library.properties
    $ platformio lib register http://my.example.com/module.json

- GitHub + detached release

- Dependencies by author and framework

- Multiple libraries in the one repository