diff options
Diffstat (limited to '3rdparty/jsoncpp/README.md')
-rw-r--r-- | 3rdparty/jsoncpp/README.md | 104 |
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. - |