generic-library/jsoncpp
1
0
Fork 0
mirror of https://github.com/open-source-parsers/jsoncpp.git synced 2025-01-19 00:46:02 +01:00
Code Issues Projects Releases Wiki Activity

README: Give some love.

Browse Source
This commit is contained in:
Iñaki Baz Castillo 2017-01-12 10:57:34 +01:00
parent 81065748e3
commit 60bfcf1715
1 changed files with 48 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
README.md
View File

@ -1,5 +1,4 @@
Introduction
------------
# JsonCpp
[JSON][json-org] is a lightweight data-interchange format. It can represent
numbers, strings, ordered sequences of values, and collections of name/value
@ -7,20 +6,29 @@ pairs.
[json-org]: http://json.org/
[JsonCpp][] is a C++ library that allows manipulating JSON values, including
JsonCpp is a C++ library that allows manipulating JSON values, including
serialization and deserialization to and from strings. It can also preserve
existing comment in unserialization/serialization steps, making it a convenient
format to store user input files.
[JsonCpp]: http://open-source-parsers.github.io/jsoncpp-docs/doxygen/index.html
## Documentation
[JsonCpp documentation][JsonCpp-documentation] is generated using [Doxygen][].
[JsonCpp-documentation]: http://open-source-parsers.github.io/jsoncpp-docs/doxygen/index.html
[Doxygen]: http://www.doxygen.org
## A note on backward-compatibility
* `1.y.z` is built with C++11.
* `0.y.z` can be used with older compilers.
* Major versions maintain binary-compatibility.
# Using JsonCpp in your project
-----------------------------
## Using JsonCpp in your project
The recommended approach to integrating JsonCpp in your project is to include
the [amalgamated source](#generating-amalgamated-source-and-header) (a single
`.cpp` file and two `.h` files) in your project, and compile and build as you
@ -28,16 +36,15 @@ would any other source file. This ensures consistency of compilation flags and
ABI compatibility, issues which arise when building shared or static
libraries. See the next section for instructions.
The `include/` should be added to your compiler include path. Jsoncpp headers
The `include/` should be added to your compiler include path. JsonCpp headers
should be included as follow:
#include <json/json.h>
If JsonCpp was built as a dynamic library on Windows, then your project needs to
define the macro `JSON_DLL`.
If JsonCpp was built as a dynamic library on Windows, then your project needs to define the macro `JSON_DLL`.
### Generating amalgamated source and header
Generating amalgamated source and header
----------------------------------------
JsonCpp is provided with a script to generate a single header and a single
source file to ease inclusion into an existing project. The amalgamated source
can be generated at any time by running the following command from the
@ -48,6 +55,7 @@ top-directory (this requires Python 2.6):
It is possible to specify header name. See the `-h` option for detail.
By default, the following files are generated:
* `dist/jsoncpp.cpp`: source file that needs to be added to your project.
* `dist/json/json.h`: corresponding header file for use in your project. It is
equivalent to including `json/json.h` in non-amalgamated source. This header
@ -56,15 +64,14 @@ By default, the following files are generated:
JsonCpp types.
The amalgamated sources are generated by concatenating JsonCpp source in the
correct order and defining the macro `JSON_IS_AMALGAMATION` to prevent inclusion
of other headers.
correct order and defining the macro `JSON_IS_AMALGAMATION` to prevent inclusion of other headers.
# Contributing to JsonCpp
Building and testing with CMake
-------------------------------
[CMake][] is a C++ Makefiles/Solution generator. It is usually available on most
Linux system as package. On Ubuntu:
## Contributing to JsonCpp
### Building and testing with CMake
[CMake][] is a C++ Makefiles/Solution generator. It is usually available on most Linux system as package. On Ubuntu:
sudo apt-get install cmake
@ -75,9 +82,9 @@ missing, the build will skip running those tests.
When running CMake, a few parameters are required:
* a build directory where the makefiles/solution are generated. It is also used
* A build directory where the makefiles/solution are generated. It is also used
to store objects, libraries and executables files.
* the generator to use: makefiles or Visual Studio solution? What version or
* The generator to use: makefiles or Visual Studio solution? What version or
Visual Studio, 32 or 64 bits solution?
Steps for generating solution/makefiles using `cmake-gui`:
@ -107,10 +114,10 @@ the `-G` option).
By default CMake hides compilation commands. This can be modified by specifying
`-DCMAKE_VERBOSE_MAKEFILE=true` when generating makefiles.
Building and testing with SCons
-------------------------------
**Note:** The SCons-based build system is deprecated. Please use CMake; see the
section above.
### Building and testing with SCons
**Note:** The SCons-based build system is deprecated. Please use CMake (see the
section above).
JsonCpp can use [Scons][] as a build system. Note that SCons requires Python to
be installed.
@ -137,7 +144,8 @@ If you are building with Microsoft Visual Studio 2008, you need to set up the
environment by running `vcvars32.bat` (e.g. MSVC 2008 command prompt) before
running SCons.
## Running the tests manually
### Running the tests manually
You need to run tests manually only if you are troubleshooting an issue.
In the instructions below, replace `path/to/jsontest` with the path of the
@ -160,21 +168,22 @@ In the instructions below, replace `path/to/jsontest` with the path of the
# You can run the tests using valgrind:
python rununittests.py --valgrind path/to/test_lib_json
## Running the tests using scons
### Running the tests using SCons
Note that tests can be run using SCons using the `check` target:
scons platform=$PLATFORM check
Building the documentation
--------------------------
### Building the documentation
Run the Python script `doxybuild.py` from the top directory:
python doxybuild.py --doxygen=$(which doxygen) --open --with-dot
See `doxybuild.py --help` for options.
Adding a reader/writer test
---------------------------
### Adding a reader/writer test
To add a test, you need to create two files in test/data:
* a `TESTNAME.json` file, that contains the input document in JSON format.
@ -183,21 +192,19 @@ To add a test, you need to create two files in test/data:
The `TESTNAME.expected` file format is as follows:
* each line represents a JSON element of the element tree represented by the
* Each line represents a JSON element of the element tree represented by the
input document.
* each line has two parts: the path to access the element separated from the
* Each line has two parts: the path to access the element separated from the
element value by `=`. Array and object values are always empty (i.e.
represented by either `[]` or `{}`).
* element path: `.` represents the root element, and is used to separate object
* Element path `.` represents the root element, and is used to separate object
members. `[N]` is used to specify the value of an array element at index `N`.
See the examples `test_complex_01.json` and `test_complex_01.expected` to better
understand element paths.
See the examples `test_complex_01.json` and `test_complex_01.expected` to better understand element paths.
Understanding reader/writer test output
---------------------------------------
When a test is run, output files are generated beside the input test files.
Below is a short description of the content of each file:
### Understanding reader/writer test output
When a test is run, output files are generated beside the input test files. Below is a short description of the content of each file:
* `test_complex_01.json`: input JSON document.
* `test_complex_01.expected`: flattened JSON element tree used to check if
@ -212,7 +219,7 @@ Below is a short description of the content of each file:
* `test_complex_01.process-output`: `jsontest` output, typically useful for
understanding parsing errors.
License
-------
## License
See the `LICENSE` file for details. In summary, JsonCpp is licensed under the
MIT license, or public domain if desired and recognized in your jurisdiction.