fkYAML is a C++ header-only YAML library.
If you want portability & development speed-up, fkYAML is the way to go.
No need to build a library only for a third party project.
You can add YAML support into your projects by just including header files where it's needed.
- Design goals
- Community Support
- How to use fkYAML
- How to test fkYAML
- Supported compilers
- Benchmarking
- License
- Used third-party tools
There are a lot of YAML libraries out there, and each may have its reason to exist.
fkYAML has been developed with these design goals:
The library depends only on C++ standards, and is carefully designed to work on many platforms so that fkYAML can be imported into existing C++ projects written in C++11 or better.
No external dependencies, no sub-project, or no additional compiler flags are required.
Although fkYAML is a library with multiple header files by default, you can use the single-header version (single_include/fkYAML/node.hpp) located in the single_include directory. You can further use single_include/fkYAML/fkyaml_fwd.hpp for forward declarations.
Furthermore, the project supports CMake and provides the documentation exclusively for CMake integration.
Those characteristics allow existing C++ project using CMake for builds to quickly incorporate YAML support with just a little effort.
The documentation provides plenty of information so that users can understand what fkYAML is and what they can achieve with fkYAML.
For instance, the tutorial pages show how you can read/write/customize fkYAML to handle YAML documents while creating a simple C++ project using CMake.
More detailed, exclusive descriptions with example usages for each fkYAML API are available in the API reference pages.
fkYAML has been unit-tested and its test suite covers 100% of lines and conditions of the codebase. (You can see the actual coverage here.)
We check with Valgrind and the Clang Sanitizers that there are no runtime issues such as memory leak.
Furthermore, the quality of our codebase has been checked with Clang-Tidy and CodeQL.
GitHub Actions workflows run against every commit pushed on the main & develop branches to ensure that the fkYAML library can be successfully built/tested with a variety of compilers and C++ standards.
See the supported compilers section for more details.
If you have questions regarding the fkYAML library, feel free to open a Q&A discussion at GitHub.
If you have feature requests for the fkYAML library, let us know by opening an Ideas discussion.
It's really helpful for us if you describe what the new feature aims at and why it's needed.
If you encounter a issue or find a bug, open an issue.
Please describe your problem as detailed as possible, and also mention the version of the library you are using as well as the versions of your compiler and operating system.
Opening an issue at GitHub allows other users and contributors to this library to collabolate.
If you want to make a private report (e.g., for a vulnerability or to attach an example that is not meant to be published), please send an email to [email protected].
The documentation is available on GitHub Pages.
Here is the list you might want to know:
- Tutorial - getting started
- CMake Integration - CMake integration with your project
- API references - all the details with examples
You can execute the unit tests with the following commands.
Make sure the CMake executable has been registered to your PATH.
$ cd path/to/fkYAML
$ cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug -DFK_YAML_BUILD_TEST=ON
$ cmake --build build --config Debug
$ ctest -C Debug --test-dir build --output-on-failureCurrently, the following compilers are known to work and used in GitHub Actions workflows:
| Compiler | Operating System |
|---|---|
| AppleClang 14.0.0.14000029 | macOS 13 |
| AppleClang 14.0.3.14030022 | macOS 13 |
| AppleClang 15.0.0.15000040 | macOS 13 |
| AppleClang 15.0.0.15000040 | macOS 14 |
| AppleClang 15.0.0.15000100 | macOS 13 |
| AppleClang 15.0.0.15000100 | macOS 14 |
| AppleClang 15.0.0.15000309 | macOS 14 |
| AppleClang 16.0.0.16000026 | macOS 15 |
| Clang 3.4.2 | Ubuntu 22.04 |
| Clang 3.5.2 | Ubuntu 22.04 |
| Clang 3.6.2 | Ubuntu 22.04 |
| Clang 3.7.1 | Ubuntu 22.04 |
| Clang 3.8.1 | Ubuntu 22.04 |
| Clang 3.9.1 | Ubuntu 22.04 |
| Clang 4.0.1 | Ubuntu 22.04 |
| Clang 5.0.2 | Ubuntu 22.04 |
| Clang 6.0.1 | Ubuntu 22.04 |
| Clang 7.1.0 | Ubuntu 22.04 |
| Clang 9.0.1 | Ubuntu 22.04 |
| Clang 10.0.1 | Ubuntu 22.04 |
| Clang 11.1.0 | Ubuntu 22.04 |
| Clang 12.0.1 | Ubuntu 22.04 |
| Clang 13.0.1 | Ubuntu 22.04 |
| Clang 14.0.6 | Ubuntu 22.04 |
| Clang 15.0.7 | Ubuntu 22.04 |
| Clang 16.0.6 | Ubuntu 22.04 |
| Clang 17.0.6 | Ubuntu 22.04 |
| Clang 18.1.6 | Ubuntu 22.04 |
| Clang 19.1.4 | Ubuntu 22.04 |
| GCC 4.8.5 | Ubuntu 22.04 |
| GCC 5.3.1 | Ubuntu 22.04 |
| GCC 6.4.0 | Ubuntu 22.04 |
| GCC 7.5.0 | Ubuntu 22.04 |
| GCC 8.5.0 | Ubuntu 22.04 |
| GCC 9.5.0 | Ubuntu 22.04 |
| GCC 10.5.0 | Ubuntu 22.04 |
| GCC 11.4.0 | Ubuntu 22.04 |
| GCC 12.3.0 | Ubuntu 22.04 |
| GCC 13.3.0 | Ubuntu 22.04 |
| GCC 14.2.0 | Ubuntu 22.04 |
| IntelLLVM 2024.1.2 | Ubuntu 22.04 |
| MinGW-64 8.1.0 | Windows Server 2019 |
| MinGW-64 12.2.0 | Windows Server 2022 |
| Visual Studio 16 2019 | Windows Server 2019 |
| Visual Studio 17 2022 | Windows Server 2022 |
Requests for new compiler supports are welcome.
If you encounter a problem regarding compilers, please let us know by creating an issue or a PR with the information of your Operating System so that the same situation can be reproduced.
Though efficiency is not everything, speed and memory consumption are very important characteristics for C++ developers. Regarding speed, benchmarking scores are now available with the dedicated benchmarking tool for the parsing.
The following tables are created from the benchmarking results in the following environment:
- CPU: AMD Ryzen 7 5800H @3.20GHz
- OS: Ubuntu22.04 (WSL2)
- Compiler: g++11.4.0
Parsing ubuntu.yml
| Benchmark | processed bytes per second (Release) |
|---|---|
| fkYAML | 60.1886Mi/s |
| libfyaml | 34.9689Mi/s |
| rapidyaml (with mutable buff) |
19.4415Gi/s |
| rapidyaml (with immutable buff) |
139.381Mi/s |
| yaml-cpp | 8.8139Mi/s |
Parsing citm_catalog.json
| Benchmark | processed bytes per second (Release) |
|---|---|
| fkYAML | 91.1523Mi/s |
| libfyaml | 51.8156Mi/s |
| rapidyaml (with mutable buff) |
29.7284Gi/s |
| rapidyaml (with immutable buff) |
140.764Mi/s |
| yaml-cpp | 14.8521Mi/s |
Parsing citm_catalog.yml
| Benchmark | processed bytes per second (Release) |
|---|---|
| fkYAML | 36.0492Mi/s |
| libfyaml | 21.547Mi/s |
| rapidyaml (with mutable buff) |
22.6904Gi/s |
| rapidyaml (with immutable buff) |
64.3972Mi/s |
| yaml-cpp | 6.2337Mi/s |
Although rapidyaml is about 2x faster with immutable buffers and far faster with mutable buffers than fkYAML as it focuses on high performance, fkYAML is in general 70% faster than libfyaml and also about 6x faster than yaml-cpp.
Note that, since fkYAML deserializes scalars into native booleans or integers during the parsing, the performance could be more faster in some use cases since there is no need for string manipulations upon data queries.
This project is distributed under the MIT License:
Copyright (c) 2023-2024 Kensuke Fukutani
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
See the CONTRIBUTING.md file for detailed information.
The library itself depends only on C++ standards and licensed under the MIT licence.
However, it is built, tested or documented with a lot of third-party tools and services.
Thanks a lot!
- amalgamate.py - Amalgamate C source and header files to generate a single header file.
- Clang for compilation, coding style checks, and static/runtime analysis.
- CMake for automation of build & testing.
- Codacy for further code analysis.
- Coveralls to measure code coverage.
- Catch2 as a unit-test framework.
- Google Benchmark as a benchmarking framework.
- github-changelog-generator to generate the CHANGELOG.md file.
- include-what-you-use to check the fkYAML library source files are each self-contained.
- lcov to process coverage information and generate an HTML view.
- Material for MkDocs for the style of the documentation site.
- MkDocs as the documentation site generator.
- reuse-tool to generate license/copyright headers in source files to meet REUSE software recommendations.
- Valgrind for runtime memory leak check.