📝 add more package managers (#4533)

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)

docs/mkdocs/docs/integration/macports/example.cpp

@@ -0,0 +1,10 @@
+#include <nlohmann/json.hpp>
+#include <iostream>
+#include <iomanip>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::setw(4) << json::meta() << std::endl;
+}

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
+        <?xml version="1.0" encoding="utf-8"?>
+        <packages>
+          <package id="nlohmann.json" version="3.5.0" targetFramework="native" />
+        </packages>
+        ```
+
+    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    
+        <?xml version="1.0" encoding="utf-8"?>
+        <Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+            <ItemDefinitionGroup>
+                <ClCompile>
+                    <AdditionalIncludeDirectories>$(MSBuildThisFileDirectory)include;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+                </ClCompile>
+            </ItemDefinitionGroup>
+        </Project>
+        ```
+
+        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
+        ```