1 Introduction 2 ------------ 3 4 [JSON][json-org] is a lightweight data-interchange format. It can represent 5 numbers, strings, ordered sequences of values, and collections of name/value 6 pairs. 7 8 [json-org]: http://json.org/ 9 10 JsonCpp is a C++ library that allows manipulating JSON values, including 11 serialization and deserialization to and from strings. It can also preserve 12 existing comment in unserialization/serialization steps, making it a convenient 13 format to store user input files. 14 15 ## A note on backward-compatibility 16 Very soon, we are switching to C++11 only. For older compilers, try the `pre-C++11` branch. 17 18 Using JsonCpp in your project 19 ----------------------------- 20 21 The recommended approach to integrating JsonCpp in your project is to build 22 the amalgamated source (a single `.cpp` file) with your own build system. This 23 ensures consistency of compilation flags and ABI compatibility. See the section 24 "Generating amalgamated source and header" for instructions. 25 26 The `include/` should be added to your compiler include path. Jsoncpp headers 27 should be included as follow: 28 29 #include <json/json.h> 30 31 If JsonCpp was build as a dynamic library on Windows, then your project needs to 32 define the macro `JSON_DLL`. 33 34 35 Building and testing with new CMake 36 ----------------------------------- 37 38 [CMake][] is a C++ Makefiles/Solution generator. It is usually available on most 39 Linux system as package. On Ubuntu: 40 41 sudo apt-get install cmake 42 43 [CMake]: http://www.cmake.org 44 45 Note that Python is also required to run the JSON reader/writer tests. If 46 missing, the build will skip running those tests. 47 48 When 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 55 Steps 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 65 Alternatively, 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 72 Running `cmake -`" will display the list of available generators (passed using 73 the `-G` option). 74 75 By default CMake hides compilation commands. This can be modified by specifying 76 `-DCMAKE_VERBOSE_MAKEFILE=true` when generating makefiles. 77 78 79 Building and testing with SCons 80 ------------------------------- 81 82 **Note:** The SCons-based build system is deprecated. Please use CMake; see the 83 section above. 84 85 JsonCpp can use [Scons][] as a build system. Note that SCons requires Python to 86 be installed. 87 88 [SCons]: http://www.scons.org/ 89 90 Invoke SCons as follows: 91 92 scons platform=$PLATFORM [TARGET] 93 94 where `$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 106 If you are building with Microsoft Visual Studio 2008, you need to set up the 107 environment by running `vcvars32.bat` (e.g. MSVC 2008 command prompt) before 108 running SCons. 109 110 111 Running the tests manually 112 -------------------------- 113 114 Note that test can be run using SCons using the `check` target: 115 116 scons platform=$PLATFORM check 117 118 You need to run tests manually only if you are troubleshooting an issue. 119 120 In 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 141 Building the documentation 142 -------------------------- 143 144 Run the Python script `doxybuild.py` from the top directory: 145 146 python doxybuild.py --doxygen=$(which doxygen) --open --with-dot 147 148 See `doxybuild.py --help` for options. 149 150 151 Generating amalgamated source and header 152 ---------------------------------------- 153 154 JsonCpp is provided with a script to generate a single header and a single 155 source file to ease inclusion into an existing project. The amalgamated source 156 can be generated at any time by running the following command from the 157 top-directory (this requires Python 2.6): 158 159 python amalgamate.py 160 161 It is possible to specify header name. See the `-h` option for detail. 162 163 By 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 171 The amalgamated sources are generated by concatenating JsonCpp source in the 172 correct order and defining the macro `JSON_IS_AMALGAMATION` to prevent inclusion 173 of other headers. 174 175 176 Adding a reader/writer test 177 --------------------------- 178 179 To 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 185 The `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 195 See the examples `test_complex_01.json` and `test_complex_01.expected` to better 196 understand element paths. 197 198 199 Understanding reader/writer test output 200 --------------------------------------- 201 202 When a test is run, output files are generated beside the input test files. 203 Below 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 219 License 220 ------- 221 222 See the `LICENSE` file for details. In summary, JsonCpp is licensed under the 223 MIT license, or public domain if desired and recognized in your jurisdiction. 224 225
