mirror/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2024-11-27 16:49:02 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

📝 overworked documentation wrt. amalgamation #906

Browse Source
This commit is contained in:
Niels Lohmann 2018-01-14 13:08:28 +01:00
parent fea5f3792b
commit 411c16cbb2
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
5 changed files with 30 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.github/CONTRIBUTING.md vendored
View File

@ -8,7 +8,7 @@ To make it as easy as possible for you to contribute and for me to keep an overv
## Private reports
Usually, all issues are tracked publicly on [Github](https://github.com/nlohmann/json/issues). If you want to make a private report (e.g., for a vulnerability or to attach an example that is not meant to be publisheed), please send an email to <mail@nlohmann.me>.
Usually, all issues are tracked publicly on [GitHub](https://github.com/nlohmann/json/issues). If you want to make a private report (e.g., for a vulnerability or to attach an example that is not meant to be published), please send an email to <mail@nlohmann.me>.
## Prerequisites
@ -26,9 +26,11 @@ Please stick to the [issue template](https://github.com/nlohmann/json/blob/devel
## Files to change
There are currently two files which need to be edited:
:exclamation: Before you make any changes, note the single-header file [`src/json.hpp`](https://github.com/nlohmann/json/blob/develop/src/json.hpp) is **generated** from the source files in the [`develop` directory](https://github.com/nlohmann/json/tree/develop/develop). Please **do not** edit file `src/json.hpp` directly, but change the `develop` sources and regenerate file `src/json.hpp` by executing `make amalgamate`.
1. [`src/json.hpp`](https://github.com/nlohmann/json/blob/master/src/json.hpp)
To make changes, you need to edit the following files:
1. [`develop/*`](https://github.com/nlohmann/json/tree/develop/develop) - These files are the sources of the library. Before testing or creating a pull request, execute `make amalgamate` to regenerate `src/json.hpp`.
2. [`test/src/unit-*.cpp`](https://github.com/nlohmann/json/tree/develop/test/src) - These files contain the [Catch](https://github.com/philsquared/Catch) unit tests which currently cover [100 %](https://coveralls.io/github/nlohmann/json) of the library's code.

3
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@ -4,9 +4,12 @@
## Pull request checklist
Read the [Contribution Guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md) for detailed information.
- [ ] Changes are described in the pull request, or an [existing issue is referenced](https://github.com/nlohmann/json/issues).
- [ ] The test suite [compiles and runs](https://github.com/nlohmann/json/blob/develop/README.md#execute-unit-tests) without error.
- [ ] [Code coverage](https://coveralls.io/github/nlohmann/json) is 100%. Test cases can be added by editing the [test suite](https://github.com/nlohmann/json/tree/develop/test/src).
- [ ] The source code is amalgamated; that is, after making changes to the sources in the `develop` directory, run `make amalgamate` to create the single-header file `src/json.hpp`. The whole process is described [here](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#files-to-change).
## Please don't

5
.travis.yml
View File

@ -278,6 +278,11 @@ script:
- ctest -C Release -V -j
- cd ..
# check if header was correctly amalgamated
- if [ `which python` ]; then
make check-amalgamation ;
fi
# check if homebrew works (only checks develop branch)
- if [ `which brew` ]; then
brew update ;

4
Makefile
View File

@ -32,7 +32,7 @@ all:
@echo "amalgamate - amalgamate file src/json.hpp from the develop sources"
@echo "ChangeLog.md - generate ChangeLog file"
@echo "check - compile and execute test suite"
@echo "check-amalagamation - check whether sources have been amalgamated"
@echo "check-amalgamation - check whether sources have been amalgamated"
@echo "check-fast - compile and execute test suite (skip long-running tests)"
@echo "clean - remove built files"
@echo "coverage - create coverage information with lcov"
@ -258,7 +258,7 @@ src/json.hpp: $(SRCS)
$(MAKE) pretty
# check if src/json.hpp has been amalgamated from the develop sources
check-amalagamation:
check-amalgamation:
@mv src/json.hpp src/json.hpp~
@$(MAKE) amalgamate
@diff src/json.hpp src/json.hpp~ || (echo "===================================================================\n Amalgamation required! Please read the contribution guidelines\n in file .github/CONTRIBUTING.md.\n===================================================================" ; mv src/json.hpp~ src/json.hpp ; false)

23
README.md
View File

@ -8,8 +8,8 @@
[![Try online](https://img.shields.io/badge/try-online-blue.svg)](https://wandbox.org/permlink/Op57X0V7fTf2tdwl)
[![Documentation](https://img.shields.io/badge/docs-doxygen-blue.svg)](http://nlohmann.github.io/json)
[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/nlohmann/json/master/LICENSE.MIT)
[![Github Releases](https://img.shields.io/github/release/nlohmann/json.svg)](https://github.com/nlohmann/json/releases)
[![Github Issues](https://img.shields.io/github/issues/nlohmann/json.svg)](http://github.com/nlohmann/json/issues)
[![GitHub Releases](https://img.shields.io/github/release/nlohmann/json.svg)](https://github.com/nlohmann/json/releases)
[![GitHub Issues](https://img.shields.io/github/issues/nlohmann/json.svg)](http://github.com/nlohmann/json/issues)
[![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/nlohmann/json.svg)](http://isitmaintained.com/project/nlohmann/json "Average time to resolve an issue")
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/289/badge)](https://bestpractices.coreinfrastructure.org/projects/289)
@ -65,14 +65,20 @@ using json = nlohmann::json;
to the files you want to use JSON objects. That's it. Do not forget to set the necessary switches to enable C++11 (e.g., `-std=c++11` for GCC and Clang).
You can further use file [`develop/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/develop/json_fwd.hpp) for forward-declarations.
### Package Managers
:beer: If you are using OS X and [Homebrew](http://brew.sh), just type `brew tap nlohmann/json` and `brew install nlohmann_json` and you're set. If you want the bleeding edge rather than the latest release, use `brew install nlohmann_json --HEAD`.
If you are using the [Meson Build System](http://mesonbuild.com), then you can wrap this repo as a subproject.
If you are using the [Meson Build System](http://mesonbuild.com), then you can wrap this repository as a subproject.
If you are using [Conan](https://www.conan.io/) to manage your dependencies, merely add `jsonformoderncpp/x.y.z@vthiery/stable` to your `conanfile.py`'s requires, where `x.y.z` is the release version you want to use. Please file issues [here](https://github.com/vthiery/conan-jsonformoderncpp/issues) if you experience problems with the packages.
If you are using [hunter](https://github.com/ruslo/hunter/) on your project for external dependencies, then you can use the [nlohmann_json package](https://docs.hunter.sh/en/latest/packages/pkg/nlohmann_json.html). Please see the hunter project for any issues regarding the packaging.
If you are using [Buckaroo](https://buckaroo.pm), you can install this library's module with `buckaroo install nlohmann/json`. Please file issues [here](https://github.com/LoopPerfect/buckaroo-recipes/issues/new?title=nlohmann/nlohmann/json).
If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project for external dependencies, then you can use the [nlohmann-json package](https://github.com/Microsoft/vcpkg/tree/master/ports/nlohmann-json). Please see the vcpkg project for any issues regarding the packaging.
@ -809,7 +815,7 @@ The class contains the UTF-8 Decoder from Bjoern Hoehrmann which is licensed und
## 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.
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). For encrypted messages, please use [this key](https://keybase.io/nlohmann/pgp_keys.asc).
@ -847,7 +853,7 @@ I deeply appreciate the help of the following people.
- [Corbin Hughes](https://github.com/nibroc) fixed some typos in the contribution guidelines.
- [twelsby](https://github.com/twelsby) fixed the array subscript operator, an issue that failed the MSVC build, and floating-point parsing/dumping. He further added support for unsigned integer numbers and implemented better roundtrip support for parsed numbers.
- [Volker Diels-Grabsch](https://github.com/vog) fixed a link in the README file.
- [msm-](https://github.com/msm-) added support for american fuzzy lop.
- [msm-](https://github.com/msm-) added support for American Fuzzy Lop.
- [Annihil](https://github.com/Annihil) fixed an example in the README file.
- [Themercee](https://github.com/Themercee) noted a wrong URL in the README file.
- [Lv Zheng](https://github.com/lv-zheng) fixed a namespace issue with `int64_t` and `uint64_t`.
@ -893,7 +899,7 @@ I deeply appreciate the help of the following people.
- [Vincent Thiery](https://github.com/vthiery) maintains a package for the Conan package manager.
- [Steffen](https://github.com/koemeet) fixed a potential issue with MSVC and `std::min`.
- [Mike Tzou](https://github.com/Chocobo1) fixed some typos.
- [amrcode](https://github.com/amrcode) noted a missleading documentation about comparison of floats.
- [amrcode](https://github.com/amrcode) noted a misleading documentation about comparison of floats.
- [Oleg Endo](https://github.com/olegendo) reduced the memory consumption by replacing `<iostream>` with `<iosfwd>`.
- [dan-42](https://github.com/dan-42) cleaned up the CMake files to simplify including/reusing of the library.
- [Nikita Ofitserov](https://github.com/himikof) allowed for moving values from initializer lists.
@ -910,7 +916,7 @@ I deeply appreciate the help of the following people.
- [Nate Vargas](https://github.com/eld00d) added a Doxygen tag file.
- [pvleuven](https://github.com/pvleuven) helped fixing a warning in ICC.
- [Pavel](https://github.com/crea7or) helped fixing some warnings in MSVC.
- [Jamie Seward](https://github.com/jseward) avoided unneccessary string copies in `find()` and `count()`.
- [Jamie Seward](https://github.com/jseward) avoided unnecessary string copies in `find()` and `count()`.
- [Mitja](https://github.com/Itja) fixed some typos.
- [Jorrit Wronski](https://github.com/jowr) updated the Hunter package links.
- [Matthias Möller](https://github.com/TinyTinni) added a `.natvis` for the MSVC debug view.
@ -925,6 +931,7 @@ Thanks a lot for helping out! Please [let me know](mailto:mail@nlohmann.me) if I
The library itself contains of a single header file licensed under the MIT license. However, it is built, tested, documented, and whatnot using a lot of third-party tools and services. Thanks a lot!
- [**amalgamate.py - Amalgamate C source and header files**](https://github.com/edlund/amalgamate) to create a single header file
- [**American fuzzy lop**](http://lcamtuf.coredump.cx/afl/) for fuzz testing
- [**AppVeyor**](https://www.appveyor.com) for [continuous integration](https://ci.appveyor.com/project/nlohmann/json) on Windows
- [**Artistic Style**](http://astyle.sourceforge.net) for automatic source code identation
@ -939,7 +946,7 @@ The library itself contains of a single header file licensed under the MIT licen
- [**cxxopts**](https://github.com/jarro2783/cxxopts) to let benchpress parse command-line parameters
- [**Doxygen**](http://www.stack.nl/~dimitri/doxygen/) to generate [documentation](https://nlohmann.github.io/json/)
- [**git-update-ghpages**](https://github.com/rstacruz/git-update-ghpages) to upload the documentation to gh-pages
- [**Github Changelog Generator**](https://github.com/skywinder/github-changelog-generator) to generate the [ChangeLog](https://github.com/nlohmann/json/blob/develop/ChangeLog.md)
- [**GitHub Changelog Generator**](https://github.com/skywinder/github-changelog-generator) to generate the [ChangeLog](https://github.com/nlohmann/json/blob/develop/ChangeLog.md)
- [**libFuzzer**](http://llvm.org/docs/LibFuzzer.html) to implement fuzz testing for OSS-Fuzz
- [**OSS-Fuzz**](https://github.com/google/oss-fuzz) for continuous fuzz testing of the library
- [**Probot**](https://probot.github.io) for automating maintainer tasks such as closing stale issues, requesting missing information, or detecting toxic comments.