zhangyiss/toml11
1
0
Fork 0
mirror of https://github.com/ToruNiina/toml11.git synced 2025-09-18 02:08:09 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
Files
gh-pages
toml11/docs/installation/index.html
ToruNiina e671b8e3bd Merge pull request #291 from franzpoeschel/namespace-versioning 
Use an inline namespace to distinguish emitted symbols by version numbers e4051f77d7
2025-05-17 07:21:19 +00:00

87 lines
23 KiB
HTML
Raw Permalink Blame History

<!doctype html><html lang=en dir=ltr><head><meta charset=UTF-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="
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."><meta name=theme-color media="(prefers-color-scheme: light)" content="#ffffff"><meta name=theme-color media="(prefers-color-scheme: dark)" content="#343a40"><meta name=color-scheme content="light dark"><meta property="og:url" content="https://toruniina.github.io/toml11/docs/installation/"><meta property="og:site_name" content="toml11"><meta property="og:title" content="installation"><meta property="og:description" content="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."><meta property="og:locale" content="en"><meta property="og:type" content="website"><title>installation | toml11</title>
<link rel=manifest href=/toml11/manifest.json><link rel=icon href=/toml11/favicon.png><link rel=canonical href=https://toruniina.github.io/toml11/docs/installation/><link rel=alternate hreflang=ja href=https://toruniina.github.io/toml11/ja/docs/installation/ title=installation><link rel=stylesheet href=/toml11/book.min.ddac3efe7ea4c1007ff53e5a8fd67f12517e5d2e99984d8c67a18668f7ecaa03.css integrity="sha256-3aw+/n6kwQB/9T5aj9Z/ElF+XS6ZmE2MZ6GGaPfsqgM=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.db4a558804ac41f081539588cec8e4a415587801da466728166bb5341dd62411.js integrity="sha256-20pViASsQfCBU5WIzsjkpBVYeAHaRmcoFmu1NB3WJBE=" crossorigin=anonymous></script><link rel=alternate type=application/rss+xml href=https://toruniina.github.io/toml11/docs/installation/index.xml title=toml11></head><body dir=ltr><input type=checkbox class="hidden toggle" id=menu-control>
<input type=checkbox class="hidden toggle" id=toc-control><main class="container flex"><aside class=book-menu><div class=book-menu-content><nav><h2 class=book-brand><a class="flex align-center" href=/toml11/><span>toml11</span></a></h2><div class="book-search hidden"><input type=text id=book-search-input placeholder=Search aria-label=Search maxlength=64 data-hotkeys=s/><div class="book-search-spinner hidden"></div><ul id=book-search-results></ul></div><script>document.querySelector(".book-search").classList.remove("hidden")</script><ul class=book-languages><li><input type=checkbox id=languages class=toggle>
<label for=languages class="flex justify-between"><a role=button class="flex align-center"><img src=/toml11/svg/translate.svg class=book-icon alt=Languages>
English</a></label><ul><li><a href=https://toruniina.github.io/toml11/ja/docs/installation/>日本語</a></li></ul></li></ul><ul><li><a href=/toml11/docs/installation/ class=active>installation</a><ul></ul></li><li><input type=checkbox id=section-291123c850af98d8b815ccdbb4c33657 class=toggle>
<label for=section-291123c850af98d8b815ccdbb4c33657 class="flex justify-between"><a href=/toml11/docs/features/>features</a></label><ul><li><a href=/toml11/docs/features/parsing_files/>parsing files</a></li><li><a href=/toml11/docs/features/value/>getting values</a></li><li><a href=/toml11/docs/features/error_message/>error message</a></li><li><a href=/toml11/docs/features/serialize/>serializing values</a></li><li><a href=/toml11/docs/features/configure_types/>configuring types</a></li><li><a href=/toml11/docs/features/literal/>toml literal</a></li><li><a href=/toml11/docs/features/toml_spec/>toml spec</a></li><li><a href=/toml11/docs/features/extension/>extension</a></li></ul></li><li><input type=checkbox id=section-e2e812e55021b82e114feaae98f1a02e class=toggle>
<label for=section-e2e812e55021b82e114feaae98f1a02e class="flex justify-between"><a href=/toml11/docs/reference/>reference</a></label><ul><li><a href=/toml11/docs/reference/color/>color.hpp</a></li><li><a href=/toml11/docs/reference/comments/>comments.hpp</a></li><li><a href=/toml11/docs/reference/conversion/>conversion.hpp</a></li><li><a href=/toml11/docs/reference/datetime/>datetime.hpp</a></li><li><a href=/toml11/docs/reference/error_info/>error_info.hpp</a></li><li><a href=/toml11/docs/reference/exception/>exception.hpp</a></li><li><a href=/toml11/docs/reference/find/>find.hpp</a></li><li><a href=/toml11/docs/reference/format/>format.hpp</a></li><li><a href=/toml11/docs/reference/from/>from.hpp</a></li><li><a href=/toml11/docs/reference/get/>get.hpp</a></li><li><a href=/toml11/docs/reference/into/>into.hpp</a></li><li><a href=/toml11/docs/reference/literal/>literal.hpp</a></li><li><a href=/toml11/docs/reference/ordered_map/>ordered_map.hpp</a></li><li><a href=/toml11/docs/reference/parser/>parser.hpp</a></li><li><a href=/toml11/docs/reference/result/>result.hpp</a></li><li><a href=/toml11/docs/reference/serializer/>serializer.hpp</a></li><li><a href=/toml11/docs/reference/source_location/>source_location.hpp</a></li><li><a href=/toml11/docs/reference/spec/>spec.hpp</a></li><li><a href=/toml11/docs/reference/toml_fwd/>toml_fwd.hpp</a></li><li><a href=/toml11/docs/reference/toml/>toml.hpp</a></li><li><a href=/toml11/docs/reference/types/>types.hpp</a></li><li><a href=/toml11/docs/reference/value_t/>value_t.hpp</a></li><li><a href=/toml11/docs/reference/value/>value.hpp</a></li><li><a href=/toml11/docs/reference/version/>version.hpp</a></li><li><a href=/toml11/docs/reference/visit/>visit.hpp</a></li></ul></li><li><a href=/toml11/docs/changelog/>changelog</a><ul></ul></li></ul><ul><li><a href=https://github.com/ToruNiina/toml11 target=_blank rel=noopener>GitHub</a></li></ul></nav><script>(function(){var e=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script></div></aside><div class=book-page><header class=book-header><div class="flex align-center justify-between"><label for=menu-control><img src=/toml11/svg/menu.svg class=book-icon alt=Menu>
</label><strong>installation</strong>
<label for=toc-control><img src=/toml11/svg/toc.svg class=book-icon alt="Table of Contents"></label></div><aside class="hidden clearfix"><nav id=TableOfContents><ul><li><a href=#installation>Installation</a><ul><li><a href=#using-single_include>Using <code>single_include</code></a></li><li><a href=#cloning-toml11-and-using-cmake>Cloning toml11 and using cmake</a><ul><li><a href=#cmake-fetchcontent>CMake <code>FetchContent</code></a></li><li><a href=#cmake-package-manager-cpm>CMake Package Manager (CPM)</a></li></ul></li><li><a href=#installing-using-cmake>Installing using cmake</a></li><li><a href=#compiling-with-cmake-to-create-a-static-library>Compiling with cmake to Create a Static Library</a></li><li><a href=#compiling-examples>Compiling Examples</a></li><li><a href=#running-tests>Running Tests</a></li></ul></li></ul></nav></aside></header><article class="markdown book-article"><h1 id=installation>Installation
<a class=anchor href=#installation>#</a></h1><h2 id=using-single_include>Using <code>single_include</code>
<a class=anchor href=#using-single_include>#</a></h2><p>The <code>ingle_include/toml.hpp</code>s is a single-file, header-only library that consolidates all the functionalities of toml11 into one file.</p><p>The simplest way to use it is to copy this file to a location included in your <code>INCLUDE_PATH</code> and then add <code>#include &lt;toml.hpp></code> to your source code.</p><p>The MIT license notice is included in both the comments and the <code>toml::license_notice()</code> 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 <code>toml::license_notice()</code> function can be called.</p><h2 id=cloning-toml11-and-using-cmake>Cloning toml11 and using cmake
<a class=anchor href=#cloning-toml11-and-using-cmake>#</a></h2><p>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 <code>add_subdirectory(toml11)</code> to your <code>CMakeLists.txt</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cmake data-lang=cmake><span style=display:flex><span>add_subdirectory(<span style=color:#e6db74>toml11</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>add_executable(<span style=color:#e6db74>main</span> <span style=color:#e6db74>main.cpp</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>target_link_libraries(<span style=color:#e6db74>main</span> <span style=color:#e6db74>PUBLIC</span> <span style=color:#e6db74>toml11::toml11</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span></code></pre></div><p>toml11 will only run tests and install when it is the root project.</p><h3 id=cmake-fetchcontent>CMake <code>FetchContent</code>
<a class=anchor href=#cmake-fetchcontent>#</a></h3><p>Using <code>FetchContent</code>, you can automatically download toml11 to your <code>build</code> directory.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cmake data-lang=cmake><span style=display:flex><span>include(<span style=color:#e6db74>FetchContent</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>FetchContent_Declare(
</span></span><span style=display:flex><span> <span style=color:#e6db74>toml11</span>
</span></span><span style=display:flex><span> <span style=color:#e6db74>GIT_REPOSITORY</span> <span style=color:#e6db74>https://github.com/ToruNiina/toml11.git</span>
</span></span><span style=display:flex><span> <span style=color:#e6db74>GIT_TAG</span> <span style=color:#e6db74>v4.4.0</span>
</span></span><span style=display:flex><span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>FetchContent_MakeAvailable(<span style=color:#e6db74>toml11</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>add_executable(<span style=color:#e6db74>main</span> <span style=color:#e6db74>main.cpp</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>target_link_libraries(<span style=color:#e6db74>main</span> <span style=color:#e6db74>PRIVATE</span> <span style=color:#e6db74>toml11::toml11</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span></code></pre></div><h3 id=cmake-package-manager-cpm>CMake Package Manager (CPM)
<a class=anchor href=#cmake-package-manager-cpm>#</a></h3><p>After <a href="https://github.com/cpm-cmake/CPM.cmake?tab=readme-ov-file#adding-cpm">adding cpm to your project</a>, you can use toml11 by doing:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cmake data-lang=cmake><span style=display:flex><span>include(<span style=color:#e6db74>cmake/CPM.cmake</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>CPMAddPackage(<span style=color:#e6db74>&#34;gh:ToruNiina/toml11@4.4.0&#34;</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span><span style=color:#75715e># OR
</span></span></span><span style=display:flex><span><span style=color:#75715e></span><span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>CPMAddPackage(
</span></span><span style=display:flex><span> <span style=color:#e6db74>NAME</span> <span style=color:#e6db74>toml11</span>
</span></span><span style=display:flex><span> <span style=color:#e6db74>GITHUB_REPOSITORY</span> <span style=color:#e6db74>&#34;ToruNiina/toml11&#34;</span>
</span></span><span style=display:flex><span> <span style=color:#e6db74>VERSION</span> <span style=color:#e6db74>4.4.0</span>
</span></span><span style=display:flex><span> <span style=color:#e6db74>OPTIONS</span>
</span></span><span style=display:flex><span> <span style=color:#e6db74>&#34;TOML11_PRECOMPILE ON&#34;</span> <span style=color:#75715e># to pre-compile
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> <span style=color:#e6db74>&#34;TOML11_ENABLE_ACCESS_CHECK ON&#34;</span> <span style=color:#75715e># to use value.accessed()
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> )<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>add_executable(<span style=color:#e6db74>main</span> <span style=color:#e6db74>main.cpp</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>target_link_libraries(<span style=color:#e6db74>main</span> <span style=color:#e6db74>PUBLIC</span> <span style=color:#e6db74>toml11::toml11</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span></code></pre></div><h2 id=installing-using-cmake>Installing using cmake
<a class=anchor href=#installing-using-cmake>#</a></h2><p>After cloning toml11, you can install it using cmake.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-console data-lang=console><span style=display:flex><span>$ cmake -B ./build/ -DTOML11_BUILD_TESTS<span style=color:#f92672>=</span>ON
</span></span><span style=display:flex><span>$ cmake --install ./build/ --prefix<span style=color:#f92672>=</span>/opt/toml11
</span></span></code></pre></div><p>If you want to run the test programs before installation, make sure to set <code>-DTOML11_BUILD_TESTS=ON</code> first.</p><p>Once the installation is complete, you can use it as follows:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cmake data-lang=cmake><span style=display:flex><span>find_package(<span style=color:#e6db74>toml11</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>add_executable(<span style=color:#e6db74>main</span> <span style=color:#e6db74>main.cpp</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>target_link_libraries(<span style=color:#e6db74>main</span> <span style=color:#e6db74>PRIVATE</span> <span style=color:#e6db74>toml11::toml11</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span></code></pre></div><h2 id=compiling-with-cmake-to-create-a-static-library>Compiling with cmake to Create a Static Library
<a class=anchor href=#compiling-with-cmake-to-create-a-static-library>#</a></h2><p>By defining <code>-DTOML11_PRECOMPILE=ON</code> when running cmake, you can precompile some of the functions in toml11, thereby reducing the overall compile time.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-console data-lang=console><span style=display:flex><span>$ cmake -B ./build/ -DTOML11_PRECOMPILE<span style=color:#f92672>=</span>ON
</span></span></code></pre></div><p>When linking the library, use <code>target_link_libraries</code> in CMake</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cmake data-lang=cmake><span style=display:flex><span>target_link_libraries(<span style=color:#e6db74>your_target</span> <span style=color:#e6db74>PUBLIC</span> <span style=color:#e6db74>toml11::toml11</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span></code></pre></div><p>or pass <code>-DTOML11_COMPILE_SOURCES</code> to the compiler to suppress header-only features.</p><p>However, since toml11 supports multiple C++ versions and may switch types based on the value of <code>__cplusplus</code>,
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 <code>CMAKE_CXX_STANDARD</code> during compilation.
If this is difficult, use it as a header-only library as usual.</p><p>The <code>find_package(toml11)</code> command defines <code>TOML11_INCLUDE_DIR</code>.
Even if you install it as a precompiled library, you can still use it as a header-only library by adding <code>TOML11_INCLUDE_DIR</code> to <code>target_include_directories</code> and avoiding the use of <code>target_link_libraries</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cmake data-lang=cmake><span style=display:flex><span>find_package(<span style=color:#e6db74>toml11</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span>add_executable(<span style=color:#e6db74>main</span> <span style=color:#e6db74>main.cpp</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span><span style=display:flex><span><span style=color:#960050;background-color:#1e0010></span><span style=color:#75715e># Include only, do not link
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>target_include_directories(<span style=color:#e6db74>main</span> <span style=color:#e6db74>PRIVATE</span> <span style=color:#f92672>${</span>TOML11_INCLUDE_DIR<span style=color:#f92672>}</span>)<span style=color:#960050;background-color:#1e0010>
</span></span></span></code></pre></div><h2 id=compiling-examples>Compiling Examples
<a class=anchor href=#compiling-examples>#</a></h2><p>You can compile the <code>examples/</code> directory by setting <code>-DTOML11_BUILD_EXAMPLES=ON</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-console data-lang=console><span style=display:flex><span>$ cmake -B ./build/ -DTOML11_BUILD_EXAMPLES<span style=color:#f92672>=</span>ON
</span></span><span style=display:flex><span>$ cmake --build ./build/
</span></span></code></pre></div><p>The executable binaries for the examples will be generated in the <code>examples/</code> directory.</p><h2 id=running-tests>Running Tests
<a class=anchor href=#running-tests>#</a></h2><p>To build the tests, set <code>-DTOML11_BUILD_TESTS=ON</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-console data-lang=console><span style=display:flex><span>$ git submodule update --init --recursive
</span></span><span style=display:flex><span>$ cmake -B ./build/ -DTOML11_BUILD_TESTS<span style=color:#f92672>=</span>ON
</span></span><span style=display:flex><span>$ cmake --build ./build/
</span></span><span style=display:flex><span>$ ctest --test-dir ./build/
</span></span></code></pre></div><p>To run the <code>toml-lang/toml-tests</code>, set <code>-DTOML11_BUILD_TOML_TESTS=ON</code>. This will build <code>toml11_decoder</code> and <code>toml11_encoder</code> in the <code>tests/</code> directory.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-console data-lang=console><span style=display:flex><span>$ git submodule update --init --recursive
</span></span><span style=display:flex><span>$ cmake -B ./build/ -DTOML11_BUILD_TOML_TESTS<span style=color:#f92672>=</span>ON
</span></span><span style=display:flex><span>$ cmake --build ./build/
</span></span><span style=display:flex><span>$ ctest --test-dir ./build/
</span></span></code></pre></div></article><footer class=book-footer><div class="flex flex-wrap justify-between"></div><script>(function(){function e(e){const t=window.getSelection(),n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)}document.querySelectorAll("pre code").forEach(t=>{t.addEventListener("click",function(){if(window.getSelection().toString())return;e(t.parentElement),navigator.clipboard&&navigator.clipboard.writeText(t.parentElement.textContent)})})})()</script></footer><label for=menu-control class="hidden book-menu-overlay"></label></div><aside class=book-toc><div class=book-toc-content><nav id=TableOfContents><ul><li><a href=#installation>Installation</a><ul><li><a href=#using-single_include>Using <code>single_include</code></a></li><li><a href=#cloning-toml11-and-using-cmake>Cloning toml11 and using cmake</a><ul><li><a href=#cmake-fetchcontent>CMake <code>FetchContent</code></a></li><li><a href=#cmake-package-manager-cpm>CMake Package Manager (CPM)</a></li></ul></li><li><a href=#installing-using-cmake>Installing using cmake</a></li><li><a href=#compiling-with-cmake-to-create-a-static-library>Compiling with cmake to Create a Static Library</a></li><li><a href=#compiling-examples>Compiling Examples</a></li><li><a href=#running-tests>Running Tests</a></li></ul></li></ul></nav></div></aside></main></body></html>
Reference in New Issue View Git Blame Copy Permalink