🔨 cleaned up Makefiles and docs #698

.github/PULL_REQUEST_TEMPLATE.md

@@ -9,9 +9,13 @@ There are currently two files which need to be edited:
 
    If you add or change a feature, please also add a unit test to this file. The unit tests can be compiled and executed with
 
-   ```sh
+    ```sh
-   make check
+    $ mkdir build
-   ```
+    $ cd build
+    $ cmake ..
+    $ make
+    $ ctest
+    ```
 
    The test cases are also executed with several different compilers on [Travis](https://travis-ci.org/nlohmann/json) once you open a pull request.
 

Makefile

@@ -1,15 +1,19 @@
 .PHONY: pretty clean ChangeLog.md
 
-# main target
 all:
-	$(MAKE) -C test
+	@echo "ChangeLog.md - generate ChangeLog file"
-
+	@echo "check - compile and execute test suite"
-# clean up
+	@echo "check-fast - compile and execute test suite (skip long-running tests)"
-clean:
+	@echo "clean - remove built files"
-	rm -fr json_unit json_benchmarks fuzz fuzz-testing *.dSYM test/*.dSYM
+	@echo "cppcheck - analyze code with cppcheck"
-	rm -fr benchmarks/files/numbers/*.json
+	@echo "doctest - compile example files and check their output"
-	$(MAKE) clean -Cdoc
+	@echo "fuzz_testing - prepare fuzz testing of the JSON parser"
-	$(MAKE) clean -Ctest
+	@echo "fuzz_testing_cbor - prepare fuzz testing of the CBOR parser"
+	@echo "fuzz_testing_msgpack - prepare fuzz testing of the MessagePack parser"
+	@echo "json_unit - create single-file test executable"
+	@echo "pedantic_clang - run Clang with maximal warning flags"
+	@echo "pedantic_gcc - run GCC with maximal warning flags"
+	@echo "pretty - beautify code with Artistic Style"
 
 
 ##########################################################################
@@ -27,6 +31,14 @@ check:
 check-fast:
 	$(MAKE) check -C test TEST_PATTERN=""
 
+# clean up
+clean:
+	rm -fr json_unit json_benchmarks fuzz fuzz-testing *.dSYM test/*.dSYM
+	rm -fr benchmarks/files/numbers/*.json
+	$(MAKE) clean -Cdoc
+	$(MAKE) clean -Ctest
+	$(MAKE) clean -Cbenchmarks
+
 
 ##########################################################################
 # documentation tests
@@ -49,6 +61,8 @@ doctest:
 # -Wno-weak-vtables: exception class is defined inline, but has virtual method
 # -Wno-range-loop-analysis: iterator_wrapper tests "for(const auto i...)"
 # -Wno-float-equal: not all comparisons in the tests can be replaced by Approx
+# -Wno-switch-enum -Wno-covered-switch-default: pedantic/contradicting warnings about switches
+# -Wno-padded: padding is nothing to warn about
 pedantic_clang:
 	$(MAKE) json_unit CXXFLAGS="\
 		-std=c++11 -Wno-c++98-compat -Wno-c++98-compat-pedantic \
@@ -178,10 +192,6 @@ fuzzing-stop:
 cppcheck:
 	cppcheck --enable=warning --inconclusive --force --std=c++11 src/json.hpp --error-exitcode=1
 
-# run clang sanitize (we are overrding the CXXFLAGS provided by travis in order to use gcc's libstdc++)
-clang_sanitize: clean
-	CXX=clang++ CXXFLAGS="-g -O2 -fsanitize=address -fsanitize=undefined -fno-omit-frame-pointer" $(MAKE) check
-
 
 ##########################################################################
 # maintainer targets
@@ -195,18 +205,7 @@ pretty:
 	   --align-reference=type --add-brackets --convert-tabs --close-templates \
 	   --lineend=linux --preserve-date --suffix=none --formatted \
 	   src/json.hpp test/src/*.cpp \
-	   benchmarks/benchmarks.cpp doc/examples/*.cpp
+	   benchmarks/src/benchmarks.cpp doc/examples/*.cpp
-
-
-##########################################################################
-# benchmarks
-##########################################################################
-
-# benchmarks
-json_benchmarks: benchmarks/benchmarks.cpp benchmarks/benchpress.hpp benchmarks/cxxopts.hpp src/json.hpp
-	cd benchmarks/files/numbers ; python generate.py
-	$(CXX) -std=c++11 -pthread $(CXXFLAGS) -DNDEBUG -O3 -flto -I src -I benchmarks $< $(LDFLAGS) -o $@
-	./json_benchmarks
 
 
 ##########################################################################

README.md

@@ -26,6 +26,7 @@
   - [Binary formats (CBOR and MessagePack)](#binary-formats-cbor-and-messagepack)
 - [Supported compilers](#supported-compilers)
 - [License](#license)
+- [Contact](#contact)
 - [Thanks](#thanks)
 - [Used third-party tools](#used-third-party-tools)
 - [Projects using JSON for Modern C++](#projects-using-json-for-modern-c)
@@ -718,6 +719,7 @@ Though it's 2016 already, the support for C++11 is still a bit sparse. Currently
 
 - GCC 4.9 - 7.1 (and possibly later)
 - Clang 3.4 - 5.0 (and possibly later)
+- Intel C++ Compiler 17.0.2 (and possibly later)
 - Microsoft Visual C++ 2015 / Build Tools 14.0.25123.0 (and possibly later)
 - Microsoft Visual C++ 2017 / Build Tools 15.1.548.43366 (and possibly later)
 
@@ -778,6 +780,13 @@ The above copyright notice and this permission notice shall be included in all c
 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 
+## Contact
+
+If you have questions regarding the library, I would like to invite you to [open an issue at Github](https://github.com/nlohmann/json/issues/new). Please describe your request, problem, or question as detailed as possible, and also mention the version of the library you are using as well as the version of your compiler and operating system. Opening an issue at Github allows other users and contributors to this library to collaborate. For instance, I have little experience with MSVC, and most issues in this regard have been solved by a growing community. If you have a look at the [closed issues](https://github.com/nlohmann/json/issues?q=is%3Aissue+is%3Aclosed), you will see that we react quite timely in most cases.
+
+Only if your request would contain confidential information, please [send me an email](mailto:mail@nlohmann.me).
+
+
 ## Thanks
 
 I deeply appreciate the help of the following people.
@@ -864,6 +873,8 @@ I deeply appreciate the help of the following people.
 - [kbthomp1](https://github.com/kbthomp1) fixed an issue related to the Intel OSX compiler.
 - [Markus Werle](https://github.com/daixtrose) fixed a typo.
 - [WebProdPP](https://github.com/WebProdPP) fixed a subtle error in a precondition check.
+- [Alex](https://github.com/leha-bot) noted an error in a code sample.
+- [Tom de Geus](https://github.com/tdegeus) reported some warnings with ICC and helped fixing them.
 
 
 Thanks a lot for helping out! Please [let me know](mailto:mail@nlohmann.me) if I forgot someone.
@@ -881,7 +892,6 @@ The library itself contains of a single header file licensed under the MIT licen
 - [**Clang**](http://clang.llvm.org) for compilation with code sanitizers
 - [**Cmake**](https://cmake.org) for build automation
 - [**Codacity**](https://www.codacy.com) for further [code analysis](https://www.codacy.com/app/nlohmann/json)
-- [**cotire**](https://github.com/sakra/cotire) to speed of compilation
 - [**Coveralls**](https://coveralls.io) to measure [code coverage](https://coveralls.io/github/nlohmann/json)
 - [**Coverity Scan**](https://scan.coverity.com) for [static analysis](https://scan.coverity.com/projects/nlohmann-json)
 - [**cppcheck**](http://cppcheck.sourceforge.net) for static analysis
@@ -921,16 +931,6 @@ The library is currently used in Apple macOS Sierra and iOS 10. I am not sure wh
 
 To compile and run the tests, you need to execute
 
-```sh
-$ make json_unit -Ctest
-$ ./test/json_unit "*"
-
-===============================================================================
-All tests passed (14504461 assertions in 48 test cases)
-```
-
-Alternatively, you can use [CMake](https://cmake.org) and run
-
 ```sh
 $ mkdir build
 $ cd build

benchmarks/Makefile

@@ -0,0 +1,11 @@
+all: json_benchmarks
+	./json_benchmarks
+
+json_benchmarks: src/benchmarks.cpp ../src/json.hpp number_jsons
+	$(CXX) -std=c++11 -pthread $(CXXFLAGS) -DNDEBUG -O3 -flto -I thirdparty/benchpress -I thirdparty/cxxopts -I../src src/benchmarks.cpp $(LDFLAGS) -o $@
+
+number_jsons:
+	(test -e files/numbers/floats.json -a -e files/numbers/signed_ints.json -a -e files/numbers/unsigned_ints.json) || (cd files/numbers ; python generate.py)
+
+clean:
+	rm -f json_benchmarks files/numbers/*.json

benchmarks/README.md

@@ -0,0 +1,3 @@
+# Bechmarks
+
+Run `make` to compile and run a small set of benchmarks.

benchmarks/src/benchmarks.cpp

@@ -104,15 +104,15 @@ static void bench(benchpress::context& ctx,
         bench(*ctx, (in_path), (mode));             \
     })
 
-BENCHMARK_I(EMode::input, "parse jeopardy.json",              "benchmarks/files/jeopardy/jeopardy.json");
+BENCHMARK_I(EMode::input, "parse jeopardy.json",              "files/jeopardy/jeopardy.json");
-BENCHMARK_I(EMode::input, "parse canada.json",                "benchmarks/files/nativejson-benchmark/canada.json");
+BENCHMARK_I(EMode::input, "parse canada.json",                "files/nativejson-benchmark/canada.json");
-BENCHMARK_I(EMode::input, "parse citm_catalog.json",          "benchmarks/files/nativejson-benchmark/citm_catalog.json");
+BENCHMARK_I(EMode::input, "parse citm_catalog.json",          "files/nativejson-benchmark/citm_catalog.json");
-BENCHMARK_I(EMode::input, "parse twitter.json",               "benchmarks/files/nativejson-benchmark/twitter.json");
+BENCHMARK_I(EMode::input, "parse twitter.json",               "files/nativejson-benchmark/twitter.json");
-BENCHMARK_I(EMode::input, "parse numbers/floats.json",        "benchmarks/files/numbers/floats.json");
+BENCHMARK_I(EMode::input, "parse numbers/floats.json",        "files/numbers/floats.json");
-BENCHMARK_I(EMode::input, "parse numbers/signed_ints.json",   "benchmarks/files/numbers/signed_ints.json");
+BENCHMARK_I(EMode::input, "parse numbers/signed_ints.json",   "files/numbers/signed_ints.json");
-BENCHMARK_I(EMode::input, "parse numbers/unsigned_ints.json", "benchmarks/files/numbers/unsigned_ints.json");
+BENCHMARK_I(EMode::input, "parse numbers/unsigned_ints.json", "files/numbers/unsigned_ints.json");
 
-BENCHMARK_I(EMode::output_no_indent,   "dump jeopardy.json",             "benchmarks/files/jeopardy/jeopardy.json");
+BENCHMARK_I(EMode::output_no_indent,   "dump jeopardy.json",             "files/jeopardy/jeopardy.json");
-BENCHMARK_I(EMode::output_with_indent, "dump jeopardy.json with indent", "benchmarks/files/jeopardy/jeopardy.json");
+BENCHMARK_I(EMode::output_with_indent, "dump jeopardy.json with indent", "files/jeopardy/jeopardy.json");
-BENCHMARK_I(EMode::output_no_indent,   "dump numbers/floats.json",       "benchmarks/files/numbers/floats.json");
+BENCHMARK_I(EMode::output_no_indent,   "dump numbers/floats.json",       "files/numbers/floats.json");
-BENCHMARK_I(EMode::output_no_indent,   "dump numbers/signed_ints.json",  "benchmarks/files/numbers/signed_ints.json");
+BENCHMARK_I(EMode::output_no_indent,   "dump numbers/signed_ints.json",  "files/numbers/signed_ints.json");

benchmarks/thirdparty/benchpress/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Christopher Gilbert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

benchmarks/thirdparty/cxxopts/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2014 Jarryd Beck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.