# library.json

`library.json` is a manifest file of development library. It allows developers to keep project in own structure and define:

- location of source code

- examples list

- compatible frameworks and platforms

- library dependencies

- advanced build settings

PlatformIO Library Crawler uses `library.json` manifest to extract source code from developer’s location and keeps a cleaned library in own Library Registry.

A data in `library.json` should be represented in JSON-style via associative array (name/value pairs). An order doesn’t matter. The allowable fields (names from pairs) are described below.

Fields

- `name`

- `version`

- `description`

- `keywords`

- `authors`

- `repository`

- `license`

- `downloadUrl`

- `homepage`

- `export`

  - `include`

  - `exclude`

- `frameworks`

- `platforms`

- `dependencies`

- `examples`

- `build`

  - `flags`

  - `unflags`

  - `includeDir`

  - `srcDir`

  - `srcFilter`

  - `extraScript`

  - `libArchive`

  - `libLDFMode`

  - `libCompatMode`

- Examples

## `name`

Required | Type: `String` | Max. Length: 50

A name of the library.

- Must be unique.

- Should be slug style for simplicity, consistency and compatibility. Example: Arduino-SPI

- Title Case, Aa-z, can contain digits and dashes (but not start/end with them).

- Consecutive dashes are not allowed.

## `version`

Required | Type: `String` | Max. Length: 20

A version of the current library source code. Can contain a-z, digits, dots or dash and should be Semantic Versioning <http://semver.org> compatible.

Example:

    "name": "Bar",
    "version": "1.0.0",
    "repository":
    {
        "type": "git",
        "url": "https://github.com/foo/bar.git"
    }

## `description`

Required | Type: `String` | Max. Length: 255

The field helps users to identify and search for your library with a brief description. Describe the hardware devices (sensors, boards and etc.) which are suitable with it.

## `keywords`

Required | Type: `String` | Max. Length: 255

Used for search by keyword. Helps to make your library easier to discover without people needing to know its name.

The keyword should be lowercased, can contain a-z, digits and dash (but not start/end with them). A list from the keywords can be specified with separator `,`

## `authors`

Required if repository field is not defined | Type: `Object` or `Array`

An author contact information

- `name` Full name (Required)

- `email`

- `url` An author’s contact page

- `maintainer` Specify “maintainer” status

Examples:

    "authors":
    {
        "name": "John Smith",
        "email": "me@john-smith.com",
        "url": "http://www.john-smith/contact"
    }

    ...

    "authors":
    [
        {
            "name": "John Smith",
            "email": "me@john-smith.com",
            "url": "http://www.john-smith/contact"
        },
        {
            "name": "Andrew Smith",
            "email": "me@andrew-smith.com",
            "url": "http://www.andrew-smith/contact",
            "maintainer": true
        }
    ]

Note

You can omit authors field and define repository field. Only GitHub-based repository is supported now. In this case PlatformIO Library Registry Crawler will use information from GitHub API Users.

## `repository`

Required if downloadUrl field is not defined | Type: `Object`

The repository in which the source code can be found. The field consists of the next items:

- `type` the only “git”, “hg” or “svn” are supported

- `url`

- `branch` if is not specified, default branch will be used. This field will be ignored if tag/release exists with the value of version.

Example:

    "repository":
    {
        "type": "git",
        "url": "https://github.com/foo/bar.git"
    }

## `license`

Optional | Type: `String`

A license of the library. You can check the full list of SPDX license IDs. Ideally you should pick one that is OSI approved.

    "license": "Apache-2.0"

## `downloadUrl`

Required if repository field is not defined | Type: `String`

It is the HTTP URL to the archived source code of library. It should end with the type of archive (`.zip` or `.tar.gz`).

Note

downloadUrl has higher priority than repository.

Example with detached release/tag on GitHub:

    "version": "1.0.0",
    "downloadUrl": "https://github.com/foo/bar/archive/v1.0.0.tar.gz",
    "include": "bar-1.0.0"

See more `library.json` Examples.

## `homepage`

Optional | Type: `String` | Max. Length: 255

Home page of library (if is different from repository url).

## `export`

Optional | Type: `Object`

Explain PlatformIO Library Crawler which content from the repository/archive should be exported as “source code” of the library. This option is useful if need to exclude extra data (test code, docs, images, PDFs, etc). It allows one to reduce size of the final archive.

