This commit is contained in:
nlohmann committed 2026-10-27 12:14:00 +00:00
1 parent b36f8a9821
commit 11a863958e
1180 files changed
+14211 -6025

No files matched your search

+20
View File
@@ -8,6 +8,19 @@ to point to the appropriate include directories and [`INTERFACE_COMPILE_FEATURES
for the necessary C++11 flags. Most [package managers](package_managers.md) that provide a CMake package configuration
for this library expose this same target.
All ways of adding the library described below end at this one target:
```mermaid
flowchart LR
FP["<b>find_package()</b><br>installed package"] --> T
AS["<b>add_subdirectory()</b><br>embedded source tree"] --> T
FC["<b>FetchContent</b><br>downloaded at configure time"] --> T
PM["<b>Package manager</b><br>its CMake package"] --> T
T["<b>nlohmann_json::nlohmann_json</b><br>one INTERFACE target"] --> L["<b>target_link_libraries()</b><br>link it PRIVATE"]
```
<p class="nj-caption" markdown>The four ways to add the library in CMake all lead to the same `nlohmann_json::nlohmann_json` interface target, which a project links with `target_link_libraries`. The CMake options below apply to `add_subdirectory()` and `FetchContent`; installed packages have their options fixed at install time.</p>
### External
To use this library from a CMake project, you can locate it directly with [`find_package()`](https://cmake.org/cmake/help/latest/command/find_package.html)
@@ -255,3 +268,10 @@ add_executable(myproject main.cpp)
target_link_libraries(myproject PRIVATE nlohmann_json_modules)
target_compile_definitions(myproject PRIVATE NLOHMANN_JSON_BUILD_MODULES)
```
## See also
- [Macros](../api/macros/index.md) - reference of all macros
- [Supported Macros](../features/macros.md) - the macros that the CMake options set
- [Modules](../features/modules.md) - C++20 module support
- [`nlohmann` Namespace](../features/namespace.md) - namespace options set by CMake
+7 -2
View File
@@ -1,4 +1,9 @@
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/cmake/" rel="canonical"><link href=../migration_guide/ rel=prev><link href=../package_managers/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>CMake - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../css/custom.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#cmake class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> CMake </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-mdLine truncated
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/cmake/" rel="canonical"><link href=../migration_guide/ rel=prev><link href=../package_managers/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>CMake - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../css/custom.css><link rel=stylesheet href=../../css/brand.css><link rel=stylesheet href=../../css/fig-sax.css><link rel=stylesheet href=../../css/fig-jsonview.css><link rel=stylesheet href=../../css/fig-exceptions.css><link rel=stylesheet href=../../css/fig-pointer.css><link rel=stylesheet href=../../css/fig-charts.css><link rel=stylesheet href=../../css/fig-integration.css><link rel=stylesheet href=../../css/fig-macros.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#cmake class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> CMake </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-Line truncated
FP["&lt;b&gt;find_package()&lt;/b&gt;&lt;br&gt;installed package"] --&gt; T
AS["&lt;b&gt;add_subdirectory()&lt;/b&gt;&lt;br&gt;embedded source tree"] --&gt; T
FC["&lt;b&gt;FetchContent&lt;/b&gt;&lt;br&gt;downloaded at configure time"] --&gt; T
PM["&lt;b&gt;Package manager&lt;/b&gt;&lt;br&gt;its CMake package"] --&gt; T
T["&lt;b&gt;nlohmann_json::nlohmann_json&lt;/b&gt;&lt;br&gt;one INTERFACE target"] --&gt; L["&lt;b&gt;target_link_libraries()&lt;/b&gt;&lt;br&gt;link it PRIVATE"]</code></pre> <p class=nj-caption>The four ways to add the library in CMake all lead to the same <code>nlohmann_json::nlohmann_json</code> interface target, which a project links with <code>target_link_libraries</code>. The CMake options below apply to <code>add_subdirectory()</code> and <code>FetchContent</code>; installed packages have their options fixed at install time.</p> <h3 id=external>External<a class=headerlink href=#external title="Permanent link">&para;</a></h3> <p>To use this library from a CMake project, you can locate it directly with <a href="https://cmake.org/cmake/help/latest/command/find_package.html"><code>find_package()</code></a> and use the namespaced imported target from the generated package configuration:</p> <div class="admonition example"> <p class=admonition-title>Example</p> <div class=highlight><span class=filename>CMakeLists.txt</span><pre><span></span><code><span class=nb>cmake_minimum_required</span><span class=p>(</span><span class=s>VERSION</span><span class=w> </span><span class=s>3.5</span><span class=p>)</span>
<span class=nb>project</span><span class=p>(</span><span class=s>ExampleProject</span><span class=w> </span><span class=s>LANGUAGES</span><span class=w> </span><span class=s>CXX</span><span class=p>)</span>
<span class=nb>find_package</span><span class=p>(</span><span class=s>nlohmann_json</span><span class=w> </span><span class=s>3.12.0</span><span class=w> </span><span class=s>REQUIRED</span><span class=p>)</span>
@@ -55,4 +60,4 @@
<span class=nb>add_executable</span><span class=p>(</span><span class=s>myproject</span><span class=w> </span><span class=s>main.cpp</span><span class=p>)</span>
<span class=nb>target_link_libraries</span><span class=p>(</span><span class=s>myproject</span><span class=w> </span><span class=s>PRIVATE</span><span class=w> </span><span class=s>nlohmann_json_modules</span><span class=p>)</span>
<span class=nb>target_compile_definitions</span><span class=p>(</span><span class=s>myproject</span><span class=w> </span><span class=s>PRIVATE</span><span class=w> </span><span class=s>NLOHMANN_JSON_BUILD_MODULES</span><span class=p>)</span>
</code></pre></div> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 14, 2026 15:40:55 UTC">October 14, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M162.7 210c-1.8 3.3-25.2 44.4-70.1 123.5-4.9 8.3-10.8 12.5-17.7 12.5H9.8c-7.7 0-12.1-7.5-8.5-14.4l69-121.3q.3 0 0-.3l-43.9-75.6c-4.3-7.8.3-14.1 8.5-14.1H100c7.3 0 13.3 4.1 18 12.2zM382.6 46.1l-144 253v.3L330.2 466c3.9 7.1.2 14.1-8.5 14.1h-65.2c-7.6 0-13.6-4-18-12.2l-92.4-168.5c3.3-5.8 51.5-90.8 144.8-255.2 4Line truncated
</code></pre></div> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/macros/ >Macros</a> - reference of all macros</li> <li><a href=../../features/macros/ >Supported Macros</a> - the macros that the CMake options set</li> <li><a href=../../features/modules/ >Modules</a> - C++20 module support</li> <li><a href=../../features/namespace/ ><code>nlohmann</code> Namespace</a> - namespace options set by CMake</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../migration_guide/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Migration Guide"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Migration Guide </div> </div> </a> <a href=../package_managers/ class="md-footer__link md-footer__link--next" aria-label="Next: Package Managers"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Package Managers </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="Line truncated
+20
View File
@@ -4,6 +4,19 @@
You can use the `nlohmann_json::nlohmann_json` interface target in CMake. This target populates the appropriate usage requirements for [`INTERFACE_INCLUDE_DIRECTORIES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.html) to point to the appropriate include directories and [`INTERFACE_COMPILE_FEATURES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_COMPILE_FEATURES.html) for the necessary C++11 flags. Most [package managers](https://json.nlohmann.me/integration/package_managers/index.md) that provide a CMake package configuration for this library expose this same target.
All ways of adding the library described below end at this one target:
```
flowchart LR
FP["<b>find_package()</b><br>installed package"] --> T
AS["<b>add_subdirectory()</b><br>embedded source tree"] --> T
FC["<b>FetchContent</b><br>downloaded at configure time"] --> T
PM["<b>Package manager</b><br>its CMake package"] --> T
T["<b>nlohmann_json::nlohmann_json</b><br>one INTERFACE target"] --> L["<b>target_link_libraries()</b><br>link it PRIVATE"]
```
The four ways to add the library in CMake all lead to the same `nlohmann_json::nlohmann_json` interface target, which a project links with `target_link_libraries`. The CMake options below apply to `add_subdirectory()` and `FetchContent`; installed packages have their options fixed at install time.
### External
To use this library from a CMake project, you can locate it directly with [`find_package()`](https://cmake.org/cmake/help/latest/command/find_package.html) and use the namespaced imported target from the generated package configuration:
@@ -220,3 +233,10 @@ add_executable(myproject main.cpp)
target_link_libraries(myproject PRIVATE nlohmann_json_modules)
target_compile_definitions(myproject PRIVATE NLOHMANN_JSON_BUILD_MODULES)
```
## See also
- [Macros](https://json.nlohmann.me/api/macros/index.md) - reference of all macros
- [Supported Macros](https://json.nlohmann.me/features/macros/index.md) - the macros that the CMake options set
- [Modules](https://json.nlohmann.me/features/modules/index.md) - C++20 module support
- [`nlohmann` Namespace](https://json.nlohmann.me/features/namespace/index.md) - namespace options set by CMake
+341 -18
View File
@@ -6,9 +6,128 @@ that cost, ordered by how much they typically save.
!!! info "Measurements"
The numbers below are medians of nine runs compiling a single translation unit with `-std=c++17 -c` against the
single-header version, with Apple clang and GCC 16 on macOS (Apple silicon). They show the order of magnitude to
expect; measure your own code before and after a change.
The numbers below are medians of the wall-clock time of nine runs compiling a single translation unit with
`-std=c++17 -c` against the single-header version, with Apple clang 21.0.0 (clang-2100.3.34.2) and Homebrew GCC
16.2.0 on macOS (Apple M1 Max). All configurations were run interleaved, in alternating order. They show the order
of magnitude to expect; measure your own code before and after a change.
The translation units are listed below. They replace the ones used for earlier versions of this page, whose
sources were not published, so the numbers differ from earlier versions.
??? example "Measured translation units"
The *model* and *parsing* translation units start with `#include <string>`, `#include <vector>`, and
`#include <nlohmann/json.hpp>`; the *header-only* translation unit includes only the library header.
```cpp title="model translation unit"
struct person
{
std::string name;
int age = 0;
std::vector<std::string> tags;
};
void to_json(nlohmann::json& j, const person& p)
{
j = nlohmann::json{{"name", p.name}, {"age", p.age}, {"tags", p.tags}};
}
void from_json(const nlohmann::json& j, person& p)
{
j.at("name").get_to(p.name);
j.at("age").get_to(p.age);
j.at("tags").get_to(p.tags);
}
nlohmann::json roundtrip(const person& p)
{
nlohmann::json j = p;
return nlohmann::json(j.get<person>());
}
```
```cpp title="parsing translation unit"
std::size_t parse_and_dump(const std::string& s)
{
const nlohmann::json j = nlohmann::json::parse(s);
return j.dump(2).size();
}
```
```cpp title="header-only translation unit"
#include <nlohmann/json.hpp> // or <nlohmann/json_fwd.hpp>
struct person;
void to_json(nlohmann::json& j, const person& p);
void from_json(const nlohmann::json& j, person& p);
```
<div class="nj-fig-wrap" markdown>
<svg class="nj-fig nj-charts nj-charts--compile" viewBox="0 0 470 516" role="img" aria-labelledby="nj-charts-ct nj-charts-ct-d" xmlns="http://www.w3.org/2000/svg">
<title id="nj-charts-ct">Change in compile time against the default configuration at -O0, Apple clang and G&#8203;CC 16</title>
<desc id="nj-charts-ct-d">Grouped horizontal bars, negative is faster. json_fwd.hpp instead of json.hpp on a header-only translation unit: Apple clang -62 %, G&#8203;CC 16 -82 %; extern template on a parsing translation unit: Apple clang -7 %, G&#8203;CC 16 -21 %; JSON_NO_AUTOMATIC_UDLS on a model translation unit: Apple clang -11 %, G&#8203;CC 16 -11 %; JSON_NO_AUTOMATIC_UDLS on a parsing translation unit: Apple clang -1 %, G&#8203;CC 16 -2 %; JSON_HAS_FILESYSTEM=0 + JSON_NO_IO on a model translation unit: Apple clang -8 %, G&#8203;CC 16 -11 %; JSON_HAS_FILESYSTEM=0 on a model translation unit: Apple clang -5 %, G&#8203;CC 16 -9 %; JSON_NO_IO on a model translation unit: Apple clang -2 %, G&#8203;CC 16 -2 %; JSON_USE_GLOBAL_UDLS=0 on a model translation unit: Apple clang 0 %, G&#8203;CC 16 -1 %.</desc>
<rect class="nj-charts-clang" x="8" y="10" width="12" height="12" rx="3"/>
<text class="nj-charts-leg" x="26" y="20.5">Apple clang</text>
<rect class="nj-charts-gcc" x="126" y="10" width="12" height="12" rx="3"/>
<text class="nj-charts-leg" x="144" y="20.5">G&#8203;CC 16</text>
<line class="nj-charts-grid" x1="47.4" y1="58" x2="47.4" y2="472"/>
<text class="nj-charts-tick" x="47.4" y="488">&#8722;80 %</text>
<line class="nj-charts-grid" x1="126.2" y1="58" x2="126.2" y2="472"/>
<text class="nj-charts-tick" x="126.2" y="488">&#8722;60 %</text>
<line class="nj-charts-grid" x1="205" y1="58" x2="205" y2="472"/>
<text class="nj-charts-tick" x="205" y="488">&#8722;40 %</text>
<line class="nj-charts-grid" x1="283.8" y1="58" x2="283.8" y2="472"/>
<text class="nj-charts-tick" x="283.8" y="488">&#8722;20 %</text>
<text class="nj-charts-tick" x="362.6" y="488">0 %</text>
<text class="nj-charts-tick nj-charts-tick--l" x="8" y="506">&#8592; faster</text>
<text class="nj-charts-tick nj-charts-tick--r" x="462" y="506">slower &#8594;</text>
<text class="nj-charts-rowlabel" x="8" y="62"><tspan class="nj-charts-code">json_fwd.hpp instead of json.hpp</tspan><tspan class="nj-charts-sub"> &#183; header-only TU</tspan></text>
<path class="nj-charts-clang" d="M362.6 70 H122.32 Q118.32 70 118.32 74 V78 Q118.32 82 122.32 82 H362.6 Z"><title>json_fwd.hpp instead of json.hpp, header-only TU (Apple clang): &#8722;62 %</title></path>
<text class="nj-charts-val" x="367.6" y="80.5">&#8722;62 %</text>
<path class="nj-charts-gcc" d="M362.6 84 H43.52 Q39.52 84 39.52 88 V92 Q39.52 96 43.52 96 H362.6 Z"><title>json_fwd.hpp instead of json.hpp, header-only TU (G&#8203;CC 16): &#8722;82 %</title></path>
<text class="nj-charts-val" x="367.6" y="94.5">&#8722;82 %</text>
<text class="nj-charts-rowlabel" x="8" y="114"><tspan class="nj-charts-code">extern template</tspan><tspan class="nj-charts-sub"> &#183; parsing TU</tspan></text>
<path class="nj-charts-clang" d="M362.6 122 H339.02 Q335.02 122 335.02 126 V130 Q335.02 134 339.02 134 H362.6 Z"><title>extern template, parsing TU (Apple clang): &#8722;7 %</title></path>
<text class="nj-charts-val" x="367.6" y="132.5">&#8722;7 %</text>
<path class="nj-charts-gcc" d="M362.6 136 H283.86 Q279.86 136 279.86 140 V144 Q279.86 148 283.86 148 H362.6 Z"><title>extern template, parsing TU (G&#8203;CC 16): &#8722;21 %</title></path>
<text class="nj-charts-val" x="367.6" y="146.5">&#8722;21 %</text>
<text class="nj-charts-rowlabel" x="8" y="166"><tspan class="nj-charts-code">JSON_NO_AUTOMATIC_UDLS</tspan><tspan class="nj-charts-sub"> &#183; model TU</tspan></text>
<path class="nj-charts-clang" d="M362.6 174 H323.26 Q319.26 174 319.26 178 V182 Q319.26 186 323.26 186 H362.6 Z"><title>JSON_NO_AUTOMATIC_UDLS, model TU (Apple clang): &#8722;11 %</title></path>
<text class="nj-charts-val" x="367.6" y="184.5">&#8722;11 %</text>
<path class="nj-charts-gcc" d="M362.6 188 H323.26 Q319.26 188 319.26 192 V196 Q319.26 200 323.26 200 H362.6 Z"><title>JSON_NO_AUTOMATIC_UDLS, model TU (G&#8203;CC 16): &#8722;11 %</title></path>
<text class="nj-charts-val" x="367.6" y="198.5">&#8722;11 %</text>
<text class="nj-charts-rowlabel" x="8" y="218"><tspan class="nj-charts-code">JSON_NO_AUTOMATIC_UDLS</tspan><tspan class="nj-charts-sub"> &#183; parsing TU</tspan></text>
<path class="nj-charts-clang" d="M362.6 226 H362.6 Q358.66 226 358.66 229.94 V234.06 Q358.66 238 362.6 238 H362.6 Z"><title>JSON_NO_AUTOMATIC_UDLS, parsing TU (Apple clang): &#8722;1 %</title></path>
<text class="nj-charts-val" x="367.6" y="236.5">&#8722;1 %</text>
<path class="nj-charts-gcc" d="M362.6 240 H358.72 Q354.72 240 354.72 244 V248 Q354.72 252 358.72 252 H362.6 Z"><title>JSON_NO_AUTOMATIC_UDLS, parsing TU (G&#8203;CC 16): &#8722;2 %</title></path>
<text class="nj-charts-val" x="367.6" y="250.5">&#8722;2 %</text>
<text class="nj-charts-rowlabel" x="8" y="270"><tspan class="nj-charts-code">JSON_HAS_FILESYSTEM=0 + JSON_NO_IO</tspan><tspan class="nj-charts-sub"> &#183; model TU</tspan></text>
<path class="nj-charts-clang" d="M362.6 278 H335.08 Q331.08 278 331.08 282 V286 Q331.08 290 335.08 290 H362.6 Z"><title>JSON_HAS_FILESYSTEM=0 + JSON_NO_IO, model TU (Apple clang): &#8722;8 %</title></path>
<text class="nj-charts-val" x="367.6" y="288.5">&#8722;8 %</text>
<path class="nj-charts-gcc" d="M362.6 292 H323.26 Q319.26 292 319.26 296 V300 Q319.26 304 323.26 304 H362.6 Z"><title>JSON_HAS_FILESYSTEM=0 + JSON_NO_IO, model TU (G&#8203;CC 16): &#8722;11 %</title></path>
<text class="nj-charts-val" x="367.6" y="302.5">&#8722;11 %</text>
<text class="nj-charts-rowlabel" x="8" y="322"><tspan class="nj-charts-code">JSON_HAS_FILESYSTEM=0</tspan><tspan class="nj-charts-sub"> &#183; model TU</tspan></text>
<path class="nj-charts-clang" d="M362.6 330 H346.9 Q342.9 330 342.9 334 V338 Q342.9 342 346.9 342 H362.6 Z"><title>JSON_HAS_FILESYSTEM=0, model TU (Apple clang): &#8722;5 %</title></path>
<text class="nj-charts-val" x="367.6" y="340.5">&#8722;5 %</text>
<path class="nj-charts-gcc" d="M362.6 344 H331.14 Q327.14 344 327.14 348 V352 Q327.14 356 331.14 356 H362.6 Z"><title>JSON_HAS_FILESYSTEM=0, model TU (G&#8203;CC 16): &#8722;9 %</title></path>
<text class="nj-charts-val" x="367.6" y="354.5">&#8722;9 %</text>
<text class="nj-charts-rowlabel" x="8" y="374"><tspan class="nj-charts-code">JSON_NO_IO</tspan><tspan class="nj-charts-sub"> &#183; model TU*</tspan></text>
<path class="nj-charts-clang" d="M362.6 382 H358.72 Q354.72 382 354.72 386 V390 Q354.72 394 358.72 394 H362.6 Z"><title>JSON_NO_IO, model TU (Apple clang): &#8722;2 %</title></path>
<text class="nj-charts-val" x="367.6" y="392.5">&#8722;2 %</text>
<path class="nj-charts-gcc" d="M362.6 396 H358.72 Q354.72 396 354.72 400 V404 Q354.72 408 358.72 408 H362.6 Z"><title>JSON_NO_IO, model TU (G&#8203;CC 16): &#8722;2 %</title></path>
<text class="nj-charts-val" x="367.6" y="406.5">&#8722;2 %</text>
<text class="nj-charts-rowlabel" x="8" y="426"><tspan class="nj-charts-code">JSON_USE_GLOBAL_UDLS=0</tspan><tspan class="nj-charts-sub"> &#183; model TU*</tspan></text>
<path class="nj-charts-clang" d="M362.6 434 h0.5 v12 h-0.5 Z"><title>JSON_USE_GLOBAL_UDLS=0, model TU (Apple clang): 0 %</title></path>
<text class="nj-charts-val" x="367.6" y="444.5">0 %</text>
<path class="nj-charts-gcc" d="M362.6 448 H362.6 Q358.66 448 358.66 451.94 V456.06 Q358.66 460 362.6 460 H362.6 Z"><title>JSON_USE_GLOBAL_UDLS=0, model TU (G&#8203;CC 16): &#8722;1 %</title></path>
<text class="nj-charts-val" x="367.6" y="458.5">&#8722;1 %</text>
<line class="nj-charts-zero" x1="362.6" y1="58" x2="362.6" y2="472"/>
</svg>
</div>
<p class="nj-charts-caption" markdown>Change in compile time at `-O0` against the default configuration of the same
translation unit, taken from the tables below (medians of nine runs, see above). * computed from the milliseconds in
[Options without effect on compile times](#options-without-effect-on-compile-times).</p>
## Include `json_fwd.hpp` in headers
@@ -37,8 +156,10 @@ void from_json(const nlohmann::json& j, person& p) { /* ... */ }
| Compiler | `json.hpp` (`-O0`) | `json_fwd.hpp` (`-O0`) | Change |
|-------------|-------------------:|-----------------------:|-------:|
| Apple clang | 704 ms | 329 ms | −53% |
| GCC 16 | 779 ms | 242 ms | −69% |
| Apple clang | 868 ms | 332 ms | −62% |
| GCC 16 | 1164 ms | 210 ms | −82% |
<p class="nj-table-caption" markdown>Compile time of the header-only translation unit at `-O0` with each header, as the median wall-clock time of nine runs (see "Measurements" above). A negative change means a faster build.</p>
This is the most effective option, because it avoids the full header in every translation unit that includes
*your* headers.
@@ -67,13 +188,15 @@ conversions or only pass `json` values around:
| Compiler | Translation unit | Default (`-O0` / `-O2`) | `JSON_NO_AUTOMATIC_UDLS` (`-O0` / `-O2`) | Change |
|-------------|------------------|------------------------:|-----------------------------------------:|------------:|
| Apple clang | model | 776 ms / 846 ms | 629 ms / 692 ms | −19% / −18% |
| GCC 16 | model | 1022 ms / 1120 ms | 882 ms / 965 ms | −14% / −14% |
| Apple clang | parsing | 992 ms / 1815 ms | 1006 ms / 1823 ms | +1% / 0% |
| GCC 16 | parsing | 2018 ms / 3420 ms | 1990 ms / 3454 ms | −1% / +1% |
| Apple clang | model | 1051 ms / 1300 ms | 935 ms / 1170 ms | −11% / −10% |
| GCC 16 | model | 1801 ms / 2106 ms | 1598 ms / 1983 ms | −11% / −6% |
| Apple clang | parsing | 1157 ms / 2016 ms | 1146 ms / 2006 ms | −1% / 0% |
| GCC 16 | parsing | 2529 ms / 4087 ms | 2484 ms / 4059 ms | −2% / −1% |
Translation units that include only the header save up to a third. Translation units that parse anyway instantiate
the parser regardless and see no difference.
<p class="nj-table-caption" markdown>Compile time of the model and parsing translation units without and with `JSON_NO_AUTOMATIC_UDLS`, at `-O0` and `-O2`.</p>
The model translation unit saves about a tenth. Translation units that parse anyway instantiate the parser regardless
and see no difference.
## Instantiate `basic_json` once
@@ -97,10 +220,12 @@ Include `json_instance.hpp` instead of `<nlohmann/json.hpp>` and compile and lin
| Compiler | Translation unit | Default (`-O0` / `-O2`) | `extern template` (`-O0` / `-O2`) | Change |
|-------------|---------------------|------------------------:|----------------------------------:|------------:|
| Apple clang | parsing | 992 ms / 1815 ms | 953 ms / 1625 ms | −4% / −10% |
| GCC 16 | parsing | 2018 ms / 3420 ms | 1522 ms / 2728 ms | −25% / −20% |
| Apple clang | `json_instance.cpp` | — | 2166 ms / 4660 ms | — |
| GCC 16 | `json_instance.cpp` | — | 5085 ms / 10616 ms | — |
| Apple clang | parsing | 1157 ms / 2016 ms | 1071 ms / 1844 ms | −7% / −9% |
| GCC 16 | parsing | 2529 ms / 4087 ms | 1994 ms / 3190 ms | −21% / −22% |
| Apple clang | `json_instance.cpp` | — | 2573 ms / 6221 ms | — |
| GCC 16 | `json_instance.cpp` | — | 6489 ms / 13759 ms | — |
<p class="nj-table-caption" markdown>Compile time of the parsing translation unit without and with the `extern template` declaration, at `-O0` and `-O2`. The `json_instance.cpp` rows are the one-off cost of the translation unit that holds the instantiation.</p>
Notes:
@@ -111,12 +236,127 @@ Notes:
- The declaration covers exactly `nlohmann::json`. Add the same lines for `nlohmann::ordered_json`
(`nlohmann::basic_json<nlohmann::ordered_map>`) or your own `basic_json` specializations if you use them.
## Switch off filesystem support
With C++17, the library includes `<filesystem>` to provide conversions from and to `std::filesystem::path`
(see [`JSON_HAS_FILESYSTEM`](../api/macros/json_has_filesystem.md)). Parsing `<filesystem>` is a fixed cost in every
translation unit, and it also pulls in `<iomanip>`, `<istream>`, and `<ostream>` (and, with GCC's libstdc++,
`<sstream>`). If you do not convert paths, switch the detection off for the whole project:
```cmake
target_compile_definitions(my_target PRIVATE JSON_HAS_FILESYSTEM=0 JSON_HAS_EXPERIMENTAL_FILESYSTEM=0)
```
| Compiler | Translation unit | Default (`-O0` / `-O2`) | Filesystem off (`-O0` / `-O2`) | Change |
|-------------|------------------|------------------------:|-------------------------------:|-----------:|
| Apple clang | model | 1051 ms / 1300 ms | 998 ms / 1257 ms | −5% / −3% |
| GCC 16 | model | 1801 ms / 2106 ms | 1636 ms / 2008 ms | −9% / −5% |
| Apple clang | parsing | 1157 ms / 2016 ms | 1107 ms / 1971 ms | −4% / −2% |
| GCC 16 | parsing | 2529 ms / 4087 ms | 2405 ms / 4029 ms | −5% / −1% |
<p class="nj-table-caption" markdown>Compile time with `JSON_HAS_FILESYSTEM=0` and `JSON_HAS_EXPERIMENTAL_FILESYSTEM=0` against the default configuration, at `-O0` and `-O2`.</p>
Only with filesystem support switched off does [`JSON_NO_IO`](../api/macros/json_no_io.md) remove the stream headers
from the translation unit, so the two macros save most together:
| Compiler | Translation unit | Default (`-O0` / `-O2`) | Filesystem off and `JSON_NO_IO` (`-O0` / `-O2`) | Change |
|-------------|------------------|------------------------:|------------------------------------------------:|-----------:|
| Apple clang | model | 1051 ms / 1300 ms | 969 ms / 1219 ms | −8% / −6% |
| GCC 16 | model | 1801 ms / 2106 ms | 1605 ms / 1982 ms | −11% / −6% |
| Apple clang | parsing | 1157 ms / 2016 ms | 1083 ms / 1947 ms | −6% / −3% |
| GCC 16 | parsing | 2529 ms / 4087 ms | 2384 ms / 3972 ms | −6% / −3% |
<p class="nj-table-caption" markdown>Compile time with filesystem support switched off and `JSON_NO_IO` defined, against the default configuration, at `-O0` and `-O2`.</p>
The trade-off: the library's own `to_json`/`from_json` overloads for `std::filesystem::path` (which store the path as
UTF-8) are removed. In a test with both compilers on macOS, paths still converted through their implicit conversion
from and to `std::string`; whether that fallback exists depends on the platform's native path string type
(`std::wstring` on Windows), so check code that converts paths. `JSON_NO_IO` additionally removes all stream
functions (see [Options without effect](#options-without-effect-on-compile-times)).
## Use C++20 modules
With a toolchain that supports named modules, `import nlohmann.json;` compiles the library once into a module and
avoids parsing the header in every translation unit. See [Modules](../features/modules.md) for requirements and known
issues. Module support is experimental and currently depends heavily on the compiler version.
<div class="nj-fig-wrap" markdown>
<svg class="nj-fig nj-charts nj-charts--compile" viewBox="0 0 440 282" role="img" aria-labelledby="nj-charts-mod nj-charts-mod-d" xmlns="http://www.w3.org/2000/svg">
<title id="nj-charts-mod">Compile time per translation unit with import nlohmann.json at -O0, and the one-off cost of the module</title>
<desc id="nj-charts-mod-d">Horizontal bars, negative is faster, medians of nine runs, -std=c++20 for both. model TU, Apple clang: -48 % (1311 ms to 680 ms); model TU, G&#8203;CC 16: -47 % (2156 ms to 1153 ms); parsing TU, Apple clang: -42 % (1387 ms to 800 ms); parsing TU, G&#8203;CC 16: -36 % (2838 ms to 1810 ms); one-off build, Apple clang: 1630 ms; one-off build, G&#8203;CC 16: 2538 ms.</desc>
<rect class="nj-charts-clang" x="8" y="10" width="12" height="12" rx="3"/>
<text class="nj-charts-leg" x="26" y="20.5">Apple clang</text>
<rect class="nj-charts-gcc" x="126" y="10" width="12" height="12" rx="3"/>
<text class="nj-charts-leg" x="144" y="20.5">G&#8203;CC 16</text>
<line class="nj-charts-grid" x1="68.6667" y1="58" x2="68.6667" y2="160"/>
<text class="nj-charts-tick" x="68.6667" y="176">&#8722;50 %</text>
<line class="nj-charts-grid" x1="220.333" y1="58" x2="220.333" y2="160"/>
<text class="nj-charts-tick" x="220.333" y="176">&#8722;25 %</text>
<text class="nj-charts-tick" x="372" y="176">0 %</text>
<text class="nj-charts-tick nj-charts-tick--l" x="8" y="194">&#8592; faster per TU</text>
<text class="nj-charts-rowlabel" x="8" y="62">model TU<tspan class="nj-charts-sub"> &#183; import nlohmann.json</tspan></text>
<path class="nj-charts-clang" d="M372 70 H84.8 Q80.8 70 80.8 74 V78 Q80.8 82 84.8 82 H372 Z"><title>model TU, Apple clang: 1311 ms by default, 680 ms import nlohmann.json (&#8722;48 %)</title></path>
<text class="nj-charts-val" x="377" y="80.5">&#8722;48 %</text>
<path class="nj-charts-gcc" d="M372 84 H90.8667 Q86.8667 84 86.8667 88 V92 Q86.8667 96 90.8667 96 H372 Z"><title>model TU, G&#8203;CC 16: 2156 ms by default, 1153 ms import nlohmann.json (&#8722;47 %)</title></path>
<text class="nj-charts-val" x="377" y="94.5">&#8722;47 %</text>
<text class="nj-charts-rowlabel" x="8" y="114">parsing TU<tspan class="nj-charts-sub"> &#183; import nlohmann.json</tspan></text>
<path class="nj-charts-clang" d="M372 122 H121.2 Q117.2 122 117.2 126 V130 Q117.2 134 121.2 134 H372 Z"><title>parsing TU, Apple clang: 1387 ms by default, 800 ms import nlohmann.json (&#8722;42 %)</title></path>
<text class="nj-charts-val" x="377" y="132.5">&#8722;42 %</text>
<path class="nj-charts-gcc" d="M372 136 H157.6 Q153.6 136 153.6 140 V144 Q153.6 148 157.6 148 H372 Z"><title>parsing TU, G&#8203;CC 16: 2838 ms by default, 1810 ms import nlohmann.json (&#8722;36 %)</title></path>
<text class="nj-charts-val" x="377" y="146.5">&#8722;36 %</text>
<line class="nj-charts-zero" x1="372" y1="58" x2="372" y2="160"/>
<text class="nj-charts-rowlabel" x="8" y="222">One-off cost<tspan class="nj-charts-sub"> &#183; built once, reused by every TU</tspan></text>
<rect class="nj-charts-clang" x="8" y="232.5" width="10" height="10" rx="2.5"/>
<text class="nj-charts-val" x="24" y="242">Apple clang: 1630 ms once, saves 587 to 631 ms per TU</text>
<rect class="nj-charts-gcc" x="8" y="252.5" width="10" height="10" rx="2.5"/>
<text class="nj-charts-val" x="24" y="262">G&#8203;CC 16: 2538 ms once, saves 1003 to 1028 ms per TU</text>
</svg>
</div>
<p class="nj-caption" markdown>Change in compile time per translation unit at `-O0` when `#include <nlohmann/json.hpp>` is
replaced by `import nlohmann.json;`, both with `-std=c++20`, and the one-off cost of building the module, taken from
the table below.</p>
| Compiler | Translation unit | `#include` (`-O0` / `-O2`) | `import nlohmann.json;` (`-O0` / `-O2`) | Change |
|-------------|---------------------------|---------------------------:|----------------------------------------:|------------:|
| Apple clang | model | 1311 ms / 1597 ms | 680 ms / 914 ms | −48% / −43% |
| GCC 16 | model | 2156 ms / 2588 ms | 1153 ms / 1580 ms | −47% / −39% |
| Apple clang | parsing | 1387 ms / 2319 ms | 800 ms / 1676 ms | −42% / −28% |
| GCC 16 | parsing | 2838 ms / 4520 ms | 1810 ms / 3476 ms | −36% / −23% |
| Apple clang | `json.cppm` (module) | — | 1630 ms / 1642 ms | — |
| GCC 16 | `json.cppm` (module) | — | 2538 ms / 2547 ms | — |
<p class="nj-table-caption" markdown>Compile time with `#include <nlohmann/json.hpp>` and with `import nlohmann.json;`, both with `-std=c++20`, at `-O0` and `-O2`. The `json.cppm` rows are the one-off cost of building the module.</p>
Both columns use `-std=c++20`; with `-std=c++17`, the `#include` baseline is 17% to 20% faster (see the next
section). The module is built once per set of compiler flags and pays for itself from about the third translation
unit that imports it. Notes from the measurement:
- Apple clang only accepts the module declarations with `-fcxx-modules`; without it, `module;` is a syntax error.
- GCC 16 warns with `-Wexpose-global-module-tu-local` about internal constants of the library when building the
module. With GCC 16.2, including `<string>` and `<vector>` before `import nlohmann.json;` works, but including
them after it fails with redefinition errors ([#5103](https://github.com/nlohmann/json/issues/5103)).
??? example "How these numbers were measured"
The model and parsing translation units are the ones listed at the top of this page, with `import nlohmann.json;`
in place of `#include <nlohmann/json.hpp>` (after `#include <string>` and `#include <vector>`). Same method as
for the other tables, with `-std=c++20`.
```sh
# Apple clang: build the module once, then import it
clang++ -std=c++20 -fcxx-modules -O0 -I single_include -c -x c++-module src/modules/json.cppm \
-fmodule-output=nlohmann.json.pcm -o json_mod.o
clang++ -std=c++20 -fcxx-modules -O0 -fmodule-file=nlohmann.json=nlohmann.json.pcm -c model.cpp
# GCC 16 (Homebrew on macOS): writes gcm.cache/nlohmann.json.gcm, found by the importing translation unit
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++20 -fmodules -O0 -I single_include -c src/modules/json.cppm \
-o json_mod.o
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++20 -fmodules -O0 -c model.cpp
```
Link `json_mod.o` into the program.
## Use precompiled headers
Build systems can precompile `<nlohmann/json.hpp>` together with other stable headers, for example with CMake's
@@ -129,22 +369,105 @@ target_precompile_headers(my_target PRIVATE <nlohmann/json.hpp>)
This removes the cost of parsing the header, but not of instantiating templates in each translation unit, so it
combines well with the options above.
<div class="nj-fig-wrap" markdown>
<svg class="nj-fig nj-charts nj-charts--compile" viewBox="0 0 440 282" role="img" aria-labelledby="nj-charts-pch nj-charts-pch-d" xmlns="http://www.w3.org/2000/svg">
<title id="nj-charts-pch">Compile time per translation unit with a precompiled json.hpp at -O0, and the one-off cost of the PCH</title>
<desc id="nj-charts-pch-d">Horizontal bars, negative is faster, medians of nine runs, -std=c++17. model TU, Apple clang: -43 % (1045 ms to 594 ms); model TU, G&#8203;CC 16: -41 % (1789 ms to 1060 ms); parsing TU, Apple clang: -38 % (1148 ms to 714 ms); parsing TU, G&#8203;CC 16: -25 % (2498 ms to 1884 ms); one-off build, Apple clang: 771 ms; one-off build, G&#8203;CC 16: 2254 ms.</desc>
<rect class="nj-charts-clang" x="8" y="10" width="12" height="12" rx="3"/>
<text class="nj-charts-leg" x="26" y="20.5">Apple clang</text>
<rect class="nj-charts-gcc" x="126" y="10" width="12" height="12" rx="3"/>
<text class="nj-charts-leg" x="144" y="20.5">G&#8203;CC 16</text>
<line class="nj-charts-grid" x1="68.6667" y1="58" x2="68.6667" y2="160"/>
<text class="nj-charts-tick" x="68.6667" y="176">&#8722;50 %</text>
<line class="nj-charts-grid" x1="220.333" y1="58" x2="220.333" y2="160"/>
<text class="nj-charts-tick" x="220.333" y="176">&#8722;25 %</text>
<text class="nj-charts-tick" x="372" y="176">0 %</text>
<text class="nj-charts-tick nj-charts-tick--l" x="8" y="194">&#8592; faster per TU</text>
<text class="nj-charts-rowlabel" x="8" y="62">model TU<tspan class="nj-charts-sub"> &#183; with PCH</tspan></text>
<path class="nj-charts-clang" d="M372 70 H115.133 Q111.133 70 111.133 74 V78 Q111.133 82 115.133 82 H372 Z"><title>model TU, Apple clang: 1045 ms by default, 594 ms with PCH (&#8722;43 %)</title></path>
<text class="nj-charts-val" x="377" y="80.5">&#8722;43 %</text>
<path class="nj-charts-gcc" d="M372 84 H127.267 Q123.267 84 123.267 88 V92 Q123.267 96 127.267 96 H372 Z"><title>model TU, G&#8203;CC 16: 1789 ms by default, 1060 ms with PCH (&#8722;41 %)</title></path>
<text class="nj-charts-val" x="377" y="94.5">&#8722;41 %</text>
<text class="nj-charts-rowlabel" x="8" y="114">parsing TU<tspan class="nj-charts-sub"> &#183; with PCH</tspan></text>
<path class="nj-charts-clang" d="M372 122 H145.467 Q141.467 122 141.467 126 V130 Q141.467 134 145.467 134 H372 Z"><title>parsing TU, Apple clang: 1148 ms by default, 714 ms with PCH (&#8722;38 %)</title></path>
<text class="nj-charts-val" x="377" y="132.5">&#8722;38 %</text>
<path class="nj-charts-gcc" d="M372 136 H224.333 Q220.333 136 220.333 140 V144 Q220.333 148 224.333 148 H372 Z"><title>parsing TU, G&#8203;CC 16: 2498 ms by default, 1884 ms with PCH (&#8722;25 %)</title></path>
<text class="nj-charts-val" x="377" y="146.5">&#8722;25 %</text>
<line class="nj-charts-zero" x1="372" y1="58" x2="372" y2="160"/>
<text class="nj-charts-rowlabel" x="8" y="222">One-off cost<tspan class="nj-charts-sub"> &#183; built once, reused by every TU</tspan></text>
<rect class="nj-charts-clang" x="8" y="232.5" width="10" height="10" rx="2.5"/>
<text class="nj-charts-val" x="24" y="242">Apple clang: 771 ms once, saves 434 to 451 ms per TU</text>
<rect class="nj-charts-gcc" x="8" y="252.5" width="10" height="10" rx="2.5"/>
<text class="nj-charts-val" x="24" y="262">G&#8203;CC 16: 2254 ms once, saves 614 to 729 ms per TU</text>
</svg>
</div>
<p class="nj-caption" markdown>Change in compile time per translation unit at `-O0` with a precompiled
`<nlohmann/json.hpp>` (`-std=c++17`), and the one-off cost of building the precompiled header, taken from the table
below.</p>
| Compiler | Translation unit | Default (`-O0` / `-O2`) | With PCH (`-O0` / `-O2`) | Change |
|-------------|----------------------|------------------------:|-------------------------:|------------:|
| Apple clang | model | 1045 ms / 1295 ms | 594 ms / 842 ms | −43% / −35% |
| GCC 16 | model | 1789 ms / 2101 ms | 1060 ms / 1376 ms | −41% / −35% |
| Apple clang | parsing | 1148 ms / 2008 ms | 714 ms / 1584 ms | −38% / −21% |
| GCC 16 | parsing | 2498 ms / 4075 ms | 1884 ms / 3452 ms | −25% / −15% |
| Apple clang | building the PCH | — | 771 ms / 760 ms | — |
| GCC 16 | building the PCH | — | 2254 ms / 2218 ms | — |
<p class="nj-table-caption" markdown>Compile time without and with a precompiled `<nlohmann/json.hpp>`, at `-O0` and `-O2`. The last two rows are the one-off cost of building the precompiled header.</p>
The saving is largest in translation units that instantiate little, and the PCH pays for itself from the second
(Apple clang) or fourth (GCC) translation unit. A precompiled header only works with the flags it was built with:
GCC silently ignores a mismatching `.gch` file (for example one built with another `-O` level) unless `-Winvalid-pch`
is given.
??? example "How these numbers were measured"
`pch.hpp` contains only `#include <nlohmann/json.hpp>`; the translation units are the ones
listed at the top of this page.
```sh
# Apple clang
clang++ -std=c++17 -O0 -I single_include -x c++-header pch.hpp -o pch.hpp.pch
clang++ -std=c++17 -O0 -I single_include -include-pch pch.hpp.pch -include pch.hpp -c model.cpp
# GCC 16 (Homebrew on macOS): pch.hpp.gch next to pch.hpp is picked up by -include pch.hpp
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++17 -O0 -I single_include -x c++-header pch.hpp -o pch.hpp.gch
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++17 -O0 -I single_include -include pch.hpp -Winvalid-pch -c model.cpp
```
## Options without effect on compile times
Some configuration macros change what the library declares, but do not measurably change compile times:
| Macro | Apple clang, model (`-O0` / `-O2`) | GCC 16, model (`-O0` / `-O2`) |
|------------------------------------------------------------------------|-----------------------------------:|------------------------------:|
| default | 776 ms / 846 ms | 1022 ms / 1120 ms |
| [`JSON_NO_IO`](../api/macros/json_no_io.md) | 764 ms / 836 ms | 1022 ms / 1117 ms |
| [`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md)`=0` | 763 ms / 852 ms | 1019 ms / 1106 ms |
| default | 1051 ms / 1300 ms | 1801 ms / 2106 ms |
| [`JSON_NO_IO`](../api/macros/json_no_io.md) | 1034 ms / 1288 ms | 1756 ms / 2087 ms |
| [`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md)`=0` | 1055 ms / 1298 ms | 1783 ms / 2109 ms |
<p class="nj-table-caption" markdown>Compile time of the model translation unit with each macro defined; the first row is the default configuration for comparison.</p>
`JSON_NO_IO` removes the library's stream functions and its `#include`s of `<istream>` and `<ostream>`, but with the
default C++17 settings `<filesystem>` includes these headers anyway (and with libc++, `<vector>` already includes
`<streambuf>` via `<locale>`), so only a few hundred lines of the library's own stream code go away. It also does not
change what the translation unit instantiates. On the parsing translation unit, the change is 0% / 0% (Apple clang)
and −2% / 0% (GCC). To get a saving, combine it with
[switching off filesystem support](#switch-off-filesystem-support).
`JSON_USE_GLOBAL_UDLS` only controls *where* the literals are declared; to avoid their cost, use
`JSON_NO_AUTOMATIC_UDLS` instead.
## See also
- [`JSON_HAS_FILESYSTEM`](../api/macros/json_has_filesystem.md) - control the conversions from and to
`std::filesystem::path`
- [`JSON_NO_AUTOMATIC_UDLS`](../api/macros/json_no_automatic_udls.md) - do not include the user-defined string
literals automatically
- [Modules](../features/modules.md) - C++20 module support
- [Header only](index.md) - including the library
- [Macros](../api/macros/index.md) - reference of all macros
- [Supported Macros](../features/macros.md) - overview of all configuration macros
- [Performance](../features/performance.md) - run-time performance
- [`JSON_NO_IO`](../api/macros/json_no_io.md) - remove all stream and file I/O
+56 -5
View File
@@ -1,4 +1,38 @@
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/compile_times/" rel="canonical"><link href=../pkg-config/ rel=prev><link href=../../api/basic_json/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Compile times - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../css/custom.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#compile-times class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Compile times </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> Line truncated
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/compile_times/" rel="canonical"><link href=../pkg-config/ rel=prev><link href=../../api/basic_json/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Compile times - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../css/custom.css><link rel=stylesheet href=../../css/brand.css><link rel=stylesheet href=../../css/fig-sax.css><link rel=stylesheet href=../../css/fig-jsonview.css><link rel=stylesheet href=../../css/fig-exceptions.css><link rel=stylesheet href=../../css/fig-pointer.css><link rel=stylesheet href=../../css/fig-charts.css><link rel=stylesheet href=../../css/fig-integration.css><link rel=stylesheet href=../../css/fig-macros.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#compile-times class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Compile times </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.Line truncated
<span class=p>{</span>
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=w> </span><span class=n>name</span><span class=p>;</span>
<span class=w> </span><span class=kt>int</span><span class=w> </span><span class=n>age</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=mi>0</span><span class=p>;</span>
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o>&lt;</span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=o>&gt;</span><span class=w> </span><span class=n>tags</span><span class=p>;</span>
<span class=p>};</span>
<span class=kt>void</span><span class=w> </span><span class=nf>to_json</span><span class=p>(</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>person</span><span class=o>&amp;</span><span class=w> </span><span class=n>p</span><span class=p>)</span>
<span class=p>{</span>
<span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>{{</span><span class=s>"name"</span><span class=p>,</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>name</span><span class=p>},</span><span class=w> </span><span class=p>{</span><span class=s>"age"</span><span class=p>,</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>age</span><span class=p>},</span><span class=w> </span><span class=p>{</span><span class=s>"tags"</span><span class=p>,</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>tags</span><span class=p>}};</span>
<span class=p>}</span>
<span class=kt>void</span><span class=w> </span><span class=nf>from_json</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>person</span><span class=o>&amp;</span><span class=w> </span><span class=n>p</span><span class=p>)</span>
<span class=p>{</span>
<span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>at</span><span class=p>(</span><span class=s>"name"</span><span class=p>).</span><span class=n>get_to</span><span class=p>(</span><span class=n>p</span><span class=p>.</span><span class=n>name</span><span class=p>);</span>
<span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>at</span><span class=p>(</span><span class=s>"age"</span><span class=p>).</span><span class=n>get_to</span><span class=p>(</span><span class=n>p</span><span class=p>.</span><span class=n>age</span><span class=p>);</span>
<span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>at</span><span class=p>(</span><span class=s>"tags"</span><span class=p>).</span><span class=n>get_to</span><span class=p>(</span><span class=n>p</span><span class=p>.</span><span class=n>tags</span><span class=p>);</span>
<span class=p>}</span>
<span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=w> </span><span class=nf>roundtrip</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>person</span><span class=o>&amp;</span><span class=w> </span><span class=n>p</span><span class=p>)</span>
<span class=p>{</span>
<span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>p</span><span class=p>;</span>
<span class=w> </span><span class=k>return</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>(</span><span class=n>j</span><span class=p>.</span><span class=n>get</span><span class=o>&lt;</span><span class=n>person</span><span class=o>&gt;</span><span class=p>());</span>
<span class=p>}</span>
</code></pre></div> <div class=highlight><span class=filename>parsing translation unit</span><pre><span></span><code><span class=n>std</span><span class=o>::</span><span class=kt>size_t</span><span class=w> </span><span class=nf>parse_and_dump</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=o>&amp;</span><span class=w> </span><span class=n>s</span><span class=p>)</span>
<span class=p>{</span>
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>s</span><span class=p>);</span>
<span class=w> </span><span class=k>return</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>dump</span><span class=p>(</span><span class=mi>2</span><span class=p>).</span><span class=n>size</span><span class=p>();</span>
<span class=p>}</span>
</code></pre></div> <div class=highlight><span class=filename>header-only translation unit</span><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span><span class=w> </span><span class=c1>// or &lt;nlohmann/json_fwd.hpp&gt;</span>
<span class=k>struct</span><span class=w> </span><span class=nc>person</span><span class=p>;</span>
<span class=kt>void</span><span class=w> </span><span class=nf>to_json</span><span class=p>(</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>person</span><span class=o>&amp;</span><span class=w> </span><span class=n>p</span><span class=p>);</span>
<span class=kt>void</span><span class=w> </span><span class=nf>from_json</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>person</span><span class=o>&amp;</span><span class=w> </span><span class=n>p</span><span class=p>);</span>
</code></pre></div> </details> <div class=nj-fig-wrap> <p><svg class="nj-fig nj-charts nj-charts--compile" viewbox="0 0 470 516" role=img aria-labelledby="nj-charts-ct nj-charts-ct-d" xmlns=http://www.w3.org/2000/svg> <title id=nj-charts-ct>Change in compile time against the default configuration at -O0, Apple clang and G&#8203;CC 16</title> <desc id=nj-charts-ct-d>Grouped horizontal bars, negative is faster. json_fwd.hpp instead of json.hpp on a header-only translation unit: Apple clang -62 %, G&#8203;CC 16 -82 %; extern template on a parsing translation unit: Apple clang -7 %, G&#8203;CC 16 -21 %; JSON_NO_AUTOMATIC_UDLS on a model translation unit: Apple clang -11 %, G&#8203;CC 16 -11 %; JSON_NO_AUTOMATIC_UDLS on a parsing translation unit: Apple clang -1 %, G&#8203;CC 16 -2 %; JSON_HAS_FILESYSTEM=0 + JSON_NO_IO on a model translation unit: Apple clang -8 %, G&#8203;CC 16 -11 %; JSON_HAS_FILESYSTEM=0 on a model translation unit: Apple clang -5 %, G&#8203;CC 16 -9 %; JSON_NO_IO on a model translation unit: Apple clang -2 %, G&#8203;CC 16 -2 %; JSON_USE_GLOBAL_UDLS=0 on a model translation unit: Apple clang 0 %, G&#8203;CC 16 -1 %.</desc> <rect class=nj-charts-clang x=8 y=10 width=12 height=12 rx=3 /> <text class=nj-charts-leg x=26 y=20.5>Apple clang</text> <rect class=nj-charts-gcc x=126 y=10 width=12 height=12 rx=3 /> <text class=nj-charts-leg x=144 y=20.5>G&#8203;CC 16</text> <line class=nj-charts-grid x1=47.4 y1=58 x2=47.4 y2=472 /> <text class=nj-charts-tick x=47.4 y=488>&#8722;80 %</text> <line class=nj-charts-grid x1=126.2 y1=58 x2=126.2 y2=472 /> <text class=nj-charts-tick x=126.2 y=488>&#8722;60 %</text> <line class=nj-charts-grid x1=205 y1=58 x2=205 y2=472 /> <text class=nj-charts-tick x=205 y=488>&#8722;40 %</text> <line class=nj-charts-grid x1=283.8 y1=58 x2=283.8 y2=472 /> <text class=nj-charts-tick x=283.8 y=488>&#8722;20 %</text> <text class=nj-charts-tick x=362.6 y=488>0 %</text> <text class="nj-charts-tick nj-charts-tick--l" x=8 y=506>&#8592; faster</text> <text class="nj-charts-tick nj-charts-tick--r" x=462 y=506>slower &#8594;</text> <text class=nj-charts-rowlabel x=8 y=62><tspan class=nj-charts-code>json_fwd.hpp instead of json.hpp</tspan><tspan class=nj-charts-sub> &#183; header-only TU</tspan></text> <path class=nj-charts-clang d="M362.6 70 H122.32 Q118.32 70 118.32 74 V78 Q118.32 82 122.32 82 H362.6 Z"><title>json_fwd.hpp instead of json.hpp, header-only TU (Apple clang): &#8722;62 %</title></path> <text class=nj-charts-val x=367.6 y=80.5>&#8722;62 %</text> <path class=nj-charts-gcc d="M362.6 84 H43.52 Q39.52 84 39.52 88 V92 Q39.52 96 43.52 96 H362.6 Z"><title>json_fwd.hpp instead of json.hpp, header-only TU (G&#8203;CC 16): &#8722;82 %</title></path> <text class=nj-charts-val x=367.6 y=94.5>&#8722;82 %</text> <text class=nj-charts-rowlabel x=8 y=114><tspan class=nj-charts-code>extern template</tspan><tspan class=nj-charts-sub> &#183; parsing TU</tspan></text> <path class=nj-charts-clang d="M362.6 122 H339.02 Q335.02 122 335.02 126 V130 Q335.02 134 339.02 134 H362.6 Z"><title>extern template, parsing TU (Apple clang): &#8722;7 %</title></path> <text class=nj-charts-val x=367.6 y=132.5>&#8722;7 %</text> <path class=nj-charts-gcc d="M362.6 136 H283.86 Q279.86 136 279.86 140 V144 Q279.86 148 283.86 148 H362.6 Z"><title>extern template, parsing TU (G&#8203;CC 16): &#8722;21 %</title></path> <text class=nj-charts-val x=367.6 y=146.5>&#8722;21 %</text> <text class=nj-charts-rowlabel x=8 y=166><tspan class=nj-charts-code>JSON_NO_AUTOMATIC_UDLS</tspan><tspan class=nj-charts-sub> &#183; model TU</tspan></text> <path class=nj-charts-clang d="M362.6 174 H323.26 Q319.26 174 319.26 178 V182 Q319.26 186 323.26 186 H362.6 Z"><title>JSON_NO_AUTOMATIC_UDLS, model TU (Apple clang): &#8722;11 %</title></path> <text class=nj-charts-val x=367.6 y=184.5>&#8722;11 %</text> <path class=nj-charts-gcc d="M362.6 188 H323.26 Q319.26 188 319.26 192 V196 Q319.26 200 323.26 200 H362.6 Z"><title>JSON_NO_AUTOMATIC_UDLS, model TU (G&#8203;CC 16): &#8722;11 %</title></path> <text class=nj-charts-val x=367.6 y=198.5>&#8722;11 %</text> <text class=nj-charts-rowlabel x=8 y=218><tspan class=nj-charts-code>JSON_NO_AUTOMATIC_UDLS</tspan><tspan class=nj-charts-sub> &#183; parsing TU</tspan></text> <path class=nj-charts-clang d="M362.6 226 H362.6 Q358.66 226 358.66 229.94 V234.06 Q358.66 238 362.6 238 H362.6 Z"><title>JSON_NO_AUTOMATIC_UDLS, parsing TU (Apple clang): &#8722;1 %</title></path> <text class=nj-charts-val x=367.6 y=236.5>&#8722;1 %</text> <path class=nj-charts-gcc d="M362.6 240 H358.72 Q354.72 240 354.72 244 V248 Q354.72 252 358.72 252 H362.6 Z"><title>JSON_NO_AUTOMATIC_UDLS, parsing TU (G&#8203;CC 16): &#8722;2 %</title></path> <text class=nj-charts-val x=367.6 y=250.5>&#8722;2 %</text> <text class=nj-charts-rowlabel x=8 y=270><tspan class=nj-charts-code>JSON_HAS_FILESYSTEM=0 + JSON_NO_IO</tspan><tspan class=nj-charts-sub> &#183; model TU</tspan></text> <path class=nj-charts-clang d="M362.6 278 H335.08 Q331.08 2Line truncated
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json_fwd.hpp&gt;</span>
<span class=k>struct</span><span class=w> </span><span class=nc>person</span><span class=p>;</span>
@@ -9,14 +43,31 @@
<span class=kt>void</span><span class=w> </span><span class=nf>to_json</span><span class=p>(</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>person</span><span class=o>&amp;</span><span class=w> </span><span class=n>p</span><span class=p>)</span><span class=w> </span><span class=p>{</span><span class=w> </span><span class=cm>/* ... */</span><span class=w> </span><span class=p>}</span>
<span class=kt>void</span><span class=w> </span><span class=nf>from_json</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>person</span><span class=o>&amp;</span><span class=w> </span><span class=n>p</span><span class=p>)</span><span class=w> </span><span class=p>{</span><span class=w> </span><span class=cm>/* ... */</span><span class=w> </span><span class=p>}</span>
</code></pre></div> <table> <thead> <tr> <th>Compiler</th> <th style="text-align: right;"><code>json.hpp</code> (<code>-O0</code>)</th> <th style="text-align: right;"><code>json_fwd.hpp</code> (<code>-O0</code>)</th> <th style="text-align: right;">Change</th> </tr> </thead> <tbody> <tr> <td>Apple clang</td> <td style="text-align: right;">704 ms</td> <td style="text-align: right;">329 ms</td> <td style="text-align: right;">−53%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td style="text-align: right;">779 ms</td> <td style="text-align: right;">242 ms</td> <td style="text-align: right;">−69%</td> </tr> </tbody> </table> <p>This is the most effective option, because it avoids the full header in every translation unit that includes <em>your</em> headers.</p> <h2 id=opt-out-of-the-automatic-user-defined-string-literals>Opt out of the automatic user-defined string literals<a class=headerlink href=#opt-out-of-the-automatic-user-defined-string-literals title="Permanent link">&para;</a></h2> <p>The user-defined string literals <a href=../../api/operator_literal_json/ ><code>operator""_json</code></a> and <a href=../../api/operator_literal_json_pointer/ ><code>operator""_json_pointer</code></a> are ordinary inline functions whose bodies call the parser. As <code>&lt;nlohmann/json.hpp&gt;</code> includes them by default, every translation unit instantiates the parser, even if it never parses anything itself.</p> <p>Define <a href=../../api/macros/json_no_automatic_udls/ ><code>JSON_NO_AUTOMATIC_UDLS</code></a> for the whole project and include <code>&lt;nlohmann/json_literals.hpp&gt;</code> instead of <code>&lt;nlohmann/json.hpp&gt;</code> in the files that use the literals (it includes <code>&lt;nlohmann/json.hpp&gt;</code> itself):</p> <div class=highlight><pre><span></span><code><span class=nb>target_compile_definitions</span><span class=p>(</span><span class=s>my_target</span><span class=w> </span><span class=s>PRIVATE</span><span class=w> </span><span class=s>JSON_NO_AUTOMATIC_UDLS</span><span class=p>)</span>
</code></pre></div> <table> <thead> <tr> <th>Compiler</th> <th style="text-align: right;"><code>json.hpp</code> (<code>-O0</code>)</th> <th style="text-align: right;"><code>json_fwd.hpp</code> (<code>-O0</code>)</th> <th style="text-align: right;">Change</th> </tr> </thead> <tbody> <tr> <td>Apple clang</td> <td style="text-align: right;">868 ms</td> <td style="text-align: right;">332 ms</td> <td style="text-align: right;">−62%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td style="text-align: right;">1164 ms</td> <td style="text-align: right;">210 ms</td> <td style="text-align: right;">−82%</td> </tr> </tbody> </table> <p class=nj-table-caption>Compile time of the header-only translation unit at <code>-O0</code> with each header, as the median wall-clock time of nine runs (see "Measurements" above). A negative change means a faster build.</p> <p>This is the most effective option, because it avoids the full header in every translation unit that includes <em>your</em> headers.</p> <h2 id=opt-out-of-the-automatic-user-defined-string-literals>Opt out of the automatic user-defined string literals<a class=headerlink href=#opt-out-of-the-automatic-user-defined-string-literals title="Permanent link">&para;</a></h2> <p>The user-defined string literals <a href=../../api/operator_literal_json/ ><code>operator""_json</code></a> and <a href=../../api/operator_literal_json_pointer/ ><code>operator""_json_pointer</code></a> are ordinary inline functions whose bodies call the parser. As <code>&lt;nlohmann/json.hpp&gt;</code> includes them by default, every translation unit instantiates the parser, even if it never parses anything itself.</p> <p>Define <a href=../../api/macros/json_no_automatic_udls/ ><code>JSON_NO_AUTOMATIC_UDLS</code></a> for the whole project and include <code>&lt;nlohmann/json_literals.hpp&gt;</code> instead of <code>&lt;nlohmann/json.hpp&gt;</code> in the files that use the literals (it includes <code>&lt;nlohmann/json.hpp&gt;</code> itself):</p> <div class=highlight><pre><span></span><code><span class=nb>target_compile_definitions</span><span class=p>(</span><span class=s>my_target</span><span class=w> </span><span class=s>PRIVATE</span><span class=w> </span><span class=s>JSON_NO_AUTOMATIC_UDLS</span><span class=p>)</span>
</code></pre></div> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json_literals.hpp&gt;</span><span class=w> </span><span class=c1>// only where "..."_json is used; includes &lt;nlohmann/json.hpp&gt;</span>
</code></pre></div> <p>The saving applies to translation units that do not parse <abbr title="JavaScript Object Notation">JSON</abbr>, for example ones that define types and their conversions or only pass <code>json</code> values around:</p> <table> <thead> <tr> <th>Compiler</th> <th>Translation unit</th> <th style="text-align: right;">Default (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;"><code>JSON_NO_AUTOMATIC_UDLS</code> (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;">Change</th> </tr> </thead> <tbody> <tr> <td>Apple clang</td> <td>model</td> <td style="text-align: right;">776 ms / 846 ms</td> <td style="text-align: right;">629 ms / 692 ms</td> <td style="text-align: right;">−19% / −18%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>model</td> <td style="text-align: right;">1022 ms / 1120 ms</td> <td style="text-align: right;">882 ms / 965 ms</td> <td style="text-align: right;">−14% / −14%</td> </tr> <tr> <td>Apple clang</td> <td>parsing</td> <td style="text-align: right;">992 ms / 1815 ms</td> <td style="text-align: right;">1006 ms / 1823 ms</td> <td style="text-align: right;">+1% / 0%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>parsing</td> <td style="text-align: right;">2018 ms / 3420 ms</td> <td style="text-align: right;">1990 ms / 3454 ms</td> <td style="text-align: right;">−1% / +1%</td> </tr> </tbody> </table> <p>Translation units that include only the header save up to a third. Translation units that parse anyway instantiate the parser regardless and see no difference.</p> <h2 id=instantiate-basic_json-once>Instantiate <code>basic_json</code> once<a class=headerlink href=#instantiate-basic_json-once title="Permanent link">&para;</a></h2> <p>Each translation unit instantiates the member functions of <code>nlohmann::json</code> it uses. An explicit instantiation declaration tells the compiler that the non-template members are instantiated elsewhere, so it can skip them:</p> <div class=highlight><span class=filename>json_instance.hpp</span><pre><span></span><code><span class=cp>#pragma once</span>
</code></pre></div> <p>The saving applies to translation units that do not parse <abbr title="JavaScript Object Notation">JSON</abbr>, for example ones that define types and their conversions or only pass <code>json</code> values around:</p> <table> <thead> <tr> <th>Compiler</th> <th>Translation unit</th> <th style="text-align: right;">Default (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;"><code>JSON_NO_AUTOMATIC_UDLS</code> (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;">Change</th> </tr> </thead> <tbody> <tr> <td>Apple clang</td> <td>model</td> <td style="text-align: right;">1051 ms / 1300 ms</td> <td style="text-align: right;">935 ms / 1170 ms</td> <td style="text-align: right;">−11% / −10%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>model</td> <td style="text-align: right;">1801 ms / 2106 ms</td> <td style="text-align: right;">1598 ms / 1983 ms</td> <td style="text-align: right;">−11% / −6%</td> </tr> <tr> <td>Apple clang</td> <td>parsing</td> <td style="text-align: right;">1157 ms / 2016 ms</td> <td style="text-align: right;">1146 ms / 2006 ms</td> <td style="text-align: right;">−1% / 0%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>parsing</td> <td style="text-align: right;">2529 ms / 4087 ms</td> <td style="text-align: right;">2484 ms / 4059 ms</td> <td style="text-align: right;">−2% / −1%</td> </tr> </tbody> </table> <p class=nj-table-caption>Compile time of the model and parsing translation units without and with <code>JSON_NO_AUTOMATIC_UDLS</code>, at <code>-O0</code> and <code>-O2</code>.</p> <p>The model translation unit saves about a tenth. Translation units that parse anyway instantiate the parser regardless and see no difference.</p> <h2 id=instantiate-basic_json-once>Instantiate <code>basic_json</code> once<a class=headerlink href=#instantiate-basic_json-once title="Permanent link">&para;</a></h2> <p>Each translation unit instantiates the member functions of <code>nlohmann::json</code> it uses. An explicit instantiation declaration tells the compiler that the non-template members are instantiated elsewhere, so it can skip them:</p> <div class=highlight><span class=filename>json_instance.hpp</span><pre><span></span><code><span class=cp>#pragma once</span>
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
<span class=k>extern</span><span class=w> </span><span class=k>template</span><span class=w> </span><span class=k>class</span><span class=w> </span><span class=nc>nlohmann</span><span class=o>::</span><span class=n>basic_json</span><span class=o>&lt;&gt;</span><span class=p>;</span>
</code></pre></div> <div class=highlight><span class=filename>json_instance.cpp</span><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>"json_instance.hpp"</span>
<span class=k>template</span><span class=w> </span><span class=k>class</span><span class=w> </span><span class=nc>nlohmann</span><span class=o>::</span><span class=n>basic_json</span><span class=o>&lt;&gt;</span><span class=p>;</span>
</code></pre></div> <p>Include <code>json_instance.hpp</code> instead of <code>&lt;nlohmann/json.hpp&gt;</code> and compile and link <code>json_instance.cpp</code> once.</p> <table> <thead> <tr> <th>Compiler</th> <th>Translation unit</th> <th style="text-align: right;">Default (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;"><code>extern template</code> (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;">Change</th> </tr> </thead> <tbody> <tr> <td>Apple clang</td> <td>parsing</td> <td style="text-align: right;">992 ms / 1815 ms</td> <td style="text-align: right;">953 ms / 1625 ms</td> <td style="text-align: right;">−4% / −10%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>parsing</td> <td style="text-align: right;">2018 ms / 3420 ms</td> <td style="text-align: right;">1522 ms / 2728 ms</td> <td style="text-align: right;">−25% / −20%</td> </tr> <tr> <td>Apple clang</td> <td><code>json_instance.cpp</code></td> <td style="text-align: right;">—</td> <td style="text-align: right;">2166 ms / 4660 ms</td> <td style="text-align: right;">—</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td><code>json_instance.cpp</code></td> <td style="text-align: right;">—</td> <td style="text-align: right;">5085 ms / 10616 ms</td> <td style="text-align: right;">—</td> </tr> </tbody> </table> <p>Notes:</p> <ul> <li>The saving grows with the number of translation units that use <code>json</code>, while the instantiation translation unit is compiled only once (and is rarely recompiled, as it does not depend on your code).</li> <li>Member function templates (such as <code>get&lt;T&gt;()</code>, <code>parse(InputType&amp;&amp;)</code>, or <code>value(key, default)</code>) are not covered by the explicit instantiation and are still instantiated where they are used.</li> <li>The declaration covers exactly <code>nlohmann::json</code>. Add the same lines for <code>nlohmann::ordered_json</code> (<code>nlohmann::basic_json&lt;nlohmann::ordered_map&gt;</code>) or your own <code>basic_json</code> specializations if you use them.</li> </ul> <h2 id=use-c20-modules>Use C++20 modules<a class=headerlink href=#use-c20-modules title="Permanent link">&para;</a></h2> <p>With a toolchain that supports named modules, <code>import nlohmann.json;</code> compiles the library once into a module and avoids parsing the header in every translation unit. See <a href=../../features/modules/ >Modules</a> for requirements and known issues. Module support is experimental and currently depends heavily on the compiler version.</p> <h2 id=use-precompiled-headers>Use precompiled headers<a class=headerlink href=#use-precompiled-headers title="Permanent link">&para;</a></h2> <p>Build systems can precompile <code>&lt;nlohmann/json.hpp&gt;</code> together with other stable headers, for example with CMake's <a href="https://cmake.org/cmake/help/latest/command/target_precompile_headers.html"><code>target_precompile_headers</code></a>:</p> <div class=highlight><pre><span></span><code><span class=nb>target_precompile_headers</span><span class=p>(</span><span class=s>my_target</span><span class=w> </span><span class=s>PRIVATE</span><span class=w> </span><span class=s>&lt;nlohmann/json.hpp&gt;</span><span class=p>)</span>
</code></pre></div> <p>This removes the cost of parsing the header, but not of instantiating templates in each translation unit, so it combines well with the options above.</p> <h2 id=options-without-effect-on-compile-times>Options without effect on compile times<a class=headerlink href=#options-without-effect-on-compile-times title="Permanent link">&para;</a></h2> <p>Some configuration macros change what the library declares, but do not measurably change compile times:</p> <table> <thead> <tr> <th>Macro</th> <th style="text-align: right;">Apple clang, model (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;"><abbr title="GNU Compiler Collection">GCC</abbr> 16, model (<code>-O0</code> / <code>-O2</code>)</th> </tr> </thead> <tbody> <tr> <td>default</td> <td style="text-align: right;">776 ms / 846 ms</td> <td style="text-align: right;">1022 ms / 1120 ms</td> </tr> <tr> <td><a href=../../api/macros/json_no_io/ ><code>JSON_NO_IO</code></a></td> <td style="text-align: right;">764 ms / 836 ms</td> <td style="text-align: right;">1022 ms / 1117 ms</td> </tr> <tr> <td><a href=../../api/macros/json_use_global_udls/ ><code>JSON_USE_GLOBAL_UDLS</code></a><code>=0</code></td> <td style="text-align: right;">763 ms / 852 ms</td> <td style="text-align: right;">1019 ms / 1106 ms</td> </tr> </tbody> </table> <p><code>JSON_USE_GLOBAL_UDLS</code> only controls <em>where</em> the literals are declared; to avoid their cost, use <code>JSON_NO_AUTOMATIC_UDLS</code> instead.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/macros/json_no_automatic_udls/ ><code>JSON_NO_AUTOMATIC_UDLS</code></a> - do not include the user-defined string literals automatically</li> <li><a href=../../features/modules/ >Modules</a> - C++20 module support</li> <li><a href=../ >Header only</a> - including the library</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 14, 2026 15:40:55 UTC">October 14, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8Line truncated
</code></pre></div> <p>Include <code>json_instance.hpp</code> instead of <code>&lt;nlohmann/json.hpp&gt;</code> and compile and link <code>json_instance.cpp</code> once.</p> <table> <thead> <tr> <th>Compiler</th> <th>Translation unit</th> <th style="text-align: right;">Default (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;"><code>extern template</code> (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;">Change</th> </tr> </thead> <tbody> <tr> <td>Apple clang</td> <td>parsing</td> <td style="text-align: right;">1157 ms / 2016 ms</td> <td style="text-align: right;">1071 ms / 1844 ms</td> <td style="text-align: right;">−7% / −9%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>parsing</td> <td style="text-align: right;">2529 ms / 4087 ms</td> <td style="text-align: right;">1994 ms / 3190 ms</td> <td style="text-align: right;">−21% / −22%</td> </tr> <tr> <td>Apple clang</td> <td><code>json_instance.cpp</code></td> <td style="text-align: right;">—</td> <td style="text-align: right;">2573 ms / 6221 ms</td> <td style="text-align: right;">—</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td><code>json_instance.cpp</code></td> <td style="text-align: right;">—</td> <td style="text-align: right;">6489 ms / 13759 ms</td> <td style="text-align: right;">—</td> </tr> </tbody> </table> <p class=nj-table-caption>Compile time of the parsing translation unit without and with the <code>extern template</code> declaration, at <code>-O0</code> and <code>-O2</code>. The <code>json_instance.cpp</code> rows are the one-off cost of the translation unit that holds the instantiation.</p> <p>Notes:</p> <ul> <li>The saving grows with the number of translation units that use <code>json</code>, while the instantiation translation unit is compiled only once (and is rarely recompiled, as it does not depend on your code).</li> <li>Member function templates (such as <code>get&lt;T&gt;()</code>, <code>parse(InputType&amp;&amp;)</code>, or <code>value(key, default)</code>) are not covered by the explicit instantiation and are still instantiated where they are used.</li> <li>The declaration covers exactly <code>nlohmann::json</code>. Add the same lines for <code>nlohmann::ordered_json</code> (<code>nlohmann::basic_json&lt;nlohmann::ordered_map&gt;</code>) or your own <code>basic_json</code> specializations if you use them.</li> </ul> <h2 id=switch-off-filesystem-support>Switch off filesystem support<a class=headerlink href=#switch-off-filesystem-support title="Permanent link">&para;</a></h2> <p>With C++17, the library includes <code>&lt;filesystem&gt;</code> to provide conversions from and to <code>std::filesystem::path</code> (see <a href=../../api/macros/json_has_filesystem/ ><code>JSON_HAS_FILESYSTEM</code></a>). Parsing <code>&lt;filesystem&gt;</code> is a fixed cost in every translation unit, and it also pulls in <code>&lt;iomanip&gt;</code>, <code>&lt;istream&gt;</code>, and <code>&lt;ostream&gt;</code> (and, with <abbr title="GNU Compiler Collection">GCC</abbr>'s libstdc++, <code>&lt;sstream&gt;</code>). If you do not convert paths, switch the detection off for the whole project:</p> <div class=highlight><pre><span></span><code><span class=nb>target_compile_definitions</span><span class=p>(</span><span class=s>my_target</span><span class=w> </span><span class=s>PRIVATE</span><span class=w> </span><span class=s>JSON_HAS_FILESYSTEM=0</span><span class=w> </span><span class=s>JSON_HAS_EXPERIMENTAL_FILESYSTEM=0</span><span class=p>)</span>
</code></pre></div> <table> <thead> <tr> <th>Compiler</th> <th>Translation unit</th> <th style="text-align: right;">Default (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;">Filesystem off (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;">Change</th> </tr> </thead> <tbody> <tr> <td>Apple clang</td> <td>model</td> <td style="text-align: right;">1051 ms / 1300 ms</td> <td style="text-align: right;">998 ms / 1257 ms</td> <td style="text-align: right;">−5% / −3%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>model</td> <td style="text-align: right;">1801 ms / 2106 ms</td> <td style="text-align: right;">1636 ms / 2008 ms</td> <td style="text-align: right;">−9% / −5%</td> </tr> <tr> <td>Apple clang</td> <td>parsing</td> <td style="text-align: right;">1157 ms / 2016 ms</td> <td style="text-align: right;">1107 ms / 1971 ms</td> <td style="text-align: right;">−4% / −2%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>parsing</td> <td style="text-align: right;">2529 ms / 4087 ms</td> <td style="text-align: right;">2405 ms / 4029 ms</td> <td style="text-align: right;">−5% / −1%</td> </tr> </tbody> </table> <p class=nj-table-caption>Compile time with <code>JSON_HAS_FILESYSTEM=0</code> and <code>JSON_HAS_EXPERIMENTAL_FILESYSTEM=0</code> against the default configuration, at <code>-O0</code> and <code>-O2</code>.</p> <p>Only with filesystem support switched off does <a href=../../api/macros/json_no_io/ ><code>JSON_NO_IO</code></a> remove the stream headers from the translation unit, so the two macros save most together:</p> <table> <thead> <tr> <th>Compiler</th> <th>Translation unit</th> <th style="text-align: right;">Default (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;">Filesystem off and <code>JSON_NO_IO</code> (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;">Change</th> </tr> </thead> <tbody> <tr> <td>Apple clang</td> <td>model</td> <td style="text-align: right;">1051 ms / 1300 ms</td> <td style="text-align: right;">969 ms / 1219 ms</td> <td style="text-align: right;">−8% / −6%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>model</td> <td style="text-align: right;">1801 ms / 2106 ms</td> <td style="text-align: right;">1605 ms / 1982 ms</td> <td style="text-align: right;">−11% / −6%</td> </tr> <tr> <td>Apple clang</td> <td>parsing</td> <td style="text-align: right;">1157 ms / 2016 ms</td> <td style="text-align: right;">1083 ms / 1947 ms</td> <td style="text-align: right;">−6% / −3%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>parsing</td> <td style="text-align: right;">2529 ms / 4087 ms</td> <td style="text-align: right;">2384 ms / 3972 ms</td> <td style="text-align: right;">−6% / −3%</td> </tr> </tbody> </table> <p class=nj-table-caption>Compile time with filesystem support switched off and <code>JSON_NO_IO</code> defined, against the default configuration, at <code>-O0</code> and <code>-O2</code>.</p> <p>The trade-off: the library's own <code>to_json</code>/<code>from_json</code> overloads for <code>std::filesystem::path</code> (which store the path as <abbr title="Unicode Transformation Format">UTF</abbr>-8) are removed. In a test with both compilers on macOS, paths still converted through their implicit conversion from and to <code>std::string</code>; whether that fallback exists depends on the platform's native path string type (<code>std::wstring</code> on Windows), so check code that converts paths. <code>JSON_NO_IO</code> additionally removes all stream functions (see <a href=#options-without-effect-on-compile-times>Options without effect</a>).</p> <h2 id=use-c20-modules>Use C++20 modules<a class=headerlink href=#use-c20-modules title="Permanent link">&para;</a></h2> <p>With a toolchain that supports named modules, <code>import nlohmann.json;</code> compiles the library once into a module and avoids parsing the header in every translation unit. See <a href=../../features/modules/ >Modules</a> for requirements and known issues. Module support is experimental and currently depends heavily on the compiler version.</p> <div class=nj-fig-wrap> <p><svg class="nj-fig nj-charts nj-charts--compile" viewbox="0 0 440 282" role=img aria-labelledby="nj-charts-mod nj-charts-mod-d" xmlns=http://www.w3.org/2000/svg> <title id=nj-charts-mod>Compile time per translation unit with import nlohmann.json at -O0, and the one-off cost of the module</title> <desc id=nj-charts-mod-d>Horizontal bars, negative is faster, medians of nine runs, -std=c++20 for both. model TU, Apple clang: -48 % (1311 ms to 680 ms); model TU, G&#8203;CC 16: -47 % (2156 ms to 1153 ms); parsing TU, Apple clang: -42 % (1387 ms to 800 ms); parsing TU, G&#8203;CC 16: -36 % (2838 ms to 1810 ms); one-off build, Apple clang: 1630 ms; one-off build, G&#8203;CC 16: 2538 ms.</desc> <rect class=nj-charts-cLine truncated
clang++<span class=w> </span>-std<span class=o>=</span>c++20<span class=w> </span>-fcxx-modules<span class=w> </span>-O0<span class=w> </span>-I<span class=w> </span>single_include<span class=w> </span>-c<span class=w> </span>-x<span class=w> </span>c++-module<span class=w> </span>src/modules/json.cppm<span class=w> </span><span class=se>\</span>
<span class=w> </span>-fmodule-output<span class=o>=</span>nlohmann.json.pcm<span class=w> </span>-o<span class=w> </span>json_mod.o
clang++<span class=w> </span>-std<span class=o>=</span>c++20<span class=w> </span>-fcxx-modules<span class=w> </span>-O0<span class=w> </span>-fmodule-file<span class=o>=</span>nlohmann.json<span class=o>=</span>nlohmann.json.pcm<span class=w> </span>-c<span class=w> </span>model.cpp
<span class=c1># GCC 16 (Homebrew on macOS): writes gcm.cache/nlohmann.json.gcm, found by the importing translation unit</span>
g++-16<span class=w> </span>--sysroot<span class=o>=</span><span class=k>$(</span>xcrun<span class=w> </span>--show-sdk-path<span class=k>)</span><span class=w> </span>-std<span class=o>=</span>c++20<span class=w> </span>-fmodules<span class=w> </span>-O0<span class=w> </span>-I<span class=w> </span>single_include<span class=w> </span>-c<span class=w> </span>src/modules/json.cppm<span class=w> </span><span class=se>\</span>
<span class=w> </span>-o<span class=w> </span>json_mod.o
g++-16<span class=w> </span>--sysroot<span class=o>=</span><span class=k>$(</span>xcrun<span class=w> </span>--show-sdk-path<span class=k>)</span><span class=w> </span>-std<span class=o>=</span>c++20<span class=w> </span>-fmodules<span class=w> </span>-O0<span class=w> </span>-c<span class=w> </span>model.cpp
</code></pre></div> <p>Link <code>json_mod.o</code> into the program.</p> </details> <h2 id=use-precompiled-headers>Use precompiled headers<a class=headerlink href=#use-precompiled-headers title="Permanent link">&para;</a></h2> <p>Build systems can precompile <code>&lt;nlohmann/json.hpp&gt;</code> together with other stable headers, for example with CMake's <a href="https://cmake.org/cmake/help/latest/command/target_precompile_headers.html"><code>target_precompile_headers</code></a>:</p> <div class=highlight><pre><span></span><code><span class=nb>target_precompile_headers</span><span class=p>(</span><span class=s>my_target</span><span class=w> </span><span class=s>PRIVATE</span><span class=w> </span><span class=s>&lt;nlohmann/json.hpp&gt;</span><span class=p>)</span>
</code></pre></div> <p>This removes the cost of parsing the header, but not of instantiating templates in each translation unit, so it combines well with the options above.</p> <div class=nj-fig-wrap> <p><svg class="nj-fig nj-charts nj-charts--compile" viewbox="0 0 440 282" role=img aria-labelledby="nj-charts-pch nj-charts-pch-d" xmlns=http://www.w3.org/2000/svg> <title id=nj-charts-pch>Compile time per translation unit with a precompiled json.hpp at -O0, and the one-off cost of the PCH</title> <desc id=nj-charts-pch-d>Horizontal bars, negative is faster, medians of nine runs, -std=c++17. model TU, Apple clang: -43 % (1045 ms to 594 ms); model TU, G&#8203;CC 16: -41 % (1789 ms to 1060 ms); parsing TU, Apple clang: -38 % (1148 ms to 714 ms); parsing TU, G&#8203;CC 16: -25 % (2498 ms to 1884 ms); one-off build, Apple clang: 771 ms; one-off build, G&#8203;CC 16: 2254 ms.</desc> <rect class=nj-charts-clang x=8 y=10 width=12 height=12 rx=3 /> <text class=nj-charts-leg x=26 y=20.5>Apple clang</text> <rect class=nj-charts-gcc x=126 y=10 width=12 height=12 rx=3 /> <text class=nj-charts-leg x=144 y=20.5>G&#8203;CC 16</text> <line class=nj-charts-grid x1=68.6667 y1=58 x2=68.6667 y2=160 /> <text class=nj-charts-tick x=68.6667 y=176>&#8722;50 %</text> <line class=nj-charts-grid x1=220.333 y1=58 x2=220.333 y2=160 /> <text class=nj-charts-tick x=220.333 y=176>&#8722;25 %</text> <text class=nj-charts-tick x=372 y=176>0 %</text> <text class="nj-charts-tick nj-charts-tick--l" x=8 y=194>&#8592; faster per TU</text> <text class=nj-charts-rowlabel x=8 y=62>model TU<tspan class=nj-charts-sub> &#183; with PCH</tspan></text> <path class=nj-charts-clang d="M372 70 H115.133 Q111.133 70 111.133 74 V78 Q111.133 82 115.133 82 H372 Z"><title>model TU, Apple clang: 1045 ms by default, 594 ms with PCH (&#8722;43 %)</title></path> <text class=nj-charts-val x=377 y=80.5>&#8722;43 %</text> <path class=nj-charts-gcc d="M372 84 H127.267 Q123.267 84 123.267 88 V92 Q123.267 96 127.267 96 H372 Z"><title>model TU, G&#8203;CC 16: 1789 ms by default, 1060 ms with PCH (&#8722;41 %)</title></path> <text class=nj-charts-val x=377 y=94.5>&#8722;41 %</text> <text class=nj-charts-rowlabel x=8 y=114>parsing TU<tspan class=nj-charts-sub> &#183; with PCH</tspan></text> <path class=nj-charts-clang d="M372 122 H145.467 Q141.467 122 141.467 126 V130 Q141.467 134 145.467 134 H372 Z"><title>parsing TU, Apple clang: 1148 ms by default, 714 ms with PCH (&#8722;38 %)</title></path> <text class=nj-charts-val x=377 y=132.5>&#8722;38 %</text> <path class=nj-charts-gcc d="M372 136 H224.333 Q220.333 136 220.333 140 V144 Q220.333 148 224.333 148 H372 Z"><title>parsing TU, G&#8203;CC 16: 2498 ms by default, 1884 ms with PCH (&#8722;25 %)</title></path> <text class=nj-charts-val x=377 y=146.5>&#8722;25 %</text> <line class=nj-charts-zero x1=372 y1=58 x2=372 y2=160 /> <text class=nj-charts-rowlabel x=8 y=222>One-off cost<tspan class=nj-charts-sub> &#183; built once, reused by every TU</tspan></text> <rect class=nj-charts-clang x=8 y=232.5 width=10 height=10 rx=2.5 /> <text class=nj-charts-val x=24 y=242>Apple clang: 771 ms once, saves 434 to 451 ms per TU</text> <rect class=nj-charts-gcc x=8 y=252.5 width=10 height=10 rx=2.5 /> <text class=nj-charts-val x=24 y=262>G&#8203;CC 16: 2254 ms once, saves 614 to 729 ms per TU</text> </svg></p> </div> <p class=nj-caption>Change in compile time per translation unit at <code>-O0</code> with a precompiled <code>&lt;nlohmann/json.hpp&gt;</code> (<code>-std=c++17</code>), and the one-off cost of building the precompiled header, taken from the table below.</p> <table> <thead> <tr> <th>Compiler</th> <th>Translation unit</th> <th style="text-align: right;">Default (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;">With PCH (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;">Change</th> </tr> </thead> <tbody> <tr> <td>Apple clang</td> <td>model</td> <td style="text-align: right;">1045 ms / 1295 ms</td> <td style="text-align: right;">594 ms / 842 ms</td> <td style="text-align: right;">−43% / −35%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>model</td> <td style="text-align: right;">1789 ms / 2101 ms</td> <td style="text-align: right;">1060 ms / 1376 ms</td> <td style="text-align: right;">−41% / −35%</td> </tr> <tr> <td>Apple clang</td> <td>parsing</td> <td style="text-align: right;">1148 ms / 2008 ms</td> <td style="text-align: right;">714 ms / 1584 ms</td> <td style="text-align: right;">−38% / −21%</td> </tr> <tr> <td><abbr title="GNU Compiler Collection">GCC</abbr> 16</td> <td>parsing</td> <td style="text-align: right;">2498 ms / 4075 ms</td> <td style="text-align: right;">1884 ms / 3452 ms</td> <td style="text-align: right;">−25% / −15%</td> </tr> <tr> <td>Apple clang</td> <td>building the PCH</td> <td style="text-align: right;">—</td> <td style="text-align: right;">771 ms / 760 ms</td> <td style="text-align: right;">—</td> </tr> <tr> <tdLine truncated
clang++<span class=w> </span>-std<span class=o>=</span>c++17<span class=w> </span>-O0<span class=w> </span>-I<span class=w> </span>single_include<span class=w> </span>-x<span class=w> </span>c++-header<span class=w> </span>pch.hpp<span class=w> </span>-o<span class=w> </span>pch.hpp.pch
clang++<span class=w> </span>-std<span class=o>=</span>c++17<span class=w> </span>-O0<span class=w> </span>-I<span class=w> </span>single_include<span class=w> </span>-include-pch<span class=w> </span>pch.hpp.pch<span class=w> </span>-include<span class=w> </span>pch.hpp<span class=w> </span>-c<span class=w> </span>model.cpp
<span class=c1># GCC 16 (Homebrew on macOS): pch.hpp.gch next to pch.hpp is picked up by -include pch.hpp</span>
g++-16<span class=w> </span>--sysroot<span class=o>=</span><span class=k>$(</span>xcrun<span class=w> </span>--show-sdk-path<span class=k>)</span><span class=w> </span>-std<span class=o>=</span>c++17<span class=w> </span>-O0<span class=w> </span>-I<span class=w> </span>single_include<span class=w> </span>-x<span class=w> </span>c++-header<span class=w> </span>pch.hpp<span class=w> </span>-o<span class=w> </span>pch.hpp.gch
g++-16<span class=w> </span>--sysroot<span class=o>=</span><span class=k>$(</span>xcrun<span class=w> </span>--show-sdk-path<span class=k>)</span><span class=w> </span>-std<span class=o>=</span>c++17<span class=w> </span>-O0<span class=w> </span>-I<span class=w> </span>single_include<span class=w> </span>-include<span class=w> </span>pch.hpp<span class=w> </span>-Winvalid-pch<span class=w> </span>-c<span class=w> </span>model.cpp
</code></pre></div> </details> <h2 id=options-without-effect-on-compile-times>Options without effect on compile times<a class=headerlink href=#options-without-effect-on-compile-times title="Permanent link">&para;</a></h2> <p>Some configuration macros change what the library declares, but do not measurably change compile times:</p> <table> <thead> <tr> <th>Macro</th> <th style="text-align: right;">Apple clang, model (<code>-O0</code> / <code>-O2</code>)</th> <th style="text-align: right;"><abbr title="GNU Compiler Collection">GCC</abbr> 16, model (<code>-O0</code> / <code>-O2</code>)</th> </tr> </thead> <tbody> <tr> <td>default</td> <td style="text-align: right;">1051 ms / 1300 ms</td> <td style="text-align: right;">1801 ms / 2106 ms</td> </tr> <tr> <td><a href=../../api/macros/json_no_io/ ><code>JSON_NO_IO</code></a></td> <td style="text-align: right;">1034 ms / 1288 ms</td> <td style="text-align: right;">1756 ms / 2087 ms</td> </tr> <tr> <td><a href=../../api/macros/json_use_global_udls/ ><code>JSON_USE_GLOBAL_UDLS</code></a><code>=0</code></td> <td style="text-align: right;">1055 ms / 1298 ms</td> <td style="text-align: right;">1783 ms / 2109 ms</td> </tr> </tbody> </table> <p class=nj-table-caption>Compile time of the model translation unit with each macro defined; the first row is the default configuration for comparison.</p> <p><code>JSON_NO_IO</code> removes the library's stream functions and its <code>#include</code>s of <code>&lt;istream&gt;</code> and <code>&lt;ostream&gt;</code>, but with the default C++17 settings <code>&lt;filesystem&gt;</code> includes these headers anyway (and with libc++, <code>&lt;vector&gt;</code> already includes <code>&lt;streambuf&gt;</code> via <code>&lt;locale&gt;</code>), so only a few hundred lines of the library's own stream code go away. It also does not change what the translation unit instantiates. On the parsing translation unit, the change is 0% / 0% (Apple clang) and −2% / 0% (<abbr title="GNU Compiler Collection">GCC</abbr>). To get a saving, combine it with <a href=#switch-off-filesystem-support>switching off filesystem support</a>.</p> <p><code>JSON_USE_GLOBAL_UDLS</code> only controls <em>where</em> the literals are declared; to avoid their cost, use <code>JSON_NO_AUTOMATIC_UDLS</code> instead.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/macros/json_has_filesystem/ ><code>JSON_HAS_FILESYSTEM</code></a> - control the conversions from and to <code>std::filesystem::path</code></li> <li><a href=../../api/macros/json_no_automatic_udls/ ><code>JSON_NO_AUTOMATIC_UDLS</code></a> - do not include the user-defined string literals automatically</li> <li><a href=../../features/modules/ >Modules</a> - C++20 module support</li> <li><a href=../ >Header only</a> - including the library</li> <li><a href=../../api/macros/ >Macros</a> - reference of all macros</li> <li><a href=../../features/macros/ >Supported Macros</a> - overview of all configuration macros</li> <li><a href=../../features/performance/ >Performance</a> - run-time performance</li> <li><a href=../../api/macros/json_no_io/ ><code>JSON_NO_IO</code></a> - remove all stream and file I/O</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../pkg-config/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Pkg-config"> <div class="md-footer__button md-icon"> <svLine truncated
+182 -15
View File
@@ -4,7 +4,64 @@ The library is header-only and makes heavy use of templates, so every translatio
Measurements
The numbers below are medians of nine runs compiling a single translation unit with `-std=c++17 -c` against the single-header version, with Apple clang and GCC 16 on macOS (Apple silicon). They show the order of magnitude to expect; measure your own code before and after a change.
The numbers below are medians of the wall-clock time of nine runs compiling a single translation unit with `-std=c++17 -c` against the single-header version, with Apple clang 21.0.0 (clang-2100.3.34.2) and Homebrew GCC 16.2.0 on macOS (Apple M1 Max). All configurations were run interleaved, in alternating order. They show the order of magnitude to expect; measure your own code before and after a change.
The translation units are listed below. They replace the ones used for earlier versions of this page, whose sources were not published, so the numbers differ from earlier versions.
Measured translation units
The *model* and *parsing* translation units start with `#include <string>`, `#include <vector>`, and `#include <nlohmann/json.hpp>`; the *header-only* translation unit includes only the library header.
model translation unit
```
struct person
{
std::string name;
int age = 0;
std::vector<std::string> tags;
};
void to_json(nlohmann::json& j, const person& p)
{
j = nlohmann::json{{"name", p.name}, {"age", p.age}, {"tags", p.tags}};
}
void from_json(const nlohmann::json& j, person& p)
{
j.at("name").get_to(p.name);
j.at("age").get_to(p.age);
j.at("tags").get_to(p.tags);
}
nlohmann::json roundtrip(const person& p)
{
nlohmann::json j = p;
return nlohmann::json(j.get<person>());
}
```
parsing translation unit
```
std::size_t parse_and_dump(const std::string& s)
{
const nlohmann::json j = nlohmann::json::parse(s);
return j.dump(2).size();
}
```
header-only translation unit
```
#include <nlohmann/json.hpp> // or <nlohmann/json_fwd.hpp>
struct person;
void to_json(nlohmann::json& j, const person& p);
void from_json(const nlohmann::json& j, person& p);
```
Change in compile time at `-O0` against the default configuration of the same translation unit, taken from the tables below (medians of nine runs, see above). * computed from the milliseconds in [Options without effect on compile times](#options-without-effect-on-compile-times).
## Include `json_fwd.hpp` in headers
@@ -33,8 +90,10 @@ void from_json(const nlohmann::json& j, person& p) { /* ... */ }
| Compiler | `json.hpp` (`-O0`) | `json_fwd.hpp` (`-O0`) | Change |
| ----------- | ------------------ | ---------------------- | ------ |
| Apple clang | 704 ms | 329 ms | −53% |
| GCC 16 | 779 ms | 242 ms | −69% |
| Apple clang | 868 ms | 332 ms | −62% |
| GCC 16 | 1164 ms | 210 ms | −82% |
Compile time of the header-only translation unit at `-O0` with each header, as the median wall-clock time of nine runs (see "Measurements" above). A negative change means a faster build.
This is the most effective option, because it avoids the full header in every translation unit that includes *your* headers.
@@ -56,12 +115,14 @@ The saving applies to translation units that do not parse JSON, for example ones
| Compiler | Translation unit | Default (`-O0` / `-O2`) | `JSON_NO_AUTOMATIC_UDLS` (`-O0` / `-O2`) | Change |
| ----------- | ---------------- | ----------------------- | ---------------------------------------- | ----------- |
| Apple clang | model | 776 ms / 846 ms | 629 ms / 692 ms | −19% / −18% |
| GCC 16 | model | 1022 ms / 1120 ms | 882 ms / 965 ms | −14% / −14% |
| Apple clang | parsing | 992 ms / 1815 ms | 1006 ms / 1823 ms | +1% / 0% |
| GCC 16 | parsing | 2018 ms / 3420 ms | 1990 ms / 3454 ms | −1% / +1% |
| Apple clang | model | 1051 ms / 1300 ms | 935 ms / 1170 ms | −11% / −10% |
| GCC 16 | model | 1801 ms / 2106 ms | 1598 ms / 1983 ms | −11% / −6% |
| Apple clang | parsing | 1157 ms / 2016 ms | 1146 ms / 2006 ms | −1% / 0% |
| GCC 16 | parsing | 2529 ms / 4087 ms | 2484 ms / 4059 ms | −2% / −1% |
Translation units that include only the header save up to a third. Translation units that parse anyway instantiate the parser regardless and see no difference.
Compile time of the model and parsing translation units without and with `JSON_NO_AUTOMATIC_UDLS`, at `-O0` and `-O2`.
The model translation unit saves about a tenth. Translation units that parse anyway instantiate the parser regardless and see no difference.
## Instantiate `basic_json` once
@@ -88,10 +149,12 @@ Include `json_instance.hpp` instead of `<nlohmann/json.hpp>` and compile and lin
| Compiler | Translation unit | Default (`-O0` / `-O2`) | `extern template` (`-O0` / `-O2`) | Change |
| ----------- | ------------------- | ----------------------- | --------------------------------- | ----------- |
| Apple clang | parsing | 992 ms / 1815 ms | 953 ms / 1625 ms | −4% / −10% |
| GCC 16 | parsing | 2018 ms / 3420 ms | 1522 ms / 2728 ms | −25% / −20% |
| Apple clang | `json_instance.cpp` | — | 2166 ms / 4660 ms | — |
| GCC 16 | `json_instance.cpp` | — | 5085 ms / 10616 ms | — |
| Apple clang | parsing | 1157 ms / 2016 ms | 1071 ms / 1844 ms | −7% / −9% |
| GCC 16 | parsing | 2529 ms / 4087 ms | 1994 ms / 3190 ms | −21% / −22% |
| Apple clang | `json_instance.cpp` | — | 2573 ms / 6221 ms | — |
| GCC 16 | `json_instance.cpp` | — | 6489 ms / 13759 ms | — |
Compile time of the parsing translation unit without and with the `extern template` declaration, at `-O0` and `-O2`. The `json_instance.cpp` rows are the one-off cost of the translation unit that holds the instantiation.
Notes:
@@ -99,10 +162,76 @@ Notes:
- Member function templates (such as `get<T>()`, `parse(InputType&&)`, or `value(key, default)`) are not covered by the explicit instantiation and are still instantiated where they are used.
- The declaration covers exactly `nlohmann::json`. Add the same lines for `nlohmann::ordered_json` (`nlohmann::basic_json<nlohmann::ordered_map>`) or your own `basic_json` specializations if you use them.
## Switch off filesystem support
With C++17, the library includes `<filesystem>` to provide conversions from and to `std::filesystem::path` (see [`JSON_HAS_FILESYSTEM`](https://json.nlohmann.me/api/macros/json_has_filesystem/index.md)). Parsing `<filesystem>` is a fixed cost in every translation unit, and it also pulls in `<iomanip>`, `<istream>`, and `<ostream>` (and, with GCC's libstdc++, `<sstream>`). If you do not convert paths, switch the detection off for the whole project:
```
target_compile_definitions(my_target PRIVATE JSON_HAS_FILESYSTEM=0 JSON_HAS_EXPERIMENTAL_FILESYSTEM=0)
```
| Compiler | Translation unit | Default (`-O0` / `-O2`) | Filesystem off (`-O0` / `-O2`) | Change |
| ----------- | ---------------- | ----------------------- | ------------------------------ | --------- |
| Apple clang | model | 1051 ms / 1300 ms | 998 ms / 1257 ms | −5% / −3% |
| GCC 16 | model | 1801 ms / 2106 ms | 1636 ms / 2008 ms | −9% / −5% |
| Apple clang | parsing | 1157 ms / 2016 ms | 1107 ms / 1971 ms | −4% / −2% |
| GCC 16 | parsing | 2529 ms / 4087 ms | 2405 ms / 4029 ms | −5% / −1% |
Compile time with `JSON_HAS_FILESYSTEM=0` and `JSON_HAS_EXPERIMENTAL_FILESYSTEM=0` against the default configuration, at `-O0` and `-O2`.
Only with filesystem support switched off does [`JSON_NO_IO`](https://json.nlohmann.me/api/macros/json_no_io/index.md) remove the stream headers from the translation unit, so the two macros save most together:
| Compiler | Translation unit | Default (`-O0` / `-O2`) | Filesystem off and `JSON_NO_IO` (`-O0` / `-O2`) | Change |
| ----------- | ---------------- | ----------------------- | ----------------------------------------------- | ---------- |
| Apple clang | model | 1051 ms / 1300 ms | 969 ms / 1219 ms | −8% / −6% |
| GCC 16 | model | 1801 ms / 2106 ms | 1605 ms / 1982 ms | −11% / −6% |
| Apple clang | parsing | 1157 ms / 2016 ms | 1083 ms / 1947 ms | −6% / −3% |
| GCC 16 | parsing | 2529 ms / 4087 ms | 2384 ms / 3972 ms | −6% / −3% |
Compile time with filesystem support switched off and `JSON_NO_IO` defined, against the default configuration, at `-O0` and `-O2`.
The trade-off: the library's own `to_json`/`from_json` overloads for `std::filesystem::path` (which store the path as UTF-8) are removed. In a test with both compilers on macOS, paths still converted through their implicit conversion from and to `std::string`; whether that fallback exists depends on the platform's native path string type (`std::wstring` on Windows), so check code that converts paths. `JSON_NO_IO` additionally removes all stream functions (see [Options without effect](#options-without-effect-on-compile-times)).
## Use C++20 modules
With a toolchain that supports named modules, `import nlohmann.json;` compiles the library once into a module and avoids parsing the header in every translation unit. See [Modules](https://json.nlohmann.me/features/modules/index.md) for requirements and known issues. Module support is experimental and currently depends heavily on the compiler version.
Change in compile time per translation unit at `-O0` when `#include <nlohmann/json.hpp>` is replaced by `import nlohmann.json;`, both with `-std=c++20`, and the one-off cost of building the module, taken from the table below.
| Compiler | Translation unit | `#include` (`-O0` / `-O2`) | `import nlohmann.json;` (`-O0` / `-O2`) | Change |
| ----------- | -------------------- | -------------------------- | --------------------------------------- | ----------- |
| Apple clang | model | 1311 ms / 1597 ms | 680 ms / 914 ms | −48% / −43% |
| GCC 16 | model | 2156 ms / 2588 ms | 1153 ms / 1580 ms | −47% / −39% |
| Apple clang | parsing | 1387 ms / 2319 ms | 800 ms / 1676 ms | −42% / −28% |
| GCC 16 | parsing | 2838 ms / 4520 ms | 1810 ms / 3476 ms | −36% / −23% |
| Apple clang | `json.cppm` (module) | — | 1630 ms / 1642 ms | — |
| GCC 16 | `json.cppm` (module) | — | 2538 ms / 2547 ms | — |
Compile time with `#include <nlohmann/json.hpp>` and with `import nlohmann.json;`, both with `-std=c++20`, at `-O0` and `-O2`. The `json.cppm` rows are the one-off cost of building the module.
Both columns use `-std=c++20`; with `-std=c++17`, the `#include` baseline is 17% to 20% faster (see the next section). The module is built once per set of compiler flags and pays for itself from about the third translation unit that imports it. Notes from the measurement:
- Apple clang only accepts the module declarations with `-fcxx-modules`; without it, `module;` is a syntax error.
- GCC 16 warns with `-Wexpose-global-module-tu-local` about internal constants of the library when building the module. With GCC 16.2, including `<string>` and `<vector>` before `import nlohmann.json;` works, but including them after it fails with redefinition errors ([#5103](https://github.com/nlohmann/json/issues/5103)).
How these numbers were measured
The model and parsing translation units are the ones listed at the top of this page, with `import nlohmann.json;` in place of `#include <nlohmann/json.hpp>` (after `#include <string>` and `#include <vector>`). Same method as for the other tables, with `-std=c++20`.
```
# Apple clang: build the module once, then import it
clang++ -std=c++20 -fcxx-modules -O0 -I single_include -c -x c++-module src/modules/json.cppm \
-fmodule-output=nlohmann.json.pcm -o json_mod.o
clang++ -std=c++20 -fcxx-modules -O0 -fmodule-file=nlohmann.json=nlohmann.json.pcm -c model.cpp
# GCC 16 (Homebrew on macOS): writes gcm.cache/nlohmann.json.gcm, found by the importing translation unit
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++20 -fmodules -O0 -I single_include -c src/modules/json.cppm \
-o json_mod.o
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++20 -fmodules -O0 -c model.cpp
```
Link `json_mod.o` into the program.
## Use precompiled headers
Build systems can precompile `<nlohmann/json.hpp>` together with other stable headers, for example with CMake's [`target_precompile_headers`](https://cmake.org/cmake/help/latest/command/target_precompile_headers.html):
@@ -113,20 +242,58 @@ target_precompile_headers(my_target PRIVATE <nlohmann/json.hpp>)
This removes the cost of parsing the header, but not of instantiating templates in each translation unit, so it combines well with the options above.
Change in compile time per translation unit at `-O0` with a precompiled `<nlohmann/json.hpp>` (`-std=c++17`), and the one-off cost of building the precompiled header, taken from the table below.
| Compiler | Translation unit | Default (`-O0` / `-O2`) | With PCH (`-O0` / `-O2`) | Change |
| ----------- | ---------------- | ----------------------- | ------------------------ | ----------- |
| Apple clang | model | 1045 ms / 1295 ms | 594 ms / 842 ms | −43% / −35% |
| GCC 16 | model | 1789 ms / 2101 ms | 1060 ms / 1376 ms | −41% / −35% |
| Apple clang | parsing | 1148 ms / 2008 ms | 714 ms / 1584 ms | −38% / −21% |
| GCC 16 | parsing | 2498 ms / 4075 ms | 1884 ms / 3452 ms | −25% / −15% |
| Apple clang | building the PCH | — | 771 ms / 760 ms | — |
| GCC 16 | building the PCH | — | 2254 ms / 2218 ms | — |
Compile time without and with a precompiled `<nlohmann/json.hpp>`, at `-O0` and `-O2`. The last two rows are the one-off cost of building the precompiled header.
The saving is largest in translation units that instantiate little, and the PCH pays for itself from the second (Apple clang) or fourth (GCC) translation unit. A precompiled header only works with the flags it was built with: GCC silently ignores a mismatching `.gch` file (for example one built with another `-O` level) unless `-Winvalid-pch` is given.
How these numbers were measured
`pch.hpp` contains only `#include <nlohmann/json.hpp>`; the translation units are the ones listed at the top of this page.
```
# Apple clang
clang++ -std=c++17 -O0 -I single_include -x c++-header pch.hpp -o pch.hpp.pch
clang++ -std=c++17 -O0 -I single_include -include-pch pch.hpp.pch -include pch.hpp -c model.cpp
# GCC 16 (Homebrew on macOS): pch.hpp.gch next to pch.hpp is picked up by -include pch.hpp
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++17 -O0 -I single_include -x c++-header pch.hpp -o pch.hpp.gch
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++17 -O0 -I single_include -include pch.hpp -Winvalid-pch -c model.cpp
```
## Options without effect on compile times
Some configuration macros change what the library declares, but do not measurably change compile times:
| Macro | Apple clang, model (`-O0` / `-O2`) | GCC 16, model (`-O0` / `-O2`) |
| ----------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------- |
| default | 776 ms / 846 ms | 1022 ms / 1120 ms |
| [`JSON_NO_IO`](https://json.nlohmann.me/api/macros/json_no_io/index.md) | 764 ms / 836 ms | 1022 ms / 1117 ms |
| [`JSON_USE_GLOBAL_UDLS`](https://json.nlohmann.me/api/macros/json_use_global_udls/index.md)`=0` | 763 ms / 852 ms | 1019 ms / 1106 ms |
| default | 1051 ms / 1300 ms | 1801 ms / 2106 ms |
| [`JSON_NO_IO`](https://json.nlohmann.me/api/macros/json_no_io/index.md) | 1034 ms / 1288 ms | 1756 ms / 2087 ms |
| [`JSON_USE_GLOBAL_UDLS`](https://json.nlohmann.me/api/macros/json_use_global_udls/index.md)`=0` | 1055 ms / 1298 ms | 1783 ms / 2109 ms |
Compile time of the model translation unit with each macro defined; the first row is the default configuration for comparison.
`JSON_NO_IO` removes the library's stream functions and its `#include`s of `<istream>` and `<ostream>`, but with the default C++17 settings `<filesystem>` includes these headers anyway (and with libc++, `<vector>` already includes `<streambuf>` via `<locale>`), so only a few hundred lines of the library's own stream code go away. It also does not change what the translation unit instantiates. On the parsing translation unit, the change is 0% / 0% (Apple clang) and −2% / 0% (GCC). To get a saving, combine it with [switching off filesystem support](#switch-off-filesystem-support).
`JSON_USE_GLOBAL_UDLS` only controls *where* the literals are declared; to avoid their cost, use `JSON_NO_AUTOMATIC_UDLS` instead.
## See also
- [`JSON_HAS_FILESYSTEM`](https://json.nlohmann.me/api/macros/json_has_filesystem/index.md) - control the conversions from and to `std::filesystem::path`
- [`JSON_NO_AUTOMATIC_UDLS`](https://json.nlohmann.me/api/macros/json_no_automatic_udls/index.md) - do not include the user-defined string literals automatically
- [Modules](https://json.nlohmann.me/features/modules/index.md) - C++20 module support
- [Header only](https://json.nlohmann.me/integration/index.md) - including the library
- [Macros](https://json.nlohmann.me/api/macros/index.md) - reference of all macros
- [Supported Macros](https://json.nlohmann.me/features/macros/index.md) - overview of all configuration macros
- [Performance](https://json.nlohmann.me/features/performance/index.md) - run-time performance
- [`JSON_NO_IO`](https://json.nlohmann.me/api/macros/json_no_io/index.md) - remove all stream and file I/O
+14 -11
View File
@@ -1,14 +1,17 @@
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/" rel="canonical"><link href=../features/json_view/ rel=prev><link href=migration_guide/ rel=next><link rel=icon href=../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Integration - JSON for Modern C++</title><link rel=stylesheet href=../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../css/custom.css><script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#integration class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Integration </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-md-componentLine truncated
A[Add the library to a C++ project] --&gt; B{Already using CMake?}
B -- no --&gt; C{Using pkg-config or plain Makefiles?}
C -- yes --&gt; D[pkg-config]
C -- no --&gt; E[Copy the single header]
B -- yes --&gt; F{Library installed system-wide?}
F -- yes --&gt; G["find_package()"]
F -- no --&gt; H{Use a package manager?}
H -- yes --&gt; I[Package manager]
H -- no --&gt; J["add_subdirectory() or FetchContent"]</code></pre> <ul> <li><strong>Copy the single header</strong>, as described <a href=#header-only>below</a> — no build-system integration required.</li> <li><strong>CMake</strong>: use <a href=cmake/#external><code>find_package()</code></a> if the library is already installed, <a href=cmake/#embedded><code>add_subdirectory()</code></a> to embed the source tree, or <a href=cmake/#fetchcontent><code>FetchContent</code></a> to download it at configure time; see <a href=cmake/ >CMake</a>.</li> <li><strong>Package managers</strong>: install the library with a package manager such as Homebrew, Conan, or vcpkg; see <a href=package_managers/ >Package Managers</a>.</li> <li><strong>pkg-config</strong>: if you use bare Makefiles instead of CMake, <a href=pkg-config/ >pkg-config</a> can supply the include flags for an already-installed library.</li> </ul> <p>Once the library is integrated, see the <a href=migration_guide/ >Migration Guide</a> for how to keep your code future-proof across releases.</p> <h2 id=header-only>Header only<a class=headerlink href=#header-only title="Permanent link">&para;</a></h2> <p><a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp"><code>json.hpp</code></a> is the single required file in <code>single_include/nlohmann</code> or <a href="https://github.com/nlohmann/json/releases">released here</a>. You need to add</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/" rel="canonical"><link href=../features/json_view/ rel=prev><link href=migration_guide/ rel=next><link rel=icon href=../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Integration - JSON for Modern C++</title><link rel=stylesheet href=../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../css/custom.css><link rel=stylesheet href=../css/brand.css><link rel=stylesheet href=../css/fig-sax.css><link rel=stylesheet href=../css/fig-jsonview.css><link rel=stylesheet href=../css/fig-exceptions.css><link rel=stylesheet href=../css/fig-pointer.css><link rel=stylesheet href=../css/fig-charts.css><link rel=stylesheet href=../css/fig-integration.css><link rel=stylesheet href=../css/fig-macros.css><script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#integration class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Integration </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.Line truncated
A[Add the library to a C++ project] --&gt; B{{Using CMake?}}
B -- no --&gt; C{{Package manager available?}}
C -- yes --&gt; D["&lt;b&gt;Use a package manager&lt;/b&gt;&lt;br&gt;see Package Managers"]
C -- no --&gt; E["&lt;b&gt;Copy the single header&lt;/b&gt;&lt;br&gt;see Header only"]
B -- yes --&gt; F{{Already installed?}}
F -- yes --&gt; G["&lt;b&gt;find_package&lt;/b&gt;&lt;br&gt;see CMake, External"]
F -- no --&gt; H{{CMake 3.14 or later?}}
H -- yes --&gt; I["&lt;b&gt;FetchContent&lt;/b&gt;&lt;br&gt;see CMake, FetchContent"]
H -- no --&gt; J["&lt;b&gt;add_subdirectory&lt;/b&gt;&lt;br&gt;see CMake, Embedded"]
G --&gt; T["&lt;code&gt;nlohmann_json::nlohmann_json&lt;/code&gt;"]
I --&gt; T
J --&gt; T</code></pre> <p class=nj-caption>Choosing an integration method: answer the questions in the hexagons from top to bottom to reach a method. All CMake methods end at the same target, <code>nlohmann_json::nlohmann_json</code>; the list below links to each method.</p> <ul> <li><strong>Single header</strong>: copy <a href=#header-only><code>json.hpp</code></a> into your project; no build-system integration required.</li> <li><strong>CMake</strong>, see <a href=cmake/ >CMake</a>:<ul> <li><a href=cmake/#external><code>find_package()</code></a> if the library is already installed;</li> <li><a href=cmake/#fetchcontent><code>FetchContent</code></a> to download it at configure time (CMake 3.14 or later);</li> <li><a href=cmake/#embedded><code>add_subdirectory()</code></a> to embed a vendored copy of the source tree;</li> <li>or <a href=cmake/#supporting-both>support both</a> with an option that selects installed or vendored.</li> </ul> </li> <li><strong>Package managers</strong>: install the library with Homebrew, Conan, vcpkg, or one of the many others; see <a href=package_managers/ >Package Managers</a> for the full list.</li> <li><strong>pkg-config</strong>: if you use bare Makefiles instead of CMake, <a href=pkg-config/ >pkg-config</a> supplies the include flags for an already-installed library.</li> </ul> <p>Once the library is integrated, see the <a href=migration_guide/ >Migration Guide</a> for how to keep your code future-proof across releases.</p> <h2 id=header-only>Header only<a class=headerlink href=#header-only title="Permanent link">&para;</a></h2> <p><a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp"><code>json.hpp</code></a> is the single required file in <code>single_include/nlohmann</code> or <a href="https://github.com/nlohmann/json/releases">released here</a>. You need to add</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
<span class=c1>// for convenience</span>
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
</code></pre></div> <p>to the files you want to process <abbr title="JavaScript Object Notation">JSON</abbr> and set the necessary switches to enable C++11 (e.g., <code>-std=c++11</code> for <abbr title="GNU Compiler Collection">GCC</abbr> and Clang).</p> <div class="admonition tip"> <p class=admonition-title>Which file do I download?</p> <p>For a project without a package manager, the library itself, including the <code>_json</code> literals, is <strong>one file</strong>: <a href="https://github.com/nlohmann/json/releases/latest/download/json.hpp"><code>json.hpp</code></a> from the <a href="https://github.com/nlohmann/json/releases">releases page</a>. You do not need to clone the repository, build anything, or link a library. Put the file in a directory named <code>nlohmann</code> that is on your include path (for example <code>third_party/nlohmann/json.hpp</code> with <code>-I third_party</code>), so that <code>#include &lt;nlohmann/json.hpp&gt;</code> works. Download the companion headers listed below only if you use them: <code>json_view.hpp</code> for the <a href=../features/json_view/ >zero-copy views</a>, <code>json_fwd.hpp</code> for forward declarations, and <code>json_literals.hpp</code> if you define <code>JSON_NO_AUTOMATIC_UDLS</code>. Keep them in the same <code>nlohmann</code> directory.</p> <p>Do not copy only parts of the repository's <code>include/</code> directory: the headers in it include each other and must be kept together. If your <abbr title="Integrated Development Environment">IDE</abbr> reports "cannot open source file" while the compiler succeeds, the compiler's include path is set correctly but the <abbr title="Integrated Development Environment">IDE</abbr>'s is not; add the same directory to the <abbr title="Integrated Development Environment">IDE</abbr>'s include paths.</p> </div> <p>You can further use file <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp"><code>single_include/nlohmann/json_fwd.hpp</code></a> for forward declarations (see <a href=compile_times/ >Compile times</a>), and file <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_literals.hpp"><code>single_include/nlohmann/json_literals.hpp</code></a> for the user-defined string literals if you define <a href=../api/macros/json_no_automatic_udls/ ><code>JSON_NO_AUTOMATIC_UDLS</code></a>.</p> <p>For the read-only, non-owning <a href=../api/basic_json_document/ ><code>basic_json_document</code></a>/<a href=../api/basic_json_view/ ><code>basic_json_view</code></a> types, additionally include <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_view.hpp"><code>single_include/nlohmann/json_view.hpp</code></a>; see <a href=../features/json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a>.</p> <h2 id=notes-for-builds-and-distribution>Notes for builds and distribution<a class=headerlink href=#notes-for-builds-and-distribution title="Permanent link">&para;</a></h2> <p><strong>Reproducible and path-independent builds.</strong> The runtime assertions use <code>assert</code>, which embeds the name of the source file (<code>__FILE__</code>) in the binary. Release builds do not contain them, because they define <code>NDEBUG</code>. If you compile with assertions enabled and need binaries that do not depend on the build directory, either define <code>NDEBUG</code> or map the prefix of the path with the compiler option <code>-ffile-prefix-map=&lt;old&gt;=&lt;new&gt;</code> (<abbr title="GNU Compiler Collection">GCC</abbr> 8 and later, Clang 10 and later). See <a href=../features/assertions/ >Runtime assertions</a>.</p> <p><strong>There is no separate source file to compile.</strong> The library is header-only, so there is no <code>.cpp</code> that could be built with different options than the code that includes it. It is also not available as a precompiled library. To compile the library with optimizations in an otherwise unoptimized build (for example to parse large files in a debug build, which is slow because of the unoptimized code and the checks of the debug standard library), keep the code that uses <code>json</code> in a separate source file and set the options for that file only. <a href=compile_times/ >Compile times</a> shows how to <a href=compile_times/#instantiate-basic_json-once>instantiate <code>basic_json</code> once</a>.</p> <p><strong>Debugger visualization.</strong> The Natvis file works with the Visual Studio debugger, including the <code>cppvsdbg</code> engine in Visual Studio Code, but not with debuggers that wrap <abbr title="LLVM Debugger">LLDB</abbr>, such as <code>codelldb</code>; see <a href=../home/debugging/ >Debugging</a>.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=cmake/ >CMake</a> - integrate the library into a CMake project</li> <li><a href=package_managers/ >Package managers</a></li> <liLine truncated
</code></pre></div> <p>to the files you want to process <abbr title="JavaScript Object Notation">JSON</abbr> and set the necessary switches to enable C++11 (e.g., <code>-std=c++11</code> for <abbr title="GNU Compiler Collection">GCC</abbr> and Clang).</p> <div class="admonition tip"> <p class=admonition-title>Which file do I download?</p> <p>For a project without a package manager, the library itself, including the <code>_json</code> literals, is <strong>one file</strong>: <a href="https://github.com/nlohmann/json/releases/latest/download/json.hpp"><code>json.hpp</code></a> from the <a href="https://github.com/nlohmann/json/releases">releases page</a>. You do not need to clone the repository, build anything, or link a library. Put the file in a directory named <code>nlohmann</code> that is on your include path (for example <code>third_party/nlohmann/json.hpp</code> with <code>-I third_party</code>), so that <code>#include &lt;nlohmann/json.hpp&gt;</code> works. Download the companion headers listed below only if you use them: <code>json_view.hpp</code> for the <a href=../features/json_view/ >zero-copy views</a>, <code>json_fwd.hpp</code> for forward declarations, and <code>json_literals.hpp</code> if you define <code>JSON_NO_AUTOMATIC_UDLS</code>. Keep them in the same <code>nlohmann</code> directory.</p> <p>Do not copy only parts of the repository's <code>include/</code> directory: the headers in it include each other and must be kept together. If your <abbr title="Integrated Development Environment">IDE</abbr> reports "cannot open source file" while the compiler succeeds, the compiler's include path is set correctly but the <abbr title="Integrated Development Environment">IDE</abbr>'s is not; add the same directory to the <abbr title="Integrated Development Environment">IDE</abbr>'s include paths.</p> </div> <p>You can further use file <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp"><code>single_include/nlohmann/json_fwd.hpp</code></a> for forward declarations (see <a href=compile_times/ >Compile times</a>), and file <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_literals.hpp"><code>single_include/nlohmann/json_literals.hpp</code></a> for the user-defined string literals if you define <a href=../api/macros/json_no_automatic_udls/ ><code>JSON_NO_AUTOMATIC_UDLS</code></a>.</p> <p>For the read-only, non-owning <a href=../api/basic_json_document/ ><code>basic_json_document</code></a>/<a href=../api/basic_json_view/ ><code>basic_json_view</code></a> types, additionally include <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_view.hpp"><code>single_include/nlohmann/json_view.hpp</code></a>; see <a href=../features/json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a>.</p> <h2 id=notes-for-builds-and-distribution>Notes for builds and distribution<a class=headerlink href=#notes-for-builds-and-distribution title="Permanent link">&para;</a></h2> <p><strong>Reproducible and path-independent builds.</strong> The runtime assertions use <code>assert</code>, which embeds the name of the source file (<code>__FILE__</code>) in the binary. Release builds do not contain them, because they define <code>NDEBUG</code>. If you compile with assertions enabled and need binaries that do not depend on the build directory, either define <code>NDEBUG</code> or map the prefix of the path with the compiler option <code>-ffile-prefix-map=&lt;old&gt;=&lt;new&gt;</code> (<abbr title="GNU Compiler Collection">GCC</abbr> 8 and later, Clang 10 and later). See <a href=../features/assertions/ >Runtime assertions</a>.</p> <p><strong>There is no separate source file to compile.</strong> The library is header-only, so there is no <code>.cpp</code> that could be built with different options than the code that includes it. It is also not available as a precompiled library. To compile the library with optimizations in an otherwise unoptimized build (for example to parse large files in a debug build, which is slow because of the unoptimized code and the checks of the debug standard library), keep the code that uses <code>json</code> in a separate source file and set the options for that file only. <a href=compile_times/ >Compile times</a> shows how to <a href=compile_times/#instantiate-basic_json-once>instantiate <code>basic_json</code> once</a>.</p> <p><strong>Debugger visualization.</strong> The Natvis file works with the Visual Studio debugger, including the <code>cppvsdbg</code> engine in Visual Studio Code, but not with debuggers that wrap <abbr title="LLVM Debugger">LLDB</abbr>, such as <code>codelldb</code>; see <a href=../home/debugging/ >Debugging</a>.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=cmake/ >CMake</a> - integrate the library into a CMake project</li> <li><a href=package_managers/ >Package managers</a> - instalLine truncated
+30 -16
View File
@@ -4,21 +4,30 @@ There are several ways to add this header-only library to a C++ project. The fol
```
flowchart TD
A[Add the library to a C++ project] --> B{Already using CMake?}
B -- no --> C{Using pkg-config or plain Makefiles?}
C -- yes --> D[pkg-config]
C -- no --> E[Copy the single header]
B -- yes --> F{Library installed system-wide?}
F -- yes --> G["find_package()"]
F -- no --> H{Use a package manager?}
H -- yes --> I[Package manager]
H -- no --> J["add_subdirectory() or FetchContent"]
A[Add the library to a C++ project] --> B{{Using CMake?}}
B -- no --> C{{Package manager available?}}
C -- yes --> D["<b>Use a package manager</b><br>see Package Managers"]
C -- no --> E["<b>Copy the single header</b><br>see Header only"]
B -- yes --> F{{Already installed?}}
F -- yes --> G["<b>find_package</b><br>see CMake, External"]
F -- no --> H{{CMake 3.14 or later?}}
H -- yes --> I["<b>FetchContent</b><br>see CMake, FetchContent"]
H -- no --> J["<b>add_subdirectory</b><br>see CMake, Embedded"]
G --> T["<code>nlohmann_json::nlohmann_json</code>"]
I --> T
J --> T
```
- **Copy the single header**, as described [below](#header-only) — no build-system integration required.
- **CMake**: use [`find_package()`](https://json.nlohmann.me/integration/cmake/#external) if the library is already installed, [`add_subdirectory()`](https://json.nlohmann.me/integration/cmake/#embedded) to embed the source tree, or [`FetchContent`](https://json.nlohmann.me/integration/cmake/#fetchcontent) to download it at configure time; see [CMake](https://json.nlohmann.me/integration/cmake/index.md).
- **Package managers**: install the library with a package manager such as Homebrew, Conan, or vcpkg; see [Package Managers](https://json.nlohmann.me/integration/package_managers/index.md).
- **pkg-config**: if you use bare Makefiles instead of CMake, [pkg-config](https://json.nlohmann.me/integration/pkg-config/index.md) can supply the include flags for an already-installed library.
Choosing an integration method: answer the questions in the hexagons from top to bottom to reach a method. All CMake methods end at the same target, `nlohmann_json::nlohmann_json`; the list below links to each method.
- **Single header**: copy [`json.hpp`](#header-only) into your project; no build-system integration required.
- **CMake**, see [CMake](https://json.nlohmann.me/integration/cmake/index.md):
- [`find_package()`](https://json.nlohmann.me/integration/cmake/#external) if the library is already installed;
- [`FetchContent`](https://json.nlohmann.me/integration/cmake/#fetchcontent) to download it at configure time (CMake 3.14 or later);
- [`add_subdirectory()`](https://json.nlohmann.me/integration/cmake/#embedded) to embed a vendored copy of the source tree;
- or [support both](https://json.nlohmann.me/integration/cmake/#supporting-both) with an option that selects installed or vendored.
- **Package managers**: install the library with Homebrew, Conan, vcpkg, or one of the many others; see [Package Managers](https://json.nlohmann.me/integration/package_managers/index.md) for the full list.
- **pkg-config**: if you use bare Makefiles instead of CMake, [pkg-config](https://json.nlohmann.me/integration/pkg-config/index.md) supplies the include flags for an already-installed library.
Once the library is integrated, see the [Migration Guide](https://json.nlohmann.me/integration/migration_guide/index.md) for how to keep your code future-proof across releases.
@@ -56,8 +65,13 @@ For the read-only, non-owning [`basic_json_document`](https://json.nlohmann.me/a
## See also
- [CMake](https://json.nlohmann.me/integration/cmake/index.md) - integrate the library into a CMake project
- [Package managers](https://json.nlohmann.me/integration/package_managers/index.md)
- [pkg-config](https://json.nlohmann.me/integration/pkg-config/index.md)
- [Package managers](https://json.nlohmann.me/integration/package_managers/index.md) - install the library with a package manager
- [pkg-config](https://json.nlohmann.me/integration/pkg-config/index.md) - generate include flags for plain Makefiles
- [Compile times](https://json.nlohmann.me/integration/compile_times/index.md) - reduce the compile time overhead
- [Migration guide](https://json.nlohmann.me/integration/migration_guide/index.md) - upgrade from an earlier version
- [Releases](https://json.nlohmann.me/home/releases/index.md)
- [Releases](https://json.nlohmann.me/home/releases/index.md) - release notes of all versions
- [`basic_json`](https://json.nlohmann.me/api/basic_json/index.md) - the main class and all its member functions
- [Macros](https://json.nlohmann.me/api/macros/index.md) - reference of all macros
- [Supported Macros](https://json.nlohmann.me/features/macros/index.md) - configure the library with macros
- [Modules](https://json.nlohmann.me/features/modules/index.md) - C++20 module support
- [`NLOHMANN_JSON_VERSION_MAJOR`](https://json.nlohmann.me/api/macros/nlohmann_json_version_major/index.md) - library version macros
+9
View File
@@ -283,3 +283,12 @@ exact version and configuration is relevant, use macro
The `nlohmann::detail` namespace is not part of the public API of the library and can change in any version without
an announcement. Do not rely on any function or type in the `detail` namespace.
## See also
- [`JSON_DELETE_DEPRECATED_FUNCTIONS`](../api/macros/json_delete_deprecated_functions.md) - remove deprecated functions to check the migration
- [`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md) - control implicit conversions
- [`NLOHMANN_JSON_NAMESPACE`](../api/macros/nlohmann_json_namespace.md) - refer to the library namespace without hard-coding it
- [`nlohmann` Namespace](../features/namespace.md) - how the library namespace is structured
- [Converting values](../features/conversions.md) - explicit conversions with get
- [`basic_json`](../api/basic_json/index.md) - the main class and all its member functions
+2 -2
View File
@@ -1,4 +1,4 @@
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/migration_guide/" rel="canonical"><link href=../ rel=prev><link href=../cmake/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Migration Guide - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../css/custom.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#migration-guide class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Migration Guide </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-sLine truncated
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/migration_guide/" rel="canonical"><link href=../ rel=prev><link href=../cmake/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Migration Guide - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../css/custom.css><link rel=stylesheet href=../../css/brand.css><link rel=stylesheet href=../../css/fig-sax.css><link rel=stylesheet href=../../css/fig-jsonview.css><link rel=stylesheet href=../../css/fig-exceptions.css><link rel=stylesheet href=../../css/fig-pointer.css><link rel=stylesheet href=../../css/fig-charts.css><link rel=stylesheet href=../../css/fig-integration.css><link rel=stylesheet href=../../css/fig-macros.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#migration-guide class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Migration Guide </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5Line truncated
<span class=n>std</span><span class=o>::</span><span class=n>stringstream</span><span class=w> </span><span class=n>ss</span><span class=p>(</span><span class=s>"[1,2,3]"</span><span class=p>);</span>
<span class=n>j</span><span class=w> </span><span class=o>&lt;&lt;</span><span class=w> </span><span class=n>ss</span><span class=p>;</span>
</code></pre></div> </div> <div class=tabbed-block> <div class=highlight><pre><span></span><code><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=p>;</span>
@@ -54,4 +54,4 @@
<span class=p>{</span>
<span class=w> </span><span class=n>j</span><span class=p>[</span><span class=s>"age"</span><span class=p>]</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>age</span><span class=p>;</span>
<span class=p>}</span>
</code></pre></div> </div> </div> </div> <h2 id=do-not-use-the-detail-namespace>Do not use the <code>detail</code> namespace<a class=headerlink href=#do-not-use-the-detail-namespace title="Permanent link">&para;</a></h2> <p>The <code>nlohmann::detail</code> namespace is not part of the public <abbr title="Application Programming Interface">API</abbr> of the library and can change in any version without an announcement. Do not rely on any function or type in the <code>detail</code> namespace.</p> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 8, 2026 14:11:16 UTC">October 8, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - hLine truncated
</code></pre></div> </div> </div> </div> <h2 id=do-not-use-the-detail-namespace>Do not use the <code>detail</code> namespace<a class=headerlink href=#do-not-use-the-detail-namespace title="Permanent link">&para;</a></h2> <p>The <code>nlohmann::detail</code> namespace is not part of the public <abbr title="Application Programming Interface">API</abbr> of the library and can change in any version without an announcement. Do not rely on any function or type in the <code>detail</code> namespace.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/macros/json_delete_deprecated_functions/ ><code>JSON_DELETE_DEPRECATED_FUNCTIONS</code></a> - remove deprecated functions to check the migration</li> <li><a href=../../api/macros/json_use_implicit_conversions/ ><code>JSON_USE_IMPLICIT_CONVERSIONS</code></a> - control implicit conversions</li> <li><a href=../../api/macros/nlohmann_json_namespace/ ><code>NLOHMANN_JSON_NAMESPACE</code></a> - refer to the library namespace without hard-coding it</li> <li><a href=../../features/namespace/ ><code>nlohmann</code> Namespace</a> - how the library namespace is structured</li> <li><a href=../../features/conversions/ >Converting values</a> - explicit conversions with get</li> <li><a href=../../api/basic_json/ ><code>basic_json</code></a> - the main class and all its member functions</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../ class="md-footer__link md-footer__link--prev" aria-label="Previous: Integration"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Integration </div> </div> </a> <a href=../cmake/ class="md-footer__link md-footer__link--next" aria-label="Next: CMake"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> CMake </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 Line truncated
+9
View File
@@ -185,3 +185,12 @@ void to_json(NLOHMANN_JSON_NAMESPACE::json& j, const person& p)
## Do not use the `detail` namespace
The `nlohmann::detail` namespace is not part of the public API of the library and can change in any version without an announcement. Do not rely on any function or type in the `detail` namespace.
## See also
- [`JSON_DELETE_DEPRECATED_FUNCTIONS`](https://json.nlohmann.me/api/macros/json_delete_deprecated_functions/index.md) - remove deprecated functions to check the migration
- [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/index.md) - control implicit conversions
- [`NLOHMANN_JSON_NAMESPACE`](https://json.nlohmann.me/api/macros/nlohmann_json_namespace/index.md) - refer to the library namespace without hard-coding it
- [`nlohmann` Namespace](https://json.nlohmann.me/features/namespace/index.md) - how the library namespace is structured
- [Converting values](https://json.nlohmann.me/features/conversions/index.md) - explicit conversions with get
- [`basic_json`](https://json.nlohmann.me/api/basic_json/index.md) - the main class and all its member functions
+7
View File
@@ -1316,3 +1316,10 @@ There is no official package published to the [ESP-IDF Component Registry](https
new release and can be used as an unofficial component/package for ESP-IDF and PlatformIO projects. As the library
is header-only, it can otherwise be used directly by adding its `include/` directory to your component's/project's
include paths, like any other integration method described on this page.
## See also
- [CMake](cmake.md) - use the library from CMake
- [Pkg-config](pkg-config.md) - use the library with pkg-config
- [`meta`](../api/basic_json/meta.md) - query the library version at run time
- [`NLOHMANN_JSON_VERSION_MAJOR`](../api/macros/nlohmann_json_version_major.md) - library version macros
+2 -2
View File
@@ -1,4 +1,4 @@
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/package_managers/" rel="canonical"><link href=../cmake/ rel=prev><link href=../pkg-config/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Package Managers - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../css/custom.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#package-managers class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Package Managers </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> Line truncated
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/package_managers/" rel="canonical"><link href=../cmake/ rel=prev><link href=../pkg-config/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Package Managers - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../css/custom.css><link rel=stylesheet href=../../css/brand.css><link rel=stylesheet href=../../css/fig-sax.css><link rel=stylesheet href=../../css/fig-jsonview.css><link rel=stylesheet href=../../css/fig-exceptions.css><link rel=stylesheet href=../../css/fig-pointer.css><link rel=stylesheet href=../../css/fig-charts.css><link rel=stylesheet href=../../css/fig-integration.css><link rel=stylesheet href=../../css/fig-macros.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#package-managers class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Package Managers </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.Line truncated
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iomanip&gt;</span>
@@ -452,4 +452,4 @@ cmake<span class=w> </span>--build<span class=w> </span>build
<span class=w> </span><span class=nf>set_languages</span><span class=p>(</span><span class=s2>"cxx11"</span><span class=p>)</span>
</code></pre></div> </li> <li> <p>Build</p> <div class=highlight><pre><span></span><code>xmake
</code></pre></div> </li> <li> <p>Run</p> <div class=highlight><pre><span></span><code>xmake<span class=w> </span>run
</code></pre></div> </li> </ol> </details> <hr> <h2 id=other-package-managers>Other package managers<a class=headerlink href=#other-package-managers title="Permanent link">&para;</a></h2> <p>The library is also contained in many other package repositories; <a href="https://repology.org/project/nlohmann-json/versions">Repology</a> tracks the packaged versions across repositories.</p> <hr> <h2 id=buckaroo>Buckaroo<a class=headerlink href=#buckaroo title="Permanent link">&para;</a></h2> <p>If you are using <a href="https://github.com/LoopPerfect/buckaroo">Buckaroo</a>, you can install this library's module with <code>buckaroo add github.com/buckaroo-pm/nlohmann-json</code>. There is a demo repo <a href="https://github.com/njlr/buckaroo-nholmann-json-example">here</a>.</p> <div class="admonition warning"> <p class=admonition-title>Warning</p> <p>The module is outdated as the respective <a href="https://github.com/buckaroo-pm/nlohmann-json">repository</a> has not been updated in years.</p> </div> <h2 id=cocoapods>CocoaPods<a class=headerlink href=#cocoapods title="Permanent link">&para;</a></h2> <p>If you are using <a href="https://cocoapods.org">CocoaPods</a>, you can use the library by adding pod <code>"nlohmann_json", '~&gt;3.1.2'</code> to your podfile (see <a href="https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/">an example</a>). Please file issues at <a href="https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/">the repository</a>, as its issue tracker is no longer reachable.</p> <p><a href="https://cocoapods.org/pods/nlohmann_json"><img alt="CocoaPods package" src="https://img.shields.io/cocoapods/v/nlohmann_json"></a></p> <div class="admonition warning"> <p class=admonition-title>Warning</p> <p>The module is outdated as the respective <a href="https://cocoapods.org/pods/nlohmann_json">pod</a> has not been updated in years.</p> </div> <h2 id=npm>npm<a class=headerlink href=#npm title="Permanent link">&para;</a></h2> <p>This project does not publish an official <a href="https://www.npmjs.com">npm</a> package. The npm package <a href="https://www.npmjs.com/package/nlohmann-json"><code>nlohmann-json</code></a> (or similarly named packages) is not maintained or endorsed by this project. Use one of the package managers listed above, or integrate the single header directly.</p> <h2 id=esp-idf-and-platformio>ESP-IDF and PlatformIO<a class=headerlink href=#esp-idf-and-platformio title="Permanent link">&para;</a></h2> <p>There is no official package published to the <a href="https://components.espressif.com">ESP-IDF Component Registry</a> or the <a href="https://registry.platformio.org">PlatformIO Registry</a>. A community-maintained fork, <a href="https://github.com/Johboh/nlohmann-json">Johboh/nlohmann-json</a>, publishes this library to both registries on each new release and can be used as an unofficial component/package for ESP-IDF and PlatformIO projects. As the library is header-only, it can otherwise be used directly by adding its <code>include/</code> directory to your component's/project's include paths, like any other integration method described on this page.</p> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 7, 2026 20:20:05 UTC">October 7, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener"Line truncated
</code></pre></div> </li> </ol> </details> <hr> <h2 id=other-package-managers>Other package managers<a class=headerlink href=#other-package-managers title="Permanent link">&para;</a></h2> <p>The library is also contained in many other package repositories; <a href="https://repology.org/project/nlohmann-json/versions">Repology</a> tracks the packaged versions across repositories.</p> <hr> <h2 id=buckaroo>Buckaroo<a class=headerlink href=#buckaroo title="Permanent link">&para;</a></h2> <p>If you are using <a href="https://github.com/LoopPerfect/buckaroo">Buckaroo</a>, you can install this library's module with <code>buckaroo add github.com/buckaroo-pm/nlohmann-json</code>. There is a demo repo <a href="https://github.com/njlr/buckaroo-nholmann-json-example">here</a>.</p> <div class="admonition warning"> <p class=admonition-title>Warning</p> <p>The module is outdated as the respective <a href="https://github.com/buckaroo-pm/nlohmann-json">repository</a> has not been updated in years.</p> </div> <h2 id=cocoapods>CocoaPods<a class=headerlink href=#cocoapods title="Permanent link">&para;</a></h2> <p>If you are using <a href="https://cocoapods.org">CocoaPods</a>, you can use the library by adding pod <code>"nlohmann_json", '~&gt;3.1.2'</code> to your podfile (see <a href="https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/">an example</a>). Please file issues at <a href="https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/">the repository</a>, as its issue tracker is no longer reachable.</p> <p><a href="https://cocoapods.org/pods/nlohmann_json"><img alt="CocoaPods package" src="https://img.shields.io/cocoapods/v/nlohmann_json"></a></p> <div class="admonition warning"> <p class=admonition-title>Warning</p> <p>The module is outdated as the respective <a href="https://cocoapods.org/pods/nlohmann_json">pod</a> has not been updated in years.</p> </div> <h2 id=npm>npm<a class=headerlink href=#npm title="Permanent link">&para;</a></h2> <p>This project does not publish an official <a href="https://www.npmjs.com">npm</a> package. The npm package <a href="https://www.npmjs.com/package/nlohmann-json"><code>nlohmann-json</code></a> (or similarly named packages) is not maintained or endorsed by this project. Use one of the package managers listed above, or integrate the single header directly.</p> <h2 id=esp-idf-and-platformio>ESP-IDF and PlatformIO<a class=headerlink href=#esp-idf-and-platformio title="Permanent link">&para;</a></h2> <p>There is no official package published to the <a href="https://components.espressif.com">ESP-IDF Component Registry</a> or the <a href="https://registry.platformio.org">PlatformIO Registry</a>. A community-maintained fork, <a href="https://github.com/Johboh/nlohmann-json">Johboh/nlohmann-json</a>, publishes this library to both registries on each new release and can be used as an unofficial component/package for ESP-IDF and PlatformIO projects. As the library is header-only, it can otherwise be used directly by adding its <code>include/</code> directory to your component's/project's include paths, like any other integration method described on this page.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../cmake/ >CMake</a> - use the library from CMake</li> <li><a href=../pkg-config/ >Pkg-config</a> - use the library with pkg-config</li> <li><a href=../../api/basic_json/meta/ ><code>meta</code></a> - query the library version at run time</li> <li><a href=../../api/macros/nlohmann_json_version_major/ ><code>NLOHMANN_JSON_VERSION_MAJOR</code></a> - library version macros</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-componeLine truncated
+7
View File
@@ -1259,3 +1259,10 @@ This project does not publish an official [npm](https://www.npmjs.com) package.
## ESP-IDF and PlatformIO
There is no official package published to the [ESP-IDF Component Registry](https://components.espressif.com) or the [PlatformIO Registry](https://registry.platformio.org). A community-maintained fork, [Johboh/nlohmann-json](https://github.com/Johboh/nlohmann-json), publishes this library to both registries on each new release and can be used as an unofficial component/package for ESP-IDF and PlatformIO projects. As the library is header-only, it can otherwise be used directly by adding its `include/` directory to your component's/project's include paths, like any other integration method described on this page.
## See also
- [CMake](https://json.nlohmann.me/integration/cmake/index.md) - use the library from CMake
- [Pkg-config](https://json.nlohmann.me/integration/pkg-config/index.md) - use the library with pkg-config
- [`meta`](https://json.nlohmann.me/api/basic_json/meta/index.md) - query the library version at run time
- [`NLOHMANN_JSON_VERSION_MAJOR`](https://json.nlohmann.me/api/macros/nlohmann_json_version_major/index.md) - library version macros
+6
View File
@@ -14,3 +14,9 @@ Users of the [Meson build system](package_managers.md#meson) will also be able t
```meson
json = dependency('nlohmann_json', required: true)
```
## See also
- [Integration](index.md) - all ways to integrate the library
- [CMake](cmake.md) - use the library from CMake
- [Package Managers](package_managers.md) - install the library via package managers
+2 -2
View File
@@ -1,3 +1,3 @@
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/pkg-config/" rel="canonical"><link href=../package_managers/ rel=prev><link href=../compile_times/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Pkg-config - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../css/custom.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#pkg-config class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Pkg-config </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div classLine truncated
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/integration/pkg-config/" rel="canonical"><link href=../package_managers/ rel=prev><link href=../compile_times/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Pkg-config - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../css/custom.css><link rel=stylesheet href=../../css/brand.css><link rel=stylesheet href=../../css/fig-sax.css><link rel=stylesheet href=../../css/fig-jsonview.css><link rel=stylesheet href=../../css/fig-exceptions.css><link rel=stylesheet href=../../css/fig-pointer.css><link rel=stylesheet href=../../css/fig-charts.css><link rel=stylesheet href=../../css/fig-integration.css><link rel=stylesheet href=../../css/fig-macros.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#pkg-config class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Pkg-config </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27hLine truncated
</code></pre></div> <p>A pkg-config file is installed by <a href=../cmake/#json_install>CMake</a> (when the <code>JSON_Install</code> option is enabled, which is the default for a top-level build) as well as by several <a href=../package_managers/ >package managers</a>.</p> <p>Users of the <a href=../package_managers/#meson>Meson build system</a> will also be able to use a system-wide library, which will be found by <code>pkg-config</code>:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>dependency</span><span class=p>(</span><span class=s>'nlohmann_json'</span><span class=p>,</span><span class=w> </span><span class=n>required</span><span class=p>:</span><span class=w> </span><span class=kc>true</span><span class=p>)</span>
</code></pre></div> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M162.7 210c-1.8 3.3-25.2 44.4-70.1 123.5-4.9 8.3-10.8 12.5-17.7 12.5H9.8c-7.7 0-12.1-7.5-8.5-14.4l69-121.3q.3 0 0-.3l-43.9-75.6c-4.3-7.8.3-14.1 8.5-14.1H100c7.3 0 13.3 4.1 18 12.2zM382.6 46.1l-144 253v.3L330.2 466c3.9 7.1.2 14.1-8.5 14.1h-65.2c-7.6 0-13.6-4-18-12.2l-92.4-168.5c3.3-5.8 51.5-90.8 144.8-255.2 4.6Line truncated
</code></pre></div> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../ >Integration</a> - all ways to integrate the library</li> <li><a href=../cmake/ >CMake</a> - use the library from CMake</li> <li><a href=../package_managers/ >Package Managers</a> - install the library via package managers</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../package_managers/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Package Managers"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Package Managers </div> </div> </a> <a href=../compile_times/ class="md-footer__link md-footer__link--next" aria-label="Next: Compile times"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Compile times </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7Line truncated
+6
View File
@@ -13,3 +13,9 @@ Users of the [Meson build system](https://json.nlohmann.me/integration/package_m
```
json = dependency('nlohmann_json', required: true)
```
## See also
- [Integration](https://json.nlohmann.me/integration/index.md) - all ways to integrate the library
- [CMake](https://json.nlohmann.me/integration/cmake/index.md) - use the library from CMake
- [Package Managers](https://json.nlohmann.me/integration/package_managers/index.md) - install the library via package managers