README.md
1Introduction
2------------
3
4[JSON][json-org] is a lightweight data-interchange format. It can represent
5numbers, strings, ordered sequences of values, and collections of name/value
6pairs.
7
8[json-org]: http://json.org/
9
10JsonCpp is a C++ library that allows manipulating JSON values, including
11serialization and deserialization to and from strings. It can also preserve
12existing comment in unserialization/serialization steps, making it a convenient
13format to store user input files.
14
15## A note on backward-compatibility
16Very soon, we are switching to C++11 only. For older compilers, try the `pre-C++11` branch.
17
18Using JsonCpp in your project
19-----------------------------
20
21The recommended approach to integrating JsonCpp in your project is to build
22the amalgamated source (a single `.cpp` file) with your own build system. This
23ensures consistency of compilation flags and ABI compatibility. See the section
24"Generating amalgamated source and header" for instructions.
25
26The `include/` should be added to your compiler include path. Jsoncpp headers
27should be included as follow:
28
29 #include <json/json.h>
30
31If JsonCpp was build as a dynamic library on Windows, then your project needs to
32define the macro `JSON_DLL`.
33
34
35Building and testing with new CMake
36-----------------------------------
37
38[CMake][] is a C++ Makefiles/Solution generator. It is usually available on most
39Linux system as package. On Ubuntu:
40
41 sudo apt-get install cmake
42
43[CMake]: http://www.cmake.org
44
45Note that Python is also required to run the JSON reader/writer tests. If
46missing, the build will skip running those tests.
47
48When running CMake, a few parameters are required:
49
50* a build directory where the makefiles/solution are generated. It is also used
51 to store objects, libraries and executables files.
52* the generator to use: makefiles or Visual Studio solution? What version or
53 Visual Studio, 32 or 64 bits solution?
54
55Steps for generating solution/makefiles using `cmake-gui`:
56
57* Make "source code" point to the source directory.
58* Make "where to build the binary" point to the directory to use for the build.
59* Click on the "Grouped" check box.
60* Review JsonCpp build options (tick `JSONCPP_LIB_BUILD_SHARED` to build as a
61 dynamic library).
62* Click the configure button at the bottom, then the generate button.
63* The generated solution/makefiles can be found in the binary directory.
64
65Alternatively, from the command-line on Unix in the source directory:
66
67 mkdir -p build/debug
68 cd build/debug
69 cmake -DCMAKE_BUILD_TYPE=debug -DJSONCPP_LIB_BUILD_SHARED=OFF -G "Unix Makefiles" ../..
70 make
71
72Running `cmake -`" will display the list of available generators (passed using
73the `-G` option).
74
75By default CMake hides compilation commands. This can be modified by specifying
76`-DCMAKE_VERBOSE_MAKEFILE=true` when generating makefiles.
77
78
79Building and testing with SCons
80-------------------------------
81
82**Note:** The SCons-based build system is deprecated. Please use CMake; see the
83section above.
84
85JsonCpp can use [Scons][] as a build system. Note that SCons requires Python to
86be installed.
87
88[SCons]: http://www.scons.org/
89
90Invoke SCons as follows:
91
92 scons platform=$PLATFORM [TARGET]
93
94where `$PLATFORM` may be one of:
95
96* `suncc`: Sun C++ (Solaris)
97* `vacpp`: Visual Age C++ (AIX)
98* `mingw`
99* `msvc6`: Microsoft Visual Studio 6 service pack 5-6
100* `msvc70`: Microsoft Visual Studio 2002
101* `msvc71`: Microsoft Visual Studio 2003
102* `msvc80`: Microsoft Visual Studio 2005
103* `msvc90`: Microsoft Visual Studio 2008
104* `linux-gcc`: Gnu C++ (linux, also reported to work for Mac OS X)
105
106If you are building with Microsoft Visual Studio 2008, you need to set up the
107environment by running `vcvars32.bat` (e.g. MSVC 2008 command prompt) before
108running SCons.
109
110
111Running the tests manually
112--------------------------
113
114Note that test can be run using SCons using the `check` target:
115
116 scons platform=$PLATFORM check
117
118You need to run tests manually only if you are troubleshooting an issue.
119
120In the instructions below, replace `path/to/jsontest` with the path of the
121`jsontest` executable that was compiled on your platform.
122
123 cd test
124 # This will run the Reader/Writer tests
125 python runjsontests.py path/to/jsontest
126
127 # This will run the Reader/Writer tests, using JSONChecker test suite
128 # (http://www.json.org/JSON_checker/).
129 # Notes: not all tests pass: JsonCpp is too lenient (for example,
130 # it allows an integer to start with '0'). The goal is to improve
131 # strict mode parsing to get all tests to pass.
132 python runjsontests.py --with-json-checker path/to/jsontest
133
134 # This will run the unit tests (mostly Value)
135 python rununittests.py path/to/test_lib_json
136
137 # You can run the tests using valgrind:
138 python rununittests.py --valgrind path/to/test_lib_json
139
140
141Building the documentation
142--------------------------
143
144Run the Python script `doxybuild.py` from the top directory:
145
146 python doxybuild.py --doxygen=$(which doxygen) --open --with-dot
147
148See `doxybuild.py --help` for options.
149
150
151Generating amalgamated source and header
152----------------------------------------
153
154JsonCpp is provided with a script to generate a single header and a single
155source file to ease inclusion into an existing project. The amalgamated source
156can be generated at any time by running the following command from the
157top-directory (this requires Python 2.6):
158
159 python amalgamate.py
160
161It is possible to specify header name. See the `-h` option for detail.
162
163By default, the following files are generated:
164* `dist/jsoncpp.cpp`: source file that needs to be added to your project.
165* `dist/json/json.h`: corresponding header file for use in your project. It is
166 equivalent to including `json/json.h` in non-amalgamated source. This header
167 only depends on standard headers.
168* `dist/json/json-forwards.h`: header that provides forward declaration of all
169 JsonCpp types.
170
171The amalgamated sources are generated by concatenating JsonCpp source in the
172correct order and defining the macro `JSON_IS_AMALGAMATION` to prevent inclusion
173of other headers.
174
175
176Adding a reader/writer test
177---------------------------
178
179To add a test, you need to create two files in test/data:
180
181* a `TESTNAME.json` file, that contains the input document in JSON format.
182* a `TESTNAME.expected` file, that contains a flatened representation of the
183 input document.
184
185The `TESTNAME.expected` file format is as follows:
186
187* each line represents a JSON element of the element tree represented by the
188 input document.
189* each line has two parts: the path to access the element separated from the
190 element value by `=`. Array and object values are always empty (i.e.
191 represented by either `[]` or `{}`).
192* element path: `.` represents the root element, and is used to separate object
193 members. `[N]` is used to specify the value of an array element at index `N`.
194
195See the examples `test_complex_01.json` and `test_complex_01.expected` to better
196understand element paths.
197
198
199Understanding reader/writer test output
200---------------------------------------
201
202When a test is run, output files are generated beside the input test files.
203Below is a short description of the content of each file:
204
205* `test_complex_01.json`: input JSON document.
206* `test_complex_01.expected`: flattened JSON element tree used to check if
207 parsing was corrected.
208* `test_complex_01.actual`: flattened JSON element tree produced by `jsontest`
209 from reading `test_complex_01.json`.
210* `test_complex_01.rewrite`: JSON document written by `jsontest` using the
211 `Json::Value` parsed from `test_complex_01.json` and serialized using
212 `Json::StyledWritter`.
213* `test_complex_01.actual-rewrite`: flattened JSON element tree produced by
214 `jsontest` from reading `test_complex_01.rewrite`.
215* `test_complex_01.process-output`: `jsontest` output, typically useful for
216 understanding parsing errors.
217
218
219License
220-------
221
222See the `LICENSE` file for details. In summary, JsonCpp is licensed under the
223MIT license, or public domain if desired and recognized in your jurisdiction.
224
225
README.version