2014-07-01 03:54:14 +02:00
|
|
|
Introduction
|
|
|
|
------------
|
2007-06-14 23:01:26 +02:00
|
|
|
|
2014-07-01 03:56:56 +02:00
|
|
|
[JSON][json-org] is a lightweight data-interchange format. It can represent
|
|
|
|
numbers, strings, ordered sequences of values, and collections of name/value
|
|
|
|
pairs.
|
2007-06-14 23:01:26 +02:00
|
|
|
|
2014-07-01 03:56:56 +02:00
|
|
|
[json-org]: http://json.org/
|
2007-06-14 23:01:26 +02:00
|
|
|
|
2014-07-01 03:56:56 +02:00
|
|
|
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.
|
2007-06-14 23:01:26 +02:00
|
|
|
|
2013-05-08 22:21:11 +02:00
|
|
|
|
2014-07-01 03:59:25 +02:00
|
|
|
Using JsonCpp in your project
|
|
|
|
-----------------------------
|
2013-05-08 22:21:11 +02:00
|
|
|
|
2014-07-01 03:59:25 +02:00
|
|
|
The recommended approach to integrating JsonCpp in your project is to build the
|
|
|
|
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.
|
2013-05-08 22:21:11 +02:00
|
|
|
|
2014-07-01 03:59:25 +02:00
|
|
|
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
|
|
|
|
define the macro `JSON_DLL`.
|
2013-05-08 22:21:11 +02:00
|
|
|
|
|
|
|
|
2014-07-01 04:02:57 +02:00
|
|
|
Building and testing with new 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
|
|
|
|
|
|
|
|
[CMake]: http://www.cmake.org
|
|
|
|
|
|
|
|
Note that Python is also required to run the JSON reader/writer tests. If
|
2013-05-08 22:21:11 +02:00
|
|
|
missing, the build will skip running those tests.
|
2014-07-01 04:02:57 +02:00
|
|
|
|
2013-05-08 22:21:11 +02:00
|
|
|
When running CMake, a few parameters are required:
|
2014-07-01 04:02:57 +02:00
|
|
|
|
|
|
|
* 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
|
|
|
|
Visual Studio, 32 or 64 bits solution?
|
|
|
|
|
|
|
|
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
|
|
|
|
dynamic library).
|
|
|
|
* Click the configure button at the bottom, then the generate button.
|
|
|
|
* The generated solution/makefiles can be found in the binary directory.
|
|
|
|
|
2013-05-08 22:21:11 +02:00
|
|
|
Alternatively, from the command-line on Unix in the source directory:
|
2014-07-01 04:02:57 +02:00
|
|
|
|
|
|
|
mkdir -p ../build/debug
|
|
|
|
cd ../build/debug
|
|
|
|
cmake -DCMAKE_BUILD_TYPE=debug -DJSONCPP_LIB_BUILD_SHARED=OFF -G "Unix Makefiles" ../../jsoncpp-src
|
|
|
|
make
|
|
|
|
|
|
|
|
Running `cmake -`" 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.
|
|
|
|
|
2010-02-22 05:16:10 +01:00
|
|
|
|
2014-07-01 03:54:14 +02:00
|
|
|
Building/Testing with the legacy build system based on SCons
|
|
|
|
------------------------------------------------------------
|
2007-06-14 23:01:26 +02:00
|
|
|
|
|
|
|
JsonCpp uses Scons (http://www.scons.org) as a build system. Scons requires
|
|
|
|
python to be installed (http://www.python.org).
|
|
|
|
|
|
|
|
You download scons-local distribution from the following url:
|
2011-05-01 17:06:40 +02:00
|
|
|
http://sourceforge.net/projects/scons/files/scons-local/1.2.0/
|
2007-06-14 23:01:26 +02:00
|
|
|
|
|
|
|
Unzip it in the directory where you found this README file. scons.py Should be
|
|
|
|
at the same level as README.
|
|
|
|
|
|
|
|
python scons.py platform=PLTFRM [TARGET]
|
|
|
|
where PLTFRM may be one of:
|
|
|
|
suncc Sun C++ (Solaris)
|
|
|
|
vacpp Visual Age C++ (AIX)
|
|
|
|
mingw
|
|
|
|
msvc6 Microsoft Visual Studio 6 service pack 5-6
|
|
|
|
msvc70 Microsoft Visual Studio 2002
|
|
|
|
msvc71 Microsoft Visual Studio 2003
|
|
|
|
msvc80 Microsoft Visual Studio 2005
|
2010-03-13 11:59:50 +01:00
|
|
|
msvc90 Microsoft Visual Studio 2008
|
2007-06-14 23:01:26 +02:00
|
|
|
linux-gcc Gnu C++ (linux, also reported to work for Mac OS X)
|
2010-03-13 11:59:50 +01:00
|
|
|
|
|
|
|
Notes: if you are building with Microsoft Visual Studio 2008, you need to
|
|
|
|
setup the environment by running vcvars32.bat (e.g. MSVC 2008 command prompt)
|
|
|
|
before running scons.
|
2007-06-14 23:01:26 +02:00
|
|
|
|
2010-03-13 11:59:50 +01:00
|
|
|
Adding platform is fairly simple. You need to change the Sconstruct file
|
2007-06-14 23:01:26 +02:00
|
|
|
to do so.
|
|
|
|
|
|
|
|
and TARGET may be:
|
|
|
|
check: build library and run unit tests.
|
2010-02-22 05:16:10 +01:00
|
|
|
|
2014-07-01 03:54:14 +02:00
|
|
|
Running the test manually
|
|
|
|
-------------------------
|
2010-02-22 05:16:10 +01:00
|
|
|
|
2011-05-01 17:06:40 +02:00
|
|
|
Notes that test can be run by scons using the 'check' target (see above).
|
|
|
|
|
|
|
|
You need to run test manually only if you are troubleshooting an issue.
|
|
|
|
|
|
|
|
In the instruction below, replace "path to jsontest.exe" with the path
|
|
|
|
of the 'jsontest' executable that was compiled on your platform.
|
|
|
|
|
2009-11-18 22:38:54 +01:00
|
|
|
cd test
|
2009-11-22 14:11:14 +01:00
|
|
|
# This will run the Reader/Writer tests
|
2009-11-18 22:38:54 +01:00
|
|
|
python runjsontests.py "path to jsontest.exe"
|
2010-02-22 05:16:10 +01:00
|
|
|
|
|
|
|
# This will run the Reader/Writer tests, using JSONChecker test suite
|
|
|
|
# (http://www.json.org/JSON_checker/).
|
|
|
|
# Notes: not all tests pass: JsonCpp is too lenient (for example,
|
|
|
|
# it allows an integer to start with '0'). The goal is to improve
|
|
|
|
# strict mode parsing to get all tests to pass.
|
|
|
|
python runjsontests.py --with-json-checker "path to jsontest.exe"
|
|
|
|
|
2009-11-22 14:11:14 +01:00
|
|
|
# This will run the unit tests (mostly Value)
|
|
|
|
python rununittests.py "path to test_lib_json.exe"
|
|
|
|
|
2010-02-22 05:16:10 +01:00
|
|
|
You can run the tests using valgrind:
|
2009-11-22 14:11:14 +01:00
|
|
|
python rununittests.py --valgrind "path to test_lib_json.exe"
|
2010-02-22 05:16:10 +01:00
|
|
|
|
|
|
|
|
2014-07-01 03:54:14 +02:00
|
|
|
Building the documentation
|
|
|
|
--------------------------
|
2010-02-22 05:16:10 +01:00
|
|
|
|
|
|
|
Run the python script doxybuild.py from the top directory:
|
|
|
|
|
|
|
|
python doxybuild.py --open --with-dot
|
|
|
|
|
|
|
|
See doxybuild.py --help for options.
|
|
|
|
|
2010-04-27 18:38:30 +02:00
|
|
|
Notes that the documentation is also available for download as a tarball.
|
|
|
|
The documentation of the latest release is available online at:
|
|
|
|
http://jsoncpp.sourceforge.net/
|
|
|
|
|
2014-07-01 03:54:14 +02:00
|
|
|
Generating amalgamated source and header
|
|
|
|
----------------------------------------
|
2011-05-01 22:13:40 +02:00
|
|
|
|
|
|
|
JsonCpp is provided with a script to generate a single header and a single
|
|
|
|
source file to ease inclusion in an existing project.
|
|
|
|
|
2011-05-02 23:09:30 +02:00
|
|
|
The amalgamated source can be generated at any time by running the following
|
2011-05-01 22:13:40 +02:00
|
|
|
command from the top-directory (requires python 2.6):
|
|
|
|
|
2011-05-02 23:09:30 +02:00
|
|
|
python amalgamate.py
|
2011-05-01 22:13:40 +02:00
|
|
|
|
|
|
|
It is possible to specify header name. See -h options for detail. By default,
|
|
|
|
the following files are generated:
|
|
|
|
- dist/jsoncpp.cpp: source file that need to be added to your project
|
|
|
|
- dist/json/json.h: header file corresponding to use in your project. It is
|
2011-05-02 23:09:30 +02:00
|
|
|
equivalent to including json/json.h in non-amalgamated source. This header
|
2011-05-01 22:13:40 +02:00
|
|
|
only depends on standard headers.
|
|
|
|
- dist/json/json-forwards.h: header the provides forward declaration
|
|
|
|
of all JsonCpp types. This typically what should be included in headers to
|
|
|
|
speed-up compilation.
|
|
|
|
|
2011-05-02 23:09:30 +02:00
|
|
|
The amalgamated sources are generated by concatenating JsonCpp source in the
|
|
|
|
correct order and defining macro JSON_IS_AMALGAMATION to prevent inclusion
|
|
|
|
of other headers.
|
2010-02-22 05:16:10 +01:00
|
|
|
|
2014-07-01 03:54:14 +02:00
|
|
|
Adding a reader/writer test
|
|
|
|
---------------------------
|
2010-02-22 05:16:10 +01:00
|
|
|
|
|
|
|
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.
|
|
|
|
- a TESTNAME.expected file, that contains a flatened representation of
|
|
|
|
the input document.
|
|
|
|
|
|
|
|
TESTNAME.expected file format:
|
|
|
|
- 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 element value by '='. Array and object values are always empty
|
|
|
|
(e.g. represented by either [] or {}).
|
|
|
|
- element path: '.' represented 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 test_complex_01.json and test_complex_01.expected to better understand
|
|
|
|
element path.
|
|
|
|
|
|
|
|
|
2014-07-01 03:54:14 +02:00
|
|
|
Understanding reader/writer test output
|
|
|
|
---------------------------------------
|
2010-02-22 05:16:10 +01:00
|
|
|
|
|
|
|
When a test is run, output files are generated aside 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
|
|
|
|
parsing was corrected.
|
|
|
|
|
|
|
|
- test_complex_01.actual: flattened JSON element tree produced by
|
|
|
|
jsontest.exe from reading test_complex_01.json
|
|
|
|
- test_complex_01.rewrite: JSON document written by jsontest.exe using the
|
|
|
|
Json::Value parsed from test_complex_01.json and serialized using
|
|
|
|
Json::StyledWritter.
|
|
|
|
- test_complex_01.actual-rewrite: flattened JSON element tree produced by
|
|
|
|
jsontest.exe from reading test_complex_01.rewrite.
|
|
|
|
test_complex_01.process-output: jsontest.exe output, typically useful to
|
|
|
|
understand parsing error.
|
2010-04-20 23:35:19 +02:00
|
|
|
|
2014-07-01 03:54:14 +02:00
|
|
|
License
|
|
|
|
-------
|
2010-04-20 23:35:19 +02:00
|
|
|
|
|
|
|
See file LICENSE for details. Basically JsonCpp is licensed under
|
|
|
|
MIT license, or public domain if desired and recognized in your jurisdiction.
|
2011-06-21 22:34:40 +02:00
|
|
|
|