////
Copyright (c) 2024 The C++ Alliance, Inc. (https://cppalliance.org)

Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Official repository: https://github.com/boostorg/website-v2-docs
////
= Library Metadata
:idprefix:
:idseparator: -
:navtitle: Metadata
     
The sources for each library, or possibly a number of related libraries, is contained in a sub-module of the xref:version-control.adoc#super-project[Boost super-project].
Each sub-module _must_ contain a file which describes the libraries that it contains. This is located at `meta/libraries.json`.

== Json Objects

If the sub-module contains a single library, `libraries.json` should contain a single object, for example:

```
{
    "key": "unordered",
    "name": "Unordered",
    "authors": [
        "Daniel James"
    ],
    "maintainers": [
        "Daniel James <dnljms -at- gmail.com>"
    ],
    "description": "Unordered associative containers.",
    "std": [
        "tr1"
    ],
    "category": [
        "Containers"
    ],
    "cxxstd": "03"
}
```
Or view: https://github.com/vinniefalco/unordered/blob/d05824312f4b4748f8975a4bdb9e51bfc10327b2/meta/libraries.json[unordered/meta
/libraries.json].

=== Multiple Libraries

If the sub-module contains multiple libraries, `libraries.json` should contain a list of objects, for example:

```
[
    {
        "key": "algorithm",
        "name": "Algorithm",
        "authors": [
            "Marshall Clow"
        ],
        "description": "A collection of useful generic algorithms.",
        "category": [
            "Algorithms"
        ],
        "maintainers": [
            "Marshall Clow <marshall -at- idio.com>"
        ],
        "cxxstd": "03"
    },
    {
        "key": "algorithm/minmax",
        "name": "Min-Max",
        "authors": [
            "Hervé Brönnimann"
        ],
        "description": "Standard library extensions for simultaneous min/max and min/max element computations.",
        "documentation": "minmax/",
        "category": [
            "Algorithms"
        ],
        "maintainers": [
            "Marshall Clow <marshall -at- idio.com>"
        ],
        "cxxstd": "03"
    },
    {
        "key": "algorithm/string",
        "name": "String Algo",
        "authors": [
            "Pavol Droba"
        ],
        "description": "String algorithms library.",
        "documentation": "string/",
        "category": [
            "Algorithms",
            "String"
        ],
        "maintainers": [
            "Marshall Clow <marshall -at- idio.com>"
        ],
        "cxxstd": "03"
    }
]
```

Or view: https://github.com/boostorg/algorithm/blob/28dd87b90e79c5e1d9de82835125aa2bcbb3f468/meta/libraries.json[algorithm/meta/libraries.json].


== Json Fields

All meta files should contain `key`, `name`, `description`, `authors`, `maintainers`, and `category`. The other fields are optional. 

=== `key`

This is a unique identifier for the library, typically the path to it from the `libs` directory.

=== `boost-version`

The Boost version where the library was first added, such as: `"boost-version": "1.33.0"`.

=== `name`

Human friendly name of the library.

=== `status`

Used for libraries with special statuses, currently can have the value `deprecated` for deprecated libraries, and `hidden` for libraries which shouldn't be displayed to the user. Hidden libraries include *detail* and *winapi*, both of which are hidden because they are used as components of other libraries, and not intended as stand-alone libraries themselves.

The library https://github.com/boostorg/coroutine/blob/1e1347c0b1910b9310ec1719edad8b0bf2fd03c8/meta/libraries.json[coroutine] is marked as "deprecated", though this does not mean full deprecation as this library is part of the Boost super-project, and will be tested each time the super-project is tested.

=== `authors`

Strings containing the names of the authors.

=== `description`

A brief description of the purpose of the library.

=== `maintainers`

One, or more, strings containing both the names and, usually, email addresses of the maintainers.

=== `std`

This is now an unused field.

=== `category`

A list of one or more of the <<Categories>> that the library belongs to.

=== `documentation`

Path to the documentation, defaults to the root of the module.

=== `cxxstd`

The minimum pass:[C++] standard compilation level at which all, or the large majority, of the functionality in the library is usable. The possible values are: 

* 98 = pass:[C++]98
* 03 = pass:[C++]03
* 11 = pass:[C++]11
* 14 = pass:[C++]14
* 17 = pass:[C++]17
* 20 = pass:[C++]20
* 23 = pass:[C++]23

The level only indicates the minimum level, which means that the functionality of the library can be used when compiling at that level or at a higher level. There may be some functionality in the library which will need a higher pass:[C++] standard compilation level than is indicated by this value, but the information about that specific functionality will be provided for the end-user within the documentation for that library. If a library does not have this field it indicates that the end-user will have to read the library documentation to understand what pass:[C++] standard compilation level is needed to use the library. 

Note that `11` and `14` are commonly set minimum levels.

== Categories

A library can be in one or more categories. The string is not case-sensitive. In some cases, the string used to describe the category on our website is slightly more descriptive than the string used in the `category` field.

[cols="1,2",options="header",stripes=none]
|===
| Metadata Category | Website Category
| `Algorithms` | Algorithms
| `Concurrent`| Concurrent Programming
| `Containers` | Containers
| `Correctness`| Correctness and testing
| `Data` | Data structures
| `Domain` | Domain Specific
| `Emulation` | Language Features Emulation
| `Error-handling` | Error handling and recovery
| `Function-objects` | Function objects and higher-order programming
| `Generic` | Generic Programming
| `Image-processing` | Image processing
| `IO` | Input/Output
| `Inter-language` | Inter-language support
| `Iterators` | Iterators
| `Math` | Math and numerics
| `Memory` | Memory
| `Metaprogramming` | Template Metaprogramming
| `Miscellaneous` | Miscellaneous
| `Parsing` | Parsing
| `Patterns` | Patterns and Idioms
| `Preprocessor` | Preprocessor Metaprogramming
| `Programming` | Programming Interfaces
| `State` | State Machines
| `String` | String and text processing
| `System` | System
| `Workarounds` | Broken compiler workarounds
|===

== See Also

* https://www.boost.org/doc/libs/latest/libs/libraries.htm[Boost Libraries]