Possible options:

- `include`

- `exclude`

### `include`

Optional | Type: `String` or `Array` | Glob Pattern

If `include` field is a type of `String`, then PlatformIO Library Registry Crawler will recognize it like a “relative path inside repository/archive to library source code”. See example below where the only source code from the relative directory `LibrarySourceCodeHere` will be included.

    "include": "some/child/dir/LibrarySourceCodeHere"

If `include` field is a type of `Array`, then PlatformIO Library Registry Crawler will include only directories/files which match with `include` patterns.

Example:

    "export": {
        "include":
        [
            "dir/*.[ch]pp",
            "dir/examples/*",
            "*/*/*.h"
        ]
    }

Pattern Meaning

Pattern | Meaning
--- | ---
`*` | matches everything
`?` | matches any single character
`[seq]` | matches any character in seq
`[!seq]` | matches any character not in seq

See more `library.json` Examples.

### `exclude`

Optional | Type: `String` or `Array` | Glob Pattern

Exclude the directories and files which match with `exclude` patterns.

## `frameworks`

Optional | Type: `String` or `Array`

A list with compatible frameworks. The available framework types are defined in the Frameworks section.

If the library is compatible with the all frameworks, then you can use `*` symbol:

    "frameworks": "*"

## `platforms`

Optional | Type: `String` or `Array`

A list with compatible platforms. The available platform types are defined in Development Platforms section.

If the library is compatible with the all platforms, then you can use `*` symbol:

    "platforms": "*"

## `dependencies`

Optional | Type: `Array` or `Object`

A list of dependent libraries. They will be installed automatically with platformio lib install command.

Allowed requirements for dependent library:

- `name` | Type: `String`

- `version` | Type: `String`

- `authors` | Type: `String` or `Array`

- `frameworks` | Type: `String` or `Array`

- `platforms` | Type: `String` or `Array`

The `version` supports Semantic Versioning ( `<major>.<minor>.<patch>`) and can take any of the following forms:

- `1.2.3` - an exact version number. Use only this exact version

