diff --git a/docs/mkdocs/docs/integration/macports/CMakeLists.txt b/docs/mkdocs/docs/integration/macports/CMakeLists.txt new file mode 100644 index 000000000..12f4ae1f2 --- /dev/null +++ b/docs/mkdocs/docs/integration/macports/CMakeLists.txt @@ -0,0 +1,7 @@ +cmake_minimum_required(VERSION 3.15) +project(json_example) + +find_package(nlohmann_json CONFIG REQUIRED) + +add_executable(json_example example.cpp) +target_link_libraries(json_example PRIVATE nlohmann_json::nlohmann_json) diff --git a/docs/mkdocs/docs/integration/macports/example.cpp b/docs/mkdocs/docs/integration/macports/example.cpp new file mode 100644 index 000000000..1a7ac4de2 --- /dev/null +++ b/docs/mkdocs/docs/integration/macports/example.cpp @@ -0,0 +1,10 @@ +#include +#include +#include + +using json = nlohmann::json; + +int main() +{ + std::cout << std::setw(4) << json::meta() << std::endl; +} diff --git a/docs/mkdocs/docs/integration/nuget/nuget-package-content.png b/docs/mkdocs/docs/integration/nuget/nuget-package-content.png new file mode 100644 index 000000000..cc975b98b Binary files /dev/null and b/docs/mkdocs/docs/integration/nuget/nuget-package-content.png differ diff --git a/docs/mkdocs/docs/integration/nuget/nuget-project-changes.png b/docs/mkdocs/docs/integration/nuget/nuget-project-changes.png new file mode 100644 index 000000000..eb2a520a8 Binary files /dev/null and b/docs/mkdocs/docs/integration/nuget/nuget-project-changes.png differ diff --git a/docs/mkdocs/docs/integration/nuget/nuget-project-makefile.png b/docs/mkdocs/docs/integration/nuget/nuget-project-makefile.png new file mode 100644 index 000000000..74657f264 Binary files /dev/null and b/docs/mkdocs/docs/integration/nuget/nuget-project-makefile.png differ diff --git a/docs/mkdocs/docs/integration/nuget/nuget-search-package.png b/docs/mkdocs/docs/integration/nuget/nuget-search-package.png new file mode 100644 index 000000000..da4c6e6dc Binary files /dev/null and b/docs/mkdocs/docs/integration/nuget/nuget-search-package.png differ diff --git a/docs/mkdocs/docs/integration/nuget/nuget-select-package.png b/docs/mkdocs/docs/integration/nuget/nuget-select-package.png new file mode 100644 index 000000000..b80ebc7bb Binary files /dev/null and b/docs/mkdocs/docs/integration/nuget/nuget-select-package.png differ diff --git a/docs/mkdocs/docs/integration/package_managers.md b/docs/mkdocs/docs/integration/package_managers.md index d0dcf3191..4f0b5c1ed 100644 --- a/docs/mkdocs/docs/integration/package_managers.md +++ b/docs/mkdocs/docs/integration/package_managers.md @@ -224,7 +224,7 @@ requires, where `x.y.z` is the release version you want to use. - :octicons-tag-24: Availalbe versions: current version and older versions (see [Spack package](https://packages.spack.io/package.html?name=nlohmann-json)) - - :octicons-rocket-24: The formula is updated with every release. + - :octicons-rocket-24: The package is updated with every release. - :octicons-person-24: Maintainer: [Axel Huebl](https://github.com/ax3l) - :octicons-file-24: File issues at the [Spack issue tracker](https://github.com/spack/spack/issues) - :octicons-question-24: [Spack website](https://spack.io) @@ -277,7 +277,7 @@ Please see the [Spack project](https://github.com/spack/spack) for any issues re - :octicons-tag-24: Availalbe versions: current version and older versions (see [Hunter package](https://hunter.readthedocs.io/en/latest/packages/pkg/nlohmann_json.html)) - - :octicons-rocket-24: The formula is updated with every release. + - :octicons-rocket-24: The package is updated with every release. - :octicons-file-24: File issues at the [Hunter issue tracker](https://github.com/cpp-pm/hunter/issues) - :octicons-question-24: [Hunter website](https://hunter.readthedocs.io/en/latest/) @@ -332,7 +332,7 @@ If you are using [Buckaroo](https://buckaroo.pm), you can install this library's package: [**`nlohmann-json`**](https://github.com/Microsoft/vcpkg/tree/master/ports/nlohmann-json) - :octicons-tag-24: Availalbe versions: current version - - :octicons-rocket-24: The formula is updated with every release. + - :octicons-rocket-24: The package is updated with every release. - :octicons-file-24: File issues at the [vcpkg issue tracker](https://github.com/microsoft/vcpkg/issues) - :octicons-question-24: [vcpkg website](https://vcpkg.io/) @@ -377,7 +377,7 @@ and follow the then displayed descriptions. Please see the vcpkg project for any package: [**`nlohmann/json`**](https://github.com/pfultz2/cget-recipes/blob/master/recipes/nlohmann/json/package.txt) - :octicons-tag-24: Availalbe versions: current version and older versions - - :octicons-rocket-24: The formula is updated with every release. + - :octicons-rocket-24: The package is updated with every release. - :octicons-file-24: File issues at the [cget issue tracker](https://github.com/pfultz2/cget-recipes/issues) - :octicons-question-24: [cget website](https://cget.readthedocs.io/) @@ -427,7 +427,136 @@ If you are using [CocoaPods](https://cocoapods.org), you can use the library by ## NuGet -If you are using [NuGet](https://www.nuget.org), you can use the package [nlohmann.json](https://www.nuget.org/packages/nlohmann.json/). Please check [this extensive description](https://github.com/nlohmann/json/issues/1132#issuecomment-452250255) on how to use the package. Please file issues [here](https://github.com/hnkb/nlohmann-json-nuget/issues). +!!! abstract "Summary" + + package: [**`nlohmann.json`**](https://www.nuget.org/packages/nlohmann.json/) + + - :octicons-tag-24: Availalbe versions: current and previous versions + - :octicons-rocket-24: The package is updated with every release. + - :octicons-person-24: Maintainer: [Hani Kaabi](https://github.com/hnkb) + - :octicons-file-24: File issues at the [maintainer's issue tracker](https://github.com/hnkb/nlohmann-json-nuget/issues) + - :octicons-question-24: [NuGet website](https://www.nuget.org) + +If you are using [NuGet](https://www.nuget.org), you can use the package [nlohmann.json](https://www.nuget.org/packages/nlohmann.json/) +with + +```shell +dotnet add package nlohmann.json +``` + +??? example + + Probably the easiest way to use NuGet packages is through Visual Studio graphical interface. Just right-click on a + project (any C++ project would do) in “Solution Explorer” and select “Manage NuGet Packages…” + + ![](nuget/nuget-search-package.png) + + Now you can click on “Browse” tab and find the package you like to install. + + ![](nuget/nuget-select-package.png) + + Most of the packages in NuGet gallery are .NET packages and would not be useful in a C++ project. Microsoft + recommends adding “native” and “nativepackage” tags to C++ NuGet packages to distinguish them, but even adding + “native” to search query would still show many .NET-only packages in the list. + + Nevertheless, after finding the package you want, just click on “Install” button and accept confirmation dialogs. + After the package is successfully added to the projects, you should be able to just build and execute the project + without the need for making any more changes to build settings. + + !!! note + + A few notes: + + - NuGet packages are installed per project and not system-wide. The header and binaries for the package are only + available to the project it is added to, and not other projects (obviously unless we add the package to those + projects as well) + - One of the many great things about your elegant work is that it is a header-only library, which makes + deployment very straightforward. In case of libraries which need binary deployment (`.lib`, `.dll` and `.pdb` + for debug info) the different binaries for each supported compiler version must be added to the NuGet package. + Some library creators cram binary versions for all supported Visual C++ compiler versions in the same package, + so a single package will support all compilers. Some others create a different package for each compiler + version (and you usually see things like “v140” or “vc141” in package name to clarify which VC++ compiler this + package supports). + - Packages can have dependency to other packages, and in this case, NuGet will install all dependencies as well + as the requested package recursively. + + **What happens behind the scenes** + + After you add a NuGet package, three changes occur in the project source directory. Of course, we could make these + changes manually instead of using GUI: + + ![](nuget/nuget-project-changes.png) + + 1. A `packages.config` file will be created (or updated to include the package name if one such file already + exists). This file contains a list of the packages required by this project (name and minimum version) and must + be added to the project source code repository, so if you move the source code to a new machine, MSBuild/NuGet + knows which packages it has to restore (which it does automatically before each build). + + ```xml + + + + + ``` + + 2. A `packages` folder which contains actual files in the packages (these are header and binary files required for + a successful build, plus a few metadata files). In case of this library for example, it contains `json.hpp`: + + ![](nuget/nuget-package-content.png) + + !!! note + + This directory should not be added to the project source code repository, as it will be restored before each + build by MSBuild/NuGet. If you go ahead and delete this folder, then build the project again, it will + magically re-appear! + + 3. Project MSBuild makefile (which for Visual C++ projects has a .vcxproj extension) will be updated to include + settings from the package. + + ![](nuget/nuget-project-makefile.png) + + The important bit for us here is line 170, which tells MSBuild to import settings from + `packages\nlohmann.json.3.5.0\build\native\nlohmann.json.targets` file. This is a file the package creator + created and added to the package (you can see it is one of the two files I created in this repository, the other + just contains package attributes like name and version number). What does it contain? + + For our header-only repository, the only setting we need is to add our include directory to the list of + `AdditionalIncludeDirectories`: + + ```xml + + + + + $(MSBuildThisFileDirectory)include;%(AdditionalIncludeDirectories) + + + + ``` + + For libraries with binary files, we will need to add `.lib` files to linker inputs and add settings to copy + `.dll` and other redistributable files to output directory, if needed. + + There are other changes to the makefile as well: + + - Lines 165-167 add the `packages.config` as one of project files (so it is shown in Solution Explorer tree + view). It is added as None (no build action) and removing it wouldn’t affect build. + + - Lines 172-177 check to ensure the required packages are present. This will display a build error if package + directory is empty (for example when NuGet cannot restore packages because Internet connection is down). + Again, if you omit this section, the only change in build would be a more cryptic error message if build + fails. + + !!! note + + Changes to .vcxproj makefile should also be added to project source code repository. + + As you can see, the mechanism NuGet uses to modify project settings is through MSBuild makefiles, so using NuGet + with other build systems and compilers (like CMake) as a dependency manager is either impossible or more problematic + than useful. + +Please refer to [this extensive description](https://github.com/nlohmann/json/issues/1132#issuecomment-452250255) for +more information. ## Conda @@ -441,9 +570,67 @@ If you are using [MSYS2](http://www.msys2.org/), you can use the [mingw-w64-nloh ## MacPorts -If you are using [MacPorts](https://ports.macports.org), execute `sudo port install nlohmann-json` to install the [nlohmann-json](https://ports.macports.org/port/nlohmann-json/) package. +!!! abstract "Summary" -:material-update: The [package](https://ports.macports.org/port/nlohmann-json/) is updated automatically. + port: [**`nlohmann-json`**](https://ports.macports.org/port/nlohmann-json/) + + - :octicons-tag-24: Availalbe versions: current version + - :octicons-rocket-24: The port is updated with every release. + - :octicons-file-24: File issues at the [MacPorts issue tracker](https://trac.macports.org/newticket?port=nlohmann-json) + - :octicons-question-24: [MacPorts website](https://www.macports.org) + +If you are using [MacPorts](https://ports.macports.org), execute + +```shell +sudo port install nlohmann-json +``` + +to install the [nlohmann-json](https://ports.macports.org/port/nlohmann-json/) package. + +??? example "Example: Raw compilation" + + 1. Create the following file: + + ```cpp title="example.cpp" + --8<-- "integration/macports/example.cpp" + ``` + + 2. Install the package: + + ```sh + sudo port install nlohmann-json + ``` + + 3. Compile the code and pass the Homebrew prefix to the include path such that the library can be found: + + ```sh + c++ example.cpp -I/opt/local/include -std=c++11 -o example + ``` + +??? example "Example: CMake" + + 1. Create the following files: + + ```cpp title="example.cpp" + --8<-- "integration/homebrew/example.cpp" + ``` + + ```cmake title="CMakeLists.txt" + --8<-- "integration/homebrew/CMakeLists.txt" + ``` + + 2. Install the package: + + ```sh + sudo port install nlohmann-json + ``` + + 3. Compile the code: + + ```sh + cmake -S . -B build + cmake --build build + ``` ## build2 @@ -460,7 +647,17 @@ If you are using [`wsjcpp`](http://wsjcpp.org), you can use the command `wsjcpp ## CPM.cmake -If you are using [`CPM.cmake`](https://github.com/TheLartians/CPM.cmake), you can check this [`example`](https://github.com/TheLartians/CPM.cmake/tree/master/examples/json). After [adding CPM script](https://github.com/TheLartians/CPM.cmake#adding-cpm) to your project, implement the following snippet to your CMake: +!!! abstract "Summary" + + package: **`gh:nlohmann/json`** + + - :octicons-tag-24: Availalbe versions: current and previous versions + - :octicons-rocket-24: The package is updated with every release. + - :octicons-file-24: File issues at the [CPM.cmake issue tracker](https://github.com/cpm-cmake/CPM.cmake/issues) + - :octicons-question-24: [CPM.cmake website](https://github.com/cpm-cmake/CPM.cmake) + +If you are using [`CPM.cmake`](https://github.com/TheLartians/CPM.cmake), add the +[CPM.cmake script](https://github.com/TheLartians/CPM.cmake#adding-cpm) and the following snippet to your CMake project: ```cmake CPMAddPackage("gh:nlohmann/json@3.11.3") @@ -468,16 +665,22 @@ CPMAddPackage("gh:nlohmann/json@3.11.3") ??? example - 1. Download CPM.cmake + 1. Create the following file: - ```shell - mkdir -p cmake - wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake - ``` + ```cpp title="example.cpp" + --8<-- "integration/homebrew/example.cpp" + ``` - 2. Build + 2. Download CPM.cmake - ```shell - cmake -S . -B build - cmake --build build - ``` + ```shell + mkdir -p cmake + wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake + ``` + + 3. Build + + ```shell + cmake -S . -B build + cmake --build build + ```