Installation #
Using single_include
#
The ingle_include/toml.hpp
s 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/