- `^1.2.3` - any compatible version (exact version for `1.x.x` versions

- `~1.2.3` - any version with the same major and minor versions, and an equal or greater patch version

- `>1.2.3` - any version greater than `1.2.3`. `>=`, `<`, and `<=` are also possible

- `>0.1.0,!=0.2.0,<0.3.0` - any version greater than `0.1.0`, not equal to `0.2.0` and less than `0.3.0`

The rest possible values including VCS repository URLs are documented in platformio lib install command.

Example:

    "dependencies":
    [
        {
            "name": "Library-Foo",
            "authors":
            [
                "Jhon Smith",
                "Andrew Smith"
            ]
        },
        {
            "name": "Library-Bar",
            "version": "~1.2.3"
        },
        {
            "name": "lib-from-repo",
            "version": "https://github.com/user/package.git#1.2.3"
        }
    ]

A short definition of dependencies is allowed:

    "dependencies": {
        "mylib": "1.2.3",
        "lib-from-repo": "githubuser/package"
    }

See more `library.json` Examples.

## `examples`

Optional | Type: `String` or `Array` | Glob Pattern

A list of example patterns. This field is predefined with default value:

    "examples": [
        "[Ee]xamples/*.c",
        "[Ee]xamples/*.cpp",
        "[Ee]xamples/*.ino",
        "[Ee]xamples/*.pde",
        "[Ee]xamples/*/*.c",
        "[Ee]xamples/*/*.cpp",
        "[Ee]xamples/*/*.ino",
        "[Ee]xamples/*/*.pde",
        "[Ee]xamples/*/*/*.c",
        "[Ee]xamples/*/*/*.cpp",
        "[Ee]xamples/*/*/*.ino",
        "[Ee]xamples/*/*/*.pde"
    ]

## `build`

Optional | Type: `Object`

Specify advanced settings, options and flags for the build system. Possible options:

- `flags`

- `unflags`

- `includeDir`

- `srcDir`

- `srcFilter`

- `extraScript`

- `libArchive`

- `libLDFMode`

- `libCompatMode`

### `flags`

Optional | Type: `String` or `Array`

Extra flags to control preprocessing, compilation, assembly and linking processes. More details build_flags.

### `unflags`

Optional | Type: `String` or `Array`

Remove base/initial flags which were set by development platform. More details build_unflags.

### `includeDir`

Optional | Type: `String`

New in version 4.0.

Custom location of library header files. A default value is `include` and means that folder is located in the root of a library.

### `srcDir`

Optional | Type: `String`

New in version 4.0.

Custom location of library source code. A default value is `src` and means that folder is located in the root of a library.

### `srcFilter`

Optional | Type: `String` or `Array`

Specify which source files should be included/excluded from build process. The path in filter should be relative from a root of library.

See syntax in src_filter.

Please note that you can generate source filter “on-the-fly” using `extraScript` (see below)

### `extraScript`

Optional | Type: `String`

Launch extra script before build process. More details extra_scripts.

Example (HAL-based library)

This example demonstrates how to build HAL-dependent source files and exclude other source files from a build process.

Project structure

    ├── lib
    │   ├── README
    │   └── SomeLib
    │       ├── extra_script.py
    │       ├── hal
    │       │   ├── bar
    │       │   │   ├── hal.c
    │       │   │   └── hal.h
    │       │   ├── foo
    │       │       ├── hal.c
    │       │       └── hal.h
    │       ├── library.json
    │       ├── SomeLib.c
    │       └── SomeLib.h
    ├── platformio.ini
    └── src
        └── test.c

`platformio.ini`

    [env:foo]
    platform = native
    build_flags = -DHAL=foo

    [env:bar]
    platform = native
    build_flags = -DHAL=bar

`library.json`

    {
        "name": "SomeLib",
        "version": "0.0.0",
        "build": {
            "extraScript": "extra_script.py"
        }
    }

`extra_script.py`

    Import('env')
    from os.path import join, realpath

    # private library flags
    for item in env.get("CPPDEFINES", []):
        if isinstance(item, tuple) and item[0] == "HAL":
            env.Append(CPPPATH=[realpath(join("hal", item[1]))])
            env.Replace(SRC_FILTER=["+<*>", "-<hal>", "+<%s>" % join("hal", item[1])])
            break

    # pass flags to a global build environment (for all libraries, etc)
    global_env = DefaultEnvironment()
    global_env.Append(
        CPPDEFINES=[
            ("MQTT_MAX_PACKET_SIZE", 512),
            "ARDUINOJSON_ENABLE_STD_STRING",
            ("BUFFER_LENGTH", 32)
        ]
    )

### `libArchive`

Optional | Type: `Boolean`

Create an archive (`*.a`, static library) from the object files and link it into a firmware (program). This is default behavior of PlatformIO Build System (`"libArchive": true`).

Setting `"libArchive": false` will instruct PIO Build System to link object files directly (in-line). This could be useful if you need to override `weak` symbols defined in framework or other libraries.

You can disable library archiving globally using lib_archive option in “platformio.ini” (Project Configuration File).

### `libLDFMode`

Optional | Type: `String`

Specify Library Dependency Finder Mode. See Dependency Finder Mode for details.

### `libCompatMode`

Optional | Type: `String`

Specify Library Compatibility Mode. See Compatibility Mode for details.

## Examples

1. Custom macros/defines

    "build": {
        "flags": "-D MYLIB_REV=1.2.3 -DRELEASE"
    }

2. Extra includes for C preprocessor

    "build": {
        "flags": [
            "-I inc",
            "-I inc/target_x13"
        ]
    }

3. Force to use `C99` standard instead of `C11`

    "build": {
        "unflags": "-std=gnu++11",
        "flags": "-std=c99"
    }

4. Build source files (`c, cpp, h`) at the top level of the library

    "build": {
        "srcFilter": [
            "+<*.c>",
            "+<*.cpp>",
            "+<*.h>"
        ]
    }

5. Extend PlatformIO Build System with own extra script

    "build": {
        "extraScript": "generate_headers.py"
    }

`generate_headers.py`

    Import('env')
    # print(env.Dump())
    env.Append(
        CPPDEFINES=["HELLO=WORLD", "TAG=1.2.3", "DEBUG"],
        CPPPATH=["inc", "inc/devices"]
    )

    # some python code that generates header files "on-the-fly"