Installation #

Using single_include #

The ingle_include/toml.hpps is a single-file, header-only library that consolidates all the functionalities of toml11 into one file.

The simplest way to use it is to copy this file to a location included in your INCLUDE_PATH and then add #include <toml.hpp> to your source code.

The MIT license notice is included in both the comments and the toml::license_notice() function. If you are redistributing the software without releasing the source code, you must either copy the toml11 license file and include it with your distribution, or ensure that the toml::license_notice() function can be called.

Cloning toml11 and using cmake #

If you place toml11 within your repository, for example by using git submodule, and you are using cmake, you can make use of it by adding add_subdirectory(toml11) to your CMakeLists.txt.

add_subdirectory(toml11)
add_executable(main main.cpp)
target_link_libraries(main PUBLIC toml11::toml11)

toml11 will only run tests and install when it is the root project.

Installing using cmake #

After cloning toml11, you can install it using cmake.

$ cmake -B ./build/ -DTOML11_BUILD_TESTS=ON
$ cmake --install ./build/ --prefix=/opt/toml11

If you want to run the test programs before installation, make sure to set -DTOML11_BUILD_TESTS=ON first.

Once the installation is complete, you can use it as follows:

find_package(toml11)
add_executable(main main.cpp)
target_link_libraries(main PRIVATE toml11::toml11)

Compiling with cmake to Create a Static Library #

By defining -DTOML11_PRECOMPILE=ON when running cmake, you can precompile some of the functions in toml11, thereby reducing the overall compile time.

$ cmake -B ./build/ -DTOML11_PRECOMPILE=ON

When linking the library, use target_link_libraries in CMake

target_link_libraries(your_target PUBLIC toml11::toml11)

or pass -DTOML11_COMPILE_SOURCES to the compiler to suppress header-only features.

However, since toml11 supports multiple C++ versions and may switch types based on the value of __cplusplus, there is a possibility of link failures if the version used during build differs from the version used during usage. If you encounter issues, set the required version using CMAKE_CXX_STANDARD during compilation. If this is difficult, use it as a header-only library as usual.

The find_package(toml11) command defines TOML11_INCLUDE_DIR. Even if you install it as a precompiled library, you can still use it as a header-only library by adding TOML11_INCLUDE_DIR to target_include_directories and avoiding the use of target_link_libraries.

find_package(toml11)
add_executable(main main.cpp)
# Include only, do not link
target_include_directories(main PRIVATE ${TOML11_INCLUDE_DIR})

Compiling Examples #

You can compile the examples/ directory by setting -DTOML11_BUILD_EXAMPLES=ON.

$ cmake -B ./build/ -DTOML11_BUILD_EXAMPLES=ON
$ cmake --build ./build/

The executable binaries for the examples will be generated in the examples/ directory.

Running Tests #

To build the tests, set -DTOML11_BUILD_TESTS=ON.

$ git submodule update --init --recursive
$ cmake -B ./build/ -DTOML11_BUILD_TESTS=ON
$ cmake --build ./build/
$ ctest --test-dir ./build/

To run the toml-lang/toml-tests, set -DTOML11_BUILD_TOML_TESTS=ON. This will build toml11_decoder and toml11_encoder in the tests/ directory.

$ git submodule update --init --recursive
$ cmake -B ./build/ -DTOML11_BUILD_TOML_TESTS=ON
$ cmake --build ./build/
$ ctest --test-dir ./build/