Contributions are very welcome! Either by reporting issues or submitting pull requests. If you wish to submit a PR, please be aware that:
- The single-header
toml.hppat the repository root is generated, so don't change it directly; make your changes in the files ininclude. You can leave it out of your PR too (see Generated files). - Your changes should compile warning-free with a recent GCC, Clang or MSVC. CI builds every PR with all three, and with Apple Clang.
If you've added a new header file that isn't going to be transitively included by one of the others, add an include
directive to include/toml++/toml.hpp.
For the most part the library tries to look like idiomatic standard-library-style C++, so between that and using pre-commit/clang-format, there's not much to think about.
One thing to be very aware of is compile times - the library is primarly a header-only project, so
many choices are made to avoid including certain expensive standard-library headers (e.g. <filesystem>, <algorithm>).
toml.hpp and a few other files are derived from include and VERSION.txt. You shouldn't need to do anything to keep
them up to date:
- Building from a git checkout with CMake or Meson regenerates them. Only files that actually changed get written, so this doesn't cause rebuilds on its own.
pre-commit installadds a hook that regenerates them when you commit.- After a merge, CI commits anything still out of date to
master.
If you need it, python3 tools/regenerate.py does the same by hand, and --check reports what's out of date without
changing anything. It only needs Python.
Testing is done using Catch2. It's vendored, as is everything else the tests use, so a compiler and CMake or Meson are all you need.
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -Dtomlplusplus_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failureWith Visual Studio or another multi-config generator, pass --config Debug to the build and -C Debug to ctest.
Set the language standard with CMAKE_CXX_STANDARD. The other options (examples, sanitizers, the compiled library,
unreleased TOML features and so on) are in cmake/variables.cmake, and .github/workflows/ci.yaml shows the
combinations CI tests.
meson setup build --buildtype=debug -Ddevel=true
meson test -C build-Ddevel=true builds the tests, the examples and the toml-test encoder and decoder, with all warnings on. Meson 0.61
or later works; pipx install meson gets the latest.
ℹ️ Pass
-Duse_vendored_libs=falseto Meson if you wish to use the system-installed version of Catch2 (v3 or newer) rather than the vendored one.
The library turns some groups of warnings off inside its own headers, so that it can't break a user's build that
treats warnings as errors. A pedantic build (-Dtomlplusplus_PEDANTIC=ON with CMake, -Dpedantic=true or
-Ddevel=true with Meson) defines TOML_PEDANTIC, which leaves the switch, arithmetic and analysis groups on.
A warning that such a build reports in library code is fixed, or suppressed where it fires.
The tests run once per locale, and a run whose locale isn't installed is reported as skipped. On Debian and Ubuntu,
sudo apt install locales-all installs all of them.
A test for a document that must fail to parse states the error it expects, as line:column: description:
parsing_should_fail(FILE_LINE_ARGS, "int = 0o8"sv, "1:9: Error while parsing octal integer: expected octal digit, saw '8'"sv);When the expectation is wrong, the test prints the error it saw, so a first run can supply one. Read it against the
input before keeping it. Where a build option changes the error, put each expectation under the option, as the
TOML_LANG_UNRELEASED blocks in the parsing tests do.
The conformance tests generated from toml-test call parsing_should_fail without an expectation. Hand-written tests
always give one.
Coverage needs Clang, plus the llvm-profdata and llvm-cov of the same version on PATH:
cmake -S . -B build -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Debug \
-Dtomlplusplus_BUILD_TESTS=ON -Dtomlplusplus_COVERAGE=ON
cmake --build build
ctest --test-dir build
python3 tools/coverage.py buildThe HTML report goes in build/coverage/html. The report for master is on the
homepage.
CI also builds the tests with -Dtomlplusplus_EXCEPTIONS=OFF -Dtomlplusplus_UNRELEASED_FEATURES=ON, and measures the two
builds together, so that code compiled out of one build still counts. Give coverage.py several build directories to
merge them the same way.
OSS-Fuzz fuzzes toml++ continuously, and CIFuzz runs the same fuzzers on every PR. Both build the fuzzers in
fuzzing/ with fuzzing/build.sh. OSS-Fuzz takes build.sh from master, so a change to it only takes effect after
merge.
There are three fuzzers:
toml_fuzzerparses its input from a string and from two kinds of stream, and checks that all three give the same result. It then prints each document that parses, and checks that the printed text parses to an equal table.toml_no_exceptions_fuzzeris the same code, built without exceptions and with assertions and unreleased TOML features on. It needs toml++ to be header-only.toml_float_fuzzerchecks the exact text that floats print as: the shortest digits that read back as the same value, in the layout the formatters use.
The input to the first two is a TOML document and nothing else, so a crash file is the document that failed. They skip documents over 4 KiB, because a document's printed size can grow with the square of its size.
To run one locally with Clang and libFuzzer:
CXX=clang++ CXXFLAGS="-fsanitize=address,fuzzer-no-link" LIB_FUZZING_ENGINE=-fsanitize=fuzzer \
cmake -S . -B build-fuzz -DCMAKE_BUILD_TYPE=Release -DBUILD_FUZZER=ON
cmake --build build-fuzz --target toml_fuzzer
build-fuzz/fuzzing/toml_fuzzer -dict=fuzzing/toml.dictCMake warns that it can't install the fuzzers without $OUT. That only matters to OSS-Fuzz.
tomlplusplus_BUILD_BENCHMARKS builds a program that times parsing and formatting. It uses
examples/benchmark_data.toml and a set of generated documents: mixed content, strings, numbers, non-ASCII text, deep
nesting and lots of small tables. Build it with optimisations:
cmake -S . -B build-bench -DCMAKE_BUILD_TYPE=Release -Dtomlplusplus_BUILD_BENCHMARKS=ON
cmake --build build-bench --config Release
build-bench/benchmarks/tomlplusplus_benchmarksWith Visual Studio or another multi-config generator, the program is in build-bench/benchmarks/Release.
Arguments filter the benchmarks by name, so tomlplusplus_benchmarks parse runs only the parsing ones. The generated
documents are the same in every build, so to measure a change, build both versions with the same compiler and run them
on the same machine.
Every timed parse starts from a heap shaped by the allocations before it, so a change that only alters the size or
number of allocations can move a result by up to 20% either way. With glibc, GLIBC_TUNABLES=glibc.malloc.mxfast=0
turns off the fast bins behind most of this, and results then hold to about 1%. Elsewhere, time one benchmark at a time
by passing its full name.
The address a hot function is linked at can also move a result, by up to 10%, with no change to its code. GCC and Clang builds of the benchmark align every function to 64 bytes for that reason.
Testing with the toml-test suite
As an optional extra you may wish to test against the official TOML test suite, toml-test. See the instructions at toml-test/README. Note that the toml++ tests already consume tests from the official suite via a C++ code-generation script so you are not expected to take this extra step as part of contributing to the library.
The version is stored in one place: VERSION.txt at the repository root, a bare major.minor.patch triplet. Everything
that restates it (version.hpp, toml.hpp, the natvis file and the install snippets in the docs) is one of the
generated files above. Changing the version also renames the Unreleased heading in CHANGELOG.md and starts a new one.
Releases are automated and maintainer-only. Bumping VERSION.txt on master cuts a release: once CI passes, it creates
the v<version> tag and a GitHub release with toml.hpp attached.
The practical upshot for a PR: don't touch VERSION.txt. I bump it myself when cutting a release, so a PR that also
bumps it just invites a merge conflict or an accidental release. User-visible changes go under the Unreleased heading at
the top of CHANGELOG.md.