summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/jsoncpp/README.md
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/jsoncpp/README.md')
-rw-r--r--3rdparty/jsoncpp/README.md104
1 files changed, 47 insertions, 57 deletions
diff --git a/3rdparty/jsoncpp/README.md b/3rdparty/jsoncpp/README.md
index 099f17fa2fd..93c8d1f593a 100644
--- a/3rdparty/jsoncpp/README.md
+++ b/3rdparty/jsoncpp/README.md
@@ -7,34 +7,62 @@ 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
+
## A note on backward-compatibility
-Very soon, we are switching to C++11 only. For older compilers, try the `pre-C++11` branch.
+* `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 build
-the amalgamated source (a single `.cpp` file) with your own build system. This
-ensures consistency of compilation flags and ABI compatibility. See the section
-"Generating amalgamated source and header" for instructions.
+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
+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
should be included as follow:
#include <json/json.h>
-If JsonCpp was build as a dynamic library on Windows, then your project needs to
+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
+----------------------------------------
+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
+top-directory (this requires Python 2.6):
+
+ python amalgamate.py
+
+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
+ only depends on standard headers.
+* `dist/json/json-forwards.h`: header that provides forward declaration of all
+ 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.
-Building and testing with new CMake
------------------------------------
+# 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:
@@ -57,7 +85,7 @@ Steps for generating solution/makefiles using `cmake-gui`:
* Make "source code" point to the source directory.
* Make "where to build the binary" point to the directory to use for the build.
* Click on the "Grouped" check box.
-* Review JsonCpp build options (tick `JSONCPP_LIB_BUILD_SHARED` to build as a
+* Review JsonCpp build options (tick `BUILD_SHARED_LIBS` to build as a
dynamic library).
* Click the configure button at the bottom, then the generate button.
* The generated solution/makefiles can be found in the binary directory.
@@ -66,19 +94,17 @@ Alternatively, from the command-line on Unix in the source directory:
mkdir -p build/debug
cd build/debug
- cmake -DCMAKE_BUILD_TYPE=debug -DJSONCPP_LIB_BUILD_SHARED=OFF -G "Unix Makefiles" ../..
+ cmake -DCMAKE_BUILD_TYPE=debug -DBUILD_STATIC_LIBS=ON -DBUILD_SHARED_LIBS=OFF -DARCHIVE_INSTALL_DIR=. -G "Unix Makefiles" ../..
make
-Running `cmake -`" will display the list of available generators (passed using
+Running `cmake -h` will display the list of available generators (passed using
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.
@@ -107,14 +133,7 @@ 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
---------------------------
-
-Note that test can be run using SCons using the `check` target:
-
- scons platform=$PLATFORM check
-
+## 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
@@ -137,45 +156,21 @@ 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
+Note that tests can be run using SCons using the `check` target:
+
+ scons platform=$PLATFORM check
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.
-
-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
-top-directory (this requires Python 2.6):
-
- python amalgamate.py
-
-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
- only depends on standard headers.
-* `dist/json/json-forwards.h`: header that provides forward declaration of all
- 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.
-
-
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.
@@ -195,10 +190,8 @@ The `TESTNAME.expected` file format is as follows:
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:
@@ -215,10 +208,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
-------
-
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.
-