kapidox/docs/metainfo_syntax.md

0001 # Description of the metainfo.yml syntax {#metainfo_syntax}
0002 The name is the folder name.
0003 The fancyname is the project name used in CMake.
0004
0005 Each group must contain one and only one library with the `group_info` block. If
0006 more are defined, the behavior is unknown.
0007
0008 **Be sure to to set `public_lib` to true, or the library will be ignored.** Most of
0009 the other keys are optionals. See below for a simpler example.
0010
0011 ## All possible keys.
0012
0013 ~~~{.yaml}
0014 description: Library doing X and Y
0015 fancyname: The FancyName # optional, else replaced by the `project()` value of the `CMakeLists.txt`
0016 repo_id: klib  # optional, defaults to base name of directory with the metainfo.yaml file
0017 maintainer: ochurlaud  # optional, replaced by The KDE Community
0018 group: frameworks # optional
0019 subgroup: tier 1 # optional, a group must be defined
0020 type: functional  # optional
0021 logo: relative/path/to/logo.png # Used only if not part of a group, defaults to logo.png if present
0022 platforms:  # optional, name accepted: all, Linux, FreeBSD, Windows, macOS, Android
0023     - name: Linux
0024       note: Functional only with running BlueZ 5 # optional
0025 public_lib: true  # if not defined, the library is ignored
0026 public_source_dirs:  # optional, default to src, must be a list
0027   - src1
0028   - src2
0029 public_doc_dir: docs  # optional, default to docs
0030 public_example_dirs: examples  # optional, default to examples, must be a list
0031
0032 portingAid: true/false  # optional, default to false
0033 deprecated: true/false  # optional, default to false
0034 libraries: KF5::MyLib  # optional
0035
0036 libraries:  # optional
0037   - qmake: BluezQt
0038     cmake: KF5::BluezQt
0039     license: LGPL-2.1-only OR LGPL-3.0-only # optional, SPDX expression that states outbound license of library
0040 cmakename: KF5BluezQt  # optional
0041
0042 irc: kde  # optional, overwrite group field, if both not defined, default to kde-devel
0043 mailinglist: mylib-dev  # optional, overwrite group field, if both not defined, default to kde-devel
0044
0045 group_info: # optional, only once per group
0046   name: frameworks # optional, else the name is defined by the 'group' key above.
0047   fancyname: The KDE Frameworks
0048   maintainer: dfaure
0049   irc: kde-devel
0050   mailinglist: kde-core-devel
0051   platforms:
0052     - Linux
0053     - Windows (partial)
0054     - macOS (partial)
0055   description: Providing everything from simple utility classes to ..
0056   logo: relative/path/to/logo.png # optional, defaults to logo.png if present
0057   long_description: # optional, one item per paragraph, html authorized
0058     - The KDE Frameworks build on the <a href="https://www.qt.io">Qt
0059       framework</a>, providing everything from simple utility classes (such as
0060       those in KCoreAddons) to integrated solutions for common requirements of
0061       desktop applications (such as KNewStuff, for fetching downloadable add-on
0062       content in an application, or the powerful KIO multi-protocol file access
0063       framework).
0064     - ....
0065   subgroups: # every subgroup must be declared here or will be ignored
0066     - name: Tier 1
0067       description: Tier 1 frameworks depend only on Qt (and possibly a small number of other third-party libraries), so can easily be used by an Qt-based project.
0068     - name: Tier 2
0069       description: Tier 2 frameworks additionally depend on tier 1 frameworks, but still have easily manageable dependencies.
0070     - ..
0071 ~~~
0072
0073 ## Simple example 1
0074
0075 In this case, the library is not part of a group, and the source is in `src`. If
0076 there is no logo, a default one is used.
0077
0078 ~~~{.yaml}
0079 description: Library doing X
0080 maintainer: ochurlaud
0081 public_lib: true
0082 logo: libX.png
0083 ~~~
0084
0085 ## Simple example 2
0086
0087 In this case, the libraries X and Y are part of the same group `XY`, and the
0088 source is in `src`.
0089
0090 ### libX
0091
0092 ~~~{.yaml}
0093 description: Library doing X
0094 maintainer: ochurlaud
0095 public_lib: true
0096 platforms:
0097   - name: Linux
0098   - name: Windows
0099     note: doesn't work with Windows10
0100 group: XY
0101
0102 group_info:
0103   fancyname: XY Libraries
0104   maintainer: arandomguy
0105   platforms:
0106     - Linux
0107     - Windows (partial)
0108   description: XY provides ...
0109   logo: logo_XY.png
0110   long_description:
0111     - XY does this and this
0112     - If you want to contribute please write to ...
0113 ~~~
0114
0115 ### libY
0116
0117 ~~~{.yaml}
0118 description: Library doing Y
0119 maintainer: otherrandomguy
0120 public_lib: true
0121 platforms:
0122   - name: Linux
0123 group: XY
0124 ~~~