README.md - platform/external/jsoncpp - Git at Google

 Introduction
 ------------

 [JSON][json-org] is a lightweight data-interchange format. It can represent
 numbers, strings, ordered sequences of values, and collections of name/value
 pairs.

 [json-org]: http://json.org/

 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.

 ## A note on backward-compatibility
 Very soon, we are switching to C++11 only. For older compilers, try the `pre-C++11` branch.

 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 `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`.


 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
 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
   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.

 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" ../..
     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.


 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.

 [SCons]: http://www.scons.org/

 Invoke SCons as follows:

     scons platform=$PLATFORM [TARGET]

 where `$PLATFORM` 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
 * `msvc90`: Microsoft Visual Studio 2008
 * `linux-gcc`: Gnu C++ (linux, also reported to work for Mac OS X)

 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

 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
 `jsontest` executable that was compiled on your platform.

     cd test
     # This will run the Reader/Writer tests
     python runjsontests.py path/to/jsontest

     # 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

     # This will run the unit tests (mostly Value)
     python rununittests.py path/to/test_lib_json

     # You can run the tests using valgrind:
     python rununittests.py --valgrind path/to/test_lib_json


 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.
 * a `TESTNAME.expected` file, that contains a flatened representation of the
   input document.

 The `TESTNAME.expected` file format is as follows:

 * 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 (i.e.
   represented by either `[]` or `{}`).
 * 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.


 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
   parsing was corrected.
 * `test_complex_01.actual`: flattened JSON element tree produced by `jsontest`
   from reading `test_complex_01.json`.
 * `test_complex_01.rewrite`: JSON document written by `jsontest` 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` from reading `test_complex_01.rewrite`.
 * `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.
	Introduction
	------------

	[JSON][json-org] is a lightweight data-interchange format. It can represent
	numbers, strings, ordered sequences of values, and collections of name/value
	pairs.

	[json-org]: http://json.org/

	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.

	## A note on backward-compatibility
	Very soon, we are switching to C++11 only. For older compilers, try the `pre-C++11` branch.

	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 `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`.


	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
	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
	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.

	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" ../..
	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.


	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.

	[SCons]: http://www.scons.org/

	Invoke SCons as follows:

	scons platform=$PLATFORM [TARGET]

	where `$PLATFORM` 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
	* `msvc90`: Microsoft Visual Studio 2008
	* `linux-gcc`: Gnu C++ (linux, also reported to work for Mac OS X)

	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

	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
	`jsontest` executable that was compiled on your platform.

	cd test
	# This will run the Reader/Writer tests
	python runjsontests.py path/to/jsontest

	# 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

	# This will run the unit tests (mostly Value)
	python rununittests.py path/to/test_lib_json

	# You can run the tests using valgrind:
	python rununittests.py --valgrind path/to/test_lib_json


	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.
	* a `TESTNAME.expected` file, that contains a flatened representation of the
	input document.

	The `TESTNAME.expected` file format is as follows:

	* 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 (i.e.
	represented by either `[]` or `{}`).
	* 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.


	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
	parsing was corrected.
	* `test_complex_01.actual`: flattened JSON element tree produced by `jsontest`
	from reading `test_complex_01.json`.
	* `test_complex_01.rewrite`: JSON document written by `jsontest` 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` from reading `test_complex_01.rewrite`.
	* `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.