mirror of
https://github.com/nlohmann/json.git
synced 2026-10-30 09:25:42 +00:00
docs: new design for the documentation site (#5934)
* docs: new design for the documentation site Apply the brand to the Material for MkDocs site: Inter and JetBrains Mono served by the site (upright and real italic), brand colours, blue header band with the syntax pattern, wordmark in the header, new home page (hero, cards, animated feature tour), 404 page, polish for tabs, search, footer, focus rings, tables and code blocks, and theme features (code copy, previous/next footer, TOC follow, search suggestions). Draw the number railroad diagram, the parser callback events and the iterator illustrations as inline SVGs that follow the light and dark scheme. The generator scripts are in docs/mkdocs/scripts/figures; the feature slideshow (json-light.svg, json-dark.svg, replacing json.gif on the home page) is built by docs/mkdocs/scripts/slideshow. Decision nodes in five flowcharts become hexagons, which need far less room. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: add figures, table captions and a macro chooser - Figures with numbered captions: SAX stepper, json_view layout and edit stepper, exception map, JSON pointer and patch walkers, QA pipeline, scaling and binary size charts, roadmap lanes, release timeline, integration decision tree and namespace builder - Table captions (nj-table-caption) on 9 pages - Compile times: modules and PCH charts, filesystem section, re-measured Figure 1, links between features/modules.md and compile_times.md - Interactive macro chooser for features/arbitrary_types.md - Link check: exclude URLs that answer the plugin with 400/401/419 or are dead (customers.md) Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: macro chooser generates adl_serializer for non-default-constructible types Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: cross-link concept pages and API pages in See also sections Add See also links in both directions between the concept pages (features, home, integration) and the API pages, write API links in code font, give every entry a comment after a dash, and show the callback event figure on the parser callbacks page. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: address review comments on the new design - Home: add a "Latest release" button - Sponsors: update the list and group it by tier - Features: list all feature pages on the index page - Releases: add highlights per release, link the 4.0 roadmap, add the first commit to the timeline - Exceptions: prefix all example messages with the exception name - API: no code font for format names in the See also links of the to_/from_ pages - Merge Patch: show the document before, the patch, and the result - Replace "--" with typographic dashes, mark external links with an icon, center Mermaid diagrams Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann authored and 
GitHub committed
1 parent
2bb2feeef4
commit
a47170346a
417 files changed
+11100
-3041
No files matched your search
@@ -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
|
||||
@@ -6,9 +6,68 @@ 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>
|
||||
--8<-- "images/compile_times.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 +96,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 +128,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 +160,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 +176,97 @@ 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>
|
||||
--8<-- "images/compile_times_modules.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 +279,75 @@ 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>
|
||||
--8<-- "images/compile_times_pch.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
|
||||
@@ -5,24 +5,31 @@ pick one:
|
||||
|
||||
```mermaid
|
||||
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()`](cmake.md#external) if the library is already installed,
|
||||
[`add_subdirectory()`](cmake.md#embedded) to embed the source tree, or [`FetchContent`](cmake.md#fetchcontent) to
|
||||
download it at configure time; see [CMake](cmake.md).
|
||||
- **Package managers**: install the library with a package manager such as Homebrew, Conan, or vcpkg; see
|
||||
[Package Managers](package_managers.md).
|
||||
- **pkg-config**: if you use bare Makefiles instead of CMake, [pkg-config](pkg-config.md) can supply the include flags
|
||||
<p class="nj-caption" markdown>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.</p>
|
||||
|
||||
- **Single header**: copy [`json.hpp`](#header-only) into your project; no build-system integration required.
|
||||
- **CMake**, see [CMake](cmake.md):
|
||||
- [`find_package()`](cmake.md#external) if the library is already installed;
|
||||
- [`FetchContent`](cmake.md#fetchcontent) to download it at configure time (CMake 3.14 or later);
|
||||
- [`add_subdirectory()`](cmake.md#embedded) to embed a vendored copy of the source tree;
|
||||
- or [support both](cmake.md#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](package_managers.md) for the full list.
|
||||
- **pkg-config**: if you use bare Makefiles instead of CMake, [pkg-config](pkg-config.md) supplies the include flags
|
||||
for an already-installed library.
|
||||
|
||||
Once the library is integrated, see the [Migration Guide](migration_guide.md) for how to keep your code future-proof
|
||||
@@ -91,8 +98,13 @@ Visual Studio Code, but not with debuggers that wrap LLDB, such as `codelldb`; s
|
||||
## See also
|
||||
|
||||
- [CMake](cmake.md) - integrate the library into a CMake project
|
||||
- [Package managers](package_managers.md)
|
||||
- [pkg-config](pkg-config.md)
|
||||
- [Package managers](package_managers.md) - install the library with a package manager
|
||||
- [pkg-config](pkg-config.md) - generate include flags for plain Makefiles
|
||||
- [Compile times](compile_times.md) - reduce the compile time overhead
|
||||
- [Migration guide](migration_guide.md) - upgrade from an earlier version
|
||||
- [Releases](../home/releases/index.md)
|
||||
- [Releases](../home/releases/index.md) - release notes of all versions
|
||||
- [`basic_json`](../api/basic_json/index.md) - the main class and all its member functions
|
||||
- [Macros](../api/macros/index.md) - reference of all macros
|
||||
- [Supported Macros](../features/macros.md) - configure the library with macros
|
||||
- [Modules](../features/modules.md) - C++20 module support
|
||||
- [`NLOHMANN_JSON_VERSION_MAJOR`](../api/macros/nlohmann_json_version_major.md) - library version macros
|
||||
@@ -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
|
||||
@@ -949,3 +949,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
|
||||
@@ -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
|
||||
Reference in new issue
Block a user